imodfile 0.1.0

"""
imodfile — Read, write, and inspect IMOD model files.

Provides a Pythonic interface to the `.mod` file format used by the
`IMOD <https://bio3d.colorado.edu/imod/>`_ electron microscopy toolkit.

Basic usage::

    import imodfile
    import numpy as np

    # ── Load ──
    model = imodfile.load("cells.mod")
    print(f"{len(model)} objects, image size {model.image_size}")

    # ── Read points ──
    for obj in model.objects:
        for cont in obj.contours:
            pts = cont.points          # ndarray (N, 3), float32
            xs, ys, zs = pts[:, 0], pts[:, 1], pts[:, 2]

    # ── Create ──
    obj = model.add_object()
    obj.name = "mitochondria"
    obj.color = (1.0, 0.0, 0.0)

    cont = obj.add_contour()
    cont.points = np.array([[0,0,0], [1,0,0], [0,1,0]], dtype=np.float32)
    cont.surface = 0
    cont.time = 1

    # ── Save ──
    model.save("output.mod")
    model.save("output.txt")            # ASCII format
    model.save_points("points.txt")     # point dump
"""

from typing import List, Tuple, Optional
import numpy as np
import numpy.typing as npt

# Re-exported types
__all__ = [
    "Model", "Object", "Contour", "Mesh",
    "load",
]

# ── type aliases ──

_Float3 = Tuple[float, float, float]
_PointsArray = npt.NDArray[np.float32]  # shape (N, 3)

# ═════════════════════════════════════════════════════════════════════════════
#  Contour
# ═════════════════════════════════════════════════════════════════════════════

class Contour:
    """A contour — a series of 3-D points with optional surface/time metadata.

    Points are stored as an (N, 3) float32 numpy array and can be both read
    and written::

        cont = obj.contours[0]

        # read
        pts = cont.points          # ndarray (N, 3)
        x = pts[:, 0]

        # write (must be (N, 3) float32)
        cont.points = np.array([[1,2,3],[4,5,6]], dtype=np.float32)
    """

    @property
    def points(self) -> _PointsArray:
        """(N, 3) float32 array of point coordinates.

        Setting this replaces all points in the contour.
        The array must have shape ``(N, 3)`` and dtype ``float32``.

        Example::

            cont.points = np.array([
                [10.0, 20.0, 30.0],
                [40.0, 50.0, 60.0],
            ], dtype=np.float32)
        """
        ...

    @points.setter
    def points(self, arr: _PointsArray) -> None: ...

    @property
    def psize(self) -> int:
        """Number of points (read-only, derived from ``.points``)."""
        ...

    @property
    def surface(self) -> int:
        """Surface index this contour belongs to.

        Used to group contours within an object into separate surfaces.
        Default is 0."""
        ...

    @surface.setter
    def surface(self, val: int) -> None: ...

    @property
    def time(self) -> int:
        """Time index for time-series data.  Default is 0.

        Numbered from 1 when set; 0 means no time set."""
        ...

    @time.setter
    def time(self, val: int) -> None: ...

    @property
    def flags(self) -> int:
        """Bit flags.  Common values::

            ``0x10``  — contour has scan-line pairs (not open/closed)
            ``0x08``  — draw on all planes regardless of Z
            ``0x04``  — wild contour (not in one Z plane)
        """
        ...

    @flags.setter
    def flags(self, val: int) -> None: ...

    def __repr__(self) -> str:
        """e.g. ``Contour(points=42, surface=0)``"""
        ...

# ═════════════════════════════════════════════════════════════════════════════
#  Mesh
# ═════════════════════════════════════════════════════════════════════════════

class Mesh:
    """A triangle/quad mesh with vertices and an index list.

    Vertices are stored as an (N, 3) float32 array.  The index list
    contains vertex indices plus special sentinel values:

    * ``-1``  — end of list
    * ``-21`` — begin polygon (vertices only)
    * ``-22`` — end polygon
    * ``-23`` — begin vertex/normal polygon pair
    """

    @property
    def vertices(self) -> _PointsArray:
        """(N, 3) float32 array of vertex coordinates.  Read/write.

        Example::

            mesh.vertices = np.array([
                [0,0,0], [1,0,0], [1,1,0], [0,1,0],
            ], dtype=np.float32)
        """
        ...

    @vertices.setter
    def vertices(self, arr: _PointsArray) -> None: ...

    @property
    def indices(self) -> List[int]:
        """Index list into the vertex array.

        Contains vertex indices and negative sentinels
        (``-1`` = end, ``-22`` = polygon end, etc.)

        Example::

            mesh.indices = [-23, 0, 0, 1, 0, 2, 0, -22]  # triangle
        """
        ...

    @indices.setter
    def indices(self, val: List[int]) -> None: ...

    def __repr__(self) -> str:
        """e.g. ``Mesh(vertices=128, indices=384)``"""
        ...

# ═════════════════════════════════════════════════════════════════════════════
#  Object
# ═════════════════════════════════════════════════════════════════════════════

class Object:
    """A model object — a named container for contours and meshes.

    Each object has its own colour, transparency, material properties,
    and display settings::

        obj = model.objects[0]
        obj.name = "membrane"
        obj.color = (0.0, 1.0, 0.0)       # green
        obj.flags |= 0x100                 # turn off display
    """

    @property
    def name(self) -> str:
        """Object name (up to 64 characters).  Read/write."""
        ...

    @name.setter
    def name(self, val: str) -> None: ...

    @property
    def color(self) -> _Float3:
        """RGB colour as ``(red, green, blue)``, each in [0, 1].

        Example::

            obj.color = (1.0, 0.5, 0.0)   # orange
        """
        ...

    @color.setter
    def color(self, val: _Float3) -> None: ...

    @property
    def flags(self) -> int:
        """Bit flags for display and drawing properties.

        Selected flags::

            ``0x001``  — open contours (not closed)
            ``0x002``  — fill polygons
            ``0x004``  — scattered points
            ``0x008``  — inside-out surface normals
            ``0x010``  — draw mesh in 3-D
            ``0x020``  — no lines in 3-D
            ``0x040``  — light both sides
            ``0x080``  — use fill colour
            ``0x100``  — off (do not display)
            ``0x200``  — draw label
            ``0x400``  — scale line width
            ``0x800``  — has time indices
        """
        ...

    @flags.setter
    def flags(self, val: int) -> None: ...

    @property
    def contours(self) -> List[Contour]:
        """List of contours belonging to this object.

        Use ``.add_contour()`` and ``.remove_contour()`` to modify."""
        ...

    @property
    def meshes(self) -> List[Mesh]:
        """List of meshes belonging to this object.

        Use ``.add_mesh()`` to create new meshes."""
        ...

    def add_contour(self) -> Contour:
        """Add a new empty contour and return it.

        After creation, set its ``.points``, ``.surface``, etc.::

            cont = obj.add_contour()
            cont.points = np.array([...], dtype=np.float32)
            cont.surface = 1
        """
        ...

    def remove_contour(self, index: int) -> None:
        """Remove a contour by its index.

        Raises ``IndexError`` if the index is out of range."""
        ...

    def add_mesh(self) -> Mesh:
        """Add a new empty mesh and return it."""
        ...

    def points(self) -> _PointsArray:
        """All contour points in this object, concatenated into a single
        (N, 3) float32 array.

        This is a zero-allocation view when used from Rust, but returns
        a copied numpy array to Python."""
        ...

    def __len__(self) -> int:
        """Number of contours (same as ``len(obj.contours)``)."""
        ...

    def __repr__(self) -> str:
        """e.g. ``Object(name='membrane', contours=12, meshes=1)``"""
        ...

# ═════════════════════════════════════════════════════════════════════════════
#  Model
# ═════════════════════════════════════════════════════════════════════════════

class Model:
    """Top-level IMOD model — the root container.

    A model holds a list of objects, image dimensions, coordinate
    transforms, and view settings::

        model = imodfile.load("cells.mod")
        print(model.name)               # "IMOD-NewModel"
        print(model.image_size)         # (1024, 1024, 300)
        print(model.pixel_size)         # 0.868

        # iterate all points
        for obj in model.objects:
            for cont in obj.contours:
                ...
    """

    @property
    def name(self) -> str:
        """Model name (up to 128 characters).  Read/write."""
        ...

    @name.setter
    def name(self, val: str) -> None: ...

    @property
    def image_size(self) -> Tuple[int, int, int]:
        """Image dimensions as ``(xmax, ymax, zmax)``.

        These are typically the pixel dimensions of the tomogram or image
        volume the model was drawn on.  Read/write.

        Example::

            model.image_size = (2048, 2048, 600)
        """
        ...

    @image_size.setter
    def image_size(self, val: Tuple[int, int, int]) -> None: ...

    @property
    def pixel_size(self) -> float:
        """Pixel size in physical units (e.g. nanometres).

        The ``units`` field indicates the scale (not exposed yet).
        Default is 1.0.  Read/write."""
        ...

    @pixel_size.setter
    def pixel_size(self, val: float) -> None: ...

    @property
    def objects(self) -> List[Object]:
        """List of objects in this model.

        Use ``.add_object()`` and ``.remove_object()`` to modify."""
        ...

    @staticmethod
    def load(path: str) -> "Model":
        """Load a model file.

        Automatically detects binary vs ASCII format from file contents.

        Args:
            path: Path to the ``.mod`` file (or ``.txt`` for ASCII).

        Returns:
            A new ``Model`` instance.

        Raises:
            FileNotFoundError: The file does not exist.
            IOError: The file is not a valid IMOD model.

        Example::

            model = Model.load("ribosome.mod")
        """
        ...

    def save(self, path: str) -> None:
        """Save the model to a file.

        Uses binary format by default.  If the path ends with ``.txt``
        or ``.ascii``, uses ASCII format instead.

        Args:
            path: Output file path.

        Raises:
            IOError: Failed to write the file.

        Example::

            model.save("output.mod")       # binary
            model.save("output.txt")       # ASCII
        """
        ...

    def save_points(self, path: str) -> None:
        """Write all contour points to a plain-text file.

        Each line is ``x y z``.  Contours are separated by a blank line.
        Useful for piping into external plotting tools.

        Args:
            path: Output text file path.

        Example::

            model.save_points("points.txt")
            # →  632.34 442.14 404.11
            #    649.41 558.57 420.98
            #    <blank>
            #    431.70 538.67 372.98
            #    ...
        """
        ...

    def add_object(self) -> Object:
        """Add a new empty object and return it.

        The new object has default properties (grey colour, no contours,
        no meshes)::

            obj = model.add_object()
            obj.name = "new structure"
            obj.color = (1.0, 0.0, 0.0)
        """
        ...

    def remove_object(self, index: int) -> None:
        """Remove an object by its index.

        Raises ``IndexError`` if the index is out of range."""
        ...

    def points(self) -> _PointsArray:
        """All points from all objects and contours, concatenated
        into a single (N, 3) float32 numpy array.

        This is the simplest way to get all coordinates for analysis::

            all_pts = model.points()      # shape (N, 3)
            xs, ys, zs = all_pts.T
        """
        ...

    def __len__(self) -> int:
        """Number of objects (same as ``len(model.objects)``)."""
        ...

    def __repr__(self) -> str:
        """e.g. ``Model(name='IMOD-NewModel', objects=3)``"""
        ...

# ═════════════════════════════════════════════════════════════════════════════
#  Top-level convenience
# ═════════════════════════════════════════════════════════════════════════════

def load(path: str) -> Model:
    """Load a model file.

    This is a convenience alias for ``Model.load()``::

        import imodfile
        model = imodfile.load("cells.mod")

    Args:
        path: Path to the IMOD model file.

    Returns:
        A ``Model`` instance.

    Raises:
        FileNotFoundError: The file does not exist.
        IOError: The file is not a valid IMOD model.
    """
    ...