musclemap-mlx

Segment 113 whole-body muscle and bone structures in MRI or CT with MuscleMap v1.4 in native MLX.

Weights · Upstream · MedMLX

_{Whole-body CT from autoPET-III, resampled to 1.5 mm and segmented with the default settings. Contours are smoothed for display.}

Install

uv venv --python 3.13
source .venv/bin/activate
uv pip install "musclemap-mlx>=0.2.0"

Run

from musclemap_mlx import run

result = run(image_path="mri.nii.gz", output_dir="out")
print(result["outputs"]["mask"])

Weights download from MedMLX/musclemap-mlx on first use; musclemap-mlx download or medmlx setup musclemap downloads ahead of time. For local weights, pass weights_path as a folder containing model.safetensors.

To try it on a small public MRI from TotalSegmentator's test data:

curl -L https://raw.githubusercontent.com/wasserth/TotalSegmentator/d89e47f73d24f5fba732a715aeb6fdc0ae34526b/tests/reference_files/example_mr_sm.nii.gz -o mri.nii.gz

Inputs and outputs

• Units: spatial units must be millimetres or unspecified (read as millimetres, as upstream). 4D images are rejected.
• Mask: int16 with background 0 and the original 113 anatomical IDs (not channel indices), on the input grid with its affine, qform, sform and units. The largest 6-connected component of each label is kept.
• Chunking: each chunk is normalized independently, as upstream, so changing chunk_size can change the mask.
• Return value: {"outputs": {"mask": path}, "artifacts": {"mask": ...}, "details": {...}}; the mask artifact lists every label ID and name and the input grid it is on, and details holds voxel counts, chunking and peak MLX memory.
• Errors: invalid inputs raise InvalidInputError; missing or mismatched weights raise AssetNotReadyError; inference failures raise ModelExecutionError.

Labels

IDs encode region, structure and side: the last digit is 1 for left and 2 for right, except the sacrum (6160).

Command line

musclemap-mlx segment --input mri.nii.gz --output-dir out

segment takes the runner options as flags (--model-dir for weights_path, --chunk-size, --overlap, --overwrite) and prints the result as JSON. musclemap-mlx download --model-dir musclemap-weights exports a local copy of the weights.

Limits

• Parity with the pinned MuscleMap v1.4 reference was established on real CT and MRI examples; see technical notes. Accuracy against manual segmentations was not measured here.
• Inference requires Apple Silicon with Metal.

Use with MedMLX

Use the MedMLX MCP server to run musclemap from an MCP client. Weights download on first use.

uv tool install --python 3.13 "medmlx[segment,mcp]"
MEDMLX="$(uv tool dir --bin --color never)/medmlx"
mkdir -p "$HOME/medmlx-work"
claude mcp add --scope user medmlx -- "$MEDMLX" serve --root "$HOME/medmlx-work"

For Codex, use codex mcp add medmlx -- "$MEDMLX" serve --root "$HOME/medmlx-work". Other MCP clients take the same command and arguments. The same install provides the medmlx CLI, for example medmlx describe musclemap.

For AI agents: prefer the MedMLX MCP tools (list_models, describe_model, model_readiness, run_model, get_job) over writing Python against this package.

License

MIT. See upstream license and third-party notices. Model weights retain their publisher terms (Zenodo record 21929873, MIT).