gridfinity-rebase 0.1.0__py3-none-any.whl

gridfinity_rebase/__init__.py

@@ -0,0 +1,78 @@
+"""Public library API for replacing the base of a Gridfinity bin STL.
+
+Geometry imports are lazy: presets and options do not load the native engine.
+"""
+
+from importlib import import_module
+from importlib.metadata import version
+from typing import TYPE_CHECKING
+
+from .catalog import Preset, list_presets, resolve_options
+from .errors import RebaseError
+from .options import BaseOptions
+
+__version__ = version("gridfinity-rebase")
+
+_API_EXPORTS = (
+    "Model",
+    "Inspection",
+    "GeneratedBase",
+    "DonorBase",
+    "ProgressEvent",
+    "ProgressStage",
+    "RebaseReport",
+    "RebaseResult",
+    "load_stl",
+    "inspect_model",
+    "rebase",
+    "save_stl",
+)
+
+__all__ = [
+    "BaseOptions",
+    "DonorBase",
+    "GeneratedBase",
+    "Inspection",
+    "Model",
+    "Preset",
+    "ProgressEvent",
+    "ProgressStage",
+    "RebaseError",
+    "RebaseReport",
+    "RebaseResult",
+    "__version__",
+    "inspect_model",
+    "list_presets",
+    "load_stl",
+    "rebase",
+    "resolve_options",
+    "save_stl",
+]
+
+if TYPE_CHECKING:
+    from .api import (
+        DonorBase,
+        GeneratedBase,
+        Inspection,
+        Model,
+        ProgressEvent,
+        ProgressStage,
+        RebaseReport,
+        RebaseResult,
+        inspect_model,
+        load_stl,
+        rebase,
+        save_stl,
+    )
+
+
+def __getattr__(name: str):
+    if name in _API_EXPORTS:
+        api = import_module(".api", __name__)
+        globals().update({export: getattr(api, export) for export in _API_EXPORTS})
+        return globals()[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))

gridfinity_rebase/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

gridfinity_rebase/api.py

@@ -0,0 +1,363 @@
+"""In-memory orchestration shared by CLI and other clients.
+
+All coordinates and heights are millimetres, with feet down and Z pointing up.
+Functions are synchronous and never print or write files implicitly.
+"""
+
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from numbers import Real
+from pathlib import Path
+from time import perf_counter
+from typing import Literal
+
+import manifold3d as m
+import numpy as np
+from numpy.typing import NDArray
+
+from .errors import RebaseError
+from .geometry import (
+    Grid,
+    detect_grid,
+    detect_standard_base,
+    donor_base,
+    replace_base,
+    validate_height,
+)
+from .options import BaseOptions
+from .presets import generate_base
+from .stl import read_stl, write_stl
+
+
+@dataclass(frozen=True, init=False)
+class Model:
+    """Validated solid. Obtain through load_stl() or RebaseResult.model.
+
+    The engine representation is private. to_mesh() returns independent arrays
+    suitable for rendering, without exposing the geometry engine to callers.
+    """
+
+    _solid: m.Manifold = field(repr=False)
+    source: Path | None
+
+    def __new__(cls):
+        raise TypeError("Models are created through load_stl() or rebase()")
+
+    @classmethod
+    def _from_solid(cls, solid: m.Manifold, source: Path | None = None) -> "Model":
+        model = object.__new__(cls)
+        object.__setattr__(model, "_solid", solid)
+        object.__setattr__(model, "source", source)
+        return model
+
+    @property
+    def triangles(self) -> int:
+        return self._solid.num_tri()
+
+    def to_mesh(self) -> tuple[NDArray[np.float64], NDArray[np.uint64]]:
+        """Return copies of vertices (N, 3) in mm and triangle indices (M, 3).
+
+        Coordinates retain the input origin and use float64 precision. STL
+        export separately quantizes and validates the result at float32.
+        """
+        mesh = self._solid.to_mesh64()
+        return (
+            np.array(mesh.vert_properties[:, :3], dtype=np.float64, copy=True),
+            np.array(mesh.tri_verts, dtype=np.uint64, copy=True),
+        )
+
+
+@dataclass(frozen=True)
+class Inspection:
+    """Grid and standard-base detection; an unrecognized base is non-fatal."""
+
+    grid: tuple[int, int]
+    origin_mm: tuple[float, float, float]
+    triangles: int
+    standard_bin: bool
+    recommended_base_height_mm: float | None = None
+    interior_start_mm: float | None = None
+    nominal_base_height_mm: float | None = None
+    base_detection_error: str | None = None
+    base_detection_error_code: str | None = None
+
+    def describe(self) -> dict:
+        """Return a JSON-ready report, compatible with CLI inspection fields."""
+        report = {
+            "grid": list(self.grid),
+            "origin_mm": list(self.origin_mm),
+            "triangles": self.triangles,
+            "standard_bin": self.standard_bin,
+        }
+        if self.standard_bin:
+            report.update(
+                recommended_base_height_mm=self.recommended_base_height_mm,
+                interior_start_mm=self.interior_start_mm,
+                nominal_base_height_mm=self.nominal_base_height_mm,
+            )
+        else:
+            report["base_detection_error"] = self.base_detection_error
+        return report
+
+
+@dataclass(frozen=True)
+class GeneratedBase:
+    """Generate feet using resolved options and a curve segment count."""
+
+    options: BaseOptions = field(default_factory=BaseOptions)
+    segments: int = 64
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.options, BaseOptions):
+            raise RebaseError("options must be BaseOptions", code="invalid_options")
+        if (
+            not isinstance(self.segments, int)
+            or isinstance(self.segments, bool)
+            or not 32 <= self.segments <= 256
+            or self.segments % 8
+        ):
+            raise RebaseError(
+                "Segments must be a multiple of 8 between 32 and 256",
+                code="invalid_segments",
+                details={"segments": self.segments},
+            )
+
+
+@dataclass(frozen=True)
+class DonorBase:
+    """Copy an existing model's base, including its hardware geometry."""
+
+    model: Model
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.model, Model):
+            raise RebaseError("Donor must be a Model", code="invalid_model")
+
+
+ProgressStage = Literal[
+    "detecting_grid",
+    "detecting_base",
+    "generating_base",
+    "preparing_donor",
+    "replacing_base",
+    "complete",
+]
+
+
+@dataclass(frozen=True)
+class ProgressEvent:
+    """Stage notification, with no estimate of percentage or remaining time."""
+
+    stage: ProgressStage
+
+
+ProgressCallback = Callable[[ProgressEvent], None]
+
+
+@dataclass(frozen=True)
+class RebaseReport:
+    """Resolved settings and geometry statistics, independent of file output."""
+
+    grid: tuple[int, int]
+    origin_mm: tuple[float, float, float]
+    base_height_mm: float
+    base_height_mode: Literal["auto", "manual"]
+    geometry: BaseOptions | None
+    triangles: int
+    elapsed_ms: float
+    inspection: Inspection | None
+
+    def describe(self) -> dict:
+        report = self.inspection.describe() if self.inspection is not None else {}
+        report.update(
+            grid=list(self.grid),
+            origin_mm=list(self.origin_mm),
+            base_height_mm=self.base_height_mm,
+            base_height_mode=self.base_height_mode,
+            geometry=self.geometry.describe() if self.geometry is not None else None,
+            thumbscrew=self.geometry.thumbscrew if self.geometry is not None else None,
+            triangles=self.triangles,
+            elapsed_ms=self.elapsed_ms,
+        )
+        return report
+
+
+@dataclass(frozen=True)
+class RebaseResult:
+    model: Model
+    report: RebaseReport
+
+
+@contextmanager
+def _geometry_errors(code: str, **details) -> Iterator[None]:
+    """Give legacy geometry errors a code without interpreting their messages."""
+    try:
+        yield
+    except RebaseError as exc:
+        if exc.code != "invalid_geometry":
+            raise
+        raise RebaseError(
+            str(exc), code=code, details={**exc.details, **details}
+        ) from exc
+
+
+def _notify(callback: ProgressCallback | None, stage: ProgressStage) -> None:
+    if callback is not None:
+        callback(ProgressEvent(stage))
+
+
+def _require_model(model: Model) -> None:
+    if not isinstance(model, Model):
+        raise RebaseError("Expected a Model from load_stl()", code="invalid_model")
+
+
+def _grid(model: Model) -> Grid:
+    with _geometry_errors("invalid_grid"):
+        return detect_grid(model._solid, str(model.source) if model.source else "Model")
+
+
+def _inspect(model: Model, grid: Grid) -> Inspection:
+    fields = {
+        "grid": (grid.nx, grid.ny),
+        "origin_mm": (grid.x, grid.y, grid.z),
+        "triangles": model.triangles,
+    }
+    try:
+        with _geometry_errors("unrecognized_base"):
+            standard = detect_standard_base(
+                model._solid, grid, str(model.source) if model.source else "Model"
+            )
+    except RebaseError as exc:
+        if exc.code != "unrecognized_base":
+            raise
+        return Inspection(
+            **fields,
+            standard_bin=False,
+            base_detection_error=str(exc),
+            base_detection_error_code=exc.code,
+        )
+    return Inspection(**fields, **standard.describe())
+
+
+def load_stl(path: str | Path) -> Model:
+    """Read a closed, consistently oriented STL solid without detecting its grid."""
+    path = Path(path)
+    return Model._from_solid(read_stl(path), path)
+
+
+def inspect_model(
+    model: Model, *, on_progress: ProgressCallback | None = None
+) -> Inspection:
+    """Detect the grid and base; invalid grids raise, custom bases are reported."""
+    _require_model(model)
+    _notify(on_progress, "detecting_grid")
+    grid = _grid(model)
+    _notify(on_progress, "detecting_base")
+    info = _inspect(model, grid)
+    _notify(on_progress, "complete")
+    return info
+
+
+def rebase(
+    model: Model,
+    *,
+    base: GeneratedBase | DonorBase,
+    base_height_mm: float | None = None,
+    on_progress: ProgressCallback | None = None,
+) -> RebaseResult:
+    """Return a new model, preserving the input above the validated cut.
+
+    None selects automatic standard-base detection. An explicit height is
+    measured from the bottom of the feet, not from absolute Z=0. Donor bases
+    must match the grid, match after rotation, or be 1x1 for tiling.
+
+    Callbacks run synchronously on the calling thread. Their exceptions
+    propagate unchanged; callers are responsible for dispatching GUI updates.
+    """
+    start = perf_counter()
+    _require_model(model)
+    if not isinstance(base, (GeneratedBase, DonorBase)):
+        raise RebaseError(
+            "base must be GeneratedBase or DonorBase", code="invalid_base"
+        )
+    if base_height_mm is not None and (
+        not isinstance(base_height_mm, Real) or isinstance(base_height_mm, bool)
+    ):
+        raise RebaseError("Base height must be numeric", code="invalid_height")
+    _notify(on_progress, "detecting_grid")
+    grid = _grid(model)
+    info = None
+    if base_height_mm is None:
+        _notify(on_progress, "detecting_base")
+        info = _inspect(model, grid)
+        if not info.standard_bin:
+            raise RebaseError(
+                info.base_detection_error or "Standard base not recognized",
+                code="unrecognized_base",
+            )
+        height = info.recommended_base_height_mm
+        assert height is not None
+    else:
+        height = float(base_height_mm)
+    with _geometry_errors("invalid_height", base_height_mm=height):
+        validate_height(model._solid, grid, height)
+
+    if isinstance(base, GeneratedBase):
+        _notify(on_progress, "generating_base")
+        with _geometry_errors("base_generation_failed"):
+            replacement = generate_base(base.options, grid, height, base.segments)
+        geometry = base.options
+    else:
+        _notify(on_progress, "preparing_donor")
+        with _geometry_errors("incompatible_donor"):
+            donor_grid = detect_grid(
+                base.model._solid,
+                str(base.model.source) if base.model.source else "Donor",
+            )
+            if base_height_mm is None:
+                donor_standard = detect_standard_base(
+                    base.model._solid,
+                    donor_grid,
+                    str(base.model.source) if base.model.source else "Donor",
+                )
+                if donor_standard.height < height - 0.001:
+                    raise RebaseError(
+                        f"Donor base ends at {donor_standard.height:g} mm, before the input's {height:g} mm cut; use a compatible donor or set --base-height explicitly",
+                        code="incompatible_donor",
+                        details={
+                            "donor_base_height_mm": donor_standard.height,
+                            "base_height_mm": height,
+                        },
+                    )
+            replacement = donor_base(base.model._solid, donor_grid, grid, height)
+        geometry = None
+
+    _notify(on_progress, "replacing_base")
+    with _geometry_errors("replacement_failed"):
+        solid = replace_base(model._solid, replacement, grid, height)
+    result = RebaseResult(
+        model=Model._from_solid(solid),
+        report=RebaseReport(
+            grid=(grid.nx, grid.ny),
+            origin_mm=(grid.x, grid.y, grid.z),
+            base_height_mm=height,
+            base_height_mode="auto" if base_height_mm is None else "manual",
+            geometry=geometry,
+            triangles=solid.num_tri(),
+            elapsed_ms=round((perf_counter() - start) * 1000, 2),
+            inspection=info,
+        ),
+    )
+    _notify(on_progress, "complete")
+    return result
+
+
+def save_stl(model: Model, path: str | Path, *, overwrite: bool = False) -> int:
+    """Atomically export binary STL; return the exported triangle count.
+
+    Float32 export is validated separately and may change the triangle count
+    compared to the in-memory model. Existing files are protected by default.
+    """
+    _require_model(model)
+    return write_stl(model._solid, path, overwrite=overwrite)

gridfinity_rebase/catalog.py

@@ -0,0 +1,86 @@
+"""Preset descriptions, kept importable without loading the geometry engine."""
+
+from dataclasses import dataclass, replace
+from typing import Literal
+
+from .errors import RebaseError
+from .options import BaseOptions
+
+PRESETS = {
+    "plain": "Plain mating foot, no magnet or screw holes",
+    "magnet-holes": "Smooth bottom-loading 6.5 x 2.4 mm magnet pockets, no crush ribs",
+    "rebuilt": "Rebuilt/Refined fan pattern of side-loading 5.86 x 2.1 mm magnet pockets and removal slots",
+    "press-fit": "Rebuilt bottom magnet pockets with 8 crush ribs (5.9–6.5 mm diameter)",
+    "refined": "Alias of rebuilt: side-loading magnet pockets",
+}
+
+ALIASES = {"refined": "rebuilt"}
+
+PRESET_OPTIONS = {
+    "plain": BaseOptions(),
+    "magnet-holes": BaseOptions(magnets="bottom"),
+    "rebuilt": BaseOptions(magnets="side"),
+    "press-fit": BaseOptions(magnets="bottom", crush_ribs=True),
+}
+
+
+@dataclass(frozen=True)
+class Preset:
+    """Preset metadata; aliases have the same options as their canonical preset."""
+
+    id: str
+    description: str
+    options: BaseOptions
+    alias_of: str | None = None
+
+
+def list_presets() -> tuple[Preset, ...]:
+    """Return presets and compatibility aliases without loading geometry."""
+    return tuple(
+        Preset(
+            name,
+            description,
+            PRESET_OPTIONS[ALIASES.get(name, name)],
+            ALIASES.get(name),
+        )
+        for name, description in PRESETS.items()
+    )
+
+
+def resolve_options(
+    preset: str = "plain",
+    *,
+    magnets: Literal["none", "side", "bottom"] | None = None,
+    screws: bool | None = None,
+    crush_ribs: bool | None = None,
+    thumbscrew: bool | None = None,
+    only_corners: bool | None = None,
+    side_pocket_height_mm: float | None = None,
+) -> BaseOptions:
+    """Apply explicit overrides to a preset; None means keep its setting."""
+    if preset not in PRESETS:
+        raise RebaseError(
+            f"Unknown preset: {preset}",
+            code="unknown_preset",
+            details={"preset": preset},
+        )
+    options = PRESET_OPTIONS[ALIASES.get(preset, preset)]
+    overrides = {
+        name: value
+        for name, value in {
+            "magnets": magnets,
+            "screws": screws,
+            "crush_ribs": crush_ribs,
+            "thumbscrew": thumbscrew,
+            "only_corners": only_corners,
+            "side_pocket_height_mm": side_pocket_height_mm,
+        }.items()
+        if value is not None
+    }
+    # Ribs inherited from a preset belong to its bottom-loading pockets.
+    # An explicit --crush-ribs still fails validation for other magnet styles.
+    if magnets is not None and magnets != "bottom" and crush_ribs is None:
+        overrides["crush_ribs"] = False
+    if magnets is not None and magnets != "side" and side_pocket_height_mm is None:
+        overrides["side_pocket_height_mm"] = None
+    return replace(options, **overrides)