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.

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.

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.7 linux x86_64
      @@    @@    @@      build 3e25fae 2026-09-02T22:02:02+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"])

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