Installation

Choose one of the installation types,

Full Client,
Developer, or
Minimal Client.

The Client Installations are recommended for users who will use recon3d in an analysis workflow.

Knowledge of the Python programming language is not necessary.
The Full Client includes the tutorial files.
The Minimal Client does not include the tutorial files.

The Developer Installation is recommended for users who will create or update functionality. Knowledge of the Python programming language is required.

Warning: For all installations, Python 3.11 is required. Most HPC hosts have this version of Python. If your host does not have this version, install it before proceeding. Git is required as well (except for the Minimal Client installation). Git is present on most HPC hosts. For a local host, install Git if it is not present.

Full Client Installation

Clone the repository,


git clone git@github.com:sandialabs/recon3d.git

The preceding git clone command will clone the recon3d repository into your current working directory by making a new folder called recon3d.

Note: use of SSH for cloning may require the user to setup SSH keys in GitHub. Details of this process can be found here.

Change into the recon3d directory,


cd recon3d

Virtual Environment

For all installations, a virtual environment is recommended but not necessary.

HPC users may have to load a module to use Python 3.11, e.g.,


module load python3.11  # or similar command specific to your host

Select an installation path. For example, these instructions show how to install to your home (~) directory.


cd ~                       # change to the destination directory, e.g., home (~)
deactivate                 # deactivate any active virtual environment
rm -rf .venv               # remove any previous virtual environment, e.g., ".venv"
python3.11 -m venv .venv   # create a new virtual environment called ".venv"
                           # with Python version 3.11

Activate the virtual environment based on your shell type,


source .venv/bin/activate       # for bash shell
source .venv/bin/activate.csh   # for c shell
source .venv/bin/activate.fish  # for fish shell
.\.venv\Scripts\activate        # for powershell

`automesh` Prerequisite

If the host has an out-of-date rust compiler, then automesh Python wheel must be built for the specific host,


cd ~/temp
git clone git@github.com:sandialabs/recon3d.git
module load ...
python3.11 -m venv .venv
# pip install build
# python -m build  # makes the .whl
pip install maturin
python3.11 -m maturin build --release -F python -i /usr/bin/python3.11
pip install . --force-reinstall --no-cache-dir
pip install automesh-0.3.1-cp311-cp311-manylinux_2_28_x86_64.whl
twine upload automesh-0.3.1-cp311-cp311-manylinux_2_28_x86_64.whl
pip install --trusted-host pypi.org automesh-0.3.1-cp311-cp311-manylinux_2_28_x86_64.whl

Install `recon3d`

Install the recon3d module,


pip install .

Developer Installation

Follow the instructions for the Full Client Installation, replacing the pip install . command with the following:


pip install -e .[dev]

The -e installs the code in editable form, suitable for development updates.

Minimal Client Installation

Install recon3d from the Python Package Index (PyPI).


pip install recon3d

All Installations

Confirm the installation was successful by running the following from the command line:


recon3d

which will provide the following output:



--------
recon3d
--------

recon3d
    (this command)

binary_to_semantic <path_to_file>.yml
    Converts binary image stack to semantic image stack in a
    folder specified in the user input .yml file.

    Example:
        # Edit path variables in
        # ~/recon3d/docs/userguide/src/binary_to_semantic/binary_to_semantic.yml
        (.venv) recon3d> binary_to_semantic binary_to_semantic.yml

downscale <path_to_file>.yml
    Downscales images in a folder specified in the user input .yml file.

    Example:
        # Edit path variables in
        # ~/recon3d/docs/userguide/src/downscale/downscale_thunder.yml
        (.venv) recon3d> downscale downscale_thunder.yml

grayscale_image_stack_to_segmentation <path_to_file>.yml
    Converts a series of grayscale images to a segmentation.

    Example:
        # Edit path variables in
        # ~/recon3d/docs/userguide/src/utilities/grayscale_image_stack_to_segmentation.yml
        (.venv) recon3d> grayscale_image_stack_to_segmentation grayscale_image_stack_to_segmentation.yml

hello
    Prints 'Hello world!' to the terminal to illustrate command line
    entry points.

image_to_voxel <path_to_file>.yml
    From a single image (or image stack) in a folder specified in the
    user input .yml file, creates a hdf file in the specified
    output folder.

    Example:
        # Edit path variables in
        # ~/recon3d/docs/userguide/src/voxel_to_image/image_to_voxel.yml
        (.venv) recon3d> image_to_voxel image_to_voxel.yml

image_stack_to_array <path_to_file>.yml
    From a series of images in a folder specified in the user input
    .yml file, creates a npy file in the specified output folder.

    Example:
        # Edit path variables in
        # ~/recon3d/docs/userguide/src/utilities/image_stack_to_array.yml
        (.venv) recon3d> image_stack_to_array image_stack_to_array.yml

instance_analysis <path_to_file>.yml
    Digest a semantic segmentation accessible as a folder containing an image
    stack specified in the user input .yml file.

    Example:
        # Edit path variables in
        # ~/recon3d/docs/userguide/src/instance_analysis/instance_analysis.yml
        (.venv) recon3d> instance_analysis instance_analysis.yml

semantic_to_binary <path_to_file>.yml
    Converts semantic image stack to series of binary image stacks in
    a folder specified in the user input .yml file

    Example:
        # Edit path variables in
        # ~/recon3d/docs/userguide/src/binary_to_semantic/semantic_to_binary.yml
        (.venv) recon3d> semantic_to_binary semantic_to_binary.yml

void_descriptor <path_to_file>.yml
    Work in progress.
    From a pore dataset contained within a hdf file specified by
    the input .yml file, compute the void descriptor attributes
    for the void descriptor function.

    Example:
        # Edit path variables in
        # ~/recon3d/docs/userguide/src/void_descriptor/void_descriptor.yml
        (.venv) recon3d> void_descriptor void_descriptor.yml

voxel_to_image <path_to_file>.yml
    From a dataset contained within a hdf file specified by the input
    .yml file, creates an image stack with the same dataset name in
    the specified parent output folder.

    Example:
        # Edit path variables in
        # ~/recon3d/docs/userguide/src/voxel_to_image/voxel_to_image.yml
        (.venv) recon3d> voxel_to_image voxel_to_image.yml

voxel_to_mesh <path_to_file>.yml
    Converts an instance or semantic segmentation, encoded as a .npy file,
    to an Exodus II finite element mesh using automesh.
    See https://autotwin.github.io/automesh/

    Example:
        # Edit path variables in
        # ~/recon3d/docs/userguide/src/voxel_to_mesh/letter_f_3d.yml
        (.venv) recon3d> voxel_to_mesh letter_f_3d.yml

User Guide