Saturday, August 30, 2014

Getting started

This is the introductory step in the tutorial Collecting 3D shape data using StereoMorph

1. If you do not already have R installed on your computer, begin by installing R. R can be installed on Windows, Linux and Mac OS X.

2. Open R.

3. In R, go to Packages & Data > Package Installer.

4. Find the StereoMorph package binary by typing “StereoMorph” into the Package Search box and clicking Get List.

5. Check the box next to Install Dependencies. This ensures that all the packages that StereoMorph requires to run will be installed as well. Then click Install Selected to install StereoMorph.

6. Download and unzip the StereoMorph Tutorial folder from StereoMorph Tutorial files (~63 MB). This folder contains all the files needed to perform the steps in this tutorial.

StereoMorph Tutorial files
7. Change the working directory in R to the StereoMorph Tutorial folder so that we easily access the files in R. Go to Misc > Change Working Directory....

8. Locate and select the unzipped StereoMorph Tutorial folder and click Open.

9. Load the StereoMorph package into the current R session using the library command.

> library(StereoMorph)

For the rest of this tutorial, text in Courier preceded by a “>” in the style above will be used to indicate commands to be entered into the R console. All of the R commands executed in this tutorial can be found in the ‘Tutorial code.R’ file in the Tutorial folder.

You are now ready to run all of the steps in the tutorial!

Go to the first tutorial step: Creating a checkerboard pattern

Saturday, August 23, 2014

Arranging the Cameras

This is step 4 of 10 in the tutorial Collecting 3D shape data using StereoMorph

This section covers key aspects on how to arrange cameras in a stereo setup.

Materials needed for this section:
  • 2 cameras (preferably DSLR cameras with minimal distortion lenses)
  • 2 camera remotes
  • 2 sturdy tripods
  • Masking or colored tape

General considerations:

Whether you’re collecting landmarks or curves, the number of cameras you include, the lenses that you use and how you position the cameras depends on what you want to collect landmark and curve data from.

Here are some general principles:
  1. The views among the cameras must overlap. Since 3D reconstruction requires the pixel coordinates of a point in at least two cameras, the point must be visible in at least two camera views.
  2. Theoretically, there is a trade-off between the ease of digitizing and reconstruction accuracy. For instance, if the angle between two camera views in a stereo setup is 90 degrees,
    Two-camera stereo setup with the cameras at 90 degrees relative to one another.
    you will have high reconstruction accuracy (together, the two views give you full information on a point’s position along all three axes) however the views will be so divergent that it will be difficult to identify the same point in both views. A point visible in one view may not even be visible in the other. If the angle between two cameras is reduced to around 20 degrees
    Two-camera stereo setup with the cameras at about 20 degrees relative to one another. I've found this works great for landmarks but not well for curves.
    it’s much easier to find the same point in both views (the views are nearly the same), however these slight differences in position are now the only information available on the point’s position along the depth axis (orthogonal to the image planes). In practice, I’ve found that cameras positioned with a small angle relative to one another still provide high reconstruction accuracy for landmarks but don't work well for curves. It’s best to start with the cameras as close together as possible (more convergent views), test the accuracy and make the views more divergent if the accuracy is worse than what you’re willing to accept.
  3. The volume of space visible in both cameras should be large enough to contain the object(s) and landmarks or curves you’ll be digitizing. You might have to flip the object around a couple of times (to get the opposite side, for instance). If not all of the object is visible, you’ll have to digitize sections of the object separately and then assemble the point sets based on overlapping points, which requires more time digitizing.
  4. The cameras must not move for all of data collection and calibration. The cameras can be calibrated before or after data collection but throughout and between these steps the cameras must remain in the exact same position. Because the camera is often positioned half a meter or more away from the object, a sub-millimeter shift of the camera can translate into a large shift in the image frame, causing rather large inaccuracies.
  5. The focal length (zoom) and focus of the lens must not change for all of data collection and calibration. The calibration is specific to a particular focal length and focus; thus, the cameras will have to be re-calibrated if either of these changes.
Given all of these caveats, the best course of action is to try out several different camera setups and test the accuracy fully before collecting any data (testing the calibration accuracy is detailed in the “Testing the Calibration Accuracy” section). Although your own setup might differ from the camera setup used in this tutorial, it will at least provide an example of one possible setup and how to accommodate the considerations above.

For this tutorial, the cameras were arranged as shown below on the left, using a tabletop to position the calibration grid and objects being photographed. The tabletop can also be used to position lights around the object, if desired.

In this tutorial, all stereo camera images were taken with Nikon cameras, fitted with AF-S DX Nikkor 18-55 mm lenses at a focal length of 55 mm. At a focal length of 55 mm, distortion is nearly undetectable. It is essential that the lenses have minimal distortion. About 50 cm away from the tip of the lens, the checkerboard pattern almost nearly fills the image frame. This means that during the calibration step, we can fully sample the calibration volume with fewer calibration images.
A sample calibration image from one camera in a stereo camera setup.
If you position a tripod on a smooth surface, such as a table top, put small rubber squares under each tripod foot to keep the tripod from slipping.
A small piece of rubber under a tripod leg can keep it from slipping on a smooth surface.
1. Before calibrating or starting to collect data, attach small pieces of tape to a surface in the calibration space.

Add tape to a fixed surface in the camera view to both box the calibration space and test whether the cameras move during data collection or calibration.
This serves both to remind you where the calibrated volume is when positioning objects and it also to test whether the cameras have shifted during data collection.

2. Take photos of the tape frame before beginning and after having taken all of the photos. If the images are identical then the cameras have not shifted significantly.

3. Make sure that all connections/screws in the tripod and between the tripod and the camera are tight. This reduces the possibility of any motion of the cameras during data collection.
Ensure tight connections in the tripod and between the tripod and camera.
It’s best to use a remote (wireless or cord depending on the Nikon model) to release the shutter so you minimizing touching the shutter button on the cameras as much as possible.
Shutter remotes lessen the chances of the cameras moving during data collection.
I’ve found that pressing buttons on the camera lightly (such as for reviewing photos) doesn’t cause significant movement of the cameras but pressing the shutter button requires more force and doing it repeatedly causes the cameras to move significantly over a series of photographs.

4. If your lens has vibration reduction (VR) or automatic focus, be sure to turn both of these off. Vibration reduction uses a small gyroscope in the lens to compensate for camera motion and thus reduce blur. The spinning and stopping of the gyroscope can cause the image frame to shift randomly while taking photos.

Turn off auto-focus and vibration reduction, if applicable.
5. Set the cameras to the smallest aperture (this is the largest f value).
A smaller aperture is ideal because it increases depth of field. Without increasing the lighting, the exposure time will increase.
The smaller the aperture, the greater the depth of field (i.e. the more things are in focus both close and far away from the camera). This is essential in a stereo camera setup because in order to digitize points accurately throughout the calibration volume they must be in focus.

In the next step, we’ll photograph the checkerboard we made in step 1 in different positions and orientations within the stereo camera setup and use these images to calibrate the cameras.

Arranging cameras for curve reconstruction

Collecting curve data using a stereo camera setup requires an extra consideration when arranging the cameras. Landmarks digitized in two different camera views are reconstructed in StereoMorph under the assumption that the same point in 3D space is digitized in both views. In principle, curves can be reconstructed in the same way, by breaking the curve down into a series of landmarks.

There is one complication to this, however. A point halfway along the curve in one camera view is not necessarily the same point as a point halfway along the curve in another camera view. This is due to the perspective effect of lenses. The depth of a 3D curve in one view dictates how it is projected into that image plane. Since the depth of a curve will differ depending on the perspective from which it is viewed, the same curve will be projected differently into different views.

The same curve digitized in two different camera views. Although not immediately obvious, a point halfway along the curve in one view is not necessarily the same point in 3D space as a point halfway along the curve in another.

When the two cameras are calibrated, however, it’s possible to use the calibration to identify corresponding points on the same curve in two camera views and reconstruct these corresponding points just as with landmarks. This is done using epipolar geometry.

The basis of epipolar geometry is that any point in one camera view must fall along a line in another camera view. This line is the epipolar line. The intersection of the epipolar line and the curve in the second view can be used to find the corresponding point on the second curve.
Demonstration of epipolar geometry. The point, in camera view 1 (indicated by a yellow arrow), must fall along a line in camera view 2. This line is the point’s epipolar line and can be used to identify corresponding points along two curves.

But what if the epipolar line is parallel to the curve in the second view?
The epipolar line (yellow dashed line in right image) of the point in the first camera view (yellow point in left image) is parallel to the curve in the second view along a considerable portion of its extent. Absent other information, this makes it impossible to identify the corresponding point.
Without any additional information, this makes finding the corresponding curve point in the second view impossible. At some point, StereoMorph might include the ability to compare features along the curve in the image itself to find the corresponding point. It’s best to arrange the specimen or cameras so as to minimize the chance of large sections of the curve being parallel to an epipolar line. This can be done by making a mental note of the following steps:
  1. For the curve of interest, identify a 2D plane in which most of the curve lies. Of course the curve will have some three-dimensional aspect to it (or else you would not be using 3D reconstruction). But find a plane that encompasses most of the curve.
  2. Position the cameras so that a line extending out each lens to the curve is orthogonal to this plane.
As an example, let’s say we’re photographing a curve that resembles a circle (shown in the diagram below).
If we position the cameras so that they are viewing the curve, shown as a circle here, from the side (top left), the curve will appear in the two camera images as a nearly straight line (top middle and right). There is no way we could adequately measure the true shape of the curve because we’re hardly seeing any of it in the images. Additionally, the curve points in the second view will be nearly parallel to the epipolar line of the points in the first view. In fact, these two properties are geometrically related such that if the camera views chosen do not adequately capture the major three-dimensional aspects of the curve, epipolar geometry will also be unable to accurately find the corresponding curve points.

In contrast, if the cameras are positioned so they are viewing the curve from the top (bottom left), the major aspects of the curve’s shape are represented in the images and the curve in the second image will seldom be parallel to the epipolar lines of points along the curve in the first image. As a consequence, StereoMorph currently works best for reconstructing curves that do not have an excessively 3D shape (i.e. 3D spirals) because no matter how the cameras are positioned, these shapes will always have large portions that cannot be adequately captured in both camera views.

Digitizing Photographs

This is step 8 of 10 in the tutorial Collecting 3D shape data using StereoMorph

The StereoMorph package provides a new, easy-to-use digitizing application for collecting landmark and Bézier curves from photographs. Even if you don’t use StereoMorph for collecting 3D landmarks and curves, you might find the digitizing app useful for collecting 2D data from photographs. The app runs in a user's default web browser. Safari, Chrome and Opera all provide full compatibility with the app (Firefox does not allow some features of the app and the app is not tested for Internet Explorer). Although the app runs in a browser you do not have to be connected to the internet to use it. The app runs on a local server, with the R package R package shiny handling communication between the browser and R console. In this step, I’ll provide an overview of how to get started using the app.

StereoMorph Digitizing Application.
1. Load the StereoMorph library into the current R session, if not already loaded and ensure that the StereoMorph Tutorial folder is your current working directory (see Getting Started).

> library(StereoMorph)

2. Call the function digitizeImage() with input parameters specifying the image(s) to be digitized, where the landmarks and curves should be saved and the names of the landmarks and curves to be collected. Using the files in the StereoMorph Tutorial folder, the function call would look like this:

> digitizeImage(
   image.file = 'Object Images',
   landmarks.file = 'Landmarks 2D',
   control.points.file = 'Control points 2D',
   curve.points.file = 'Curve points 2D',
   landmarks.ref = 'landmarks_ref.txt',
   curves.ref = 'curves_ref.txt')

The first argument, image.file, is the only required argument. It specifies the file path of the image or images to be digitized. Here it’s a folder that contains all the object images in the tutorial folder. You can also input a vector of file paths if you only want to digitize a particular set of images. If you input several photographs into digitizeImage() you can switch from one photo to the next within the app.

The argument landmark.file is where the landmarks will be saved to (or loaded from if some landmarks have already been digitized). If you input a folder, the filenames of the landmark files will be saved with the same as the image names, only with the extension “.txt”. If you want different names for the landmark filenames, you can input the file names as a vector.

There are two curve file inputs. The control.points.file specifies where to save the control points. These are the points (the red points in the image below) that you can drag around to define and adjust the curve shape. The curve.points.file specifies where to save the points that actually make up the curve. These are the several hundred points at single pixel spacing (the blue points in the image below) that describe the actual curve and can be used in subsequent analyses.

A 3-point Bézier curve with control points in red and curve points in blue.
The landmarks to be digitized are input via landmarks.ref. In the example above, we’ve input a file path ( landmarks_ref.txt) with the landmarks listed as a single column, each separated by a new line.


landmarks.ref can also be a vector of landmark names, rather than a file path.

The curves to be digitized are also input as a file path (curves_ref.txt). In curves_ref.txt, the curves are in the form of a three-column matrix. The StereoMorph Digitizing App assumes that all curve start and end points are also landmarks. So the curves to be digitized are defined using a matrix where the first column is the name of the curve, the second column is the start point/landmark and the last column is the end point/landmark.

tomium_L     upperbeak_tip         upperbeak_tomium_prox_L
tomium_R     upperbeak_tip         upperbeak_tomium_prox_R
orbit_L      preorbital_proc_L     postorbital_proc_L

For instance, in the above curve reference matrix the first curve is tomium_L, which starts at the landmark upperbeak_tip and ends at the landmark upperbeak_tomium_prox_L. curve_ref can also be a matrix of reference curves, rather than a path to the file containing the matrix.

Once you call digitizeImage() the digitizing app will open in your default web browser, displaying the first image in the Object images folder.
StereoMorph Digitizing Application after loading first image.
The left two-thirds of the window are the image frame. This is where you can navigate around the image and add landmarks and curves using your mouse or trackpad. The right two-thirds is the control panel, with which you can view and save landmark/curve lists and navigate between different images.
StereoMorph Digitizing App control panel.
The ‘Info’ tab contains some basic information about the image, the ‘Landmarks’ tab contains the list of landmarks and the ‘Curves’ tab contains the list of curves.

3. You can navigate around the image in the image frame using the same basic mouse actions as in Google Maps. Position your cursor somewhere over the image and scroll just as you would scroll up and down a web page (using either the scroll wheel of a mouse or the scroll feature on a trackpad). This will zoom in and out of the image. To more quickly navigate around the image, the zoom tracks the position of your cursor and zooms in and out of particular region of the image based on the current position of your cursor. For instance if you wanted to zoom in to the bottom-left corner of the image, you would position your cursor in the bottom-left of the image and scroll in the appropriate direction. This will increase the size of the image while simultaneously positioning the bottom-left corner of the image into the center of the image frame.

Zoom into the object for precise landmark positioning.
4. Click and drag somewhere on the image. This will cause the image to move with your cursor. Just be sure that your cursor is not over a selected landmark or control point - this will cause the marker to move rather than the image.

5. Click on the ‘Landmarks’ tab in the control panel. This lists all of the landmarks input via landmarks.ref and their corresponding pixel coordinates.

6. To add, move or delete a landmark, you must first select that landmark. Click on the corresponding row in the landmarks table or, if the marker is already digitized, double-click on the landmark itself with the mouse (pressing the letter ‘x’ while the cursor is over the landmark in the image frame is a keyboard shortcut).

Selecting a landmark with the cursor. Once selected, the corresponding row will become bold.
7. Once the landmark is selected, set its location by double-clicking anywhere over the image (or positioning the cursor and pressing ‘x’). You can then move the landmark by clicking-and-dragging it or using the arrows on the keyboard.

Move a landmark by clicking-and-dragging with the mouse cursor.
8. To delete a landmark, just type ‘d’ once the landmark is selected. Landmarks with ‘-’ values in the landmarks table will be ignored when saving.

9. Click on the ‘Curves’ tab in the control panel to access the digitized Bézier curves. This lists all of the curves input via curves.ref and their corresponding pixel coordinates, including the starting and ending control points (both are also treated as landmarks) and all the control points in between that define the Bézier curve. The app treats curves with more than three control points as Bézier splines (a string of Bézier curves, joined at the ends).

The Curves tab lists the start, end and middle control points for every Bézier curve.
The control points can be added and moved in same way as the landmarks: by selecting the control point, double-clicking somewhere in the image frame and then clicking-and-dragging or using the arrow keys to reposition. Control points can also be deleted by pressing ‘d’ while the point is selected.

Bézier control points can be moved by clicking-and-dragging with the cursor or using the arrow keys.
10. Once you have collected landmarks or curves, press one of the three submit buttons in the control panel to save them. ‘Submit Landmarks’ only saves the landmarks and ‘Submit Curves’ only saves the curves (both control points and curve points). ‘Submit All’ saves both the landmarks and curves. This saves them to the location you specified in the input to digitizeImage().

Use the 'Submit' Buttons in the bottom of the control panel to save the landmarks and curves.
If a curve.points.file was included, R will also save a file with all of the curve points. They will look something like this,

pterygoid_crest_R0001 1140 1672
pterygoid_crest_R0002 1140 1671
pterygoid_crest_R0003 1140 1670
pterygoid_crest_R0004 1140 1669
pterygoid_crest_R0005 1140 1668

at single pixel spacing and with numbers added after the curve name to indicate the point order. These are the points we’ll use in the next step to reconstruct the curves into 3D.

11. Click ‘Next Image’. This will move to the next image if more than one image or a folder of images is specified in image.file.

Move to the previous or next image using the buttons at the bottom of the control panel.
Although, this tutorial uses the full features of the app, you can also use the app to digitize only landmarks or only curves. To only digitize landmarks, call digitizeImage() with only a landmark file and landmark reference list.

> digitizeImage(
   image.file = 'Object Images',
   landmarks.file = 'Landmarks 2D',
   landmarks.ref = 'landmarks_ref.txt')

You can also call digitizeImage() with just image.file if you’d simply like to check the pixel coordinates of a few features in a photograph.

> digitizeImage(image.file = 'Object Images')

For more detailed instructions on how to use the StereoMorph Digitizing App, check out the digitizeImage() function in the StereoMorph package manual or click on the ‘Help’ link at the top right corner of the application window. The help file will open in a new browser window and has information on all the features available in the digitizing app, including keyboard shortcuts.

Opening the digitizing app help file.
The next step will cover how to reconstruct the digitized landmarks and curve points in 3D.

Go back to the previous step: Photographing an object