mudm 0.5.0__py3-none-any.whl

mudm/__init__.py

@@ -0,0 +1,24 @@
+"""muDM (micro Data Model) — a GeoJSON-inspired data model for microscopy."""
+
+from .model import MuDM, GeoJSON  # noqa: F401
+from .model import MuDMFeature, MuDMFeatureCollection  # noqa: F401
+from .model import (  # noqa: F401
+    TiledGeometry,
+    PolyhedralSurface,
+    TIN,
+    OntologyTerm,
+    Vocabulary,
+)
+from .tilemodel import TileJSON, TileModel, TileLayer  # noqa: F401
+from .tilemodel import PyramidEntry, PyramidJSON  # noqa: F401
+from .transforms import (  # noqa: F401
+    AffineTransform,
+    VoxelCoordinateSystem,
+    apply_transform,
+    translate_geometry,
+    voxel_to_physical,
+    physical_to_voxel,
+)
+from .layout import geometry_bounds, apply_layout  # noqa: F401
+
+__version__ = "0.5.0"

mudm/layout.py

@@ -0,0 +1,276 @@
+"""Shared layout module for MuDM feature collections.
+
+Computes spatial offsets (row or grid) and applies them by translating
+MuDM geometry coordinates directly. This makes layout reusable
+across all exporters (glTF, Neuroglancer, Arrow/Parquet).
+"""
+
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+from geojson_pydantic import Polygon, MultiPolygon
+
+from .model import (
+    MuDMFeature,
+    MuDMFeatureCollection,
+)
+from .transforms import translate_geometry
+
+# (xmin, ymin, zmin, xmax, ymax, zmax) — OGC/GeoJSON bbox ordering
+Bounds = tuple[float, float, float, float, float, float]
+
+# Translation offset
+Offset3 = tuple[float, float, float]
+
+
+# ---------------------------------------------------------------------------
+# Bounding box computation
+# ---------------------------------------------------------------------------
+
+def _collect_xyz_from_coords(
+    coords: Any,
+    xs: list[float],
+    ys: list[float],
+    zs: list[float],
+) -> None:
+    """Recursively extract X/Y/Z from nested GeoJSON coordinate arrays."""
+    if not coords:
+        return
+    if isinstance(coords[0], (int, float)):
+        xs.append(float(coords[0]))
+        ys.append(float(coords[1]) if len(coords) > 1 else 0.0)
+        zs.append(float(coords[2]) if len(coords) > 2 else 0.0)
+    else:
+        for item in coords:
+            _collect_xyz_from_coords(item, xs, ys, zs)
+
+
+def geometry_bounds(geom: Any) -> Bounds | None:
+    """Return 3-D bounding box as (xmin, ymin, zmin, xmax, ymax, zmax).
+
+    Uses ``.bbox3d()`` for 3D types (TIN,
+    PolyhedralSurface) and recursive coordinate extraction
+    for GeoJSON types.
+
+    Returns None if the geometry is empty or None.
+    """
+    if geom is None:
+        return None
+
+    # 3D types with bbox3d() — returns (xmin, ymin, zmin, xmax, ymax, zmax)
+    if hasattr(geom, "bbox3d"):
+        try:
+            return geom.bbox3d()
+        except (ValueError, IndexError):
+            return None
+
+    # GeoJSON types with .coordinates
+    if not hasattr(geom, "coordinates"):
+        return None
+
+    xs: list[float] = []
+    ys: list[float] = []
+    zs: list[float] = []
+    _collect_xyz_from_coords(geom.coordinates, xs, ys, zs)
+
+    if not xs:
+        return None
+    return (min(xs), min(ys), min(zs), max(xs), max(ys), max(zs))
+
+
+# ---------------------------------------------------------------------------
+# Layout algorithms
+# ---------------------------------------------------------------------------
+
+def _row_layout(
+    bounds: list[Bounds | None],
+    spacing: float,
+) -> list[Offset3]:
+    """Place features side-by-side along X."""
+    n = len(bounds)
+    widths = [(b[3] - b[0]) if b else 0.0 for b in bounds]  # xmax - xmin
+    max_width = max(widths) if widths else 0.0
+    gap = spacing if spacing > 0 else max_width * 0.2
+
+    offsets: list[Offset3] = [(0.0, 0.0, 0.0)] * n
+    cursor = bounds[0][3] if bounds[0] else gap  # xmax of first feature
+
+    for i in range(1, n):
+        b = bounds[i]
+        if b is None:
+            dx = cursor + gap
+            offsets[i] = (dx, 0.0, 0.0)
+            cursor = dx
+            continue
+        dx = (cursor + gap) - b[0]  # shift so xmin aligns to cursor + gap
+        offsets[i] = (dx, 0.0, 0.0)
+        cursor = b[3] + dx  # new xmax position
+
+    return offsets
+
+
+def _grid_layout(
+    bounds: list[Bounds | None],
+    spacing: float,
+    grid_max_x: int | None,
+    grid_max_y: int | None,
+    grid_max_z: int | None,
+    n: int,
+) -> list[Offset3]:
+    """Place features on a uniform grid that wraps X -> Y -> Z.
+
+    ``grid_max_x/y/z`` give the number of cells per axis directly.
+    """
+    # Bounds format: (xmin, ymin, zmin, xmax, ymax, zmax)
+    widths = [(b[3] - b[0]) if b else 0.0 for b in bounds]
+    heights = [(b[4] - b[1]) if b else 0.0 for b in bounds]
+    depths = [(b[5] - b[2]) if b else 0.0 for b in bounds]
+
+    max_w = max(widths) if widths else 0.0
+    max_h = max(heights) if heights else 0.0
+    max_d = max(depths) if depths else 0.0
+
+    max_extent = max(max_w, max_h, max_d)
+
+    if spacing > 0:
+        # Fixed cell size — center-to-center distance, ignores extent
+        cell_x = spacing
+        cell_y = spacing
+        cell_z = spacing
+    else:
+        # Auto: 20% gap on top of max extent per axis
+        gap = max_extent * 0.2 if max_extent > 0 else 1.0
+        cell_x = max_w + gap
+        cell_y = max_h + gap
+        cell_z = max_d + gap
+
+    # Grid dimensions — values are cell counts, unlimited when None
+    cols = grid_max_x if grid_max_x is not None else n
+    rows = (
+        grid_max_y
+        if grid_max_y is not None
+        else max(1, -(-n // cols))
+    )
+    layers = (
+        grid_max_z
+        if grid_max_z is not None
+        else max(1, -(-n // (cols * rows)))
+    )
+
+    capacity = cols * rows * layers
+    if n > capacity:
+        raise ValueError(
+            f"Cannot fit {n} features in grid "
+            f"({cols} cols \u00d7 {rows} rows \u00d7 {layers} layers "
+            f"= {capacity} cells). "
+            f"Increase grid_max_x/y/z or reduce feature count."
+        )
+
+    # Feature 0 is the reference point; others are placed relative to it
+    ref = bounds[0]
+    ref_cx = (ref[0] + ref[3]) / 2 if ref else 0.0  # (xmin + xmax) / 2
+    ref_cy = (ref[1] + ref[4]) / 2 if ref else 0.0  # (ymin + ymax) / 2
+    ref_cz = (ref[2] + ref[5]) / 2 if ref else 0.0  # (zmin + zmax) / 2
+
+    offsets: list[Offset3] = [(0.0, 0.0, 0.0)]
+
+    for i in range(1, n):
+        col = i % cols
+        row = (i // cols) % rows
+        layer = i // (cols * rows)
+
+        target_cx = ref_cx + col * cell_x
+        target_cy = ref_cy + row * cell_y
+        target_cz = ref_cz + layer * cell_z
+
+        b = bounds[i]
+        feat_cx = (b[0] + b[3]) / 2 if b else 0.0
+        feat_cy = (b[1] + b[4]) / 2 if b else 0.0
+        feat_cz = (b[2] + b[5]) / 2 if b else 0.0
+
+        offsets.append((
+            target_cx - feat_cx,
+            target_cy - feat_cy,
+            target_cz - feat_cz,
+        ))
+
+    return offsets
+
+
+def compute_collection_offsets(
+    features: list[MuDMFeature],
+    spacing: float | None = None,
+    grid_max_x: int | None = None,
+    grid_max_y: int | None = None,
+    grid_max_z: int | None = None,
+) -> list[Offset3]:
+    """Compute 3-D translation for each feature in a collection.
+
+    Returns a list of (dx, dy, dz) offsets in source coordinates.
+    The first feature always stays at its original position.
+
+    When *spacing* is ``None`` and no grid parameters are set, all
+    offsets are zero (coordinates are kept as-is).
+    """
+    n = len(features)
+    if n <= 1:
+        return [(0.0, 0.0, 0.0)] * n
+
+    has_grid = (
+        grid_max_x is not None
+        or grid_max_y is not None
+        or grid_max_z is not None
+    )
+
+    # No layout requested — keep coordinates as-is
+    if spacing is None and not has_grid:
+        return [(0.0, 0.0, 0.0)] * n
+
+    effective_spacing = spacing if spacing is not None else 0.0
+
+    bounds = [
+        geometry_bounds(f.geometry) if f.geometry else None
+        for f in features
+    ]
+
+    if has_grid:
+        return _grid_layout(bounds, effective_spacing, grid_max_x, grid_max_y, grid_max_z, n)
+    return _row_layout(bounds, effective_spacing)
+
+
+def apply_layout(
+    collection: MuDMFeatureCollection,
+    spacing: float | None = None,
+    grid_max_x: int | None = None,
+    grid_max_y: int | None = None,
+    grid_max_z: int | None = None,
+) -> MuDMFeatureCollection:
+    """Apply spatial layout to a collection, returning a new collection.
+
+    Computes offsets and translates each feature's geometry coordinates
+    directly. The returned collection is a copy — the original is not
+    modified.
+    """
+    features = list(collection.features)
+    offsets = compute_collection_offsets(
+        features, spacing, grid_max_x, grid_max_y, grid_max_z,
+    )
+
+    new_features = []
+    for feat, (dx, dy, dz) in zip(features, offsets):
+        if abs(dx) < 1e-12 and abs(dy) < 1e-12 and abs(dz) < 1e-12:
+            new_features.append(feat)
+            continue
+
+        if feat.geometry is None:
+            new_features.append(feat)
+            continue
+
+        new_geom = translate_geometry(feat.geometry, dx, dy, dz)
+        # Build a new feature with translated geometry
+        new_feat = feat.model_copy(update={"geometry": new_geom})
+        new_features.append(new_feat)
+
+    return collection.model_copy(update={"features": new_features})

mudm/model.py

@@ -0,0 +1,255 @@
+"""MuDM and GeoJSON models, defined manually using pydantic."""
+
+from typing import Any, List, Literal, Optional, Tuple, Union, Dict
+from pydantic import BaseModel, StrictInt, StrictStr, RootModel, field_validator, model_validator
+from .provenance import Workflow
+from .provenance import WorkflowCollection
+from .provenance import Artifact
+from .provenance import ArtifactCollection
+from geojson_pydantic import Feature, FeatureCollection, GeometryCollection
+from geojson_pydantic import Point, MultiPoint, LineString, MultiLineString
+from geojson_pydantic import Polygon, MultiPolygon
+from geojson_pydantic.types import (
+    Position,
+    LinearRing,
+    PolygonCoords,
+    MultiPolygonCoords,
+)
+
+
+# ---------------------------------------------------------------------------
+# Helper: extract all 3D positions from nested coordinate structures
+# ---------------------------------------------------------------------------
+
+def _iter_positions(coords: list) -> list[Position]:
+    """Recursively flatten nested coordinate arrays to a list of positions."""
+    if not coords:
+        return []
+    # If the first element is a number, this is a single position
+    if isinstance(coords[0], (int, float)):
+        return [tuple(coords)]  # type: ignore[return-value]
+    # If the first element is a tuple/namedtuple, this is a list of positions
+    if isinstance(coords[0], tuple) and isinstance(coords[0][0], (int, float)):
+        return list(coords)  # type: ignore[return-value]
+    # Otherwise, recurse
+    result: list[Position] = []
+    for item in coords:
+        result.extend(_iter_positions(item))
+    return result
+
+
+def _bbox3d(coords: list) -> Tuple[float, float, float, float, float, float]:
+    """Compute 3D bounding box from nested coordinate arrays."""
+    positions = _iter_positions(coords)
+    xs = [p[0] for p in positions]
+    ys = [p[1] for p in positions]
+    zs = [p[2] for p in positions]
+    return (min(xs), min(ys), min(zs), max(xs), max(ys), max(zs))
+
+
+def _centroid3d(coords: list) -> Tuple[float, float, float]:
+    """Compute centroid of unique 3D positions from nested coordinate arrays."""
+    positions = _iter_positions(coords)
+    unique = list({(float(p[0]), float(p[1]), float(p[2])) for p in positions})
+    n = len(unique)
+    return (
+        sum(p[0] for p in unique) / n,
+        sum(p[1] for p in unique) / n,
+        sum(p[2] for p in unique) / n,
+    )
+
+
+# ---------------------------------------------------------------------------
+# 3D Geometry Types
+# ---------------------------------------------------------------------------
+
+class TiledGeometry(BaseModel):
+    """Base for geometry types that reference external tiled data.
+
+    When data is stored in external tiles, coordinates may be empty and
+    the tiles field lists the spatial tile identifiers.
+    """
+    tiles: Optional[List[str]] = None
+
+
+class PolyhedralSurface(TiledGeometry):
+    """A closed surface mesh consisting of polygonal faces (ISO 19107).
+
+    Each face has the same structure as a Polygon: a list of linear rings,
+    where each ring is a list of 3D positions.
+    """
+
+    type: Literal["PolyhedralSurface"]
+    coordinates: List[PolygonCoords] = []
+
+    @field_validator("coordinates")
+    @classmethod
+    def _validate_faces(cls, v: List[PolygonCoords]) -> List[PolygonCoords]:
+        return v  # allow empty when tiles present
+
+    @model_validator(mode="after")
+    def _require_data_source(self):
+        if not self.coordinates and not self.tiles:
+            raise ValueError("PolyhedralSurface requires either coordinates or tiles")
+        return self
+
+    def bbox3d(self) -> Optional[Tuple[float, float, float, float, float, float]]:
+        if not self.coordinates:
+            return None
+        return _bbox3d(self.coordinates)
+
+    def centroid3d(self) -> Optional[Tuple[float, float, float]]:
+        if not self.coordinates:
+            return None
+        return _centroid3d(self.coordinates)
+
+
+class TIN(TiledGeometry):
+    """A Triangulated Irregular Network — triangle mesh surface (ISO 19107).
+
+    Each face must be a single closed ring of exactly 4 positions
+    (3 vertices + repeated first vertex).
+    """
+
+    type: Literal["TIN"]
+    coordinates: List[PolygonCoords] = []
+
+    @field_validator("coordinates")
+    @classmethod
+    def _validate_triangles(cls, v: List[PolygonCoords]) -> List[PolygonCoords]:
+        if len(v) == 0:
+            return v  # empty OK when tiles are present
+        for i, face in enumerate(v):
+            if len(face) != 1:
+                raise ValueError(
+                    f"TIN face {i} must have exactly one ring, got {len(face)}"
+                )
+            ring = face[0]
+            if len(ring) != 4:
+                raise ValueError(
+                    f"TIN face {i} ring must have exactly 4 positions "
+                    f"(closed triangle), got {len(ring)}"
+                )
+        return v
+
+    @model_validator(mode="after")
+    def _require_data_source(self):
+        if not self.coordinates and not self.tiles:
+            raise ValueError("TIN requires either coordinates or tiles")
+        return self
+
+    def bbox3d(self) -> Optional[Tuple[float, float, float, float, float, float]]:
+        if not self.coordinates:
+            return None
+        return _bbox3d(self.coordinates)
+
+    def centroid3d(self) -> Optional[Tuple[float, float, float]]:
+        if not self.coordinates:
+            return None
+        return _centroid3d(self.coordinates)
+
+
+
+# ---------------------------------------------------------------------------
+# Ontology Vocabulary Support
+# ---------------------------------------------------------------------------
+
+class OntologyTerm(BaseModel):
+    """A reference to a formal ontology term.
+
+    Attributes:
+        uri: Full URI of the ontology term (e.g. "http://purl.obolibrary.org/obo/CL_0000598").
+        label: Human-readable label (e.g. "pyramidal neuron").
+        description: Optional longer description of the term.
+    """
+    uri: str
+    label: Optional[str] = None
+    description: Optional[str] = None
+
+
+class Vocabulary(BaseModel):
+    """Maps property values to formal ontology terms.
+
+    Attributes:
+        namespace: Common URI prefix for the ontology (e.g. "http://purl.obolibrary.org/obo/CL_").
+        description: Optional description of this vocabulary.
+        terms: Mapping from property values to ontology terms.
+    """
+    namespace: Optional[str] = None
+    description: Optional[str] = None
+    terms: Dict[str, OntologyTerm]
+
+
+GeometryType = Union[  # type: ignore
+    Point,
+    MultiPoint,
+    LineString,
+    MultiLineString,
+    Polygon,
+    MultiPolygon,
+    GeometryCollection,
+    PolyhedralSurface,
+    TIN,
+    type(None),
+]
+
+
+class GeoJSON(RootModel):
+    """The root object of a GeoJSON file"""
+
+    root: Union[Feature, FeatureCollection, GeometryType]  # type: ignore
+
+
+class MuDMFeature(Feature):
+    """A MuDM feature, which is a GeoJSON feature with additional
+    metadata
+
+    Args:
+        geometry (Optional[GeometryType]): Extended geometry supporting 3D types
+        multiscale (Optional[Multiscale]): The coordinate system of the feature
+        ref (Optional[Union[StrictStr, StrictInt]]):
+            A reference to the parent feature
+        parentId (Optional[Union[StrictStr, StrictInt]]):
+            A reference to the parent feature
+        featureClass (Optional[str]): The class of the feature
+    """
+
+    # Override geometry to accept MuDM 3D types in addition to GeoJSON types
+    geometry: Union[GeometryType, None]  # type: ignore[assignment]
+    ref: Optional[Union[StrictStr, StrictInt]] = None
+    # reference to the parent feature
+    parentId: Optional[Union[StrictStr, StrictInt]] = None
+    # for now, only string feature class is supported
+    # in the future, it may be expanded with a class registry
+    featureClass: Optional[str] = None
+    vocabularies: Optional[Union[Dict[str, Vocabulary], str]] = None
+
+
+class MuDMFeatureCollection(FeatureCollection):
+    """A MuDM feature collection, which is a GeoJSON feature
+    collection with additional metadata.
+
+    Args:
+        features (List[MuDMFeature]): Features with extended 3D geometry support
+        properties (Optional[Props]): The properties of the feature collection
+        id (Optional[Union[StrictStr, StrictInt]]): The ID of the feature coll.
+        provenance (Optional[Union[Workflow,
+            WorkflowCollection,
+            Artifact,
+            ArtifactCollection]]): The provenance of the feature collection
+    """
+
+    # Override features to use MuDMFeature (supports 3D geometry types)
+    features: List[MuDMFeature]  # type: ignore[assignment]
+    properties: Optional[Dict[str, Any]] = None
+    id: Optional[Union[StrictStr, StrictInt]] = None
+    provenance: Optional[
+        Union[Workflow, WorkflowCollection, Artifact, ArtifactCollection]
+    ] = None
+    vocabularies: Optional[Union[Dict[str, Vocabulary], str]] = None
+
+
+class MuDM(RootModel):
+    """The root object of a MuDM file"""
+
+    root: Union[MuDMFeature, MuDMFeatureCollection, GeometryType]  # type: ignore

mudm/provenance.py

@@ -0,0 +1,46 @@
+from pydantic import BaseModel
+from typing import List, Optional, Dict, Union, Literal
+
+
+class MuDMLink(BaseModel):
+    """A link to a MuDM object"""
+    mudmId: Union[str, List[str]]
+    mudmField: Optional[str] = None
+
+
+class Artifact(BaseModel):
+    """Artifact object representing a single file or directory"""
+    id: Optional[str] = None
+    type: Literal["Artifact"]
+    uri: str
+    properties: Optional[Dict[str, Union[str, float, int]]] = None
+    mudmLinks: List['MuDMLink']
+
+
+class ArtifactCollection(BaseModel):
+    """ArtifactCollection object representing a collection of files or
+     directories"""
+    type: Literal["ArtifactCollection"]
+    artifacts: List[Artifact]
+
+
+class Workflow(BaseModel):
+    """Workflow object representing a single workflow"""
+    id: Optional[str] = None
+    type: Literal["Workflow"]
+    properties: Optional[Dict[str, Union[str, float, int]]] = None
+    subWorkflows: Optional[List['Workflow']] = None
+    workflowProvenance: Optional['WorkflowProvenance'] = None
+
+
+class WorkflowProvenance(BaseModel):
+    """WorkflowProvenance object representing an execution of a workflow"""
+    type: Literal["WorkflowProvenance"]
+    properties: Optional[Dict[str, Union[str, float, int]]] = None
+    outputArtifacts: Optional[Union[Artifact, ArtifactCollection]] = None
+
+
+class WorkflowCollection(BaseModel):
+    """WorkflowCollection object representing a collection of workflows"""
+    type: Literal["WorkflowCollection"]
+    workflows: List[Workflow]

mudm/tilemodel.py

@@ -0,0 +1,235 @@
+from typing import List, Optional, Union, Dict, Literal
+from enum import StrEnum
+from pydantic import BaseModel, AnyUrl, conlist, RootModel
+from pydantic import StrictStr
+from pathlib import Path
+
+from .model import Vocabulary
+
+
+class TileLayer(BaseModel):
+    """A vector layer in a TileJSON file.
+
+    Args:
+        id (str): The unique identifier for the layer.
+        fields (Union[None, Dict[str, str]]): The fields in the layer.
+        minzoom (Optional[int]): The minimum zoom level for the layer.
+        maxzoom (Optional[int]): The maximum zoom level for the layer.
+        description (Optional[str]): A description of the layer.
+        fieldranges (Optional[Dict[str, List[Union[int, float, str]]]]):
+            The ranges of the fields.
+        fieldenums (Optional[Dict[str, List[str]]]):
+            The enums of the fields.
+        fielddescriptions (Optional[Dict[str, str]]):
+            The descriptions of the fields.
+        vocabularies (Optional[Dict[str, Vocabulary]]):
+            Ontology vocabularies mapping property values to formal terms.
+    """
+
+    id: str
+    fields: Union[None, Dict[str, str]] = None
+    minzoom: Optional[int] = 0
+    maxzoom: Optional[int] = 22
+    description: Optional[str] = None
+    fieldranges: Optional[Dict[str, List[Union[int, float, str]]]] = None
+    fieldenums: Optional[Dict[str, List[str]]] = None
+    fielddescriptions: Optional[Dict[str, str]] = None
+    vocabularies: Optional[Dict[str, Vocabulary]] = None
+
+
+class Unit(StrEnum):
+    """A unit of measurement"""
+
+    ANGSTROM = "angstrom"
+    ATTOMETER = "attometer"
+    CENTIMETER = "centimeter"
+    DECIMETER = "decimeter"
+    EXAMETER = "exameter"
+    FEMTOMETER = "femtometer"
+    FOOT = "foot"
+    GIGAMETER = "gigameter"
+    HECTOMETER = "hectometer"
+    INCH = "inch"
+    KILOMETER = "kilometer"
+    MEGAMETER = "megameter"
+    METER = "meter"
+    MICROMETER = "micrometer"
+    MILE = "mile"
+    MILLIMETER = "millimeter"
+    NANOMETER = "nanometer"
+    PARSEC = "parsec"
+    PETAMETER = "petameter"
+    PICOMETER = "picometer"
+    TERAMETER = "terameter"
+    YARD = "yard"
+    YOCTOMETER = "yoctometer"
+    YOTTAMETER = "yottameter"
+    ZEPTOMETER = "zeptometer"
+    ZETTAMETER = "zettameter"
+    PIXEL = "pixel"
+    RADIAN = "radian"
+    DEGREE = "degree"
+
+
+class AxisType(StrEnum):
+    """The type of an axis"""
+
+    SPACE = "space"
+    TIME = "time"
+    CHANNEL = "channel"
+
+
+class Axis(BaseModel):
+    """An axis of a coordinate system
+
+    Args:
+        name (StrictStr): The name of the axis
+        type (Optional[AxisType]): The type of the axis
+        unit (Optional[Unit]): The unit of the axis
+        description (Optional[str]): A description of the axis
+    """
+
+    name: StrictStr
+    type: Optional[AxisType] = None
+    unit: Optional[Unit] = None
+    description: Optional[str] = None
+
+
+class CoordinateTransformation(BaseModel):
+    """Coordinate transformation abstract class
+    harmonized with the OME model"""
+
+
+class Identity(CoordinateTransformation):
+    """Identity transformation for coordinates
+
+    Args:
+        type (Literal["identity"]): The type of the transformation
+    """
+
+    type: Literal["identity"] = "identity"
+
+
+class Translation(CoordinateTransformation):
+    """Translation transformation
+
+    Args:
+        type (Literal["translation"]): The type of the transformation
+        translation (List[float]): The translation vector
+    """
+
+    type: Literal["translation"] = "translation"
+    translation: List[float]
+
+
+class Scale(CoordinateTransformation):
+    """Scale transformation
+
+    Args:
+        type (Literal["scale"]): The type of the transformation
+        scale (List[float]): The scale vector
+    """
+
+    type: Literal["scale"] = "scale"
+    scale: List[float]
+
+
+class Multiscale(BaseModel):
+    """A coordinate system for MuDM coordinates
+
+    Args:
+        axes (List[Axis]): The axes of the coordinate system
+        coordinateTransformations (Optional[List[CoordinateTransformation]]):
+            A list of coordinate transformations
+        transformationMatrix (Optional[List[List[float]]):
+            The transformation matrix
+    """
+
+    axes: List[Axis]
+    coordinateTransformations: Optional[List[CoordinateTransformation]] = None
+    transformationMatrix: Optional[List[List[float]]] = None
+
+
+class TileModel(BaseModel):
+    """A TileJSON object.
+
+    Args:
+        tilejson (str): The TileJSON version.
+        tiles (List[Union[Path, AnyUrl]]): The list of tile URLs.
+        name (Optional[str]): The name of the tileset.
+        description (Optional[str]): The description of the tileset.
+        version (Optional[str]): The version of the tileset.
+        attribution (Optional[str]): The attribution of the tileset.
+        template (Optional[str]): The template of the tileset.
+        legend (Optional[str]): The legend of the tileset.
+        scheme (Optional[str]): The scheme of the tileset.
+        grids (Optional[Union[Path, AnyUrl]]): The grids of the tileset.
+        data (Optional[Union[Path, AnyUrl]]): The data of the tileset.
+        minzoom (Optional[int]): The minimum zoom level of the tileset.
+        maxzoom (Optional[int]): The maximum zoom level of the tileset.
+        bounds (Optional[conlist(float, min_length=4, max_length=10)]):
+            The bounds of the tileset.
+        center (Optional[conlist(float, min_length=3, max_length=6)]):
+            The center of the tileset.
+        fillzoom (Optional[int]): The fill zoom level of the tileset.
+        vector_layers (List[TileLayer]): The vector layers of the tileset.
+
+    """
+
+    tilejson: str
+    tiles: List[Union[Path, AnyUrl]]
+    name: Optional[str] = None
+    description: Optional[str] = None
+    version: Optional[str] = None
+    attribution: Optional[str] = None
+    template: Optional[str] = None
+    legend: Optional[str] = None
+    scheme: Optional[str] = None
+    grids: Optional[Union[Path, AnyUrl]] = None
+    data: Optional[Union[Path, AnyUrl]] = None
+    minzoom: Optional[int] = 0
+    maxzoom: Optional[int] = 22
+    bounds: Optional[conlist(float, min_length=4, max_length=10)] = None  # type: ignore
+    center: Optional[conlist(float, min_length=3, max_length=6)] = None  # type: ignore
+    fillzoom: Optional[int] = None
+    vector_layers: List[TileLayer]
+    multiscale: Optional[Multiscale] = None
+    scale_factor: Optional[float] = None
+
+
+class TileJSON(RootModel):
+    """The root object of a TileJSON file."""
+
+    root: TileModel
+
+
+class PyramidEntry(BaseModel):
+    """One pyramid in a PyramidJSON manifest.
+
+    Attributes:
+        id: Unique identifier for this pyramid (used as directory name).
+        label: Human-readable display label.
+        tilejson: Relative path to TileModel3D metadata file.
+        features: Relative path to MuDM FeatureCollection.
+        tiles: Total number of tile files.
+        feature_count: Number of unique features.
+        size_bytes: Total size on disk in bytes.
+    """
+    id: str
+    label: Optional[str] = None
+    tilejson: str = "tilejson3d.json"
+    features: Optional[str] = "features.json"
+    tiles: Optional[int] = None
+    feature_count: Optional[int] = None
+    size_bytes: Optional[int] = None
+
+
+class PyramidJSON(BaseModel):
+    """Root manifest listing all available pyramids.
+
+    Attributes:
+        version: Manifest format version.
+        pyramids: List of pyramid entries.
+    """
+    version: str = "1.0"
+    pyramids: List[PyramidEntry]

mudm/transforms.py

@@ -0,0 +1,201 @@
+"""3D coordinate transforms for MuDM.
+
+Provides AffineTransform (4x4 matrix), VoxelCoordinateSystem, and helper
+functions for coordinate conversion. Extends the existing transformation
+patterns in tilemodel.py.
+"""
+
+from __future__ import annotations
+
+from typing import List, Literal, Tuple, Union
+
+from pydantic import BaseModel, field_validator
+from geojson_pydantic import (
+    Point,
+    MultiPoint,
+    LineString,
+    MultiLineString,
+    Polygon,
+    MultiPolygon,
+)
+
+from .tilemodel import CoordinateTransformation
+from .model import (
+    TIN,
+    PolyhedralSurface,
+)
+
+
+class AffineTransform(CoordinateTransformation):
+    """A 4x4 affine transformation matrix for 3D coordinates.
+
+    The matrix is stored in row-major order:
+        [[r00, r01, r02, tx],
+         [r10, r11, r12, ty],
+         [r20, r21, r22, tz],
+         [0,   0,   0,   1 ]]
+    """
+
+    type: Literal["affine"] = "affine"
+    matrix: List[List[float]]
+
+    @field_validator("matrix")
+    @classmethod
+    def _validate_4x4(cls, v: List[List[float]]) -> List[List[float]]:
+        if len(v) != 4:
+            raise ValueError(f"Affine matrix must have 4 rows, got {len(v)}")
+        for i, row in enumerate(v):
+            if len(row) != 4:
+                raise ValueError(
+                    f"Affine matrix row {i} must have 4 columns, got {len(row)}"
+                )
+        return v
+
+
+class VoxelCoordinateSystem(BaseModel):
+    """Defines voxel-to-physical coordinate mapping.
+
+    Physical coordinate = voxel * resolution + origin
+    """
+
+    axes: List[str]
+    units: List[str]
+    resolution: List[float]
+    origin: List[float] = [0.0, 0.0, 0.0]
+
+
+# ---------------------------------------------------------------------------
+# Helper functions
+# ---------------------------------------------------------------------------
+
+def _transform_position(
+    pos: tuple, matrix: List[List[float]]
+) -> tuple:
+    """Apply a 4x4 affine matrix to a single position (2D or 3D)."""
+    x = float(pos[0])
+    y = float(pos[1]) if len(pos) > 1 else 0.0
+    z = float(pos[2]) if len(pos) > 2 else 0.0
+    nx = matrix[0][0] * x + matrix[0][1] * y + matrix[0][2] * z + matrix[0][3]
+    ny = matrix[1][0] * x + matrix[1][1] * y + matrix[1][2] * z + matrix[1][3]
+    nz = matrix[2][0] * x + matrix[2][1] * y + matrix[2][2] * z + matrix[2][3]
+    if len(pos) <= 2:
+        return (nx, ny)
+    return (nx, ny, nz)
+
+
+def _transform_coords(coords, matrix: List[List[float]]):
+    """Recursively transform nested coordinate arrays."""
+    if not coords:
+        return coords
+    # Single position (tuple of numbers)
+    if isinstance(coords[0], (int, float)):
+        return _transform_position(tuple(coords), matrix)
+    # List of positions or deeper nesting
+    return [_transform_coords(c, matrix) for c in coords]
+
+
+# ---------------------------------------------------------------------------
+# 3D type transform helpers
+# ---------------------------------------------------------------------------
+
+def _transform_tin(geom: TIN, matrix: List[List[float]]) -> TIN:
+    """Transform nested polygon coordinates in a TIN."""
+    new_coords = _transform_coords(list(geom.coordinates), matrix)
+    return TIN(type="TIN", coordinates=new_coords)
+
+
+def _transform_polyhedral(
+    geom: PolyhedralSurface, matrix: List[List[float]]
+) -> PolyhedralSurface:
+    """Transform nested polygon coordinates in a PolyhedralSurface."""
+    new_coords = _transform_coords(list(geom.coordinates), matrix)
+    return PolyhedralSurface(type="PolyhedralSurface", coordinates=new_coords)
+
+
+# ---------------------------------------------------------------------------
+# Geometry union + dispatch
+# ---------------------------------------------------------------------------
+
+Geometry = Union[
+    Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon,
+    TIN, PolyhedralSurface,
+]
+
+
+def apply_transform(geometry: Geometry, transform: AffineTransform) -> Geometry:
+    """Apply an affine transform to a geometry, returning a new geometry.
+
+    Supports all GeoJSON geometry types plus MuDM 3D types
+    (TIN, PolyhedralSurface).
+
+    Args:
+        geometry: A geometry with 3D coordinates.
+        transform: A 4x4 affine transformation.
+
+    Returns:
+        A new geometry of the same type with transformed coordinates.
+    """
+    matrix = transform.matrix
+
+    if isinstance(geometry, TIN):
+        return _transform_tin(geometry, matrix)
+    if isinstance(geometry, PolyhedralSurface):
+        return _transform_polyhedral(geometry, matrix)
+
+    # GeoJSON types — all have .coordinates
+    new_coords = _transform_coords(list(geometry.coordinates), matrix)
+    return type(geometry)(type=geometry.type, coordinates=new_coords)
+
+
+def translate_geometry(
+    geometry: Geometry, dx: float, dy: float, dz: float
+) -> Geometry:
+    """Translate a geometry by (dx, dy, dz).
+
+    Convenience wrapper that builds a translation matrix and calls
+    ``apply_transform()``.
+    """
+    t = AffineTransform(
+        type="affine",
+        matrix=[
+            [1, 0, 0, dx],
+            [0, 1, 0, dy],
+            [0, 0, 1, dz],
+            [0, 0, 0, 1],
+        ],
+    )
+    return apply_transform(geometry, t)
+
+
+# ---------------------------------------------------------------------------
+# Coordinate system conversions
+# ---------------------------------------------------------------------------
+
+def voxel_to_physical(
+    coords: Tuple[float, float, float],
+    vcs: VoxelCoordinateSystem,
+) -> Tuple[float, float, float]:
+    """Convert voxel coordinates to physical coordinates.
+
+    Physical = voxel * resolution + origin
+    """
+    return (
+        coords[0] * vcs.resolution[0] + vcs.origin[0],
+        coords[1] * vcs.resolution[1] + vcs.origin[1],
+        coords[2] * vcs.resolution[2] + vcs.origin[2],
+    )
+
+
+def physical_to_voxel(
+    coords: Tuple[float, float, float],
+    vcs: VoxelCoordinateSystem,
+) -> Tuple[float, float, float]:
+    """Convert physical coordinates to voxel coordinates.
+
+    Voxel = (physical - origin) / resolution
+    """
+    return (
+        (coords[0] - vcs.origin[0]) / vcs.resolution[0],
+        (coords[1] - vcs.origin[1]) / vcs.resolution[1],
+        (coords[2] - vcs.origin[2]) / vcs.resolution[2],
+    )

mudm-0.5.0.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: mudm
+Version: 0.5.0
+Summary: muDM (micro Data Model) — a GeoJSON-inspired data model for microscopy spatial data.
+Author-email: Bengt Ljungquist <bengt.ljungquist@nih.gov>
+License: MIT
+Project-URL: Documentation, https://github.com/NovagenResearch/mudm
+Project-URL: Source, https://github.com/NovagenResearch/mudm
+Keywords: json,microscopy,mudm,spatial-data,geojson
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.3.0
+Requires-Dist: geojson-pydantic>=1.2.0
+Dynamic: license-file
+
+# muDM
+
+muDM (micro Data Model) is a GeoJSON-inspired data model for encoding microscopy spatial data — annotations, regions of interest, coordinate systems, and 3D mesh surfaces.
+
+This is the **core data model package**. It provides Pydantic models for validation and serialization with minimal dependencies. For tiling pipelines, format converters, and Rust-accelerated processing, see [mudm-tools](https://github.com/NovagenResearch/mudm-tools).
+
+## Install
+
+```bash
+pip install mudm
+```
+
+## Usage
+
+```python
+from mudm import MuDM, MuDMFeature, GeoJSON
+
+# Validate muDM data
+data = {
+    "type": "FeatureCollection",
+    "features": [{
+        "type": "Feature",
+        "geometry": {"type": "Point", "coordinates": [10, 20]},
+        "properties": {"label": "nucleus"},
+    }],
+}
+obj = MuDM.model_validate(data)
+
+# Any GeoJSON is valid muDM
+geojson = GeoJSON.model_validate(data)
+
+# Coordinate transforms
+from mudm import AffineTransform
+
+# Tile metadata
+from mudm import TileJSON, TileModel
+```
+
+## What's included
+
+- **Model validation**: MuDM, MuDMFeature, MuDMFeatureCollection, GeoJSON
+- **3D geometry types**: TIN, PolyhedralSurface, TiledGeometry
+- **Tile metadata**: TileJSON, TileModel, TileLayer, PyramidJSON
+- **Coordinate transforms**: AffineTransform, VoxelCoordinateSystem
+- **Provenance tracking**: Workflow, Artifact, MuDMLink
+
+## License
+
+MIT

mudm-0.5.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+mudm/__init__.py,sha256=ruXm9Av8zEyUqTL8t-wiEmoCYV1GyONlqJkLNLjZA3g,717
+mudm/layout.py,sha256=JmEObvGDBHJgU5u1cmi7SYXGAHzZWF815A-g6up8NGg,8434
+mudm/model.py,sha256=HnzwMlYELVHrRdkeSgnQRPU7BtgmzzfmkasEA1qqWYk,9099
+mudm/provenance.py,sha256=wEHENfWwvO1qFfRafFVg1-3r3rQeMP2KqiAKFLsiqtQ,1492
+mudm/tilemodel.py,sha256=_Ecc_lLTeScs0sSrHt1svRXgPD_nsS7gg9zVNYoKepY,7435
+mudm/transforms.py,sha256=Loq3Wktyxx_9E1xyPzf5ey7h2marseaObn6vdrTZcWg,6229
+mudm-0.5.0.dist-info/licenses/LICENSE,sha256=7KWudZy89D-fI8yqUKFp5e4YTpzpac2Hv-3jCDUwhiQ,1078
+mudm-0.5.0.dist-info/METADATA,sha256=euxy-x_Y-UjsWxjUOBp0oUlidBzQ6i702Yuag-JCcjc,2089
+mudm-0.5.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mudm-0.5.0.dist-info/top_level.txt,sha256=wvZfgiJvmL_ITRXDFkafSwnLREBTZOqN8j6H0FkeI8U,5
+mudm-0.5.0.dist-info/RECORD,,

mudm-0.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mudm-0.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NovaGen Research Fund
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mudm-0.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mudm