PyPI package

Install Metriplane v0.2.1 as a normal Python package.

The current package release makes the core Metriplane Python packages and command-line interfaces installable from PyPI on Python 3.12 or newer. The frozen v0.2.0 research evidence remains a separate, exact-version artifact.

Open PyPI Open v0.2.1 release Read changelog

v0.2.1 is a packaging and delivery release. It does not modify the frozen v0.2.0 SoftwareX evidence, measurements, or DOI.

Quick start

Create a clean environment and install the exact version.

The commands below install the published package, verify the environment, and exercise a packaged Atlas command without requiring a source checkout.

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "metriplane==0.2.1"

metriplane doctor
metriplane atlas protocol export \
  --out metriplane-protocol

Package boundary

The wheel and the research repository serve different jobs.

A clean PyPI installation is the supported path for the packaged core. Commands that refer to repository directories still require an exact source checkout. Doctor warnings about those absent source-only paths are expected when the command is run from a wheel installation.

Included in the PyPI distribution

Core Metriplane Python packages
The metriplane command-line entry point
The metriplane-run command-line entry point
Runtime dependencies needed by the packaged core

Requires a source checkout

Checked-in demo datasets under datasets/
Domain-pack and example configurations under configs/
The local web dashboard under web/
Maintainer helper scripts under tools/
Frozen evidence and reproduction records under evidence/

v0.2.1 changes

Packaging, dependency, and release verification were made explicit.

The release is deliberately narrow: it improves distribution and release engineering while preserving the previously archived research evidence.

PEP 517 package metadata

The release adds an explicit build system, complete PyPI project links, and distribution metadata sourced from the package itself.

Single version source

metriplane.__version__ is the authoritative package version and is checked against both the distribution metadata and the release tag.

ArUco-ready OpenCV dependency

The package now depends on opencv-contrib-python-headless so the ArUco APIs used by Metriplane are present in a clean installation.

Trusted PyPI publishing

GitHub Actions uses OIDC-based Trusted Publishing: the exact built files are staged on TestPyPI, verified, approved, and then promoted to PyPI without a long-lived API token.

Strict wheel smoke test

The release gate validates metadata, dependencies, package/version identity, cv2.aruco, doctor, and Atlas protocol export from a fresh environment outside the source checkout.

Explicit wheel/source boundary

The PyPI wheel contains the core Python packages and CLI entry points. Checked-in datasets, domain packs, the local dashboard, helper scripts, and frozen evidence still require a source checkout.

Optional extras

Add only the backend or analysis dependencies you need.

gpu-cuda12x

CuPy support for a Linux CUDA 12.x environment.

python -m pip install "metriplane[gpu-cuda12x]==0.2.1"

gpu-cuda13x

CuPy and optional CUDA toolkit support for a Linux CUDA 13.x environment.

python -m pip install "metriplane[gpu-cuda13x]==0.2.1"

plots

Pandas and Matplotlib for plotting and analysis helpers.

python -m pip install "metriplane[plots]==0.2.1"

Release engineering

The same built files move through staging and production.

The tagged release runs the required release gates, checks that the tag and package version agree, builds and validates the distributions, and smoke-tests the wheel outside the checkout. The files are then published to TestPyPI, installed and checked there, approved through the protected production environment, published to PyPI, and installed once more from the production registry.

Inspect publishing workflow Open release runbook

tag on main
-> release gates
-> build wheel + sdist
-> strict metadata validation
-> wheel smoke test
-> TestPyPI publish + install check
-> protected production approval
-> PyPI publish + install check

Distribution provenance

The published files are tied to the release tag and commit.

Wheel SHA-256

f52af60360a149efbd28b1a36ec0908e245ebbf6625be56a8ab2b8aee036b13a

Source distribution SHA-256

70a7038debe2226e95dcb25ee649195b8f1e223c180d0c2ef6fbfb7286d69ed4

Version boundary

Current installation, archived evidence, and benchmark evaluation are not interchangeable.

v0.2.1 package

PyPI packaging and delivery release. Use it for ordinary pip installation and packaged CLI use.

Open current release

v0.2.0 research artifact

Frozen SoftwareX research artifact. Use the exact tag for the SoftwareX reproduction and evidence claims.

Open archived DOI

v0.1.3 evaluated release

Evaluated release for the camera-first planar-twin protocol preprint. Later releases are outside that preprint's experimental boundary.

Open evaluated release