Spotcard is implemented as a pair of macros in Fiji [9]. Fiji is one of the leading open-source image analysis tools, being a distribution of ImageJ [10], the widely used image analysis software. It is simple to install a macro in Fiji, and users can therefore extend its core functionality.
Producing the SpotCard
SpotCards can be created using the SpotCard_Create.ijm macro (Additional file 1). This allows the user to specify the list of categories and values to display on the SpotCard. The macro only asks for three category/value sets at a time, as otherwise the input dialog would become unwieldy. There is no limit within the software to the number of categories and values which can be displayed on the card, although its physical size could become impractical beyond around nine categories or more than around 15 values within a category. (SpotCards are relatively compact: the SpotCard shown in Fig. 1 (set up for a 20 mm diameter flower and contaning two ‘standard’ category/value sets and one ‘integer’ set from 0 to 99) is 62 mm wide × 56 mm high; adding a further three ‘standard’ category/value sets would make it 86 mm wide × 68 mm high).
When creating a SpotCard, the user should first specify the approximate diameter of the flower with which the SpotCard is to be used, with preset options ranging from 20 to 100 mm (though smaller or larger options could be specified by changing the macro code). If the SpotCard is not to be used with specific flowers, this can be set to ‘no flower’.
The user then inputs pairs of categories and values. Categories are simple text-based descriptions of the lists of spots (e.g. ‘Variety’, ‘Plant number’ etc).
There are two ways of specifying values. The first is a simple comma-separated list (e.g. ‘1, 2, 3, 4’ or ‘A, B, C, D’). These will appear on the SpotCard as individual spots, with a value assigned to each. The second way of specifying values is useful when the user wishes to record a large series of integers which it would otherwise be impractical to record with single values (e.g. numbers from 1 to 999). In this case, the value is entered as a range, starting with 0 and ending with a series of 9 s (e.g. 0–999). The macro will output one row of spots for units, one for 10 s, one for 100 s, etc., all within the same category. Integers within the range can then be specified by marking off their individual digits (e.g. to indicate 532, colour the 5 in the 100 s row, the 3 in the 10 s row and the 2 in the units row).
Once categories and values have been specified, the macro creates a TIF image file of the SpotCard. Category names appear above the spots. If the ‘Flower diameter’ value has been set earlier, the sets of spots are arranged around a space in the centre of the SpotCard into which a slit can be cut, so the SpotCard can be slid over the stem of the flower being photographed. Otherwise, the sets are positioned one above the other.
The macro then adds four dots in the corners of the SpotCard, which enable recognition of the SpotCard within the photograph. The default colour for these dots is blue, as it is a colour found rarely in plants, but this can be changed to pink when the SpotCard is to be used to capture information about a blue sample. Each corner dot has a different coloured centre, which allows the processing script to determine the orientation of the SpotCard.
Alongside the TIF file, the macro creates a configuration file for the SpotCard. This file contains information about the X and Y coordinates of the spots, the spot width and height, the diameter of the flower with which the SpotCard is to be used, the spot values, the spot categories, the original width and height of the SpotCard, and the flower centroid Y coordinate. (The flower centroid X coordinate is always half the width of the SpotCard.) This file is read by the second macro and used to locate the positions of the spots and the flower.
The user can then print the SpotCard. To make the spots wipe-clean, the card can be laminated; however, reflections from the laminate can interfere with flower trait measurement. Covering the spots with a single layer of sticky tape and affixing matt black card behind the flower area, as in Fig. 2, mitigates this.
Using the SpotCard
Values are recorded in the spots by colouring them in using a black dry-wipe marker, which requires no solvent to erase. If the card is being used to photograph a flower, the card is then slotted over the stem and the photograph taken. (See Fig. 2 for an example.)
Photographs of plants can include the SpotCard in any orientation. The only constraint is that the SpotCard must be photographed facing directly towards the camera, as the detection macro does not apply any affine transformations to the detected images. However, spot data are still processed correctly even when the SpotCard is tilted up to around 18 degrees around any axis; in practice, it is simple to hold it flatter than this. To facilitate correct processing, corner dots must each be over around 60 px in diameter in the photograph; in practice, if using similar SpotCard positioning to the sample data sets, this equates to images of approximately 1.2 megapixels, easily within the range of modern digital cameras and phones.
Processing
Once the user has taken photographs, the SpotCard_Analyse.ijm macro (Additional file 2) can be used to detect spot values. This macro uses color thresholding on a brightness- and contrast-adjusted copy of the image to detect the four largest blue areas (which should be the four corner dots). Once the four areas have been located, their centres are examined to detect the colours. The angles of the diagonals of the SpotCards are calculated (i.e. red-centre to black-centre; green-centre to white-centre) and these used to rotate the image so that the corner dot with the red centre is at the top left. The image is then cropped to the blue dots and checked to confirm that the red dot is at the top left of the image. (Thus far, the configuration file has not been used.)
The macro then loops through the positions of all the spots on the image, as specified by the configuration file. For each spot, a selection corresponding to 25% of the spot width and height is examined, which allows for small discrepancies in the positioning of the SpotCard (as it is difficult to take pictures which are exactly face on without using a positioning rig for the camera, flower and SpotCard). The mean gray value is read for a brightness- and contrast-adjusted selection, with a low reading indicating that the spot has been coloured, and a high reading indicating that the spot has been left blank.
Additional flower measurements such as area, perimeter etc. can be performed after the spots have been read. Such analysis can output data in SI units of length and area, rather than simply pixels, as the configuration file gives information which can be used to determine the width and height in millimetres of the SpotCard, thus providing a convenient way of determining the scale of the photograph without including a separate scale bar. The SpotCard_Analyse.ijm code includes area and perimeter recording by way of example, and this has been performed for Sample Data Set 1. Reflections from the printed card may interfere with data detection (as was the case in Sample Data Set 2); affixing matt black card to the area of the SpotCard behind the flower can mitigate this (see Fig. 2). Cropped copies of the flower image and a flood-filled copy of the area used for measurement can be saved for visual confirmation of flower detection accuracy (for examples, see Sample Data Set 1 Flowers and Sample Data Set 1 Flood Fills, available on GitHub at https://github.com/GloverLab/SpotCard).
Once all measuring is complete, the macro saves its results to a text file in CSV format, which can be processed in a variety of other software. Also saved are image filename and, if the EXIF reader plugin (https://imagej.nih.gov/ij/plugins/exif-reader.html) is installed, the date and time the image was taken, and the latitude, longitude and altitude at which the image was taken.
Regular error checking is used throughout the processing script to prevent the reporting of erroneous results. If an error is detected when processing an image, the script will stop processing that image, record the error condition in the output file, and move on to the next image. These checks include:
-
Verifying that the lengths of the diagonals between opposing corner dots are within 5% of each other. In practice, this equates to a tilt of 18 degrees around the diagonal of the SpotCard relative to the camera, and it is easy to hold the SpotCard flatter than this.
-
Verifying the aspect ratio of the image once cropped to the corner dots matches the configuration file; the recorded aspect ratio and theoretical aspect ratio should differ by no more than 5%. Again, this equates to an 18-degree tilt around the x or y axes of the SpotCard relative to the camera, and it is easy to hold the SpotCard flatter than this.
-
Verifying that, once the image has been rotated and cropped, the central portion of the top left dot is red. (This checks that the SpotCard has been correctly oriented.)