# doc-cache created by Octave 10.1.0
# name: cache
# type: cell
# rows: 3
# columns: 16
# name: <cell-element>
# type: sq_string
# elements: 1
# length: 8
LongBone


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 91
 -- Class: LongBone

     Class for manipulating 3-D triangular meshes of human long bones.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 65
Class for manipulating 3-D triangular meshes of human long bones.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 11
inspect_CSG


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 3854
 -- csg-toolkit: inspect_CSG
 -- csg-toolkit: inspect_CSG ("default")
 -- csg-toolkit: inspect_CSG ("custom")
 -- csg-toolkit: inspect_CSG ("fragment")
 -- csg-toolkit: inspect_CSG (..., FILENAME)
 -- csg-toolkit: inspect_CSG (FILENAME)

     Batch inspect the CSG properties of previously analyzed long bones.

     ‘inspect_CSG’ reads all available $geometry-$$.csv files in the
     working folder, utilizes ‘visualize_CrossSections’ to retrieve the
     data in the corresponding CSV files for each associated 3D model
     and plot the cross sectional contours, and upon user confirmation,
     it aggregates the CSG properties in a tabular format and save it
     under FILENAME.  If FILENAME is not provided, "CSG Data.csv" is
     used by default.

     The rationale behind the visual inspection of the cross sectional
     contours is to avoid any erroneous values due to badly shaped long
     bone models that might be processed succesfully by the respective
     Geometry function.  For any given sample, if the contours of are
     shown as a simple polygon, then the computed CSG properties can be
     safely assumed as accurate and the user can confirm by pressing the
     "yes" button in order to append the CSG properties into tabular
     form.  If not, press "no" to ignore the particular sample and
     proceed the inspection to the next available sample.  If the user
     cancels, the process is terminated and the already appended values
     are saved in the CSV file.

     Prior to batch processing, the user is prompted for the folder
     containing the 3D models of the associated bones and, if available,
     ‘inspect_CSG’ measures their maximum length (max Distance) and
     includes it in the aggregated results, otherwise it adds NaN, as a
     missing value in the stored CSV file.

     By default, ‘inspect_CSG’ processes the available Dgeometry-,
     Dinertia-, Dpolyline2D-, and Dpolyline3D- CSV files generated with
     the ‘longbone_Geometry’ function.  This is identical to calling
     ‘inspect_CSG’ with the optional argument "default".  In this batch
     prossecing mode, 5 plots are rendered, one for each cross section
     at 20%, 35%, 50%, 65%, and 80%, respectively.

     ‘inspect_CSG ("custom")’ will process all available Cgeometry-,
     Cinertia-, Cpolyline2D-, and Cpolyline3D- CSV files generated with
     the ‘longbone_CustomGeometry’ function.  In this batch prossecing
     mode, an arbitrary number of plots is rendered, one for each
     associated cross section according to the contents of the
     respective CSV files.  Note that all files included in the same
     batch MUST contain the same number of cross sections.  However, it
     is not mandatory that they conform to the same points along the
     diaphysis.  This is especially important for 3D modes analyzed with
     custom PP point files, where the ratio used for indexing each cross
     section might vary between samples.  The ratio IDs used in the
     resulting "CSG Data.csv" are taken from the ultimate processed
     sample.  Also note that the first and last plots always refer to
     the cross sections at 20% and 80%, respectively.

     ‘inspect_CSG ("fragment")’ will process all available Fgeometry-,
     Finertia-, Fpolyline2D-, and Fpolyline3D- CSV files generated with
     the ‘longbone_FragmentGeometry’ function.  In this batch prossecing
     mode, an arbitrary number of plots is rendered, one for each
     associated cross section according to the contents of the
     respective CSV files.  Note that all files included in the same
     batch MUST contain the same number of cross sections.  However, it
     is not mandatory that they conform to the same points along the
     diaphysis.

     See also: visualize_CrossSections, longbone_Analysis.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 67
Batch inspect the CSG properties of previously analyzed long bones.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 17
longbone_Analysis


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 3634
 -- csg-toolkit: longbone_Analysis
 -- csg-toolkit: longbone_Analysis ("custom")
 -- csg-toolkit: longbone_Analysis (POINTS)
 -- csg-toolkit: longbone_Analysis ("fragment")

     A wrapper for batch processing with longbone_*Geometry functions.

     ‘longbone_Analysis’ reads the available 3D models stored in
     Wavefront OBJ file format present in some folder and calls the
     ‘longbone_Geometry’ function to analyze their geometric properties
     in a serial manner.  The user is prompted for the directory to read
     from and subsequently the type of bones that should be analyzed.
     All available 3D bone models are evaluated but only those that
     explicitly match the user selection are fully processed and their
     corresponding geometric properties stored in the corresponding CSV
     files in the current working directory.  The generated CSV files
     follow the naming conventions used by the ‘longbone_Geometry’
     function.

     ‘longbone_Analysis ("custom")’ will accordingly utilize the
     ‘longbone_CustomGeometry’ function and, besides the folder
     containing the 3D models and the user selected types of bones for
     processing, it will also pass the respective Meshlab PickedPoints
     filename with the custom sectioning points.  These files must
     reside in the same folder with the 3D models and their base
     filename must be appended with "-custom" with respect to the OBJ
     filename.  For example, assuming a 3D model named "bone_ID.obj",
     the corresponding custom sectioning points file must be named
     "bone_ID-custom.pp".

     ‘longbone_Analysis (POINTS)’ will optionally utilize the
     ‘longbone_CustomGeometry’ by parsing a preset numerical vector for
     custom sectioning points as ratios along the long bone’s maximum
     distance.  Similarly to using the "custom" optional argument, the
     generated CSV files will follow the naming conventions used by the
     ‘longbone_CustomGeometry’ function.

     ‘longbone_Analysis ("fragment")’ will utilize the
     ‘longbone_FragmentGeometry’ function, which only requires the
     folder containing the 3D models, but ignores their bone type since
     it is not required for the relevant CSG computations.  The user is
     only prompted for this folder, which must also contain the
     corresponding Meshlab PickedPoints files whose base filename must
     be appended with "-fragment" with respect to the OBJ filename.  For
     example, assuming a 3D model named "bone_ID.obj", the corresponding
     custom sectioning points file must be named "bone_ID-fragment.pp".

     Under all batch processing schemes except for the "fragment"
     option, the initial alignment points for each 3D model are either
     read from the corresponding Meshlab PickedPoints file (e.g.
     "bone_ID.pp"), if present in the same folder with the OBJ file, or
     they are automatically registered with the ‘longbone_Registration’
     function.  In either case, the opitimized alignment points are
     saved in the corresponding Meshlab PickedPoints file with the same
     base filename.  For example, assuming a 3D model named
     "bone_ID.obj", the corresponding initial alignment points file must
     be named "bone_ID.pp".  Note that existing files will be
     overwritten, hence apart from the required initial alignment
     points, other points will be lost.  Type ‘help longbone_Geometry’
     for more information about initial alignment points.

     See also: inspect_CSG, longbone_CustomGeometry,
     longbone_FragmentGeometry, longbone_Geometry.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 65
A wrapper for batch processing with longbone_*Geometry functions.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 26
longbone_AnatomicalNormals


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 372
 -- csg-toolkit: [TRANSVERSE, CORONAL] = longbone_AnatomicalNormals (V,
          F)

     Compute the normals of the transverse and coronal planes.

     This function returns the normals of the transverse and coronal
     anatomical planes of a longbone mesh defined by its vertices V and
     faces F.

     See also: longbone_AnatomicalPosition, longbone_Registration.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 57
Compute the normals of the transverse and coronal planes.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 27
longbone_AnatomicalPosition


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 755
 -- csg-toolkit: V_ROT = longbone_AnatomicalPosition (V, F)
 -- csg-toolkit: [V_ROT, VN_ROT] = longbone_AnatomicalPosition (V, F,
          VN)

     Rotate into anatomical posistion.

     This function automatically identifies the longbone defined by its
     vertices, V, and faces, F, rotates it into anatomical position and
     it translates its barycenter into the origin of the Cartesian
     coordinate axes, i.e.  [0, 0, 0].  The transformed
     (rotated/translated) vertices are returned in V_ROT.

     The function can also take a third input argument, VN, defining the
     normals of the 3D mesh, which is rotated accordingly and returned
     as the second output argument VN_ROT.

     See also: longbone_Geometry, meshRotation, readObj.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 33
Rotate into anatomical posistion.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 23
longbone_CustomGeometry


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 7176
 -- csg-toolkit: longbone_CustomGeometry (FILENAME, POINTS)
 -- csg-toolkit: longbone_CustomGeometry (FILENAME, BONES, POINTS)
 -- csg-toolkit: longbone_CustomGeometry (FOLDER, FILENAME, POINTS)
 -- csg-toolkit: longbone_CustomGeometry (FOLDER, FILENAME, BONES,
          POINTS)

     This function analyzes the cross-sectional geometry of an intact
     humerus, ulna, femur, or tibia bone along its longitudinal axis at
     custom intervals.

     ‘longbone_CustomGeometry (FILENAME, POINTS)’ will analyze the 3D
     model in FILENAME, which must be a char string, at custom intervals
     defined inPOINTS.  POINTS can be either a char string or a
     numerical vector.  The string must specify a Meshlab PickedPoints
     file containing an arbitrary number of points on the bone’s
     surface, each one of which specify a cross-sectional plane along
     the bones longitudinal axis.  Alternatively, the numerical vector
     specifies an arbitrary number of cross-sectional planes as the
     ratios of the sectioning points’ distance from the proximal end to
     the bone’s maximum length in the range [0.1, 0.9].  Values beyond
     this range are ignored.

     FOLDER, which must be a char string, defines the relative or
     absolute path to the directory containing the 3D model in FILENAME.
     When omitted, the current working directory is assumed.

     BONES must be cell array of strings specifying one or more long
     bones that should be analyzed.  ‘longbone_CustomGeometry’ will
     automatically determine what bone is represented in the 3D model,
     but it will analyze it only if it matches one of the bones named in
     BONES.  Valid options are:

        • "Humerus"
        • "Ulna"
        • "Femur"
        • "Tibia"
        • "All"

     ‘longbone_CustomGeometry’ does not return any output arguments, but
     it saves all geometric properties in CSV files as described in the
     following section.  3D models must be pure triangular meshes and
     their coordinate units are assumed to be in mm.  Each OBJ file must
     explicitly contain a single 3D model of any long bone fragment.

     Assuming a 3D model named "bone_ID.obj", the following files are
     generated:

     Filename                   Description
     ---------------------------------------------------------------------------
     Cgeometry-bone_ID.csv      It contains the properties of area (measured
                                in mm^2), perimeter (measured in mm),
                                centroid (returned as [X,Y,Z] coordinates in
                                mm units), as well as the sectioning and
                                orientation normals (returned as an [X,Y,Z]
                                vectors).  Each row of the CSV file
                                corresponds to a different cross section.
                                The first and last rows contain the default
                                cross sections at 20% and 80% respectively.
                                The intermediate rows follow the order of the
                                sectioning points in the Meshlab PickedPoints
                                file or in the numerical vector parsed in
                                POINTS.  The aforementioned properties for
                                each cross section are stored as a row vector
                                with the respective order in columns
                                [[2],[3],[4:6],[7:9],[10:12]].  The first
                                column contains the ratios of the sectioning
                                points’ distance from the proximal end to the
                                bone’s maximum length.
                                
     Cinertia-bone_ID.csv       It contains the properties of Ix, Iy Ixy,
                                Imin, and Imax, all measured in mm^4, as well
                                as theta, measured in degrees.  Accordingly,
                                they are saved as row vectors [2:7] with the
                                first column containing the ratios of the
                                sectioning points’ distance from the proximal
                                end to the bone’s maximum length.
                                
     Cpolyline2D-bone_ID.csv    It contains the 2D coordinates (on an
                                arbitrary X,Y local axis) for each cross
                                section as an Nx2 matrix, where N is the
                                number of points for each cross-sectional
                                polygon.  These polygons are ordered as
                                column duplets, i.e.
                                [[1:2],...,[end-1:end]].  The first and the
                                last column duplets contain the default cross
                                sections at 20% and 80%, respectively.  The
                                intermediate column duplets follow the order
                                of the sectioning points in the Meshlab
                                PickedPoints file or in the numerical vector
                                parsed in POINTS.  Polygon coordinates start
                                from the second row ([2:end],:), while the
                                first row contains the relevant ratios at
                                columns (1, [1,3,...,end-1]).
                                
     Cpolyline3D-bone_ID.csv    It contains the 3D model coordinates for each
                                cross section as an Nx3 matrix, where N is
                                the number of points for each cross-sectional
                                polygon.  These polygons are ordered as
                                column triplets, i.e.
                                [[1:3],...,[end-2:end]].  The first and the
                                last column triplets contain the default
                                cross sections at 20% and 80%, respectively.
                                The intermediate column triplets follow the
                                order of the sectioning points in the Meshlab
                                PickedPoints file or in the numerical vector
                                parsed in POINTS.  Polygon coordinates start
                                from the second row ([2:end],:), while the
                                first row contains the relevant ratios at
                                columns (1, [1,3,...,end-1]).

     For any analyzed 3D model, the initial alignment points are either
     read from the corresponding Meshlab PickedPoints file (e.g.
     ’bone_ID.pp’), if present in the same folder with the OBJ, or they
     are automatically registered with the ‘longbone_Registration’
     function.  The optimized alignment points are appended in the
     existing MPP file or saved in newly created, accordingly.

     See also: longbone_Geometry, longbone_FragmentGeometry,
     visualize_CrossSections.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80
This function analyzes the cross-sectional geometry of an intact
humerus, uln...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 25
longbone_FragmentGeometry


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 4928
 -- csg-toolkit: longbone_FragmentGeometry (FILENAME, POINTS)
 -- csg-toolkit: longbone_FragmentGeometry (FOLDER, FILENAME, POINTS)

     This function analyzes the cross-sectional geometry of any
     diaphyseal long bone fragment at custom intervals defined by user
     defined points on the bone’s surface.

     The fragment must be saved in Wavefront OBJ 3D model format,
     specified in FILENAME, and the user defined points saved in a
     Meshlab PickedPoints file format, specified in POINTS.  Optionally,
     the folder containing the 3D model can be defined in FOLDER, if the
     function is invoked from a different working directory.  All thre
     input arguments must be strings.

     ‘longbone_FragmentGeometry’ will process an arbitrary number of
     cross sections, according to the user defined points, as specified
     in POINTS, as long as they lie between 10% and 90% of the
     fragment’s maximum length.  Points beyond this range are ignored.

     ‘longbone_FragmentGeometry’ does not return any output arguments,
     but it saves all geometric properties in CSV files as described in
     the following section.  3D models must be pure triangular meshes
     and their coordinate units are assumed to be in mm.  Each OBJ file
     must explicitly contain a single 3D model of any long bone
     fragment.

     Assuming a 3D model named "bone_ID.obj", the following files are
     generated:

     Filename                   Description
     ---------------------------------------------------------------------------
     Fgeometry-bone_ID.csv      It contains the properties of area (measured
                                in mm^2), perimeter (measured in mm),
                                centroid (returned as [X,Y,Z] coordinates in
                                mm units), and the sectioning normal
                                (returned as an [X,Y,Z] vector).  Each row of
                                the CSV file corresponds to the user defined
                                points at the same order as they appear in
                                the relevant Meshlab PickedPoints file.  The
                                aforementioned properties for each cross
                                section are stored as a row vector with the
                                respective order in columns
                                [[2],[3],[4:6],[7:9]].  The first column
                                contains the index of the corresponding
                                cross-sectioning point in increasing order.
                                
     Finertia-bone_ID.csv       It contains the properties of Ixy, Imin, and
                                Imax, all measured in mm^4.  Accordingly,
                                they are saved in a row vector [2:4] with the
                                first column containing the index of each
                                cross section.
                                
     Fpolyline2D-bone_ID.csv    It contains the 2D coordinates (on an
                                arbitrary X,Y local axis) for each cross
                                section as an Nx2 matrix, where N is the
                                number of points for each cross-sectional
                                polygon.  These polygons are ordered as
                                column duplets, i.e.
                                [[1:2],...,[end-1:end]], in the same order
                                their corresponding points are stored in the
                                Meshlab PickedPoints file.  Polygon
                                coordinates start from the second row
                                ([2:end],:), while the first row
                                (1,[1,3,...,end-1]) contains the index of the
                                corresponding cross-sectioning points.
                                
     Fpolyline3D-bone_ID.csv    It contains the 3D model coordinates for each
                                cross section as an Nx3 matrix, where N is
                                the number of points for each cross-sectional
                                polygon.  These polygons are ordered as
                                column triplets, i.e.
                                [[1:3],...,[end-2:end]], in the same order
                                their corresponding points are stored in the
                                Meshlab PickedPoints file.  Polygon
                                coordinates start from starting from the
                                second row ([2:end],:), while the first row
                                (1,[1,4,...,end-2]) contains the index of the
                                corresponding cross-sectioning points.

     See also: longbone_Geometry, longbone_CustomGeometry,
     visualize_CrossSections.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80
This function analyzes the cross-sectional geometry of any diaphyseal
long bo...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 17
longbone_Geometry


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 9584
 -- csg-toolkit: longbone_Geometry (FILENAME)
 -- csg-toolkit: longbone_Geometry (FILENAME, BONES)
 -- csg-toolkit: longbone_Geometry (FOLDER, FILENAME)
 -- csg-toolkit: longbone_Geometry (FOLDER, FILENAME, BONES)
 -- csg-toolkit: [GEOM, SMOA, BONE, EXTRA, DATA] = longbone_Geometry
          (...)

     This function analyzes the cross-sectional geometry of an intact
     humerus, ulna, femur, or tibia bone at 20%, 35%, 50%, 65% and 80%
     along the bone’s maximum length.

     ‘longbone_Geometry (FILENAME)’ will analyze the 3D model specified
     in FILENAME provided that it conforms to the Wavefront OBJ file
     format and it is a pure tringular mesh.  The function will
     automatically determine the type of long bone in FILENAME and
     register the required initial alignment points according to the
     bone type.  The 3D model is assumed to be in mm units and present
     in the working directory.

     FOLDER, which must be a character vector, defines the relative or
     absolute path to the directory containing the 3D model in FILENAME.
     When omitted, the current working directory is assumed.

     BONES must be cell array of character vectors specifying one or
     more long bones that should be analyzed.  ‘longbone_Geometry’ will
     only analyze the 3D model if it matches one of the bones named in
     BONES, unless the ’Force’ option is also selected, in which case
     the user must specify a single bone such as in ‘{'Force',
     'Humerus'}’.  Valid options are:

       1. ’Humerus’
       2. ’Ulna’
       3. ’Femur’
       4. ’Tibia’
       5. ’All’
       6. ’Force’

     Note: When ’Force’ is included, initial alignment points are also
     required and it is the user’s responsibility to ensure the
     appropriate bone is being analyzed.  This option is provided so
     that damaged or heaviliy deformed bones, which may turn out as
     undefined, can be analyzed.

     If the user wants to define the initial alignment points, this can
     be done with a side-car Meshlab PickedPoints file with the same
     base filename and in same directory as the 3D model.  In such case,
     ‘longbone_Geometry’ skips the automatic initial point registration
     and uses the first two points in the side-car file for optimizing
     the bone’s mediolateral axis.

       1. For the humerus, these points must be positioned anteriorly on
          the trochlea and capitulum at the distal end of the humerus.
       2. For the ulna, only a single initial alignment point is
          required that must be placed at the anterior tip of the
          coronoid process.
       3. For the femur, these points must be located posteriorly on the
          medial and lateral condyles at the distal end of the femur.
       4. For the tibia, these points must be positioned posteriorly of
          the medial and lateral condyles at the proximal end of the
          tibia.

     Note: The function automatically optimizes the local extremal
     points of the mediolateral axis based on the initial points and
     subsequently uses the optimized coronal plane orientation for
     computing the second moments of area.  However, the initial
     alignment point for ulna is not optimized.  The optimized alignment
     points are appended in the existing MPP file or saved in newly
     created, accordingly.

     When ‘longbone_Geometry’ is called without any output arguments, it
     stores all geometric properties in CSV files as described in the
     following section.  Each OBJ file must explicitly contain a single
     3D bone model.

     Assuming a 3D model named ’bone_ID.obj’, the following files are
     generated:

     Filename                   Description
     ---------------------------------------------------------------------------
     Dgeometry-bone_ID.csv      It contains the properties of area (measured
                                in mm^2), perimeter (measured in mm),
                                centroid (returned as [X,Y,Z] coordinates in
                                mm units), as well as the sectioning and
                                orientation normals (returned as an [X,Y,Z]
                                vectors).  Each row of the CSV file
                                corresponds to a different cross section at
                                20%, 35%, 50%, 65%, and 80% along the bone’s
                                maximum length.  The aforementioned
                                properties for each cross section are stored
                                as a row vector with the respective order in
                                columns [:,[2],[3],[4:6],[7:9],[10:12]].  The
                                first column contains the ratios of the
                                sectioning points’ distance from the proximal
                                end to the bone’s maximum length.
                                
     Dinertia-bone_ID.csv       It contains the properties of Ix, Iy Ixy,
                                Imin, and Imax, all measured in mm^4, as well
                                as theta, measured in degrees.  Accordingly,
                                they are saved as row vectors [2:7] with the
                                first column containing the ratios of the
                                sectioning points’ distance from the proximal
                                end to the bone’s maximum length.
                                
     Dpolyline2D-bone_ID.csv    It contains the 2D coordinates (on an
                                arbitrary X,Y local axis) for each cross
                                section as an Nx2 matrix, where N is the
                                number of points for each cross-sectional
                                polygon at 20%, 35%, 50%, 65%, and 80% along
                                the bone’s maximum length.  These polygons
                                are ordered as 5 column duplets, i.e.
                                [[1:2],[3:4],[5:6],[7:8],[9:10]].  Polygon
                                coordinates start from the second row
                                ([2:end],:), while the first row contains the
                                relevant ratios at columns (1, [1,3,5,7,9]).
                                
     Dpolyline3D-bone_ID.csv    It contains the 3D model coordinates for each
                                cross section as an Nx3 matrix, where N is
                                the number of points for each cross-sectional
                                polygon at 20%, 35%, 50%, 65%, and 80% along
                                the bone’s maximum length.  These polygons
                                are ordered as 5 column triplets, i.e.
                                [[1:3],[4:6],[7:9],[10:12],[13:15]].  Polygon
                                coordinates start from the second row
                                ([2:end],:), while the first row contains the
                                relevant ratios at columns (1,
                                [1,4,7,10,13]).

     [GEOM, SMOA, BONE, EXTRA, DATA] = longbone_Geometry (...) may also
     return up to five output arguments.  GEOM and SMOA are 5x1
     structure arrays containing the cross-sectrional geometric
     properties and the second moments of area, respectively.  Each
     element of the structure arrays corresponds to 20%, 35%, 50%, 65%,
     and 80% cross sections.  For more information about the contents of
     the returned structure arrays, see ‘simple_polygon3D’.  BONE is a
     character vector containing the name of the bone as inferred by the
     ‘longbone_Registration’ function.  If a 3D model is not recognized,
     then BONE is returned as ’undefined’, unless the ’Force’ has been
     opted by the user.

     EXTRA is an additional scalar structure with the following fields:

       1. maxDistance
       2. maxd_V1
       3. maxd_V2
       4. MLA_opt_point_A
       5. MLA_opt_point_B
       6. diaphyseal_bending
       7. angle_20_35
       8. angle_35_50
       9. angle_50_65
       10. angle_65_80
       11. ArPerIndex20
       12. ArPerIndex35
       13. ArPerIndex50
       14. ArPerIndex65
       15. ArPerIndex80

     maxDistance refers to the bone’s maximum distance measurement, as
     defined by the 3D points in maxd_V1 and maxd_V2.  Optimized
     mediolateral axis points are returned in the MLA_opt_point_*
     fields.  diaphyseal_bending contains the sum of dihedral angles (in
     degrees) between each pair of consecutive cross-sectional planes,
     which are also returned in the angle_$$_$$ fields.  ArPerIndex$$
     the Area-Perimeter Index for each consecutive cross section.

     DATA is a numeric row vector containing all the measurements
     computed by the ‘longbone_Geometry’ in tabular form to facilitate
     further processing.  Use the ‘longbone_Measurements’ function to
     obtain a cell array of character vectors with the definitions of
     the measurements in DATA.

     When ‘longbone_Geometry’ is called with output arguments, then no
     CSV files are generated.  When called with more than three output
     arguments, then saving the optimized alignment points to an
     existing or new MPP file is also skipped.

     See also: longbone_CustomGeometry, longbone_FragmentGeometry,
     longbone_Measurements, longbone_Registration, simple_polygon3D.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80
This function analyzes the cross-sectional geometry of an intact
humerus, uln...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 21
longbone_Measurements


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 407
 -- csg-toolkit: MEASUREMENTS = longbone_Measurements ()

     Measurement names of long bone geometry data.

     ‘MEASUREMENTS = longbone_Measurements ()’ returns a cell array of
     character vectors with the names of the longbone measurements in
     the same order as they appear in the DATA output argument returned
     by the ‘longbone_Geometry’ function.

     See also: longbone_Geometry.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 45
Measurement names of long bone geometry data.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 16
longbone_Scaling


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 2868
 -- csg-toolkit: longbone_Scaling
 -- csg-toolkit: longbone_Scaling (FILENAME)
 -- csg-toolkit: longbone_Scaling (FILENAME, MAXD)
 -- csg-toolkit: SCALE = longbone_Scaling
 -- csg-toolkit: SCALE = longbone_Scaling (...)

     Scale triangular meshes stored in Wavefront OBJ format.

     ‘longbone_Scaling’ scales a 3D model in FILENAME to a specified
     maximum distance in MAXD and returns the scaling factor, while it
     stores the coordinates of the points corresponding to the maximum
     distance in a Meshlab PickedPoints file.

     The function may be used for scaling a single mesh or batch scaling
     multiple meshes.  When called with a single input argument, the
     function will scale the particular mesh defined in FILENAME so that
     the scaled mesh will have a user-defined maximum distance.  The
     function is primarily intended for scaling long bone triangular
     mesh models produced with 3D photogrammetry, hence the use of
     maximum distance as the target reference for scaling.
     Nevertheless, it can be used for scaling any triangular mesh of
     arbitrary shape according to its maximum distance, which can either
     be parsed as a second input argument MAXD or when prompted by the
     function.

     When called with no input arguments, the function will scan the
     working directory for all .obj files and will scale them
     iteratively in batch mode.  For each available OBJ, the user will
     be prompted for the actual maximum distance of each corresponding
     long bone and it will subsequently scale the model to the real
     world dimensions with units in mm.  Scaling is performed about the
     model’s barycentric coordinates, which are translated to origin.

     Prior to scaling, when prompted for manual measurement value, the
     user may examine the model’s maximum distance corresponding points
     by opening the triangular mesh in Meshlab and utilizing the
     corresponding .pp file, which is created automatically by the
     present function.  After scaling is performed for a given
     triangular mesh, the user may re-examine the scaled model by
     reloading the mesh and its respective .pp file, which is
     automatically updated with the new points of its maximum distance.

     ‘SCALE = longbone_Scaling (...)’ returns a cell array with each 3D
     model’s filename and scale related measurements in the following
     order: filename, ratio, old max distance, new max distance.  If no
     output argument is declared, the function will prompt the user to
     specify a CSV file (new or existing, which will be overwritten) to
     save these measurements.  The first row, either in the CSV file or
     the SCALE cell array contains the repsective column labels
     "filename", "ratio", "oldMaxD", and "newMaxD".

     See also: longbone_maxDistance.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 55
Scale triangular meshes stored in Wavefront OBJ format.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 12
longbone_Sex


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 4685
 -- csg-toolkit: TABLE = longbone_Sex (FILENAME)
 -- csg-toolkit: TABLE = longbone_Sex (FILENAME, BONES)
 -- csg-toolkit: TABLE = longbone_Sex (FOLDER, FILENAME)
 -- csg-toolkit: TABLE = longbone_Sex (FOLDER, FILENAME, BONES)
 -- csg-toolkit: [SEX, PROB, REP, VARS, OUTLIERS] = longbone_Sex (...)

     This function analyzes the geometry of an intact humerus, ulna,
     femur, or tibia bone using the ‘longbone_Geometry’ function and
     estimates the biological sex of the individual the bone belongs to.

     ‘TABLE = longbone_Sex (FILENAME)’ will analyze the 3D model
     specified in FILENAME provided that it conforms to the Wavefront
     OBJ file format and it is a pure triangular mesh.  The function
     will automatically determine the type of long bone in FILENAME and
     register the required initial alignment points according to the
     bone type.  The 3D model is assumed to be in mm units and present
     in the working directory.  When called with a single output
     argument, ‘longbone_Sex’ returns a 1x7 table, TABLE, with the
     following variables:

       1. ‘Name’: a cellstr variable with the filename of the analyzed
          bone.
       2. ‘Bone’: a cellstr variable with the type of bone as identified
          by the ‘longbone_Registration’ function.
       3. ‘Sex’: a categorical variable with the estimated sex.
       4. ‘Prob’: a numerical variable with the posterior probability of
          the estimated sex.
       5. ‘Typical’: a logical variable specifying whether the
          measurements of the analyzed bone are typical of training
          sample.
       6. ‘Used’: a cell variable specifying the variables used for
          assigning sex in a cell array of character vectors.
       7. ‘Outliers’: a cell variable specifying which of the
          measurements used for assigning sex are outliers in a cell
          array of character vectors.

     FOLDER, which must be a character vector, defines the relative or
     absolute path to the directory containing the 3D model in FILENAME.
     When omitted, the current working directory is assumed.

     BONES must be cell array of character vectors specifying one or
     more long bones that should be analyzed.  ‘longbone_Geometry’ will
     only analyze the 3D model if it matches one of the bones named in
     BONES, unless the ’Force’ option is also selected, in which case
     the user must specify a single bone such as in ‘{'Force',
     'Humerus'}’.  Valid options are:

       1. ’Humerus’
       2. ’Ulna’
       3. ’Femur’
       4. ’Tibia’
       5. ’All’
       6. ’Force’

     Note: When ’Force’ is included, initial alignment points are also
     required and it is the user’s responsibility to ensure the
     appropriate bone is being analyzed.  This option is provided so
     that damaged or heaviliy deformed bones, which may turn out as
     undefined, can be analyzed.  For more information look at the
     documentation of the ‘longbone_Geometry’ function by typing ‘help
     longbone_Geometry’.

     When called with more than one output argument, such as in ‘[SEX,
     PROB, TYP, VARS, OUTLIERS] = longbone_Sex (...)’, then the
     following output arguments as returned:

        • SEX is a numeric scalar value specifying the estimated sex,
          where 1 corresponds to male, 2 to female, and 0 to
          undetermined.
        • PROB is the posterior probability of the estimated sex.
          Unless sex is assigned, PROB is NaN.
        • TYP is a logical scalar value specifying whether the bone
          measurements used for sex estimation are typical true of the
          population samples used to train the classifiers or they
          contain outliers, in which case the sex estimation algorithm
          defaults to using only the univariate linear discriminant
          classifiers for estimating sex and TYP is false.
        • VARS is a cell array of character vectors containing the
          variables that were significant for assigning sex.  These can
          be any combination of the utilized measurements, corresponding
          to univariate classifiers, as well as ’LDA ALL’, ’KNN ALL’,
          and ’FCNN Scores’, corresponding to multivariate classifiers.
        • OUTLIERS is a cell array of character vectors containing the
          measurements that were used in sex estimation but they are
          considered outliers according to the descriptive data of the
          training population samples.

     See also: longbone_CustomGeometry, longbone_Registration.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80
This function analyzes the geometry of an intact humerus, ulna, femur,
or tib...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 18
read_MeshlabPoints


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 751
 -- csg-toolkit: MLPP = read_MeshlabPoints (FILENAME)
 -- csg-toolkit: [MLPP, PNAMES] = read_MeshlabPoints (FILENAME)

     Read 3D coordinates from a MeshLab PickedPoints file.

     This function reads a .pp MeshLab PickedPoints file and returns an
     Nx4 matrix containing the index for each point along with the
     corresponding X,Y,Z coordinates in each row.  The point name must
     be numerical, otherwise NaN is returned.  If the point names are
     stored as alpharithmetic strings, then these can be retrieved in a
     second output argument, PNAMES, as a cell array of strings.  In
     such case, MLPP is an Nx3 matrix containing the X,Y,Z point
     coordinates, where N is the number of points.

     See also: read_MeshlabPoints.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 53
Read 3D coordinates from a MeshLab PickedPoints file.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 9
renameObj


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 377
 -- csg-toolkit: renameObj (SOURCE, TARGET)
 -- csg-toolkit: TARGET = renameObj (SOURCE, TARGET)

     Rename an OBJ file containing a pure triangular mesh in Wavefront
     3D model file format and its associated material library and
     texture map files.

     Only single model in OBJ and single material in MTL files are
     supported.

     See also: readObj, writeObj.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80
Rename an OBJ file containing a pure triangular mesh in Wavefront 3D
model fi...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 16
simple_polygon3D


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 3611
 -- csg-toolkit: GEOM = polygon3D (SECTION, NORMAL)
 -- csg-toolkit: GEOM = polygon3D (SECTION, NORMAL, DIRECTION)
 -- csg-toolkit: [GEOM, SMOA] = polygon3D (...)
 -- csg-toolkit: [GEOM, SMOA, POLYLINE] = polygon3D (...)

     This function takes the 3D coordinates of a planar cross section
     along with with its normal and calculates some of its geometric
     properties such as cross sectional area, perimeter and principal
     second moments of area.  The points of the planar section may be
     unsorted, since the function will sort them in counter-clockwise
     order automatically, but need to constitute a simple polygon (a
     flat shape consisting of straight, non-intersecting line segments
     or "sides" that are joined pair-wise to form a closed path).

     If called with only 2 input arguments as in the following example

     ‘[GEOM, SMOA, POLYLINE] = simple_polygon3D (SECTION, NORMAL)’

     Then,

     SECTION            is an Nx3 matrix containing the X,Y,Z point
                        coordinates of a planar cross section.
     NORMAL             is a 1x3 vector defining the unit normal of the
                        sectioning plane.

     and,

     GEOM               is a scalar structure containing the fields:

          GEOM.Area              calculated in mm^2.
          GEOM.Perimeter         calculated in mm.
          GEOM.Centroid          X,Y,Z centroid coordinates of the cross
                                 section.

     SMOA               is a scalar structure containing the fields:

          SMOA.Ixy               product of 2nd moments of area in mm^4.
          SMOA.Imin              minimum 2nd moment of area in mm^4.
          SMOA.Imax              maximum 2nd moment of area in mm^4.

     POLYLINE           is a scalar structure containing the fields:

          POLYLINE.poly2D        Nx2 matrix containing the X,Y coordinates of
                                 the cross section on the 2D local axes of the
                                 sectioning plane ordered counter.
          POLYLINE.poly3D        Nx3 matrix containing the original 3D
                                 coordinates of the cross section ordered
                                 counter clockwise.

     If called with 3 input arguments as in the following example

     ‘[GEOM, SMOA, POLYLINE] = simple_polygon3D (SECTION, NORMAL,
     DIRECTION)’

     Then, DIRECTION is an 1x3 vector defining the unit normal of the
     coronal plane that provides alignment of the bone to anatomical
     position, while NORMAL is assumed to point upwards.  The SMOA
     structure contains the additional fields, as follows:

          SMOA.Ix                2nd moment of area with respect to x axis,
                                 which is collinear with the intersection of
                                 the coronal plane and the sectioning plane.
                                 Calculated in mm^4.
          SMOA.Iy                2nd moment of area with respect to y axis,
                                 which is collinear with the intersection of
                                 the sagital plane and the sectioning plane.
                                 Calculated in mm^4.
          SMOA.theta             angle of rotation of the principal axis Imax
                                 of 2nd moment of area with respect to x axis
                                 expressed in degrees in the range (-90, 90].

     See also: meshArea, meshBarycenter, meshSection,
     longbone_CustomGeometry, longbone_FragmentGeometry,
     longbone_Geometry.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80
This function takes the 3D coordinates of a planar cross section along
with w...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 23
visualize_CrossSections


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 6775
 -- csg-toolkit: visualize_CrossSections (BONE_ID)
 -- csg-toolkit: visualize_CrossSections (BONE_ID, MODE)
 -- csg-toolkit: CS_GEOMETRY = visualize_CrossSections (BONE_ID)
 -- csg-toolkit: CS_GEOMETRY = visualize_CrossSections (BONE_ID, MODE)
 -- csg-toolkit: [CS_GEOMETRY, SMOA] = visualize_CrossSections (...)
 -- csg-toolkit: [CS_GEOMETRY, SMOA, POLYLINE] = visualize_CrossSections
          (...)

     Plot cross sectional contours and their CSG properties for a given
     sample.

     ‘visualize_CrossSections’ reads the respective $geometry-$$.csv,
     $inertia-$$.csv, $polyline2D-$$.csv, and $polyline3D-$$.csv files
     available in the working directory, where $$ is the BONE_ID char
     string for the required bone and $ denotes the MODE of bone
     analysis, and plots the 2D cross sectional polygons from proximal
     (top) to distal (bottom) along with certain information regarding
     cross sectional area, perimeter, and second moments of area.

     When called with a single input argument, ‘visualize_CrossSections’
     reads the files produced with the ‘longbone_Analysis’ function,
     i.e.  it reads the Dgeometry-bone_id.csv, Dinertia-bone_id.csv,
     Dpolyline2D-bone_id.csv, and Dpolyline3D-bone_id.csv files
     associated with BONE_ID.  Optionally, if called with a second
     argument, MODE, then the function reads the files generated by the
     respective function as shown below.

     MODE           Function                      CSV Files
     ---------------------------------------------------------------------------
     "default"      ‘longbone_Geometry’           Dgeometry-bone_id.csv
                                                  Dinertia-bone_id.csv
                                                  Dpolyline2D-bone_id.csv
     "custom"       ‘longbone_CustomGeometry’     Cgeometry-bone_id.csv
                                                  Cinertia-bone_id.csv
                                                  Cpolyline2D-bone_id.csv
     "fragment"     ‘longbone_FragmentGeometry’   Fgeometry-bone_id.csv
                                                  Finertia-bone_id.csv
                                                  Fpolyline2D-bone_id.csv

     In default mode, ‘visualize_CrossSections’ produces 5 plots with
     the cross sections at 20%, 35%, 50%, 65%, and 80% of the longbone’s
     max distance, whereas in "custom" and "fragment" modes, it produces
     an arbitrary number of plots according to the cross sections
     contained in the associated files.  All four CSV files
     corresponding to BONE_ID must be present in the working directory.

     The centroid of each cross section is centered at origin and the
     x-axis of the plots represents the frontal axis of the bone from
     left to right side, whereas the y-axis is aligned to the sagital
     axis with the top pointing towards the front side (anterior).  Both
     axes retain equal size so that the actual shape of the cross
     sectional area is preserved.  However, each figure has a different
     scaling factor.  Consequently, size may not be visually
     proportional among different figures, but the axes in each figure
     preserve the values of the actual size for the displayed cross
     section.

     If output arguments are defined, then ‘visualize_CrossSections’
     returns up to three structures with the following fields,
     containing the data retrieved from the CSV files.  The number of
     elements of each structure correspond to the number of cross
     sections generated by the respective longbone_ function.

     Structure      Field          Data
     --------------------------------------------------------------------------
     CS_GEOMETRY    CS             The ratio of the cross section’s distance
                                   from the proximal end to the bone’s
                                   maximum length or the ordered index of
                                   the sectioning point for bone fragments.
                    Area           The cross sectional aera measured in
                                   mm^2.
                    Perimeter      The perimeter of the cross section
                                   measured in mm.
                    Centroid       The X, Y, Z coordinates of the cross
                                   sectional centroid.
                    Section_n      The X, Y, Z coordinates of the cross
                                   sectional plane’s normal.
                    Coronal_n      The X, Y, Z coordinates of the normal of
                                   the bone’s Coronal plane.
                                   
     SMOA           Ix             The 2nd moment of area with respect to
                                   the X axis, which is collinear with the
                                   intersection of the coronal plane and the
                                   sectioning plane, measured in mm^4.
                    Iy             The 2nd moment of area with respect to Y
                                   axis, which is collinear with the
                                   intersection of the sagital plane and the
                                   sectioning plane, measured in mm^4.
                    Ixy            The product of the 2nd moment of area
                                   measured in mm^4.
                    Imin           The minimum 2nd moment of area measured
                                   in mm^4.
                    Imax           The maximum 2nd moment of area measured
                                   in mm^4.
                    theta          The angle of rotation of the principal
                                   axis of 2nd moment of area with respect
                                   to X axis, measured in degrees.
                                   
     POLYLINE       poly2D         An Nx2 matrix with the X, Y coordinates
                                   of the cross section, ordered
                                   counter-clockwise, on the 2D local axes
                                   of the sectioning plane.
                    poly3D         An Nx3 matrix with the X, Y, Z
                                   coordinates of the cross section, ordered
                                   counter-clockwise, in the original 3D
                                   space of the bone’s 3D model.

     If MODE is defined as "fragment", then Coronal_n field is not
     available in CS_GEOMETRY and the fields Ixy, Iy, theta are missing
     from SMOA.

     See also: inspect_CSG, longbone_Analysis, longbone_Geometry,
     longbone_CustomGeometry, longbone_FragmentGeometry.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 74
Plot cross sectional contours and their CSG properties for a given
sample.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 19
write_MeshlabPoints


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 1312
 -- csg-toolkit: write_MeshlabPoints (FILENAME, MESHNAME, MLPP)
 -- csg-toolkit: write_MeshlabPoints (FILENAME, MESHNAME, MLPP, PNAMES)

     Write 3D coordinates in a MeshLab PickedPoints file.

     This function writes the 3D coordinates of points along with their
     associated names in a .pp MeshLab PickedPoints file.  The function
     requires at least three input arguments.  When three arguments are
     provided, the first two must be character strings with the filename
     under which the points will be saved, FILENAME and the filename of
     the associated 3D mesh, MESHNAME.  The third input argument must be
     an Nx4 matrix with each row containing the point index (only
     numeric values) along with the X,Y,Z coordinates of each point.

     If the point index is required to be alphanumeric, then an
     additional input ardument may be parsed, PNAMES, which must be a
     cell array of strings.  PNAMES must correspond to the points
     provided in the second input argument, in which case it can be an
     Nx3 matrix containing only the 3D coordinates of the points.  In
     case of four input arguments, where the third argument is an Nx4
     matrix, the first column (point index) is ignored and the point
     names in PNAMES is used.

     See also: write_MeshlabPoints.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 52
Write 3D coordinates in a MeshLab PickedPoints file.





