schnorr / phenology

My tools and LabBook for Phenological Studies

Phenology Programs and Scripts

This repository is my attempt to organize some programs and scripts related to phenology, the study of plant evolution through digital images. Below you’ll find the requirements to make this project useful for you. All code available here is released under the GPLv3. Feel free to copy, modify and do whatever you want. Contributions are very welcomed to improve the robustness or anything else you might find important. In case of problems, report here. In all these programs, pga stands for Phenological Green Average.

This repository contains the following scripts:

• pga_csv: This program takes as input a path to a directory that follows the organization specified below, a mask (JPG) and the granularity of the histogram. It prints in the standard output the histogram for every image in the CSV file format. This CSV should be used with the CPM generation tool, written in R and described below. It assumes that the program pga_hist is in the PATH.
• pga_cpm: This program takes as input the CSV file created with pga_csv, a file with the palette (as described below), the low and high limit of the histogram bins. It creates as output a Chronological Percentage Map (CPM) for each year contained in the input, and also an overview with facets. The CPM draws the green average histogram as a function of an input image, using stacked bars.

This repository contains the following programs:

• pga_hist: This program takes as input three parameters - an image (JPG), a mask (JPG) and the granularity of the histogram of pixel’s green average metric, which is basically G/(R+G+B). The granularity tells you the amount of bins in the histogram. The output is one line with the count for every bin, separated by comma as in the CSV file format. See an example of it in action:

  pga_hist ./examples/cerrado.jpg ./masks/cerrado.jpg 20
      

  0,0,0,0,0,0,82807,783737,362094,29447,1686,109,11,3,0,0,0,0,0,0
      

• pga_tiff_hist: same as pga_hist, but for TIFF files.
• pga_palette: This program takes as input seven parameters - an image (JPG), a mask (JPG), a palette in the file format specified below, the lowest and the highest bin identifier to consider, the granularity of the histogram and the output image file (that will be encoded as JPG in the RGB file format using the colors available in the palette). A crucial semantic rule is that the different between the high and lowest bin identifiers should be smaller than the number of available colors of the palette provided. The program is expected to fail otherwise.
• pga_tiff_palette: same as pga_palette, but for TIFF files.

Requirements

sudo apt-get install cmake libjpeg-dev r-base r-cran-ggplot2 r-cran-reshape plyrr-cran-plyr libgeotiff-dev libtiff-dev

Cloning, compilation and installation

You might want to customize the CMAKE_INSTALL_PREFIX variable to your machine. In the example below, this project will be made available in the /tmp/phenology/ directory.

git clone https://github.com/schnorr/phenology.git
cd phenology ; mkdir build ; cd build
cmake -DCMAKE_INSTALL_PREFIX=/tmp/phenology/ .. ; make install

Directory Organization and Photo Specifications

Images

The digital images have to be in the JPG file format. No other format is accepted as of now. All of them should have the exactly same size (width per height) and be encoded as RGB (with no alpha channel). organized image base.

Directories

Images should be organized in the following directory structure: db/year/year_sequence.jpg, where db is the name of the database, it can be anything you want (or need); year is a diretory that will hold all that year’s images; year_sequence.jpg is the name of the file: the year part should be preferably the same as the directory name holding the file and the sequence is a integer or floating-point number that indicates the sequence of images within that year. Some examples:

1. This example has four images. We can notice that the image 003 is missing, that is okay. You can use this king of sequencing if you have one digital photo per day, for instance.

   db01/2004/2004_001.jpg
   db01/2004/2004_002.jpg
   db01/2004/2004_004.jpg
   db01/2004/2004_005.jpg
       

2. This example shows another type of sequencing, using floating-point numbers. You can use this to organize multiple photos per day. Note that is up to you to give semantics to the sequencing scheme.

   mybase/2015/2015_1.1.jpg
   mybase/2015/2015_1.2.jpg
   mybase/2015/2015_1.3.jpg
   mybase/2015/2015_2.jpg
       

The mask

You probably need to mask your images. A mask image should be also in the JPG file format. It should have the exactly same size (width per height) as the digital photos of the database, and also be encoded as RGB (with no alpha channel). The white color selects the regions you are interested to. Here an example:

The palette file format

The expected file format for a palette configuration file is the following: each line has one color coded as in the HTML-style color identification #c0c0c0. Empty lines and lines starting with the question mark are considered comments and are ignored. Here as an example of a palette with 20 colors:

?lines starting with ? are comments
?one color per line in hex format
?number of lines with colors indicates palette size
#99540f
#b26f2c
#cc8e51
#e5b17e
#ffd8b2

#6b990f
#85b22c
#a3cc51
#c3e57e
#e5ffb2

#0f6b99
#2c85b2
#51a3cc
#7ec3e5
#b2e5ff

#260f99
#422cb2
#6551cc
#8f7ee5
#bfb2ff

Usage

Generating histograms with pga_csv

Let’s suppose you have a database with organized images (db-cerrado) in your home directory, a mask image (cerrado-mask.jpg) and you want to have 100 bins for your histogram. After having everything installed (as described above), just type:

pga_csv /home/researcher/db-cerrado/ /home/researcher/cerrado-mask.jpg 100 > db-cerrado.csv

All calculated histograms are redirected to the db-cerrado.csv file.