Getting Started

Work in progress

Segmentation Input

We start with a segmentation of a regular octahedron composed of three materials. The segmentation encodes

0 for void (or background), shown in gray,
1 for the inner domain, shown in green,
2 for the intermediate layer, shown in yellow, and
3 for the outer layer, shown in magenta.

The (7 x 7 x 7) segmentation, at the midline cut plane, appears as follows:

Consider each slice, 1 to 7, in succession:

Remark: The (7 x 7 x 7) segmentation can be thought of as a conceptual start point for a process called Loop subdivision, used to produce spherical shapes at higher resolutions. See Octa Loop for additional information. A sphere in resolutions of (24 x 24 x 24) and (48 x 48 x 48), used in the Sphere with Shells section, is shown below:

The .spn file can be thought of as the most elementary segmentation file type because it is saved as an ASCII text file and is therefore readily human-readable. Below is an abbreviated and commented .spn segmentation of the (7 x 7 x 7) octahedron discussed previously.

0 # slice 1, row 1
0
0
0
0
0
0
0 # slice 1, row 2
0
0
0
0
0
0
0 # slice 1, row 3
0
0
0
0
0
0
0 # slice 1, row 4
0
0
3
0
0
0
0 # slice 1, row 5
0
0
0
0
0
0
0 # slice 1, row 6
0
0
0
0
0
0
0 # slice 1, row 7
0
0
0
0
0
0
# ... and so on for the remaining six slices

A disadvantage of .spn is that it can become difficult to keep track of data slice-by-slice. Because it is not a compressed binary file, the .spn often has a large file size.

The .npy segmentation file format is an alternative to the .spn format. The .npy format can be advantageous because is can be generated easily from Python. The .npy approach can be useful because Python can be used to algorithmically create a segmentation and serialized the segmentation to a compressed binary file (in .npy format).

Here we illustrate creating the octahedron segmentation in Python:

"""This module creates a 7x7x7 octahedron segmentation."""

import numpy as np

segmentation = np.array(
    [
        [  # slice 1
            [0, 0, 0, 0, 0, 0, 0],  # row 1
            [0, 0, 0, 0, 0, 0, 0],  # row 2
            [0, 0, 0, 0, 0, 0, 0],  # row 3
            [0, 0, 0, 3, 0, 0, 0],  # row 4
            [0, 0, 0, 0, 0, 0, 0],  # row 5
            [0, 0, 0, 0, 0, 0, 0],  # row 6
            [0, 0, 0, 0, 0, 0, 0],  # row 7
        ],
        [  # slice 2
            [0, 0, 0, 0, 0, 0, 0],  # row 1
            [0, 0, 0, 0, 0, 0, 0],  # row 2
            [0, 0, 0, 3, 0, 0, 0],  # row 3
            [0, 0, 3, 2, 3, 0, 0],  # row 4
            [0, 0, 0, 3, 0, 0, 0],  # row 5
            [0, 0, 0, 0, 0, 0, 0],  # row 6
            [0, 0, 0, 0, 0, 0, 0],  # row 7
        ],
        [  # slice 3
            [0, 0, 0, 0, 0, 0, 0],  # row 1
            [0, 0, 0, 3, 0, 0, 0],  # row 2
            [0, 0, 3, 2, 3, 0, 0],  # row 3
            [0, 3, 2, 1, 2, 3, 0],  # row 4
            [0, 0, 3, 2, 3, 0, 0],  # row 5
            [0, 0, 0, 3, 0, 0, 0],  # row 6
            [0, 0, 0, 0, 0, 0, 0],  # row 7
        ],
        [  # slice 4
            [0, 0, 0, 3, 0, 0, 0],  # row 1
            [0, 0, 3, 2, 3, 0, 0],  # row 2
            [0, 3, 2, 1, 2, 3, 0],  # row 3
            [3, 2, 1, 1, 1, 2, 3],  # row 4
            [0, 3, 2, 1, 2, 3, 0],  # row 5
            [0, 0, 3, 2, 3, 0, 0],  # row 6
            [0, 0, 0, 3, 0, 0, 0],  # row 7
        ],
        [  # slice 5
            [0, 0, 0, 0, 0, 0, 0],  # row 1
            [0, 0, 0, 3, 0, 0, 0],  # row 2
            [0, 0, 3, 2, 3, 0, 0],  # row 3
            [0, 3, 2, 1, 2, 3, 0],  # row 4
            [0, 0, 3, 2, 3, 0, 0],  # row 5
            [0, 0, 0, 3, 0, 0, 0],  # row 6
            [0, 0, 0, 0, 0, 0, 0],  # row 7
        ],
        [  # slice 6
            [0, 0, 0, 0, 0, 0, 0],  # row 1
            [0, 0, 0, 0, 0, 0, 0],  # row 2
            [0, 0, 0, 3, 0, 0, 0],  # row 3
            [0, 0, 3, 2, 3, 0, 0],  # row 4
            [0, 0, 0, 3, 0, 0, 0],  # row 5
            [0, 0, 0, 0, 0, 0, 0],  # row 6
            [0, 0, 0, 0, 0, 0, 0],  # row 7
        ],
        [  # slice 7
            [0, 0, 0, 0, 0, 0, 0],  # row 1
            [0, 0, 0, 0, 0, 0, 0],  # row 2
            [0, 0, 0, 0, 0, 0, 0],  # row 3
            [0, 0, 0, 3, 0, 0, 0],  # row 4
            [0, 0, 0, 0, 0, 0, 0],  # row 5
            [0, 0, 0, 0, 0, 0, 0],  # row 6
            [0, 0, 0, 0, 0, 0, 0],  # row 7
        ],
    ],
    dtype=np.uint8,
)

FILE_NAME = "octahedron.npy"
np.save(FILE_NAME, segmentation)
print(f"Saved {FILE_NAME} with shape {segmentation.shape}.")

The `convert` Command

automesh allows for interoperability between .spn. and .npy file types. Use the automesh help to discover the command syntax:

automesh convert --help
Converts between mesh or segmentation file types

Usage: automesh convert [OPTIONS] --input <FILE> --output <FILE>

Options:
  -i, --input <FILE>   Mesh (inp) or segmentation (npy | spn) input file
  -o, --output <FILE>  Mesh (exo | mesh | stl | vtk) or segmentation (npy | spn) output
  -x, --nelx <NEL>     Number of voxels in the x-direction
  -y, --nely <NEL>     Number of voxels in the y-direction
  -z, --nelz <NEL>     Number of voxels in the z-direction
  -q, --quiet          Pass to quiet the terminal output
  -h, --help           Print help

For example, to convert the octahedron.npy to octahedron2.spn:

automesh convert -i octahedron.npy -o octahedron2.spn
[1m    automesh 0.3.3[0m
     [1;96mReading[0m octahedron.npy       [1;98mTotal[0m 168.366µs

To convert from octahedron2.spn to octahedron3.npy:

automesh convert -i octahedron2.spn -x 7 -y 7 -z 7 -o octahedron3.npy
[1m    automesh 0.3.3[0m
     [1;96mReading[0m octahedron2.spn [2m[nelx: 7, nely: 7, nelz: 7]       [1;98mTotal[0m 213.309µs

Remark: Notice that the .spn requires number of voxels in each of the x, y, and z dimensions to be specified using --nelx, --nely, --nelz (or, equivalently -x, -y, -z) flags.

We can verify the two .npy files encode the same segmentation:

"""The purpose of this module is to show that the
segmentation data encoded in two .npy files is the same.
"""

import numpy as np

aa = np.load("octahedron.npy")
print(aa)

bb = np.load("octahedron3.npy")
print(bb)

comparison = aa == bb
print(comparison)
result = np.all(comparison)
print(f"Element-by-element equality is {result}.")

Mesh Generation

automesh creates several finite element mesh file types from a segmentation.

Use the automesh help to discover the command syntax:

automesh mesh --help
Creates a finite element mesh from a segmentation

Usage: automesh mesh [OPTIONS] --input <FILE> --output <FILE> [COMMAND]

Commands:
  smooth  Applies smoothing to the mesh before output
  help    Print this message or the help of the given subcommand(s)

Options:
  -i, --input <FILE>      Segmentation input file (npy | spn)
  -o, --output <FILE>     Mesh output file (exo | inp | mesh | vtk)
  -d, --defeature <NUM>   Defeature clusters with less than NUM voxels
  -x, --nelx <NEL>        Number of voxels in the x-direction
  -y, --nely <NEL>        Number of voxels in the y-direction
  -z, --nelz <NEL>        Number of voxels in the z-direction
  -r, --remove <ID>...    Voxel IDs to remove from the mesh
      --xscale <SCALE>    Scaling (> 0.0) in the x-direction [default: 1]
      --yscale <SCALE>    Scaling (> 0.0) in the y-direction [default: 1]
      --zscale <SCALE>    Scaling (> 0.0) in the z-direction [default: 1]
      --xtranslate <VAL>  Translation in the x-direction [default: 0]
      --ytranslate <VAL>  Translation in the y-direction [default: 0]
      --ztranslate <VAL>  Translation in the z-direction [default: 0]
      --metrics <FILE>    Name of the quality metrics file
  -q, --quiet             Pass to quiet the terminal output
      --surface           Pass to mesh internal surfaces
  -h, --help              Print help

To convert the octahedron.npy into an ABAQUS finite element mesh, while removing segmentation 0 from the mesh:

automesh mesh -r 0 -i octahedron.npy -o octahedron.inp

Smoothing

Use the automesh help to discover the command syntax:

automesh smooth --help
Applies smoothing to an existing mesh

Usage: automesh smooth [OPTIONS] --input <FILE> --output <FILE>

Options:
  -c, --hierarchical      Pass to enable hierarchical control
  -i, --input <FILE>      Mesh (inp | stl) input file
  -o, --output <FILE>     Smoothed mesh (exo | inp | mesh | stl | vtk) output file
  -n, --iterations <NUM>  Number of smoothing iterations [default: 20]
  -m, --method <NAME>     Name of the smoothing method [default: Taubin]
  -k, --pass-band <FREQ>  Pass-band frequency for Taubin smoothing [default: 0.1]
  -s, --scale <SCALE>     Scaling parameter for smoothing [default: 0.6307]
      --metrics <FILE>    Name of the quality metrics file (csv | npy)
  -q, --quiet             Pass to quiet the terminal output
  -h, --help              Print help

To smooth the octahedron.inp mesh with Taubin smoothing parameters for five iterations:

automesh smooth -n 5 -i octahedron.inp -o octahedron_s05.inp
[1m    automesh 0.3.3[0m
     [1;96mReading[0m octahedron.inp       [1;98mTotal[0m 167.774µs

The original voxel mesh and the smoothed voxel mesh are shown below:

`octahedron.inp`	`octahedron_s05.inp`

See the Smoothing section for more information.

Isosurface

An isosurface can be generated from a segmentation using the --surface flag.

To create a mesh of the three isosurfaces contained in the octahedron example:

automesh mesh -i octahedron.npy -o octahedron.stl --surface
[1m    automesh 0.3.3[0m
     [1;96mReading[0m octahedron.npy       [1;98mTotal[0m 194.755µs

The surfaces are visualized below:

[to come]

See the Isosurface section for more information.

automesh