CartesianDiatom-EFA imports outline coordinate data from files generated by tpsDIG and ImageJ software in a variety of formats. It also accepts data which are entered by cut/paste transfer and by typing directly into Excel. Four Orientation Landmark x,y-coordinates are expected to preceed the coordinate data for an outline in the file, but these can be by-passed. The accepted formats and procedures for generating them are explained below; sample data files are provided in the testdata folder as part of downloading the program. Custom formats can also be designed by CartesianDiatom.

Orientation Landmarks
Outline protocols

Sample data files

tpsDIG2

To digitize image outlines using tpsDIG2,

1 assemble the outline images and micrometer image into a tps file using tpsUtil,
2 in tpsDIG2 digitize the 4 orientation landmarks (optional) using the Landmarks tool , and then
3 choose either the Landmarks, Curves or Outline Tool to capture the outline coordinates.

tpsDIG2

The procedures for the use of the 3 tools (Landmarks, Curves and Outlines) is the same for steps 1-5 and 7-8 below; they differ only in step 6.

1 Images should be in a *.tps file format. The micrometer image should be first image the file. See tpsUtil if this is not the case or the tpsDIG2 documentation.

2 Open tpsDIG2. Select File | Input Source. Choose the *.tps File containing images for processing. Then select Open.
The images may be considerably larger than the screen display, so use the "+" and "-" magnification buttons in the Main Menu to change the magnification. Use the scrolls bar to center the image, if needed.

3 Calibrate the system using the stage micrometer image. Select Image Tools | Measure. Enter a reference length and then make two clicks on the micrometer spanning that length (1st click - release (do not drag) - 2nd click). Select OK. Save this calibration by selecting from the Main Menu File | Save data . Save in the same tps file displayed in the filename window and finally choose Overwrite.
The scale factor is the number of microns per pixel in the image.

4 Select the next image (first outline image) by using the right-pointing red arrow at the left end of the Main Menu. You may need to make a magnification adjustment and scroll the window to center the specimen-of-interest.

5 Digitize the 4 Orientation Landmarks using the Digitize Landmarks Tool. Choose the Tool by clicking on its icon (it looks like cross-hairs) or selecting it from the menu Mode from the Mode | Digitize Landmarks. The markers can be repositioned by switching to Edit mode.
The 4 Orientation Landmarks will appear as the first 4 pairs of coordinates in the data file; on the right they are highlighted in blue.

If you choose not to digitize these 4 Orientation Landmarks, then just skip this section but remember to uncheck the Orientation Landmarks box during the Import Outlines process.

LM=0
IMAGE=C:\cdi\clem5\Olympus100X1.8x.JPG
ID=0
LM=74
1090.00000 1203.00000
939.00000 333.00000
1074.00000 755.00000
1022.00000 762.00000
...

6 Choose ONE the following modes of digitizing the outline: Landmarks Tool, Curves Tool, or Outlines Tool. See tpsDIG2 Help documentation for details on the use of these tools.

Digitize Landmarks Tool

Continue using the the Digitize Landmarks Tool to digitize the entire outline. Do not overlap the beginning and the end of the digitized sequence and do not digitize the first point twice. The markers can be repositioned by switching to Edit mode.

The outline coordinates will be recorded in the data file immediately following the 4th Orientation Landmark's coordinates. On the right they are highlighted in green. The "LM=74" in line 4 of the data file indicates there are for this outline 74 points recorded: 4 orientation landmarks (blue) and 70 outline (green, only 6 are shown).

Other infomation about the outline will follow these data as indicated by tpsDIG keywords: IMAGE (required) , ID (required), SCALE, COMMENT and VARIABLES.

Sample data files of 3 outlines using the Landmark Tool are provided: PclemLM.tps (with Orientation Landmarks), PclemLM_NoOL.tps (without Orientation Landmarks).

Curves Tool

Select the Curves Tool and digitize the outline. There is a 150-point limit to the number of points in the curve. End the curve with a right-click of the mouse. It may take a few seconds, but red circles should be displayed at the points on which you clicked in making the curve. Note in the data file the word "CURVES" and the number of "POINTS" in the curve will preceed the outline data (green). Note the "LM=" now indicates only the 4 Orientation Landmarks.

Other infomation about the outline will follow these data as indicated by tpsDIG keywords: IMAGE (required), ID (required) , SCALE, COMMENT and VARIABLES.

Sample data files for 3 outlines using the Curves Tool are provided : PclemCU.tps (with Orientation Landmarks), PclemCU_NoOL.tps (without Orientation Landmarks).

Outline Tool

[Note: I have found the following Outline Tool instructions work in tpsDIG (version 1), but not in tpsDIG2, version 2.01, in that the file saving routine is incorrect. However, they do work in the current version of tpsDIG2, version 2.12, downloaded 9 July 2009. When in-between things changed I do not know. ... rke 9 July 2009.]

This is easily the most complex of the 3 options.

Select Options | Image Tools (or click the Image Tools icon) The "Image Tools" window may be minimized; maximize it, but it will not be full screen.

Select Outlines. In the Object Frame select the "light" button.

Select View. This selection converts the image to a black-and-white (binary) image with all pixels having values below the threshold being set to pure black (0) and all those above the threshold to pure white (255). Repeat varying the threshold spin bar to vary the threshold until the "best" external outline margin is achieved. Click on View to see the effects of each new threshold setting. You will need to spend some time looking at the effects of different thresholds on different images with respect to the outlines they generate to appreciate use of this control.

Restore returns the original non-binary image, that is, either color or grayscale image. Use it when you think you need to start your thresholding from the beginning.

After securing a satisfactory binary image, select Modes | Outline Mode (or select the Outlines icon). The cursor changes to an open outline with an arrow tip. Select a point near but to the right of the outline* and click the left mouse button (the arrow tip indicates the point). A colored (yellow or green) line is drawn around the contour. Right click the image and a pop-up menu will appear; select Save as XY coords. The number of coordinates in the outline appears in a "No. of coords." window. Select OK.

* Once you click the cursor to start the outline, the program searches horizontally to the left until it finds the junction between the black and white pixels, and then it follows that interface (= outline) recording all the pixels at the interface. Do not click on the outline directly to start the automatic outlining, slightly to the right of where you want the recording of coordinates to start. You also should investigate the difference between the "dark" and "light" options on the Image Tools | Outlines form as to where the tracing of the outline occurs.

The window at the bottom of the screen will indicate both the number of points in your outline and the number of landmarks you have recorded, e.g., outline=1564 points, #LM=4. Note the "LM=" now indicates only the 4 Orientation Landmarks. Note also in the data file (on the right) the word "OUTLINE" and the word "POINTS" preceed the outline data in green. Again the Orientation Landmark data are in blue.

Further details and variations on the above can be found in tpDig2 Help.

Other infomation about the outline will follow these data as indicated by tpsDIG keywords: IMAGE (required), ID (required), SCALE, COMMENT or VARIABLE.

Sample data files using the Outline Tool are provided: PclemOU.tps (with Orientation Landmarks), PclemOU_NoOL.tps (without Orientation Landmarks).

7 From the Main Menu, select File | Save data | Save (or Save | Overwrite).
The data are saved in the same tps file containing your image listing; this filename will already be in the "Filename" box when this window opens. The extension should be .tps, and this also is already in the "Save as type" box. So, just select Save. A ""File exists!" message wiil appear enquiring whether you wish to "Overwrite" or "Append" to the existing saved data. Select Overwrite.

8 To process another outline return to Step 4.
After the last set of data is saved, exit tpsDIG by selecting File | eXit. *.tps files can be edited in NotePad.
CartesianDiatom-EFA will read any file produced with these formats.. Just select the tpsDIG2 option button on the ImportOutlines form.

ImageJ

For ImageJ we describe two ways in which the outline can be digitized:

(1) by using only the Crosshair Tool to mark the outline and the orientation landmarks, and
(2) by using the WandAuto Tool to automatically trace the outline after the Crosshair Tool has been used to select the Orientation Landmarks.

The protocol for each consists of 9 steps; only step 7 differs between the two.

IMAGE FOLDER SETUP
Place all images in the same folder with the image of the stage micrometer used for calibration.

OPEN ImageJ.
Check two initial settings of the program:
(1) Select Analyze | Set Measurements | Check the box to "Invert Y-coordinates". That is, Y-coordinates should be inverted.
(2) Select Edit | Options | Colors. Set the Foreground to "white", Background to "black", and Selection to "yellow".

IMPORT IMAGES
Select File | Import | Image Sequence. Choose a single file from the folder with the images, then select OPEN.
Check the box to "Convert to 8-bit Grayscale" in the "Sequence Options" window which opens. Leave the other settings as they are.
Select OK.

ORIENTATION LANDMARKS

Using the Crosshair Tool (highligted in ImageJ's main menu in figure on right), select and click on the 4 Orientation Landmarks. The coordinates of these points will pop-up in a "Results" window (upper right in figure). After the first point is clicked, the "Results" window may move behind the "Stack" (or Image) window. Move the "Stack" window out of the way, and then reposition the "Results" window on the screen in a place where you can see it.

If you hold the Shift key down while you click, the marked yellow points will remain on the screen; if you do not, only the most recent one is displayed. This does not affect their being written to the Results window, only their display.

The Results window holds a set of 6 values on one line, each line representing a point. The 6 values are:

Column 1: a serial number for the point
Column 2: the image name ("Label")
Column 3: the x-coordinate of the point
Column 4: the y-coordinate of the point
Column 5: the z-coordinate of the point, which will be zero.
Column 6: the grayscale brightness value of the point (range 0-255)

If a "Log" window opens, simply close or ignore it.

If you choose not to digitize the 4 Orientation Landmarks, then just skip this section but remember to uncheck the Orientation Landmarks box during the Import Outlines process.

Suggestions for digitizing:

- Digitize clockwise; although this is not necessary, it will reduce processing time in the EFA. However, regardless of the direction, do not make the last point chosen either the same as or beyond the starting point.
- Try to make the starting point of tracing the outline consistent among different outlines, such as, by using one extremity of an apex (on the apical axis), if available, as the starting point. However, this starting point can later be normalized in the EFA program.
- The points do not need to be evenly spaced; rather their spacing should be more-or-less proportional to the degree of curvature of the outline: the more curvature, the more closely spaced the points. Typically, the total number of points will be between 50 and 150 for those outlines captured with a Crosshair Tool, but let adequate coverage of the outline be the determining factor. Even-spacing of the points can be effected in CartesianDiatom-EFA.

The 4 Orientation Landmarks will be marked on the image as you begin to digitize the outline, ignore them. Their coordinates will not be used as part of the outline.

SAVE DATA - Orientation Landmarks and Outline Coordinates

These data are all in the Results window at this stage.
Right Click on the Results Window and choose SAVE AS. In the Save as Text window provide a file name and ".txt" as the extension. The data will be saved as a simple text (ASCII) file. The only option available for saving the Results window from its menu is SAVE AS, so in subsequent saves of the same Results window, you will asked if you want to overwite /replace the previous version of the data file - respond Yes., as the entire contents of the Results window will be written to the data file each time it is saved. Do not clear the Results window between specimens, but let the data accumulate and periodically save it.

CartesianDiatom-EFA can import the data directly from this *.txt file. A sample data file produced using this ImageJ-Crosshair Only protocol is provided; ijPclemC.txt.

NEXT VALVE or EXIT?

Select the next valve to be analyzed (Return to Step 6), or, if your sesssion is done, make sure you have made the last Save As of your Results Window.
CLOSE all ImageJ windows. Proceed to CartesianDiatom-EFA to import the data.

ORIENTATION LANDMARKS

Using the Crosshair Tool, select and click on the 4 Orientation Landmarks. The coordinates of these points will pop-up in a "Results" window. After the first point is clicked, the "Results" window may move behind the "Stack" (or Image) window. Move the "Stack" window out of the way, and then reposition the "Results" window on the screen in a place where you can see it.

The Results window holds a set of 6 values on one line, each line representing a point. The 6 values are:

Column 1: a serial number for the point
Column 2: the image name
Column 3: the x-coordinate of the point
Column 4: the y-coordinate of the point
Column 5: the z-coordinate of the point, which will be zero.
Column 6: the grayscale brightness value of the point (range 0-255)

If a "Log" window opens, simply close or ignore it.

If you choose not to digitize the 4 Orientation Landmarks, then just skip this section but remeber to uncheck the Orientation Landmarks box during the Import Outlines process.
,

IMAGE THRESHOLDING

Select Process | Binary | Threshold.

Select Image | Adjust | Threshold. The image window will preview a binary image of the outline and a new "Threshold" window will pop-up.

Let's look at this "Threshold" window.

The histogram: The histogram at the top of the window is a frequency distribution of the grayscale values of all the pixels in your image. The grayscale values values are scaled on the horizontal axis from 0 (pure black) to 255 (pure white).

The thresholds: Running vertical across the histogram are two lines. These are thresholds: a lower one (on the left) and an upper one (on the right). These two lines divide the full grayscale axis into 3 sectors: sectors with pixel values less the mimumum threshold, between the two thresholds and greater than the maximum threshold. The position of each threshold can be changed by use of the appropriate scrollbar (upper scroll bar for minimum threshold and lower scrollbar for maximum threshold). How these 3 sectors are displayed in the image depends on the setting in the "Color" window immediately below the scrollbars.

Color: There are 3 options in the color window: red, black-and-white, and over/under. The default is red. Change the color setting to "Over/Under". Pixels with grayscaled values less the minimum are blue, those with grayscale values greater than the maximum threshold are green and all pixels between the two thresholds are black. Use the scroll bars to investigate the relationship between the threshold settings and the distribution of colors in the image - paying particular attention to the distribution of black.

Change the color setting to red. The image now consists a sets of colors with red representing the pixels with grayscale values between the two thresholds. For an image with the same thresholds, red in this color pattern corresponds to black in the "over/under" mode.

In "black/white" mode, the area between the thresholds is represented as black and pixels below the minimum threshold AND above the maximum are white.

Take a few minutes and explore the effects of moving the scroll bars on the outline and of viewing the effects using the 3 different color modes.

Where is the outline of the valve wall? You will have noticed in your exploration of the threshold window that as you changed threshold maximima and minima that the breadth of the image sector corresponding to the between-threshold area changed. Somewhere in that area should be the outline you are after. We cannot provide specific instructions on how to secure that outline as it will depend on many factors of which we cannot be aware, e.g. the structure of the mantle wall of your diatom, the focus of your image on the mantle wall, etc.

As a first approximation to the outline we want to capture, let us assume in most diatoms that the darkest area of the image in the region of the wall will coincide with the mantle wall (outline), then we might try to only display only relatively "dark" pixels, those with brightness values toward the left end of the histogram. For use of the WandAuto (or Wand) tool we need the thresholded outline we use is (1) continuous, and (2) smooth on its exterior margin. When the contour of the outline is captured, we aim to capture the coordinates of the black pixels which form the outer border of its outline. What goes inside that border does not concern us in this process.

OUTLINE THE VALVE.

Use the WandAuto Tool to automatically trace the valve outline and record its coordinates..

The default Wand Tool in ImageJ's main menu can be used to capture the outline automatically, but it does not by itself record the coordinates of the outline anywhere without a set of additional commands. However, there is a tool in ImageJ which both captures the outline and writes the x,y-coordinates of the outline to the Results window. To load this tool for use:

From the main menu, choose Plugins | macros | Install. From the macros directory select the tools folder and open it. Finally select the file named WandAutoMeasure. and Open it. A small green wand icon will appear in the menu which accesses this WandAuto tool; it typically loads about 2 menu items to the right of the conventional Wand tool.

The WandAuto Tool begins its trace from its location on the screen where you first click after choosing the Tool. From the point of the click, the WandAuto Tool routine searches to the RIGHT looking for an edge (junction of black and white pixels) to follow. Because we want the trace to follow the exterior contour of the outline, we want to click within the black area of the valve outline, so the tool runs to the right across a few black pixels and stops when it hits a white one and then starts following that black-white border. If you click too far inside the valve in a white area, the tool will move across white pixels until it encounters a black one and then start its trace. This contour will be more likely something associated with the internal margin of the wall and other valve structures - not the one we want.

Upon completion of the trace of the outline, the pixel of all coordinates in that trace will be written to the Results window; there may be several thousand of them.

If the selection made by the WandAuto Tool does not get all (and more-or-less only) black pixels on the exterior outline of the valve, the trace is not acceptable and needs to be re-done. The outline will be highlighted in yellow (or red). To turn the AutoWand Tool's outlining off, that is, to deselect the outline, so that you can use it again on the same specimen, choose Edit | Selection | Select None.

The trace of the outline made by the Wand and WandAutoMeasure Tools in ImageJ captures the coordinates of the first point as also the last point, that is, the first point is duplicated in closing the trace. For EFA this last duplicated point is removed when the data file is processed by CartesianDiatom-EFA.

Capturing an outline which is satisfactory for EFA is often not a simple task. You will probably need to explore development of a scheme based on the above for your own specimens. ImageJ provides a vaiety of additional options.

SAVE DATA - the Orientation Landmarks and the Outline Coordinates

These data are all in the Results window at this stage.
Right Click on the Results Window and choose SAVE AS. In the Save as Text window provide a file name and ".txt" as the extension in the . The data will be saved as a simple text (ASCII) file. The only option available for saving the Results window from its menu is SAVE AS, so in subsequent saves of the same Results window, you will asked if you want to overwite/replace the previous version of the data file - respond Yes., as the entire contents of the Results window will be written to the data file each time it is saved. Do not clear the Results window between specimens, but let the data accumulate and periodically save it.

CartesianDiatom-EFA can import the data directly from this *.txt file. A sample data file produced using this WandAuto tool is provided; ijPclemOU.txt.

NEXT VALVE or EXIT?

Select the next valve to be analyzed (Return to Step 6), or, if your sesssion is done, make sure you have made the last save of your Results window.
CLOSE all ImageJ windows. Proceed to CartesianDiatom-EFA to import the data.

CUSTOM -

The custom option is designed for special importing routines CartesianDiatom has designed for specific users. Each requires a code to run and will be of no interest unless a protocol has been specifically designed for you.

Cut/Paste &/or Direct Entry

Enter data directly onto the OrigOutline worksheet conforming to its expected structure.

SAMPLE DATA FILES

The following sample data files have been included in the /testdata/ folder as part of the program download:

PclemLM.tps - tpsDIG2 generated; 3 outlines with Orientation Landmarks using the Landmark Tool
PclemLM_NoOL.tps - tpsDIG2 generated; 3 outlines without Orientation Landmarks using the Landmark Tool

PclemCU.tps - tpsDIG2 generated; 3 outlines with Orientation landmarks using the Curves Tool
PclemCU_NoOL.tps - tpsDIG2 generated; 3 outlines without Orientation Landmarks using the Curves Tool

PclemOU.tps - tpsDIG2 generated; 3 outlines with Orientation Landmarks using the Outline Tool
PclemOU_NoOL.tps - tpsDIG2 generated; 3 outlines without Orientation Landmarks using the Outline Tool

ijPclemC - ImageJ generated; 3 outlines with Orientation Landmarks using the Crosshair (= Point) Tool
ijPclemW - ImageJ generated; 3 outlines with Orientation Landmarks using the WandAutoMeasure Tool
The structure of ImageJ files with and without the 4 Orientation Landmarks is the same.