mudm-tools 0.5.0__tar.gz

mudm_tools-0.5.0/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_tools-0.5.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: mudm-tools
+Version: 0.5.0
+Summary: Processing pipelines, tiling engines, and format converters for muDM spatial data.
+Author-email: Bengt Ljungquist <bengt.ljungquist@nih.gov>
+License: MIT
+Project-URL: Documentation, https://github.com/NovagenResearch/mudm-tools
+Project-URL: Source, https://github.com/NovagenResearch/mudm-tools
+Keywords: microscopy,mudm,tiling,spatial-data,vector-tiles
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mudm>=0.5.0
+Requires-Dist: pydantic>=2.3.0
+Requires-Dist: geojson-pydantic>=1.2.0
+Requires-Dist: geojson2vt>=1.0.1
+Requires-Dist: protobuf>=5.29.3
+Requires-Dist: geojson>=3.1.0
+Requires-Dist: shapely>=2.0.6
+Requires-Dist: mapbox-vector-tile>=2.1.0
+Requires-Dist: pyarrow>=19.0.1
+Requires-Dist: geopandas>=1.0.1
+Requires-Dist: jsonschema>=4.23.0
+Requires-Dist: pygltflib>=1.16
+Requires-Dist: numpy>=1.26
+Provides-Extra: draco
+Requires-Dist: DracoPy>=1.4; extra == "draco"
+Dynamic: license-file
+
+# mudm-tools
+
+Processing pipelines, tiling engines, and format converters for [muDM](https://github.com/NovagenResearch/mudm) spatial data. Includes optional Rust acceleration via prebuilt wheels.
+
+## Install
+
+```bash
+pip install mudm-tools
+```
+
+On supported platforms (Linux x86_64, macOS x86_64/arm64, Windows x86_64), this automatically includes the Rust-accelerated tiling engine. On other platforms, a pure-Python fallback is used.
+
+```python
+import mudm_tools
+print(mudm_tools.RUST_AVAILABLE)  # True with prebuilt wheel
+```
+
+## Features
+
+- **2D tiling**: Rust-accelerated quadtree pipeline (StreamingTileGenerator2D) + legacy Python pipeline
+- **3D tiling**: Octree-based mesh tiling with meshopt/Draco compression (StreamingTileGenerator)
+- **Format converters**: Xenium spatial transcriptomics, OBJ meshes, GeoJSON
+- **GeoParquet/Arrow**: Import and export via Apache Arrow
+- **glTF/GLB export**: 3D mesh export with optional Draco compression
+- **Neuroglancer**: Precomputed format for browser-based 3D visualization
+- **Multiple output formats**: PBF (MVT), 3D Tiles (GLB), tiled Parquet (ZSTD), Neuroglancer precomputed
+
+## Quick start
+
+```python
+from mudm import MuDM  # core data model (separate package)
+from mudm_tools._rs import StreamingTileGenerator2D  # Rust-accelerated
+from mudm_tools.tiling2d import generate_pbf
+
+gen = StreamingTileGenerator2D(min_zoom=0, max_zoom=7, buffer=64/4096)
+gen.add_geojson(open("data.json").read(), bounds)
+generate_pbf(gen, "tiles/", bounds)
+```
+
+## License
+
+MIT

mudm_tools-0.5.0/README.md

@@ -0,0 +1,42 @@
+# mudm-tools
+
+Processing pipelines, tiling engines, and format converters for [muDM](https://github.com/NovagenResearch/mudm) spatial data. Includes optional Rust acceleration via prebuilt wheels.
+
+## Install
+
+```bash
+pip install mudm-tools
+```
+
+On supported platforms (Linux x86_64, macOS x86_64/arm64, Windows x86_64), this automatically includes the Rust-accelerated tiling engine. On other platforms, a pure-Python fallback is used.
+
+```python
+import mudm_tools
+print(mudm_tools.RUST_AVAILABLE)  # True with prebuilt wheel
+```
+
+## Features
+
+- **2D tiling**: Rust-accelerated quadtree pipeline (StreamingTileGenerator2D) + legacy Python pipeline
+- **3D tiling**: Octree-based mesh tiling with meshopt/Draco compression (StreamingTileGenerator)
+- **Format converters**: Xenium spatial transcriptomics, OBJ meshes, GeoJSON
+- **GeoParquet/Arrow**: Import and export via Apache Arrow
+- **glTF/GLB export**: 3D mesh export with optional Draco compression
+- **Neuroglancer**: Precomputed format for browser-based 3D visualization
+- **Multiple output formats**: PBF (MVT), 3D Tiles (GLB), tiled Parquet (ZSTD), Neuroglancer precomputed
+
+## Quick start
+
+```python
+from mudm import MuDM  # core data model (separate package)
+from mudm_tools._rs import StreamingTileGenerator2D  # Rust-accelerated
+from mudm_tools.tiling2d import generate_pbf
+
+gen = StreamingTileGenerator2D(min_zoom=0, max_zoom=7, buffer=64/4096)
+gen.add_geojson(open("data.json").read(), bounds)
+generate_pbf(gen, "tiles/", bounds)
+```
+
+## License
+
+MIT

mudm_tools-0.5.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mudm-tools"
+version = "0.5.0"
+description = "Processing pipelines, tiling engines, and format converters for muDM spatial data."
+readme = "README.md"
+authors = [
+    { name = "Bengt Ljungquist", email = "bengt.ljungquist@nih.gov" },
+]
+license = { text = "MIT" }
+requires-python = ">=3.11,<3.14"
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Rust",
+]
+keywords = ["microscopy", "mudm", "tiling", "spatial-data", "vector-tiles"]
+dependencies = [
+    "mudm>=0.5.0",
+    "pydantic>=2.3.0",
+    "geojson-pydantic>=1.2.0",
+    "geojson2vt>=1.0.1",
+    "protobuf>=5.29.3",
+    "geojson>=3.1.0",
+    "shapely>=2.0.6",
+    "mapbox-vector-tile>=2.1.0",
+    "pyarrow>=19.0.1",
+    "geopandas>=1.0.1",
+    "jsonschema>=4.23.0",
+    "pygltflib>=1.16",
+    "numpy>=1.26",
+]
+
+[project.optional-dependencies]
+draco = ["DracoPy>=1.4"]
+
+[project.scripts]
+mudm-serve = "mudm_tools.serve:main"
+
+[project.urls]
+Documentation = "https://github.com/NovagenResearch/mudm-tools"
+Source = "https://github.com/NovagenResearch/mudm-tools"
+
+[tool.maturin]
+manifest-path = "rust/Cargo.toml"
+python-source = "src"
+module-name = "mudm_tools._rs"
+features = ["pyo3/extension-module"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"mudm_tools.viewers" = ["**/*.html", "**/*.js", "**/*.css"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests/"]
+pythonpath = ["src/", "scripts/"]

mudm_tools-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mudm_tools-0.5.0/src/mudm_tools/__init__.py

@@ -0,0 +1,29 @@
+"""mudm-tools — processing pipelines, tiling, and format converters for muDM."""
+
+from .mudm2vt.mudm2vt import mudm2vt  # noqa: F401
+from .neuroglancer import (  # noqa: F401
+    to_neuroglancer,
+    write_annotations,
+)
+from .gltf import to_gltf, to_glb, GltfConfig  # noqa: F401
+from .arrow import to_arrow_table, to_geoparquet, ArrowConfig  # noqa: F401
+from .arrow import from_arrow_table, from_geoparquet  # noqa: F401
+from .tiling3d import (  # noqa: F401
+    TileGenerator3D,
+    OctreeConfig,
+    TileReader3D,
+    TileModel3D,
+)
+from .tiling3d.tilejson3d import (  # noqa: F401
+    TileEncoding,
+    KnownTileFormat,
+    KnownCompression,
+)
+
+try:
+    from ._rs import StreamingTileGenerator, StreamingTileGenerator2D  # noqa: F401
+    RUST_AVAILABLE = True
+except ImportError:
+    RUST_AVAILABLE = False
+
+__version__ = "0.5.0"

mudm_tools-0.5.0/src/mudm_tools/_legacy/automodel.py

@@ -0,0 +1,44 @@
+"""Microjson using manual MuDM pydantic models,
+but autogenerated GeoJSON models."""
+from typing import Optional, Union
+from pydantic import BaseModel, StrictInt, StrictStr
+from geojson.Feature import GeojsonFeature
+from geojson.FeatureCollection import GeojsonFeaturecollection
+from geojson.Geometry import GeojsonGeometry
+from geojson.GeometryCollection import GeojsonGeometrycollection
+from mudm.model import Multiscale
+
+
+class GeoJSONAuto(BaseModel):
+    """The root object of a GeoJSON file"""
+
+    __root__: Union[
+        GeojsonFeature,
+        GeojsonFeaturecollection,
+        GeojsonGeometry,
+        GeojsonGeometrycollection,
+    ]
+
+
+class MuDMFeature(GeojsonFeature):
+    """A MuDM feature, which is a GeoJSON feature with additional
+    metadata"""
+
+    multiscale: Optional[Multiscale]
+    ref: Optional[Union[StrictStr, StrictInt]]
+
+
+class MuDMFeatureCollection(GeojsonFeaturecollection):
+    """A MuDM feature collection, which is a GeoJSON feature
+    collection with additional metadata"""
+
+    multiscale: Optional[Multiscale]
+
+
+class MuDMAuto(BaseModel):
+    """The root object of a MuDM file"""
+
+    __root__: Union[
+        MuDMFeature, MuDMFeatureCollection,
+        GeojsonGeometry, GeojsonGeometrycollection
+    ]

mudm_tools-0.5.0/src/mudm_tools/_legacy/roundtrip.py

@@ -0,0 +1,225 @@
+"""MuDM Roundtrip for GeoJSON, generated automatically
+by datamodel-codegen from models exported from
+Pydantic models"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic.v1 import BaseModel, Field
+
+
+class Type(Enum):
+    point = 'Point'
+
+
+class Point(BaseModel):
+    bbox: Optional[List[float]] = Field(None, min_length=4, title='Bbox')
+    type: Type = Field(..., title='Type')
+    coordinates: List[float] = Field(...,
+                                     max_length=3,
+                                     min_length=2,
+                                     title='Coordinates')
+
+
+class Type1(Enum):
+    multi_point = 'MultiPoint'
+
+
+class MultiPoint(BaseModel):
+    bbox: Optional[List[float]] = Field(None, min_length=4, title='Bbox')
+    type: Type1 = Field(..., title='Type')
+    coordinates: List[List[float]] = Field(..., title='Coordinates')
+
+
+class Type2(Enum):
+    line_string = 'LineString'
+
+
+class LineString(BaseModel):
+    bbox: Optional[List[float]] = Field(None, min_length=4, title='Bbox')
+    type: Type2 = Field(..., title='Type')
+    coordinates: List[List[float]] = Field(..., title='Coordinates')
+
+
+class Type3(Enum):
+    multi_line_string = 'MultiLineString'
+
+
+class MultiLineString(BaseModel):
+    bbox: Optional[List[float]] = Field(None, min_length=4, title='Bbox')
+    type: Type3 = Field(..., title='Type')
+    coordinates: List[List[List[float]]] = Field(..., title='Coordinates')
+
+
+class Type4(Enum):
+    polygon = 'Polygon'
+
+
+class Polygon(BaseModel):
+    bbox: Optional[List[float]] = Field(None, min_length=4, title='Bbox')
+    type: Type4 = Field(..., title='Type')
+    coordinates: List[List[List[float]]] = Field(..., title='Coordinates')
+
+
+class Type5(Enum):
+    multi_polygon = 'MultiPolygon'
+
+
+class MultiPolygon(BaseModel):
+    bbox: Optional[List[float]] = Field(None, min_length=4, title='Bbox')
+    type: Type5 = Field(..., title='Type')
+    coordinates: List[List[List[List[float]]]] = Field(...,
+                                                       title='Coordinates')
+
+
+class Type6(Enum):
+    geometry_collection = 'GeometryCollection'
+
+
+class GeometryCollection(BaseModel):
+    bbox: Optional[List[float]] = Field(None, min_length=4, title='Bbox')
+    type: Type6 = Field(..., title='Type')
+    geometries: List[
+        Union[Point,
+              MultiPoint,
+              LineString,
+              MultiLineString,
+              Polygon,
+              MultiPolygon]
+    ] = Field(..., title='Geometries')
+
+
+class Properties(BaseModel):
+    descriptive: Optional[Dict[str, str]] = Field(None, title='Descriptive')
+    numerical: Optional[Dict[str, float]] = Field(None, title='Numerical')
+    multiNumerical: Optional[Dict[str, List[float]]] = Field(
+        None, title='Multi Numerical'
+    )
+
+
+class Unit(Enum):
+    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 Axe(Enum):
+    x = 'x'
+    y = 'y'
+    z = 'z'
+    r = 'r'
+    theta = 'theta'
+    phi = 'phi'
+
+
+class Multiscale(BaseModel):
+    axes: List[Axe] = Field(..., title='Axes')
+    units: Optional[List[Unit]] = None
+    pixelsPerUnit: Optional[List[float]] = Field(
+        None, alias='pixelsPerUnit', title='Pixelsperunit'
+    )
+
+
+class Type7(Enum):
+    feature = 'Feature'
+
+
+class MuDMFeature(BaseModel):
+    bbox: Optional[List[float]] = Field(None, min_length=4, title='Bbox')
+    type: Type7 = Field(..., title='Type')
+    geometry: Union[
+        Point,
+        MultiPoint,
+        LineString,
+        MultiLineString,
+        Polygon,
+        MultiPolygon,
+        GeometryCollection,
+    ] = Field(
+        ...,
+        description='The geometry of the feature',
+        title='Geometry',
+    )
+    properties: Properties
+    id: Optional[Union[str, int]] = Field(None, title='Id')
+    multiscale: Optional[Multiscale] = None
+    ref: Optional[Union[str, int]] = Field(None, title='Ref')
+
+
+class Feature(BaseModel):
+    bbox: Optional[List[float]] = Field(None, min_length=4, title='Bbox')
+    type: Type7 = Field(..., title='Type')
+    geometry: Union[
+        Point,
+        MultiPoint,
+        LineString,
+        MultiLineString,
+        Polygon,
+        MultiPolygon,
+        GeometryCollection,
+    ] = Field(
+        ...,
+        description='The geometry of the feature',
+        title='Geometry',
+    )
+    properties: Dict[str, Any] = Field(
+        ...,
+        description='Properties of the feature',
+        title='Properties',
+    )
+    id: Optional[Union[str, int]] = Field(None, title='Id')
+
+
+class Type9(Enum):
+    feature_collection = 'FeatureCollection'
+
+
+class MuDMFeatureCollection(BaseModel):
+    bbox: Optional[List[float]] = Field(None, min_length=4, title='Bbox')
+    type: Type9 = Field(..., title='Type')
+    features: List[Feature] = Field(..., title='Features')
+    multiscale: Optional[Multiscale] = None
+
+
+class MuDM(BaseModel):
+    __root__: Union[
+        MuDMFeature,
+        MuDMFeatureCollection,
+        Point,
+        MultiPoint,
+        LineString,
+        MultiLineString,
+        Polygon,
+        MultiPolygon,
+        GeometryCollection,
+    ] = Field(...,
+              description='The root object of a MuDM file',
+              title='MuDM')

mudm_tools-0.5.0/src/mudm_tools/arrow/__init__.py

@@ -0,0 +1,5 @@
+"""Arrow / GeoParquet export and import for MuDM."""
+
+from .models import ArrowConfig  # noqa: F401
+from .reader import from_arrow_table, from_geoparquet  # noqa: F401
+from .writer import to_arrow_table, to_geoparquet  # noqa: F401

mudm_tools-0.5.0/src/mudm_tools/arrow/_from_geometry.py

@@ -0,0 +1,119 @@
+"""Shapely → MuDM/GeoJSON geometry conversion (reverse of _geometry.py)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import shapely
+from shapely.geometry import (
+    GeometryCollection as ShapelyGeometryCollection,
+    LineString as ShapelyLineString,
+    MultiLineString as ShapelyMultiLineString,
+    MultiPoint as ShapelyMultiPoint,
+    MultiPolygon as ShapelyMultiPolygon,
+    Point as ShapelyPoint,
+    Polygon as ShapelyPolygon,
+)
+
+from geojson_pydantic import (
+    GeometryCollection,
+    LineString,
+    MultiLineString,
+    MultiPoint,
+    MultiPolygon,
+    Point,
+    Polygon,
+)
+
+from mudm.model import (
+    TIN,
+)
+
+
+def _pos(coord: tuple) -> tuple:
+    """Convert a Shapely coordinate tuple to a GeoJSON position."""
+    return tuple(float(c) for c in coord)
+
+
+def _is_tin(geom: ShapelyMultiPolygon) -> bool:
+    """Check if a MultiPolygon is a TIN (all polygons are 3D triangles)."""
+    if not geom.has_z:
+        return False
+    for poly in geom.geoms:
+        if len(poly.interiors) != 0:
+            return False
+        coords = list(poly.exterior.coords)
+        if len(coords) != 4:  # closed triangle = 4 coords
+            return False
+    return True
+
+
+def _multipolygon_to_tin(geom: ShapelyMultiPolygon) -> TIN:
+    """Convert a triangle-only 3D MultiPolygon to a TIN."""
+    faces = []
+    for poly in geom.geoms:
+        ring = [_pos(c) for c in poly.exterior.coords]
+        faces.append([ring])
+    return TIN(type="TIN", coordinates=faces)
+
+
+def _ring_coords(ring) -> list[tuple]:
+    """Extract ring coordinates from a Shapely LinearRing or coord sequence."""
+    return [_pos(c) for c in ring.coords]
+
+
+def shapely_to_microjson(geom: Any) -> Any:
+    """Convert a Shapely geometry to a GeoJSON-pydantic model.
+
+    Returns None for None input.
+    """
+    if geom is None:
+        return None
+
+    if isinstance(geom, ShapelyPoint):
+        return Point(type="Point", coordinates=_pos(geom.coords[0]))
+
+    if isinstance(geom, ShapelyMultiPoint):
+        return MultiPoint(
+            type="MultiPoint",
+            coordinates=[_pos(p.coords[0]) for p in geom.geoms],
+        )
+
+    if isinstance(geom, ShapelyLineString):
+        return LineString(
+            type="LineString",
+            coordinates=[_pos(c) for c in geom.coords],
+        )
+
+    if isinstance(geom, ShapelyMultiLineString):
+        return MultiLineString(
+            type="MultiLineString",
+            coordinates=[
+                [_pos(c) for c in line.coords] for line in geom.geoms
+            ],
+        )
+
+    if isinstance(geom, ShapelyPolygon):
+        rings = [_ring_coords(geom.exterior)]
+        for interior in geom.interiors:
+            rings.append(_ring_coords(interior))
+        return Polygon(type="Polygon", coordinates=rings)
+
+    if isinstance(geom, ShapelyMultiPolygon):
+        if _is_tin(geom):
+            return _multipolygon_to_tin(geom)
+        polys = []
+        for poly in geom.geoms:
+            rings = [_ring_coords(poly.exterior)]
+            for interior in poly.interiors:
+                rings.append(_ring_coords(interior))
+            polys.append(rings)
+        return MultiPolygon(type="MultiPolygon", coordinates=polys)
+
+    if isinstance(geom, ShapelyGeometryCollection):
+        parts = [shapely_to_microjson(g) for g in geom.geoms]
+        return GeometryCollection(type="GeometryCollection", geometries=parts)
+
+    raise TypeError(f"Unsupported Shapely geometry type: {type(geom)}")
+
+