8.4 Reading shape data

The reconstructed landmarks and curve points are saved into the 3D shapes folder. StereoMorph saves these files in a special xml-format that can be read using the StereoMorph function readShapes(). If you'd like to try using readShapes() with an example dataset 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. Input a single file to readShapes to read all the shape data from that file.

# Read 3D landmarks and curves from a particular file (object)
shapes <- readShapes(file='Shapes 3D/bubo_virginianus_FMNH488595.txt')

This reads all of the shape data from bubo_virginianus_FMNH488595.txt into the list structure "shapes" used by StereoMorph to organize different types of shape data. This structure has a custom print format that tells you all of the shapes in the list:

# Print the contents of shapes
shapes

The two shapes within "shapes" are landmarks and curves. The landmarks are in a 34 x 3 matrix, where the rows correspond to the landmarks and the columns to the 3D reconstructed coordinates. To access the landmarks matrix, use the '$' operator (as you would use to access any list element):

# Print the landmarks
shapes$landmarks

You can then access any of the landmarks by using the standard matrix notation in R:

# Print the xyz-coordinates of the cranium_occipital landmark
shapes$landmarks['cranium_occipital', ]

The curve points require one extra step. Each curve can have a different number of points, so each is saved within a separate list, accessible by the curve name. To get a list of the curve names, use the '$' operator with 'curves' and the names() function:

# Print the curve names
names(shapes$curves)

These are the 4 curves that have 3D coordinates. Use the '$' operator to return a particular curve, which yields a n x 3 matrix, where n is the number of points in the curve (specified previously through even.spacing).

# Print the upper_bill_tomium_L curve points 
shapes$curves$upper_bill_tomium_L

2. By inputting multiple filenames into readShapes(), you can read all the shape data from those files at once to create a landmark array or larger list structures of curves. Specify two files to be read by readShapes():

# Specify multiple shape files
file <- c('Shapes 3D/bubo_virginianus_FMNH488595.txt', 
   'Shapes 3D/psittacus_erithacus_FMNH312899_a1.txt')

# Read shape files
shapes <- readShapes(file=file)

Shapes is still a list, but now the landmarks are an array of dimensions n x m x k, where n is the number of landmarks, m is the number of dimensions, and k is the number of files. Also, the curves have gained an additional level. The first level are the files that have been read, then each curve.

# Print the contents of shapes
shapes

Like before, the '$' operator can be used to access the landmarks, accessing, for example, a particular landmark across all of the files,

# Print the xyz-coordinates of cranium_occipital across the files
shapes$landmarks['cranium_occipital', , ]

or accessing all the landmarks for a particular file.

# Print all the landmarks for bubo_virginianus_FMNH488595
shapes$landmarks[, , 'bubo_virginianus_FMNH488595']

3. In addition to inputting a vector of files for readShapes(), you can also input a folder containing shape files. In that case readShapes() will read in all of the shape files in that folder:

# Read all shape files in folder Shapes 3D
shapes <- readShapes(file='Shapes 3D')