Main
ControlsThe CISMM Template-Based Matching program is designed to locate and identify objects within Scanned-Probe Microscope images and produce a file of descriptive statistics about these objects. To use it, you must have first installed the NSRG Runtime from the software download page. See the Word document describing this program for detailed information about the algorithms applied.
This program is distributed as "Thank-You Ware." As a National Research Resource, we are funded by the NIH National Institute of Biomedical Imaging and Bioengineering to develop tools for scientists. Part of our mission is to distribute these tools broadly to help biomedical researchers do their work.
Rather than making you register to download our software or join a mailing list or provide other personally-identifying material to use our code, we've come up with the following easy and anonymous way for you to let us know we're helping the community. When you press the "Say Thank You!" button to let us know you appreciate having the tool, the application sends a web query to our server and logs your response (not your name or your phone number, just a web hit count). We add up these counts and report them to the reviewers for our renewal applications when we ask NIBIB to continue funding us to maintain our existing tools and to build new ones. Please press the button whenever you feel like the tool has been helpful to you.
Main
ControlsThe control panel appears in the upper-left corner of the screen. If the program was started by pulling an image onto the desktop icon, a set of image windows will appear next to the control panel. If the program is started by clicking on one of the icons, a dialog box will appear asking for a data file to open. The data file can be an SPM file, or an image file such as TIFF or JPEG. Image files will lose the metric information, so that size and volume comparisons will only be relative. The image itself will appear in a window entitled Original Image immediately to the right of the control panel (an example is seen here to the right, it is the test_field.unca file that is found in the default directory). This window includes three red '+' signs that can be moved using the left mouse button. These marks should be moved to three places on the substrate of the scan.
There are two filters that can be applied to the data. Each is on by default. The substrate_fit filter attempts to remove the effects of tip-length artifacts and other changes that cause individual scanlines to change their height. It is similar to the "line-by-line flattening" operations performed by AFM software, but it does more than simply make the average of each line match that of the line before. Rather, it takes the median step from one line to the next after filtering each line to remove the effects of noise.
The median_filter applies only to the process of determining connected-component regions. It does not apply to the data used for fitting, or to the output image. It is present to reduce the effects of noise, especially for the case of noisy surfaces that are supposed to be flat. It is on by default.
Plane FitA plane is fit through the three points, and it is used as an estimate of the subtrate. This plane is subtracted from all data points, effectively shearing the data sets so that the plane of the substrate is at Z=0.
At this point, the flattened image is searched for "islands" that poke up above a "sea level" that is set using the height_threshold control. This control is set to the fraction of the maximum height that a pixel must have to stick above the "waterline". Objects that touch the edge of the image are discarded and drawn in a lighter blue color.
Before going any
further, you should load the templates (by repeatedly selecting the Add Template
button and selecting the templates one at a time. (Do it now because later steps
make this much slower). Each template will show up in a window that looks like
the one on the left. The particular template shown is the dimer_180.unca
template from the default directory. Load each template that you want to get
from a file before going on. You might create templates using the CISMM Microscope
Simulator program, which is available from the software
download page. If you want to select templates from the image itself, this
will have to be done later.
Dilation and
ThresholdingNext, select the desired settings for dilation and the Volume Thresholds. The dilation spreads out each object "island" by the specified number of pixels. This will recover volume from the islands that is below the waterline. If this spreading causes two islands to meet, or an island to meet the edge of the image, the merged islands will turn light blue and be removed from consideration. Some such blue islands are shown in the image to the right.
Adjust the Volume Threshold sliders to select islands only of the appropriate size. These are set to the fraction of the maximum-volume object that should be selected. Objects whose volumes are above the top threshold or below the lower threshold will turn red and are removed from further consideration. An example of such removed islands is shown to the right from an image that comes from Dorothy Erie's lab showing protein complexes. The objects that remain gray are the ones that will be matched against the templates.
If you want to use objects in the image itself as templates, first dilate the image enough that a good surround for each object is produced (5 pixels, perhaps). Then click on the object in the Flattened window that you want to make into a template. This will bring up a dialog box that lets you specify the name of the template file to save this object in, and it will also load it into the list of templates to be compared against. Parts of the image that are outside of the dilated object are set to zero, so they will match substrate best.
Once saved, these templates can be re-used on other images. Note that for microscope image formats, rescanning at different sizes will be properly compensated for: the template will retain its real-world size independent of the scan resolution or scan size. This will not be true for image file formats (TIFF, JPEG), which don't have metric information telling their pixel sizes.
The final settings are the angle and pixel step to take when attempting to match the templates to each object. The angle_step setting tells how much to rotate each template between attempts at matching. The pixel_step control tells how far to shift the templates when comparing them. The center of mass of the template is translated to match the center of mass of the object, so it is possible that a large setting will be acceptible, and it is much faster to use a large setting.
Once the above settings have been made, it is time to run the template match. This is done by pressing the Save button and selecting the name of the comma-separated-values (CSV) file that holds the information about the best matches. A progress window appears, showing how many templates have been tested against each object. When the object counter has counted up to its maximum, and all templates have been tested against it, the window will close and the CSV file will contain the matches (as described below). You can cancel the operation using the cancel button in the progress window (it will stop after the current template-vs-object test is complete).
Best-Fit WindowOnce optimization has completed, visual display of the best-fit objects is provided in a third image window that is initially located below the Flattened window. This window is named Best Fit, and it displays the best-fit template for each object, translated and rotated to its best-fit location based on the angle and pixel steps provided, and resampled into the same space as the original image. The image to the right shows the result when the example templates are used with 10-degree orientation testing on the image from Dorothy Erie's laboratory shown above.
If no templates are loaded, the components themselves will be splatted into this window. Note that they may not look exactly like they did in the original image because they will have been shifted to their center of mass and resampled.
If the show_labels checkbox is checked, the identifiers from the connected components will be drawn in the best-fit window. These will match the component ids stored in the file, and can be useful to provide a map of which component was where in the image.
The comma-separated-values (CSV) file written by the program is intended to be loaded into a spreadsheet program or another data-analysis program. It consists of a header line and then one line for each of the objects in the image. The header line contains the following text names: descriptions of each are included here, but are not included in the file.
If no templates have been loaded, only the center of mass and volume entries will be filled in.
| Object_ID | Index of the objects found, starting at zero. |
| X | X coordinate (in pixels) of the center of mass of the object, X=0 at left side of the image. |
| Y | Y coordinate (in pixels) of the center of mass of the object, Y=0 at the bottom of the image. |
| Volume | Volume of the object (in cubic nanometers for DI, UNCA, TopoMetrix files; in arbitrary units for TIFF and other image file formats). |
| Best_template | Name of the file from which the template which best matches (least error) this object was loaded. |
| Best_error | Sum of squared errors between the pixels in the template images and the corresponding locations in the object, at the angle specified below. |
| Best_angle | Angle at which the template was a best match for the object. |
| Second_best_template | Name of the file from which the object that had the second-best fit (second lowest error) was loaded. |
| Second_best_error | Sum of squared errors between the pixels in the template images and the corresponding locations in the object, at the angle specified below. |
| Second_best_angle | Angle at which the template was a best match for the object. |