Skip to content

muDM

muDM (micro Data Model) is a GeoJSON-inspired data model for microscopy spatial data — annotations, regions of interest, coordinate systems, and 3D mesh surfaces. It extends GeoJSON with microscopy-specific features while keeping full backwards compatibility: any GeoJSON document is valid muDM, and any muDM document is valid GeoJSON. This is the core data model package: Pydantic v2 models for validating and serializing muDM documents, built on geojson-pydantic, pure Python with no compiled component.

Two packages, one ecosystem

  • mudm — this package: the core data model (Pydantic v2). It is pure Python with no compiled component. Provides mudm.MuDM, mudm.model, mudm.tilemodel, mudm.transforms, mudm.layout, and the provenance models.
  • mudm-tools — a separate package (import name mudm_tools) with the processing pipelines, tiling engines, and format converters, plus an optional Rust acceleration extension mudm_tools._rs. Its documentation lives at https://novagenresearch.github.io/mudm-tools/.

Capabilities

Capability Entry point Guide
Validate & serialize muDM / GeoJSON documents mudm.MuDM, mudm.GeoJSON Getting Started · Validation
Geometry, incl. 3D TIN / PolyhedralSurface mudm.model (TIN, PolyhedralSurface, TiledGeometry) Examples · Specification
Metadata & properties on features mudm.model.MuDMFeature (featureClass, properties, ref) Metadata & Properties
Ontology vocabularies mudm.model.Vocabulary, mudm.model.OntologyTerm Ontology Vocabularies
Coordinate transforms (affine, voxel↔physical) mudm.transforms (AffineTransform, VoxelCoordinateSystem) Coordinate Transforms
Spatial layout (bounds, arranging features) mudm.layout (geometry_bounds, apply_layout) Spatial Layout
Tile & pyramid metadata mudm.tilemodel (TileJSON, TileModel, PyramidJSON) Tile Metadata
Provenance & data lineage mudm.provenance (Workflow, Artifact, MuDMLink) Provenance & Traceability

Where processing happens

Core mudm defines and validates the shape of the data. To build tile pyramids, convert from Xenium/OBJ/GeoJSON, or export GeoParquet / glTF, reach for the separate mudm-tools package — see its documentation site.

Install

pip install mudm

uv add mudm

mudm is pure Python with minimal dependencies and no Rust or compiled component. See Installation for supported Python versions and details.

30-second example

Build a small feature collection, validate it against the muDM root model, and serialize it back to JSON:

from mudm import MuDM, MuDMFeature, MuDMFeatureCollection

# A single annotation: a point labelled "nucleus", classified as a cell.
feature = MuDMFeature(
    type="Feature",
    geometry={"type": "Point", "coordinates": [120.5, 88.0]},
    properties={"label": "nucleus"},
    featureClass="cell",
)

# Group features into a collection.
collection = MuDMFeatureCollection(
    type="FeatureCollection",
    features=[feature],
)

# Validate the whole document against the muDM root model.
doc = MuDM.model_validate(collection.model_dump())

# Serialize back to the wire format (camelCase fields like featureClass).
print(doc.model_dump_json(exclude_none=True, indent=2))

This prints a document that is, by construction, also a valid GeoJSON FeatureCollection — the only addition here is the optional featureClass field.

Validating data you already have

If you have a dict or JSON loaded from disk, validate it directly with MuDM.model_validate(data) (or MuDMFeatureCollection.model_validate(data)). See Validation for error handling and strictness.

Where to next