Mass Properties Estimation Protocol
From the 2013 paper in Nature entitled “Linking the evolution of body shape and
locomotor biomechanics in bird-line archosaurs”
By Vivian Allen, Karl T. Bates, Zhiheng Li and John R. Hutchinson
Understanding Our Mass Models
The following is a brief guide to interpreting what .obj files and settings we used in our different
iterations of mass properties (mass and CoM) models for each taxon. Our description and method
presumes some familiarity with the Matlab (The Mathworks, Inc.; Natick, MA, USA) programming
environment, 3D computer graphics and coordinate systems, and geometry/mechanics (e.g. centre
of mass).
The reconstructed body volumes that we used to estimate mass properties for each taxon are stored
as .obj files (in a separate folder for each taxon) in the folder ' Mass Segment objs'. The excel file
'Mass_Systems_Controller_Birdline.xlsx' (in the 'CoM Calculation Code' folder) details how these
body volume .obj's were combined into the various iterations we made of each taxon. In the excel
file, every line represents a single model iteration. The first column indicates the type of model
(whole-body or individual segment - tail, neck etc). The second column indicates the taxon. The third
column indicates the iteration (e.g. 'Best Guess', 'Max Mass', 'Max Cranial', etc). The fourth to last
columns show the .obj files that were used to make up that iteration of that model, with the prefix
'MASS_' indicating that the .obj file was a solid, positive mass object, and the prefix 'CAV_' indicating
that it was a cavity, or negative mass object (e.g. buccal cavity, lungs etc).
All of our mass properties estimations were calculated assuming a density of 1000 kg·m-3 for solid
body parts, and a density of 0 kg·m-3 for body cavities.
Explanation of Code and Acknowledgement of Third Parties
Our mass properties estimation code works on the principle of filling any arbitrary shape with small
cuboid elements. The mass properties of a cuboid (mass, CoM and inertia) are simple and can be
calculated easily from the dimensions of the cuboid. Values for these cuboid elements can then be
summed to estimate mass properties for the shape as a whole. The cuboid filling procedure consists
of making slices along the longest axis of the shape, determining how many cuboid elements of what
size will fit within the interior of the slice, and then filling it. The fidelity of the filled cuboid mass vs.
the original shape is determined by the value 'noSlices' in the functions 'get_body_mass_props.m'
and 'get_system_mass_props.m'. This value, usually set to 100, determines the number of sampling
slices that will be made along the longest axis of the input shape, and also relates to the number of
cuboids that each slice will be potentially broken into (cuboids per slice = noSlices2). A higher value
for 'noSlices' results in a potentially higher fidelity mass estimate, but also an exponentially longer
run-time. We have determined 100 slices to give equivalent results to other mass properties
estimation software, and yet not take an unreasonably amount of time to run, and so this is the
value we recommend you to use.
Currently, our code only accepts .obj files as input, and has been mainly tested with .obj output from
the following CAD packages: 3DSmax, Blender, Meshlab and Geomagic.
Our mass properties code incorporates the following publically available code:
'read_vertices_and_faces_from_obj_file(filename)' by Alex Jacobson
(http://www.alecjacobson.com/weblog/?p=917)
'FindEdgeIntersectsIndex.m' by Bruno Luong
(http://www.mathworks.co.uk/matlabcentral/fileexchange/27673-2d-polygon-edges-intersection)
' inpoly.m' by Darren Engwirda
Produced as part of undergraduate thesis:
D. Engwirda, Unstructured Mesh Methods for the Navier-Stokes Equations. Undergraduate thesis,
School of Aerospace, Mechanical and Mechatronic Engineering, Univ. of Sydney, 2005.
(http://www.mathworks.co.uk/matlabcentral/fileexchange/10391-fast-points-in-polygon-test)
'allcomb.m' by Jos van der Geest
(http://www.mathworks.co.uk/matlabcentral/fileexchange/10064)
Procedure: Individual bodies (single .obj file)
- 1: Open Matlab
- 2: Copy all .m files (Matlab functions and scripts) from the folder 'CoM Calculation Code' into
current Matlab working folder
- 3: Copy .obj file of interest into current Matlab working folder
- 4: To get mass, CoM and inertial tensor estimates for .obj file of interest, use the function
'get_body_mass_props.m'. Detailed information is contained in the headers and comments for the
function itself, which can be opened by double-clicking. To run the function with the same
parameters used in our study, type:
[mass, com, MOI_origin, MOI_com] = get_body_mass_props('name', 1000,100,1)
where name = the name of the .obj file (including extension - NB THIS MUST HAVE ' ' AROUND IT, SO
'NAME'), 1000 = the density you think the object has, in kg·m-3, 100 = the number of long-axis slices
to be used (a measure of fidelity), and 1 = the units the .obj file has (1 is meters, 0.01 is centimetres
etc). For further explanation see comments within the function itself.
EXAMPLE: Copy all .m files into the working folder, then open the 'Allosaurus' folder in the 'Mass
Segment Objs' folder and copy 'AL_2_1_head.obj' into the working folder. Type in the following:
[mass, com, MOI_origin, MOI_com] = get_body_mass_props('AL_2_1_head.obj', 1000,100,1)
The estimated mass properties will appear in the reader window and as data objects in the
workspace. Units are kg, m and kg·m2 for mass, centre of mass and moments of inertia respectively.
Procedure: Individual mass system (many .obj files, optionally including cavities)
- 1: Open Matlab
- 2: Copy all .m files (Matlab functions and scripts) from the folder 'CoM Calculation Code' into
current Matlab working folder
- 3: Copy all .obj files that make up the system of interest into current Matlab working folder. To run
the example below (EXAMPLE), copy all .obj files from the 'Allosaurus' folder in the 'Mass Segment
objs' folder into the working folder.
- 4: Generate a cell array of strings (words) listing the .obj files that will make up the positive mass
objects of the system (i.e. the non-cavities). You can do this by typing the following (EXAMPLE):
positive_objs = { 'AL_2_1_head.obj' 'AL_2_1_max_neck.obj ' 'AL_2_1_max_body.obj '}
- 5: Generate a cell array of strings (words) listing the .obj files that will make up the NEGATIVE mass
objects of the system (i.e. the cavities). You can do this by typing the following (EXAMPLE):
negative_objs = { 'AL_2_1_nas.obj ' 'AL_2_1_buc.obj ' 'AL_2_1_min_Bird_lung.obj '}
- 6: To get mass, CoM and inertial tensor estimates for .obj file of interest, use the function
'get_system_mass_props.m'. Detailed information is contained in the headers and comments for the
function itself, which can be opened by double-clicking. To run function with the same parameters
used in our study, type:
[mass, com, MOI_origin, MOI_com] = get_system_mass_props(positive_objs, negative_objs,
1000,100,1)
where 1000 = the density you think the object has, 100 = the number of long-axis slices to be used (a
measure of fidelity), and 1 = the units the .obj file has (1 is meters, 0.01 is centimetres etc). For
further explanation see comments within the function itself. The estimated mass properties for the
system (EXAMPLE = maximum mass head-and-neck for Allosaurus fragilis) will appear in the reader
window and as data objects in the workspace. Units are kg, m and kg·m2 for mass, centre of mass
and moments of inertia respectively.
Procedure: Many mass systems (all taxa, all .obj files)
- 1: Open Matlab
- 2: Copy all .m files (Matlab functions and scripts) and all excel files from the folder 'CoM Calculation
Code' into current Matlab working folder
- 3: Copy all .obj files that make up the systems of interest into the current Matlab working folder. To
use the example below, copy ALL .objs from ALL folders contained in the 'Mass Segment objs' folder
into the working folder.
- 4: Open Excel.
- 5: Create Excel 'controller' file (MUST BE XLSX FORMAT). This is a single worksheet that will tell the
Matlab script how to group the .obj files into systems. Each line of the worksheet represents a mass
system, which will classified in the following way:
- 1st column = Primary Classifications, e.g. body, tail etc
- 2nd column = Secondary Classification, e.g. taxon name
- 3rd column = Tertiary Classification, e.g. model iteration - max mass, min mass etc
- 4th column to end = .obj files to be used as mass objects, prefix 'MASS_' indicates a positive
mass object, prefix 'CAV_' indicates a negative mass object (e.g. a cavity).
- 6: (OPTIONAL) Create Excel 'order' file (MUST BE XLSX FORMAT). If you require the output of taxon
names (or other secondary classifications) to be in a specific order, put the names, in the required
order, in the first column.
- 7: (OPTIONAL) Create Excel 'normalisers' file (MUST BE XLSX FORMAT). If you require the output
data to be normalised, e.g. to body mass, place all of the taxon names (or other secondary
classification) in the first column with a corresponding value for normalisation in the second column.
- 8: Open 'Batch_Process_Mass_Systems.m' and read the headers for detailed instructions. Fill in the
'USER INPUT' part of the script, near to the top, with the name of your 'controller' .xlsx file, and if
required, the names of your 'normaliser' and 'order' .xlsx files (NB without the .xlsx extension). IF YOU
ARE NOT ORDERING OR NORMALISING: ensure that the option for 'order_out' is set to '0', and the
option for 'normalise' is also set to '0'. IF YOU ARE NORMALISING: check that the 'normaliser_type'
option is set appropriately - this controls how your normaliser will be adjusted for different types of
data, e.g. lengths will be cubed to normalise mass data, etc.
- 9: Run script (click on the green play icon). This takes a while. You might like to get a hot drink. The
script will eventually output a excel file containing all mass properties data - see comments on script
for details of output structure.
EXAMPLE: Copy all .obj folders from ALL folders in the 'Mass Segment Objs', and all .m files (Matlab
functions and scripts) and all excel files from the folder 'CoM Calculation Code' into current Matlab
working folder. Open 'Batch_Process_Mass_Systems.m' and scroll down to 'USER INPUTS'. Set the
following options:
controller_name = 'Mass_Systems_Controller_BirdLine';
order_out = 1;
ouput_order_name = 'Taxa_Order';
output_name = 'Bird_Line_CoMs';
density = 1000;
normalise = 1;
normalisers_name = 'Normalisers';
normaliser_type = 3;
Run the script (click on the green play icon). This controller will output an Excel file called
'Bird_Line_CoMs' containing mass and CoM data from all iterations of our mass models, in both raw
form and normalised to body mass.