8.3 Reconstructing landmarks and curves

If you've digitized both landmarks and curves you can use reconstructStereoSets() to reconstruct both at the same time. If you'd like to try this with an example you can download this stereo landmark and curve set (10 KB), previously used in the digitizing photographs section. Unzip the folder's contents into your current R working directory.

1. Call reconstructStereoSets().

# Reconstruct landmarks and curves
reconstructStereoSets(shapes.2d='Shapes 2D', shapes.3d='Shapes 3D', 
   cal.file='calibration.txt', even.spacing='even_spacing.txt')

For curves, the function needs an additional parameter, even.spacing that specifies how many points will be reconstructed along each curve. This can be a '.txt' file listing how many curve points you'd like each reconstructed curve to have. On each line of the '.txt' file, list the curve name and the number of points (see this example file). You can also make even.spacing a single integer if you want each curve to have the same number of points.

If you've photographed the same object in different orientations (if you have multiple aspects) the landmarks and curves in each aspect will be in different coordinate systems. These can be aligned with one another based on shared landmarks between sets into a single set, which is referred to here as "unification". By default, the reconstructStereoSets() function performs both reconstruction and unification as long as aspect labels have been added to all of the image names (e.g. "_a1", "_a2", etc.).

If the input parameter print.progress is TRUE (the default), the function prints each of the steps along with the associated errors. If you try this with the example stereo shape set, you'll see that one of the objects (bubo_virginianus_FMNH488595) has three different aspects. Landmark reconstruction is performed for each of these three aspects. Plus, the first aspect has 4 curves which are also reconstructed. Your mean landmark reconstruction errors should be near or less than 1 pixel. The curve reconstruction errors can range from 1-10 pixels. Then all three aspects are unified. Since there are three aspects, there are two separate unifications: two aspects are unified, then the third is unified with this unified set. The two errors after "Unification RMS Error" are the errors for each of these unifications in the same units as the calibration (here, mm).

The second specimen (psittacus_erithacus_FMNH312899) in the example stereo set has landmarks digitized in two aspects but I deliberately chose landmarks such that there is only 1 common landmark between the two sets. For this reason the function reports that there are not enough common points for unification. In this case, the function will save each aspect as a separate 3D set (retaining the "_a#"). To unify 3D sets you theoretically need at least 3, non-colinear points in common between the sets. However, in practice more common points are required (at least 5-6) to get a good alignment between the two sets.

2. There are several optional input parameters to reconstructStereoSets() that can be helpful. For instance, if you only want to reconstruct/unify one or more particular specimens, you can specify these as a vector using the input parameter set.names.

# Only run for particular file(s) using set.names
reconstructStereoSets(shapes.2d='Shapes 2D', shapes.3d='Shapes 3D', 
   cal.file='calibration.txt', even.spacing='even_spacing.txt',
   set.names=c('psittacus_erithacus_FMNH312899'))

3. If you want to run the function only for specimens where the 2D shape files have changed, you can set update.only to TRUE (default is FALSE).

# Only run on modified files using update.only
reconstructStereoSets(shapes.2d='Shapes 2D', shapes.3d='Shapes 3D', 
   cal.file='calibration.txt', even.spacing='even_spacing.txt', update.only=TRUE)

This saves time in running the function so that as you are digitizing specimens you can run reconstructStereoSets() only for those files that actually need to be updated.

4. If you want the function to print more details as it runs, you can set the input parameter verbose to TRUE (default is FALSE). For instance, this will print the reconstruction error for each of the landmarks. This is helpful for identifying incorrectly digitized markers.

# Print more error details using verbose
reconstructStereoSets(shapes.2d='Shapes 2D', shapes.3d='Shapes 3D', 
   cal.file='calibration.txt', even.spacing='even_spacing.txt', verbose=TRUE)

Here are some additional input parameters that might be helpful:

• reconstruct.curves: (default TRUE) Make FALSE to only reconstruct landmarks.
• unify: (default TRUE) Make FALSE to reconstruct all aspects as separate sets (no unification).
• min.common: (default 3) This is the minimum number of common points between sets that are required for unification. It is helpful to set this higher than 3 (e.g. 5) so that you can easily identify when you need more common points between different aspects.