Skip to content

UNH PhenoCam Tools

Jump to bottom Edit New page
Trey Stafford edited this page Jul 6, 2015 · 15 revisions

The University of New Hampshire hosts some tools for working with PhenoCam imagery in the Tools section of their PhenoCam website. This page describes relevant tools and their use.

PhenoCam Image Processor GUI

Overview

The PhenoCam Image Processor is a MATLAB application with a Graphical User Interface. This tool is designed to allow the user to easily browse PhenoCam images, define regions of interest, and calculate a time series of Green Chromatic Coordinate values.

PhenoCam GUI

Installation

Note: official installation notes are available in the PhenoCamGUI_UserGuide.pdf included in any download of the application.

From Source

If one has access to MATLAB, the PhenoCam Image Processor MATLAB source code can be used directly. Simply add the folder containing the downloaded source code to your MATLAB path using the path command, and then enter phenocamimageprocessor. For example, if you download the source to C:\Users\username\Matlab\PhenoCamGUI, one would use the following code to run the application:

path(path, 'C:\Users\username\Matlab\PhenoCamGUI')
phenocamimageprocessor

Alternatively, change directory to the folder containing the application source code, and then run the application:

cd C:\Users\username\Matlab\PhenoCamGUI
phenocamimageprocessor

Pre-compiled Version

Pre-compiled versions of the PhenoCam Image Processor are available for Windows 32 and 64 bit systems, and MacOSX. Simply download the correct version for your system, and extract the contents of the zipped download to an installation directory.

Once Extracted, run the included executable (phenocamW[32/64]_pkg.exe in windows or run_PhenoCamGUI_maci64.sh for Mac) and follow the self-guided directions. Note that you will need to install the MATLAB runtime libraries as part of the installation process.

Use

Note official usage notes are available in the PhenoCamGUI_UserGuide.pdf included in any download of the application.

The following sub-sections explain the use of the PhenoCam image processor GUI, in roughly the order of use.

Selecting imagery

Clicking on the Set Dir button will open a directory selection window. Select a directory containing a SINGLE year's worth of image data. The GUI is designed for working with one year of data at a time, and will throw an error if an incompatible directory structure is encountered.

Changing the displayed image

On the right-hand side of the application, under the 'Input' frame and below the Set ROI and Clear ROI buttons, is a list of images found after setting the input directory. Clicking on an image's name will change the displayed image to that image.

ROI Creation

Up to three ROIs can be drawn in the image for analysis. To set the number of ROIs, use the dropdown next to the Set Dir button.

Clicking the Set ROI button will change the mouse cursor to a polygon drawing crosshair. Select points to define a polygon representing a region of interest in your image. Double-click to finalize the polygon. The polygon draw crosshairs will return to a normal mouse pointer once all ROIs have been defined.

The Clear ROI button will clear all defined ROIs. Use this if a mistake in ROI creation is made.

Displayed ROIs are colored according to the order in which they are drawn. The first ROI is blue, the second red, and the third yellow.

If one wishes to save the ROI created using the Set ROI tool, go to File -> Save ROI. This will open a save file window. Created ROI(s) will be saved as a .tif image.

Calculation Options

The calculation options determine how the Green Chromatic Coordinate will be calculated for the selected ROI(s).

Calculation Options

One should first set the hours of the day between which images will be used for calculating GCC values. This is specified using the Hours: dropdowns.

Next, a window size can be defined. The window determines the number of days used for smoothing the data with one of the methods listed at the bottom of the Calculation Options frame (90th perc., Mean, Median). A standard window size for the 90th percentile method is 3 days.

A threshold can also be defined using the dropdown next to thresh. This determines the minimum digital number value used in the calculations. A value of 15% is suggested.

Finally, one has the option of changing the smoothing method. By default, the 90th percentile method is checked, as this is a commonly used technique. Unchecking the 90th perc. checkbox will allow one to choose the Mean or Median options.

Once all calculation options are set, click the Calculate button. A 'Processing Images' progress window will open, after which the GCC time series will be plotted in the 'Time Series' frame in the bottom half of the application window.

Time Series Plot

Once calculated, a plot of raw GCC and smoothed GCC values for the specified ROI(s) will be displayed in the bottom half of the application window. Note that the color of the GCC values correspond to the color of the drawn ROIs (first ROI is blue, second is red, third is yellow).

By default, raw and smoothed GCC data for all defined ROIs are shown. Unchecking one or more of the defaults and pressing the Update Plot button will appropriately update the displayed plot.

Unchecking both the 'Gcc' and 'Gcc Smooth' options will make the 'Red', 'Green', and 'Blue' options available. Checking one or more of these will show how the red, green, and/or blue digital number values change over time.

Saving Time Series Data

One can save the results of the GCC calculations for all ROIs by going to File -> Save Time Series Data. A save file dialog will open, where a name should be specified.

Raw and smoothed GCC data are saved as comma delimited text files with the following naming structure:

  • raw-ROInum-SaveName.txt
  • smooth-ROInum-SaveName.txt

Where ROInum is the ROI number (as shown in the ROI selection frame) and SaveName is the name given in the save file dialog.

PhenoCam_toolkit

The phenocam_toolkit consists of MATLAB and Python functions for working with PhenoCam imagery. A brief description of these functions follows.

Python

Note that the Python version of these functions requires numpy and PIL.

####get_dn_means(im, roimask) Function returns the mean digital number values for an image/mask pair.

Parameters:

  • im: an RGB PhenoCam image opened with the PIL module
  • roi: a B/W mask image opened with the PIL module. ROI must be the same size as im.

Returns:

  • [mean red ROI DN,
    mean green ROI DN,
    mean blue ROI DN]

Example:

from PIL import Image
from phenocam_toolkit import get_dn_means

# Open an RGB and roi image
img = Image.open('/path/to/RGB/PhenoCam/image.jpg')
roi = Image.open('/path/to/roi/image.tif')

# Obtain the mean red, green, and blue digital number values of the image within the ROI
[r_mean_roi, g_mean_roi, b_mean_roi] = get_dn_means(img,roi)

####fn2datetime(sitename, filename, irFlag=False) Extracts date and time information from an image filename.
From the fn2datetime() documentation:

Function to extract the datetime from a "standard" filename based on a sitename. Here we assume the filename format is the standard:

sitename_YYYY_MM_DD_HHNNSS.jpg

So we just grab components from fixed positions. If irFlag is True then the "standard" format is:

sitename_IR_YYYY_MM_DD_HHNNSS.jpg

Parameters:

  • sitename - The PhenoCam site name of the image in question.
  • filename - The filename of the image.
  • irFlag - (Optional. False by default). Boolean value signaling if image is IR.

Returns:

  • Datetime object representing the date and time of the specified image.

Example:

from phenocam_toolkit import fn2datetime

# Lets first use an RGB PhenoCam image from the Harvard Forest site as an example. 
sitename = 'harvard'
filename = 'harvard_2014_03_03_120136.jpg'

# Get the datetime
RGB_datetime = fn2datetime(sitename, filename)

# Now get the datetime of an IR image from the same site. 
filename = 'harvard_IR_2014_03_03_120136.jpg'
IR_datetime = fn2datetime(sitename, filename, irFlag = True)

####doy2date(year, doy, out='tuple') From the doy2date() documentation:

Convert year and yearday into calendar date. Output is a tuple
(out='tuple': default) ISO string (out='iso'), julian date
(out='julian'), or python date object (out='date')

Parameters:

  • year - An int representing a year (e.g., 2015)
  • doy - An int representing a day of the year (e.g., July 5, 2015 is doy 186)
  • out - (Optional. Default: 'tuple') a string specifying output date format. ('tuple', 'iso', 'julian', or 'date')

Returns:

  • Date information formatted per the 'out' parameter.

Example:

from phenocam_toolkit import doy2date

# Get year 2015, doy 186 as a Python datetime object
date = doy2date(2015, 186, out='date')

####date2doy(year, month, day) Converts a year/month/day calendar date into a day of year (doy). Parameters:

  • year - An integer representing a year (e.g., 2015)
  • month - An integer representing a month of the year (e.g., 7)
  • day - An integer representing a day of the month (e.g., 6)

Returns:

  • An integer representing the day of the year of the given calendar date.

Example:

from phenocam_toolkit import date2doy

# Convert July 6th, 2015 to DOY
doy = date2doy(2015, 7, 6)

####datetime2fdoy(myDateTime) Converts a datetime object into a fractional day of year (doy). NOTE: THIS FUNCTION RETURNS QUESTIONABLE RESULTS. As Per comments included in the function:

# add a day so that doy 1.5 is Jan 1 at noon. This matches
# sample output of Steve K. and Michael T. ???? Probably
# needs some attention! DOY is really integer in range 1-366.
# Here we get decimal between 1 and 367.

Parameters:

  • myDateTime - A python datetime object

Returns:

  • A floating point value representing a fractional day of year

Example:

import datetime
from phenocam_toolkit import datetime2fdoy

# Create a datetime object representing July 6th, 2015 at 11:56 AM
date = datetime.datetime(2015, 7, 6, 11, 56)

# Get the fdoy for the above datetime
fdoy = datetime2fdoy(date)  # Returns 187.49722222222223

####getsiteimglist(archive_dir, sitename, startDT, endDT, getIR) Returns a list of full-paths to PhenoCam images contained within an archive directory. NOTE: This function may be considered inefficient and could be significantly improved with use of the glob module. Relatively fast nevertheless.

Parameters:

  • archive_dir - String giving full path to a PhenoCam archive directory (this directory should include folders named after PhenoCam sitenames, under which Phenocam images are stored by date).
  • startDT - (Optional. Default: datetime.datetime(1990,1,1,0,0,0)). Datetime object representing start date and time to return images for.
  • endDT - (Optional. Default: datetime.datetime.now()). Datetime object representing end date and time to return images for.
  • getIR - (Optional. Default: False). True if IR images should be returned instead of RGB images.

Returns:

  • List of strings representing the full paths to phenocam images.

Example:

import datetime
from phenocam_toolkit import getsiteimglist

# Lets use Harvard forest as an example
archive_dir = '/path/to/phenocamdata/'
sitename = 'harvard'

# Get images between June 2011 and the present.
start = datetime.datetime(2011,6,1,1)

# Get the RGB image list:
rgb_paths = getsiteimglist(archive_dir, sitename, startDT=start)

For another example, see Finding images

MATLAB

The MATLAB Phenocam toolkit is similar to the Python version (similar functions). More details soon.

Add a custom footer
Add a custom sidebar

Clone this wiki locally