Authors for contact: Alexandre Falcao (e-mail: afalcao@ic.unicamp.br)
Samuel Crowell (e-mail: svc27@cornell.edu)
Overview:
This readme file describes how to install, compile, and use PANorama1.0 and PANorama2.0 for Panicle Image Acquisition, Processing, and Phenotyping. PANorama is an open-source software, and is available for download within the "Files" tab at the top of this webpage. By downloading and installing PANorama, you agree to the conditions as outlined within the included Open Source (GNU) licensing agreement (see COPYING.txt file).
Dependencies:
PANorama depends on lapack, blas, and ift libraries. The first two should be publicly available in your linux distribution and should be installed to compile the programs. The ift library is given in the libift directory within the PANorama1.0 and PANorama2.0 downloads. You should find this library already compiled for 64-bit and 32-bit linux machines. For image capture, PANorama is dependent on the open-source software package gPhoto2. gPhoto2 is available for download at http://www.gphoto.org/, and is compatible with a wide range of camera models.
More information regarding the light box and tripod that we use to capture images is available at the following links:
The core source code of PANorama is open in include/iftPANorama.h and src/iftPANorama.c, where you will find the main data structures and routines to manipulate panicle information. The main programs are also provided in src. The experiments should be executed in a data directory, created by the user according to the usage instructions.
From the user point of view, PANorama essentially consists of a sequence of python scripts, given in the python directory.
Corresponding publication:
Samuel Crowell, Alexandre X. Falcão, Ankur Shah, Zachary Wilson, Anthony J. Greenberg, & Susan R. McCouch. (2014). High-Resolution Inflorescence Phenotyping Using a Novel Image Analysis Pipeline, PANorama. Plant Physiology 165(2): 479-495.
Link: http://www.plantphysiol.org/content/165/2/479.short
Samuel Crowell, Pavel Korniliev, Alexandre Falcão, Abdelbagi Ismail, Glenn Gregorio, Jason Mezey, & Susan McCouch. Genome-wide association and high-resolution phenotyping link Oryza sativa traits to numerous trait-specific QTL clusters. (2016) Nature Communications (in press).
Useful Linux Commands:
man <command> -- Display the usage of the commands below and their parameters
mkdir -- Open a directory
rmdir -- Remove a directory
cd -- Goes to a directory in a given path
display <image> --- Displays an image on the screen (this requires installation of the ImageMagick package)
mv -- to rename a file
rm -- to remove a file
cp -- to copy a file
ln -s -- to link files/directories
pwd -- to tell the current directory
ls -s -- to list files/directories
sudo -- to execute any command as root (administrator)
tar -cvzf -- to create a ball of a directory with all its files (tar.gz extension)
tar -xvzf -- to decompress the files from a ball of a directory (tar.gz extension)
tar -cvjf -- to create a ball of a directory with all its files (tar.bz2 extension)
tar -xvjf -- to decompress the files from a ball of a directory (tar.bz2 extension)
Installation instructions:
Place the PANorama2.0.tar.bz2 zipped file into your root directory. To unzip the file, execute the following command using terminal:
tar -xvjf PANorama2.0.tar.bz2
Edit the .bashrc file in the root directory with the following command at its end:
The .bashrc will be executed everytime you open an xterminal. You may also execute it whenever you change its content by typing the following within the root directory:
source .bashrc
After editing the .bashrc, it's best to close the terminal and reopen a new window. You can double check that the .bashrc contains the PATH above by executing:
echo $PATH
If you are having difficulty editing the .bashrc file from terminal, go to your Home folder, click View>ShowHiddenFiles, and open the .bashrc file manually. Within the text editor, you can paste the command on a new line at the bottom of the file and click save:
After manually editing the .bashrc file, execute the following within the terminal:
source .bashrc
Compilation instructions:
Go to PANorama2.0 and edit the Makefile to select LIBIFT as ift-64bits (for 64-bit linux machines) or ift-32bits (for 32-bit linux machines). To do so, open Makefile and place a # in front of the version that is not installed on your computer. To find out if our linux machine is 32 or 64-bit, type the following into terminal:
uname -a
Save the Makefile and close the text editor. To compile the program, type the following from terminal within the PANorama2.0 directory:
make all
You may also need to remove binaries and recompile everything someday. In this case, type:
make clean
make all
After compilation, you may want to return to the root directory by typing:
cd
Using PANorama:
PANorama scripts are executed within a structured directory (see screenshot). Several demo images are included within the subdirectory 'demo', stored within PANorama2.0. Detailed instruction videos are also available on the CornellRiceLab Vimeo page: http://vimeo.com/user25410343
In the root directory or on your desktop, create a data directory for your experiment. For example, enter the following into the terminal:
mkdir data_PANorama_05012014
Inside the data directory,
cd data_PANorama_05012014
you will execute the first 4 scripts below in the given order. If you wish to test the included demo images, paste the entire originals directory stored within PANorama2.0/demo into your experimental folder and start the pipeline below at step 2.
Scripts:
GetPictures.py
1. GetPictures.py: This script must be used for image acquisition. It saves the images in a subdirectory originals and their names in imagefiles.txt, which will be used by the other scripts. If the user wishes to analyze images that are acquired outside the PANorama pipeline, the images must be in .jpg format and stored within the subdirectory originals.
CreateSkeletons.py
2. CreateSkeletons.py: This script computes the skeleton of each panicle image, listed in imagefiles.txt and stored in originals, and saves each skeleton image in a subdirectory skeletons. Two files are created with the same root name and stored within the subdirectory /skeletons: a _skel.jpg and a .inf file. Re-executing CreateSkeletons.py will regenerate both of these files.
DefineMainAxis.py
3. DefineMainAxis.py: This script should be used to mark the three developmental points: Extrusion Point, Intial Main Axis Point, and Final Main Axis Point. A First/Next Image button is provided to load each skeleton image related to a panicle image in imagefiles.txt. The marked points are saved in the subdirectory skeletons, using a text file with the same basename of the skeleton image file and extension .txt.
ExtractInfo.py
4. ExtractInfo.py: For each panicle image in imagefiles.txt, this script reads the skeleton image and the _mainaxis.txt file containing the marked points on the skeleton; computes the extrusion, the main axis, the primary branches, and the nodes along the main axis; and stores these informations in the subdirectory skeletons, within the binary .inf file.
After you have executed the previous 4 scripts in all data directories, you can copy multiple experimental directories into a new data analysis directory (e.g. exper_analysis_05052014) for the measure extraction. You can also link all data directories within an analysis folder.
Example: This example links to data directories of dates 05012014 and 05022014.
cd
mkdir exper_05052014
cd exper_05052014
ln -s ~/data_05012014
ln -s ~/data_05022014
Finally, to extract measures from the skeleton images storedbin all data directories that you have included in exper_05052014:
ExtractMeasures.py
5. ExtractMeasures.py: This script will create the spreadsheet file PanicleMeasures.csv with all extracted measures. The script appends lines into PanicleMeasures.csv, so it must be removed before you re-execute the script. It also creates ExtraPanicleMeasures.csv with individual measures for branches and segments within the main axis.
Error Correction:
Two additional scripts have been included for error correction within the pipeline. Detailed instruction videos are also available on the CornellRiceLab Vimeo page: http://vimeo.com/user25410343
RebuildImageFiles.py
6. RebuildImageFiles.py: This script can be executed inside a data directory to rebuild the imagefiles.txt with the images stored in originals. It might be useful if the imagefiles.txt get corrupted, or if you add or remove files to originals.
CorrectBranches.py
7. CorrectBranches.py: This script allows to add/delete primary branches of the skeleton by selecting bullets at their end points. It works by directly editing the .inf file within the skeletons subdirectory. Thus, any edits you make using CorrectBranches.py will be lost if the CreateSkeletons.py script is rerun--because a new .inf file is generated every time CreateSkeletons.py is executed.
Adjusting PANorama settings:
Multiple aspects of the PANorama pipeline are controlled by parameters
stored within a single file. You can adjust these settings by going to
the following file:
PANorama2.0/include/iftPANorama.h
To edit parameters, change the numeric value beside a parameter name. For example, the ANWSTHICK parameter is automatically set to filter awns that are equal to or thinner than a diameter of 0.032cm. To turn this filter off, change this value to 0.0. Any time you edit the iftPANorama.h file, you must recompile the program in order for the changes to go into effect. To do this:
cd PANorama2.0
make all
Measurements:
PANorama2.0 currently supports measuring and extracting the following phenotypic measures from images:
Length of Extrusion (cm).
Length of Main Axis (cm).
Mean Length Between Nodes along the Main Axis (cm).
Standard deviation of the Length Between Nodes along the Main Axis (cm).
Maximum Length Between Nodes along the Main Axis (cm).
Minimum Length Between Nodes along the Main Axis (cm).
Mean Length of the Primary Branches (cm).
Standard deviation of the Length of the Primary Branches (cm).
Maximum Length of the Primary Branches (cm).
Minimum Length of the Primary Branches (cm).
Mean Length of the Primary Branches In Inferior Slab (cm).
Standard deviation of the Length of the Primary Branches In Inferior Slab (cm).
Maximum Length of Primary Branches In Inferior Slab (cm).
Minimum Length of Primary Branches In Inferior Slab (cm).
Mean Length of Primary Branches In Superior Slab (cm).
Standard deviation of Length Of Primary Branches In Superior Slab (cm).
Maximum Length of Primary Branches In Superior Slab (cm).
Minimum Length of Primary Branches In Superior Slab (cm).
Asymmetry of Primary Branch Length: the absolute diference between the mean lengths of the primary branches at the left and right sides of the main axis divided by the sum of those mean lengths. This represents a number between 0 and 1 (higher the number, higher is the asymmetry).
Asymmetry of Primary Branch Length In Inferior Slab.
Asymmetry of Primary Branch Length In Superior Slab.
Asymmetry of Number of Primary Branches: the absolute diference between the number of primary branches at the left and right sides of the main axis divided by the sum of those numbers.
Asymmetry of Number of Primary Branches In Inferior Slab.
Asymmetry of Number of Primary Branches In Superior Slab.
Mean Thickness of the Main Axis (cm).
Standard Deviation of the Thickness of the Main Axis (cm).
Number of Skeleton Points on the Main Axis.
Maximum Thickness of the Main Axis (cm).
Minimum Thickness of the Main Axis (cm).
Mean Thickness of Extrusion (cm).
Standard deviation of the Thickness of Extrusion (cm).
Number of Skeleton Points on Extrusion.
Maximum Thickness of Extrusion (cm).
Minimum Thickness of Extrusion (cm).
Number of Primary Branches.
Number of Primary Branches in the Superior Slab.
Number of Primary Branches in the Inferior Slab.
Number of Nodes along the Main Axis.
Number of Nodes along the Main Axis in the Superior Slab.
Number of Nodes along the Main Axis in the Inferior Slab.
Number of Seeds.
Number of Tips (end points).
Mean Number of Branches per Node.
Standard deviation of the Number of Branches per Node.
Mean Number of Branches per Node in the Superior Slab.
Standard deviation of the Number of Branches per Node in the Superior Slab.
Mean Number of Branches per Node in the Inferior Slab.
Standard deviation of the Number of Branches per Node in the Nnferior Slab.
Maximum Number of Branches per Node.
Maximum Number of Branches per Node in the Superior Slab.
Maximum Number of Branches per Node in the Inferior Slab.
Last edit: PANorama 2015-12-30
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Authors for contact: Alexandre Falcao (e-mail: afalcao@ic.unicamp.br)
Samuel Crowell (e-mail: svc27@cornell.edu)
Overview:
This readme file describes how to install, compile, and use PANorama1.0 and PANorama2.0 for Panicle Image Acquisition, Processing, and Phenotyping. PANorama is an open-source software, and is available for download within the "Files" tab at the top of this webpage. By downloading and installing PANorama, you agree to the conditions as outlined within the included Open Source (GNU) licensing agreement (see COPYING.txt file).
Dependencies:
PANorama depends on lapack, blas, and ift libraries. The first two should be publicly available in your linux distribution and should be installed to compile the programs. The ift library is given in the libift directory within the PANorama1.0 and PANorama2.0 downloads. You should find this library already compiled for 64-bit and 32-bit linux machines. For image capture, PANorama is dependent on the open-source software package gPhoto2. gPhoto2 is available for download at http://www.gphoto.org/, and is compatible with a wide range of camera models.
More information regarding the light box and tripod that we use to capture images is available at the following links:
http://www.hallpro.com/bl.html
http://www.bhphotovideo.com/c/product/438354-REG/Dot_Line_RS_CS1070_RS_CS1070_Copy_Stand.html
Implementation:
The core source code of PANorama is open in include/iftPANorama.h and src/iftPANorama.c, where you will find the main data structures and routines to manipulate panicle information. The main programs are also provided in src. The experiments should be executed in a data directory, created by the user according to the usage instructions.
From the user point of view, PANorama essentially consists of a sequence of python scripts, given in the python directory.
Corresponding publication:
Samuel Crowell, Alexandre X. Falcão, Ankur Shah, Zachary Wilson, Anthony J. Greenberg, & Susan R. McCouch. (2014). High-Resolution Inflorescence Phenotyping Using a Novel Image Analysis Pipeline, PANorama. Plant Physiology 165(2): 479-495.
Link: http://www.plantphysiol.org/content/165/2/479.short
Samuel Crowell, Pavel Korniliev, Alexandre Falcão, Abdelbagi Ismail, Glenn Gregorio, Jason Mezey, & Susan McCouch. Genome-wide association and high-resolution phenotyping link Oryza sativa traits to numerous trait-specific QTL clusters. (2016) Nature Communications (in press).
Useful Linux Commands:
Installation instructions:
Place the PANorama2.0.tar.bz2 zipped file into your root directory. To unzip the file, execute the following command using terminal:
Edit the .bashrc file in the root directory with the following command at its end:
The .bashrc will be executed everytime you open an xterminal. You may also execute it whenever you change its content by typing the following within the root directory:
After editing the .bashrc, it's best to close the terminal and reopen a new window. You can double check that the .bashrc contains the PATH above by executing:
If you are having difficulty editing the .bashrc file from terminal, go to your Home folder, click View>ShowHiddenFiles, and open the .bashrc file manually. Within the text editor, you can paste the command on a new line at the bottom of the file and click save:
After manually editing the .bashrc file, execute the following within the terminal:
Compilation instructions:
Go to PANorama2.0 and edit the Makefile to select LIBIFT as ift-64bits (for 64-bit linux machines) or ift-32bits (for 32-bit linux machines). To do so, open Makefile and place a # in front of the version that is not installed on your computer. To find out if our linux machine is 32 or 64-bit, type the following into terminal:
Save the Makefile and close the text editor. To compile the program, type the following from terminal within the PANorama2.0 directory:
You may also need to remove binaries and recompile everything someday. In this case, type:
After compilation, you may want to return to the root directory by typing:
Using PANorama:
PANorama scripts are executed within a structured directory (see screenshot). Several demo images are included within the subdirectory 'demo', stored within PANorama2.0. Detailed instruction videos are also available on the CornellRiceLab Vimeo page: http://vimeo.com/user25410343
In the root directory or on your desktop, create a data directory for your experiment. For example, enter the following into the terminal:
Inside the data directory,
you will execute the first 4 scripts below in the given order. If you wish to test the included demo images, paste the entire originals directory stored within PANorama2.0/demo into your experimental folder and start the pipeline below at step 2.
Scripts:
1. GetPictures.py: This script must be used for image acquisition. It saves the images in a subdirectory originals and their names in imagefiles.txt, which will be used by the other scripts. If the user wishes to analyze images that are acquired outside the PANorama pipeline, the images must be in .jpg format and stored within the subdirectory originals.
2. CreateSkeletons.py: This script computes the skeleton of each panicle image, listed in imagefiles.txt and stored in originals, and saves each skeleton image in a subdirectory skeletons. Two files are created with the same root name and stored within the subdirectory /skeletons: a _skel.jpg and a .inf file. Re-executing CreateSkeletons.py will regenerate both of these files.
3. DefineMainAxis.py: This script should be used to mark the three developmental points: Extrusion Point, Intial Main Axis Point, and Final Main Axis Point. A First/Next Image button is provided to load each skeleton image related to a panicle image in imagefiles.txt. The marked points are saved in the subdirectory skeletons, using a text file with the same basename of the skeleton image file and extension .txt.
4. ExtractInfo.py: For each panicle image in imagefiles.txt, this script reads the skeleton image and the _mainaxis.txt file containing the marked points on the skeleton; computes the extrusion, the main axis, the primary branches, and the nodes along the main axis; and stores these informations in the subdirectory skeletons, within the binary .inf file.
After you have executed the previous 4 scripts in all data directories, you can copy multiple experimental directories into a new data analysis directory (e.g. exper_analysis_05052014) for the measure extraction. You can also link all data directories within an analysis folder.
Example: This example links to data directories of dates 05012014 and 05022014.
Finally, to extract measures from the skeleton images storedbin all data directories that you have included in exper_05052014:
5. ExtractMeasures.py: This script will create the spreadsheet file PanicleMeasures.csv with all extracted measures. The script appends lines into PanicleMeasures.csv, so it must be removed before you re-execute the script. It also creates ExtraPanicleMeasures.csv with individual measures for branches and segments within the main axis.
Error Correction:
Two additional scripts have been included for error correction within the pipeline. Detailed instruction videos are also available on the CornellRiceLab Vimeo page: http://vimeo.com/user25410343
6. RebuildImageFiles.py: This script can be executed inside a data directory to rebuild the imagefiles.txt with the images stored in originals. It might be useful if the imagefiles.txt get corrupted, or if you add or remove files to originals.
7. CorrectBranches.py: This script allows to add/delete primary branches of the skeleton by selecting bullets at their end points. It works by directly editing the .inf file within the skeletons subdirectory. Thus, any edits you make using CorrectBranches.py will be lost if the CreateSkeletons.py script is rerun--because a new .inf file is generated every time CreateSkeletons.py is executed.
Adjusting PANorama settings:
Multiple aspects of the PANorama pipeline are controlled by parameters
stored within a single file. You can adjust these settings by going to
the following file:
To edit parameters, change the numeric value beside a parameter name. For example, the ANWSTHICK parameter is automatically set to filter awns that are equal to or thinner than a diameter of 0.032cm. To turn this filter off, change this value to 0.0. Any time you edit the iftPANorama.h file, you must recompile the program in order for the changes to go into effect. To do this:
Measurements:
PANorama2.0 currently supports measuring and extracting the following phenotypic measures from images:
Last edit: PANorama 2015-12-30