Installation

automesh is a single command line program. There is no Python API — there is only one automesh, and every way of installing it produces the exact same command line interface (CLI), with the same subcommands, same flags, same output.

There are two independent, equivalent ways to get automesh onto your machine:

• Rust, via cargo install automesh, which compiles the binary from the source code, or
• Python, via pipx install automesh (or pip install automesh), which installs a prebuilt binary through PyPI.

Neither depends on the other — you don't need Rust installed to use the Python route, and you don't need Python installed to use the Rust route. Pick whichever toolchain you already have set up. The Python route exists for exactly one reason: it lets someone who already has Python and pip on their machine — a data scientist or researcher working with segmentation data, for example — get the automesh CLI without installing Rust and Cargo first. It is not a Python library; import automesh will not work. See Step 2 for the details of what the Python route actually installs.

For macOS and Linux, use a terminal. For Windows, use a Command Prompt (CMD) or PowerShell.

The Rust route links against a netCDF library already present on your system rather than building one — see netCDF Prerequisite below for how to install it on each platform.

Step 1: Install Prerequisites

• The Rust route depends on Rust and Cargo.
  • Cargo is the Rust package manager.
  • Cargo is included with the Rust installation.
• The Python route depends on Python and pip, and works best with pipx, which is the standard tool for installing Python-packaged command line applications.
  • pip is included with the standard installation of Python starting from Python 3.4.
  • pipx itself is installed via pip: pip install pipx (or brew install pipx on macOS, sudo apt install pipx on Debian/Ubuntu).

Rust Prerequisites

It is recommended to install Rust using Rustup, which is an installer and version management tool.

netCDF Prerequisite

automesh links against netCDF rather than building it from source, so a netCDF library must already be on your system before cargo install automesh or cargo build will succeed. This applies to the Rust route, and to the Python route's source-distribution fallback (see Step 2).

Install it with your platform's package manager, the same way the project's own CI does (see .github/workflows/Rust.yml):

macOS

brew install netcdf

Linux (Debian/Ubuntu)

sudo apt-get update && sudo apt-get install -y libnetcdf-dev

Windows

vcpkg install netcdf-c:x64-windows

Then add C:\vcpkg\installed\x64-windows\bin to your PATH so the netCDF DLL can be found at runtime.

Note: the Windows vcpkg install of netCDF is currently unreliable in CI (see the TODO in Rust.yml), so the Windows build is not exercised by continuous integration. If you hit trouble building on Windows, prefer the Python route, which installs a prebuilt binary and does not require a local netCDF install.

Python Prerequisites

macOS

1. Install Homebrew (if you don't have it already). Open the Terminal and run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install Python. After Homebrew is installed, run:

brew install python

3. Verify Python and pip are installed:

python3 --version
pip3 --version

Linux

1. Update Package List. Open a terminal and run:

sudo apt update

2. Install Python and pip. For Ubuntu or Debian-based systems, run:

sudo apt install python3 python3-pip

3. Verify Python and pip are installed:

python3 --version
pip3 --version

Windows

1. Download Python. Go to the official Python website and download the latest version of Python for Windows.
2. Run the Installer. During installation, make sure to check the box that says "Add Python to PATH."
3. Verify Python and pip are installed:

python --version
pip --version

All Environments

On all environments, a virtual environment is recommended, but not required. Create a virtual environment:

python3 -m venv .venv  # venv, or
uv venv .venv          # using uv

uv is a fast Python package manager, written in Rust. It is an alternative to pip.

Activate the virtual environment:

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

Step 2: Install automesh

Install with either route — both put the same automesh binary on your PATH.

Rust: build from source with Cargo

cargo install automesh

Cargo downloads the source from crates.io and compiles it locally.

Python: install a prebuilt binary with pip

pipx install automesh    # recommended, or
pip install automesh     # using pip, or
uv pip install automesh  # using uv

automesh's PyPI project publishes one prebuilt wheel per supported platform, plus a source distribution as a fallback for anything else. As of version 0.4.1, the published files are:

Each wheel's py3-none-<platform> tag is a tell that this isn't a normal Python extension module — a real compiled Python module (built with, say, pyo3) is tagged with a specific interpreter ABI, like cp312-cp312-macosx_.... py3-none means "works with any CPython 3, no Python ABI dependency at all," which is exactly what you'd expect from a wheel that contains nothing but a native executable. That's what maturin's bindings = "bin" mode does: it compiles the ordinary Rust binary, then packages it inside a wheel the same way pip packages any console-script entry point, and installs it straight into your environment's bin/ (or Scripts/ on Windows) directory — no Python import machinery is ever involved.

pipx is recommended over plain pip install because automesh is an application, not a library you'd import into other Python code; pipx installs it into its own isolated environment and adds it to your PATH, the same way you'd expect a CLI tool to be installed, without needing to manage a virtual environment yourself.

Step 3: Verify Installation

Whichever route you used, verification is identical — it's the same program either way.

Run the command line help:

automesh

which should display the following:

     @@@@@@@@@@@@@@@@
      @@@@  @@@@@@@@@@
     @@@@  @@@@@@@@@@@    automesh: Automatic mesh generation
    @@@@  @@@@@@@@@@@@
      @@    @@    @@      v0.4.3 linux x86_64
      @@    @@    @@      build 338a6cd 2026-07-29T18:52:35+0000
    @@@@@@@@@@@@  @@@     Chad B. Hovey <chovey@sandia.gov>
    @@@@@@@@@@@  @@@@     Michael R. Buche <mrbuche@sandia.gov>
    @@@@@@@@@@ @@@@@ @
     @@@@@@@@@@@@@@@@

Usage: automesh [OPTIONS] [COMMAND]

Commands:
  convert    Converts between mesh or segmentation file types
  defeature  Defeatures and creates a new segmentation
  diff       Show the difference between two segmentations
  extract    Extracts a specified range of voxels from a segmentation
  mesh       Creates a finite element mesh from a segmentation
  metrics    Quality metrics for an existing finite element mesh
  remesh     Applies isotropic remeshing to an existing mesh [default mode: uniform]
  segment    Creates a segmentation or voxelized mesh from an existing mesh
  smooth     Applies smoothing to an existing mesh
  help       Print this message or the help of the given subcommand(s)

Options:
      --log <FILE>  Mirror terminal output to a log file
  -q, --quiet       Pass to quiet the terminal output
  -h, --help        Print help
  -V, --version     Print version

There is no Python module to import. If you installed with pipx/pip and want to call automesh from a Python script, invoke it as a subprocess, exactly as you would a Cargo-installed copy:

import subprocess

subprocess.run(["automesh", "mesh", "hex", "-i", "in.npy", "-o", "out.exo", "-r", "0"])

Troubleshooting

netCDF library not found

automesh's build script does not use pkg-config or an environment variable to locate netCDF — it checks a fixed, OS-specific location instead:

If cargo install automesh or cargo build fails with a "Could not find netCDF library" error, the library isn't installed in one of these locations. Reinstall netCDF with the package manager for your platform (see netCDF Prerequisite), which installs to the expected location by default, then retry:

cargo clean
cargo build

Environment Modules

The automesh application can be installed as a service on a High-Performance Computing (HPC) system with the following steps:

Install and Compile Application

automesh must be available and installed to a file location that is accessible by all compute nodes and users who need it.

• Location: Choose a central directory such as /opt/hpc/ or /sw/ for the automesh binaries, libraries, and associated files. For example, let's assume the install path is /opt/hpc/apps/automesh/0.4.1.
• Compilation: Compile automesh and all its dependencies statically if possible, or ensure all shared libraries (.so files) are also included in the installation directory structure.

Create a Module File

The module file, a small script usually written in Tcl or Lua, provides the module load functionality. It tells the shell what changes to make to the user's environment when the module is loaded.

• Location: Module files are placed in a specific directory structure that is scanned by the Environment Modules software (e.g., Lmod or Tcl-based modules). A common path would be /opt/hpc/modules/automesh/0.4.1.

A typical module file would be something like this:

#%Module
# Define the application name and version
set name automesh
set version 0.4.1

# 1. Prerequisite check (e.g., automesh needs a specific compiler)
# If your app needs a specific compiler, you can ensure it's loaded first:
# prereq gcc/11.2

# 2. Update the PATH variable
# This is the most critical step, allowing the user to run 'automesh' command
prepend-path PATH /opt/hpc/apps/$name/$version/bin

# 3. Update the LD_LIBRARY_PATH variable
# Allows the application to find shared libraries if not statically linked
prepend-path LD_LIBRARY_PATH /opt/hpc/apps/$name/$version/lib

# 4. Define other environment variables (optional)
# For configuration files, data paths, etc.
setenv MYAPP_HOME /opt/hpc/apps/$name/$version

# 5. Provide a short description (optional)
module-whatis "Loads $name $version, a high-performance compute application."

System Configuration

Finally, an HPC administrator needs to ensure that the directory containing the new module file is known to the module system. The administrator must add the root of your module directory (e.g., /opt/hpc/modules) to the central module configuration, typically via a command such as:

module use /opt/hpc/modules

This is usually done in a global system profile script so it is active for all users.

End User

Users can discover and load automesh:

• Check for the module: module avail automesh
• Load the service: module load automesh/0.4.1 (or module load automesh if it is the default)
• Run the program: automesh --version