fungeom 0.1.0__py3-none-any.whl

fungeom/__init__.py

@@ -0,0 +1,215 @@
+"""fungeom — a functional geometry API.
+
+Geometry is described as an immutable, lazily-evaluated graph of resolvers. Each
+primitive is one class — ``Scalar``, ``Vec2``, ``Vec3``, ``Direction3``,
+``Transform``, ``Frame``, ``Point3`` — that you both construct from (classmethods
+like ``Vec3.of`` / ``Point3.at``) and compose with (fluent methods like
+``a.midpoint(b)``). Build a graph, ``decide()`` whether it can be resolved, then
+``resolve()`` to get a concrete value (reachable as ``<Primitive>.Value``).
+
+The decidability core (``Resolver``, ``Resolvable``, ``Unresolvable``,
+``gather``) is public; the concrete resolvers behind each facade are not.
+"""
+
+from fungeom.core import (
+    Resolvability,
+    Resolvable,
+    Resolver,
+    Unresolvable,
+    UnresolvableError,
+    gather,
+)
+from fungeom.primitives import (
+    MASTER_CLOCK,
+    WORLD_FRAME,
+    WORLD_FRAME2,
+    AffineTimeMap,
+    Bool,
+    BoolSeries,
+    BoolSignal,
+    Boundary,
+    Clock,
+    CoordinateFrame,
+    CoordinateFrame2,
+    Direction3Signal,
+    Coverage,
+    CoverageValue,
+    Direction2,
+    Direction2Value,
+    Direction3,
+    Duration,
+    Frame,
+    Frame2,
+    Instant,
+    Interpolation,
+    Interval,
+    IntervalValue,
+    Line,
+    Line2,
+    Line2Value,
+    LineValue,
+    Mat3,
+    Mat4,
+    Plane,
+    PlaneValue,
+    Point2,
+    Point2Value,
+    Point3,
+    PlaneSignal,
+    Point3Signal,
+    Ray,
+    Ray2,
+    Ray2Value,
+    RayValue,
+    Face,
+    FaceValue,
+    Region2,
+    Region2Value,
+    Roster,
+    RosterValue,
+    RosterMap,
+    KeyCorrespondence,
+    Mat2,
+    RigidTransform,
+    RigidTransform2,
+    Segment,
+    Segment2,
+    Segment2Value,
+    SegmentValue,
+    Transform2,
+    SampledSeries,
+    Sampling,
+    SamplingValue,
+    Scalar,
+    ScalarSignal,
+    BoolBundle,
+    Bundle,
+    BundleValue,
+    Direction3Bundle,
+    PiecewiseLinearWarp,
+    Point2Bundle,
+    Point3Bundle,
+    Point3BundleSignal,
+    ScalarBundleSignal,
+    ScalarBundle,
+    TransformBundle,
+    TransformBundleSignal,
+    Vec3Bundle,
+    TimeMap,
+    TimeWarp,
+    Timeline,
+    Transform,
+    TransformSignal,
+    Vec2,
+    Vec3,
+    Vec3Signal,
+)
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _package_version
+
+from fungeom.viz import render_tree, resolver_tree
+
+try:
+    __version__ = _package_version("fungeom")
+except PackageNotFoundError:  # pragma: no cover - only hit running from an uninstalled source tree
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "__version__",
+    # primitives (facades)
+    "Bool",
+    "Scalar",
+    "Vec2",
+    "Vec3",
+    "Direction2",
+    "Direction3",
+    "Transform",
+    "Transform2",
+    "Frame",
+    "Frame2",
+    "Point2",
+    "Point3",
+    "Plane",
+    "Region2",
+    "Face",
+    "Line",
+    "Line2",
+    "Ray",
+    "Ray2",
+    "Segment",
+    "Segment2",
+    # temporal
+    "Duration",
+    "Instant",
+    "Interval",
+    "Coverage",
+    "TimeMap",
+    "TimeWarp",
+    "Timeline",
+    "Sampling",
+    "Bundle",
+    "ScalarBundle",
+    "Vec3Bundle",
+    "Direction3Bundle",
+    "BoolBundle",
+    "TransformBundle",
+    "Point2Bundle",
+    "Point3Bundle",
+    "PlaneSignal",
+    "Point3BundleSignal",
+    "ScalarBundleSignal",
+    "TransformBundleSignal",
+    "BoolSignal",
+    "Roster",
+    "RosterMap",
+    "Interpolation",
+    "Boundary",
+    "ScalarSignal",
+    "Vec3Signal",
+    "Direction3Signal",
+    "TransformSignal",
+    "Point3Signal",
+    # commonly-used value types
+    "RigidTransform",
+    "RigidTransform2",
+    "Mat2",
+    "Point2Value",
+    "Region2Value",
+    "FaceValue",
+    "PlaneValue",
+    "LineValue",
+    "Line2Value",
+    "RayValue",
+    "Ray2Value",
+    "SegmentValue",
+    "Segment2Value",
+    "Direction2Value",
+    "CoordinateFrame",
+    "WORLD_FRAME",
+    "CoordinateFrame2",
+    "WORLD_FRAME2",
+    "IntervalValue",
+    "CoverageValue",
+    "AffineTimeMap",
+    "PiecewiseLinearWarp",
+    "BundleValue",
+    "RosterValue",
+    "KeyCorrespondence",
+    "Clock",
+    "MASTER_CLOCK",
+    "SamplingValue",
+    "BoolSeries",
+    "SampledSeries",
+    "Mat3",
+    "Mat4",
+    # decidability core
+    "Resolver",
+    "Resolvability",
+    "Resolvable",
+    "Unresolvable",
+    "UnresolvableError",
+    "gather",
+    # visualization
+    "resolver_tree",
+    "render_tree",
+]

fungeom/core/__init__.py

@@ -0,0 +1,22 @@
+from .arrays import ArrayLike, freeze
+from .resolvability import (
+    Resolvability,
+    Resolvable,
+    Unresolvable,
+    UnresolvableError,
+    gather,
+)
+from .resolver import Resolver
+
+__all__ = [
+    # resolver / resolvability
+    "Resolver",
+    "Resolvability",
+    "Resolvable",
+    "Unresolvable",
+    "UnresolvableError",
+    "gather",
+    # arrays
+    "ArrayLike",
+    "freeze",
+]

fungeom/core/arrays.py

@@ -0,0 +1,25 @@
+"""Generic numpy helpers shared across primitives.
+
+These have no geometric meaning of their own — they are the small,
+primitive-agnostic array utilities that the value types lean on. Keeping them in
+``core`` lets every primitive (vectors, transforms, points) depend on them
+without any of them depending on each other.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy.typing as npt
+
+type ArrayLike = npt.ArrayLike
+"""Anything coercible into an array: a numpy array, a list, a tuple of numbers."""
+
+
+def freeze(arr: npt.NDArray[Any]) -> None:
+    """Mark a numpy array read-only, in place.
+
+    Used by the frozen value dataclasses so that an immutable value object cannot
+    have its backing buffer mutated out from under it.
+    """
+    arr.setflags(write=False)

fungeom/core/resolvability.py

@@ -0,0 +1,74 @@
+"""Resolvability: evidence about whether a resolver can be resolved.
+
+Deciding whether a :class:`~fungeom.core.resolver.Resolver` can produce a
+value is itself a computation over its graph. Rather than collapse that into a
+bare ``bool`` (which would throw away *why* something cannot be resolved), the
+decision is reified as a small sum type:
+
+* :class:`Resolvable` — proof that resolution succeeds, carrying the value it
+  computed along the way (so a later ``resolve()`` is free).
+* :class:`Unresolvable` — proof that it does not, carrying a human-readable
+  reason.
+
+``Resolvability[T] = Resolvable[T] | Unresolvable`` is what ``Resolver.decide()``
+returns. :class:`Unresolvable` is deliberately *not* generic: a failure carries
+only a reason, so the same value can flow out of a ``Vec3`` decision and into a
+``Point3`` one without rewrapping. Because the decision is an ordinary value, you
+can pass it around, ``match`` on it, or require :class:`Resolvable` in a function
+signature to demand a *proven-resolvable* input at type-check time.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import ClassVar, NoReturn
+
+
+class UnresolvableError(Exception):
+    """Raised when something that cannot be resolved is asked to resolve."""
+
+
+@dataclass(frozen=True)
+class Resolvable[T]:
+    """Evidence that a resolver resolves, carrying the computed value."""
+
+    value: T
+
+    ok: ClassVar[bool] = True
+
+    def unwrap(self) -> T:
+        """Return the resolved value."""
+        return self.value
+
+
+@dataclass(frozen=True)
+class Unresolvable:
+    """Evidence that a resolver does not resolve, and why."""
+
+    reason: str
+
+    ok: ClassVar[bool] = False
+
+    def unwrap(self) -> NoReturn:
+        """Raise :class:`UnresolvableError` with the captured reason."""
+        raise UnresolvableError(self.reason)
+
+
+type Resolvability[T] = Resolvable[T] | Unresolvable
+"""The result of :meth:`~fungeom.core.resolver.Resolver.decide`."""
+
+
+def gather[T](decisions: Iterable[Resolvability[T]]) -> Resolvability[list[T]]:
+    """Collect many decisions into one.
+
+    Returns :class:`Resolvable` with every value once they all succeed, or the
+    first :class:`Unresolvable` encountered. This is the ``traverse`` that makes
+    N-ary combinators (a centroid, a polyline, ...) short and uniform.
+    """
+    values: list[T] = []
+    for decision in decisions:
+        if isinstance(decision, Unresolvable):
+            return decision
+        values.append(decision.value)
+    return Resolvable(values)

fungeom/core/resolver.py

@@ -0,0 +1,85 @@
+"""The ``Resolver`` abstraction: the spine of the functional API.
+
+A ``Resolver[T]`` is a *deferred* description of a value of type ``T``. Nothing
+is computed when you build one; the value is produced only when you resolve it.
+Because resolvers are immutable, every transformation (``translate``,
+``reframe``, ...) returns a *new* resolver rather than mutating the existing one.
+Chains of resolvers therefore form a directed acyclic graph (a lazy expression
+tree) that is evaluated on demand.
+
+The single primitive every concrete resolver implements is :meth:`_decide`, which
+*proves* whether the resolver can be resolved (returning the value on success or
+a reason on failure). The public :meth:`decide` memoizes it; ``resolve()`` and
+``is_resolvable`` are derived from :meth:`decide`, so deciding and resolving can
+never disagree, and a shared sub-graph is decided at most once.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from fungeom.core.resolvability import Resolvability
+
+
+class Resolver[T](ABC):
+    """A generic object that can be resolved to a value of type ``T``.
+
+    Subclasses describe *how* to produce a ``T`` and implement :meth:`_decide`.
+    Resolvers are expected to be immutable value objects so that the expression
+    graph they form is safe to share and cache.
+    """
+
+    @abstractmethod
+    def _decide(self) -> Resolvability[T]:
+        """Compute this resolver's decision. Implemented by each concrete resolver.
+
+        Returns :class:`~fungeom.core.resolvability.Resolvable` carrying
+        the computed value, or
+        :class:`~fungeom.core.resolvability.Unresolvable` carrying the
+        reason it cannot be resolved. Call :meth:`decide` (which memoizes this).
+        """
+
+    def decide(self) -> Resolvability[T]:
+        """Prove whether this resolver can be resolved (memoized).
+
+        The result is cached on the (immutable) resolver, so deciding it again —
+        or deciding a graph that reuses it as a sub-expression — is free.
+        """
+        cached: Resolvability[T] | None = getattr(self, "_decision", None)
+        if cached is None:
+            cached = self._decide()
+            object.__setattr__(self, "_decision", cached)
+        return cached
+
+    def resolve(self) -> T:
+        """Resolve to a concrete value, or raise ``UnresolvableError``.
+
+        This is total only when you already hold proof of resolvability (e.g.
+        the value returned by :meth:`decide` matched as ``Resolvable``).
+        """
+        return self.decide().unwrap()
+
+    @property
+    def is_resolvable(self) -> bool:
+        """Whether :meth:`resolve` would succeed."""
+        return self.decide().ok
+
+    def children(self) -> list[Resolver[Any]]:
+        """The immediate sub-resolvers this one is built from.
+
+        Found by inspecting dataclass fields (including those holding a tuple or
+        list of resolvers), so combinators expose their structure for free —
+        enough to walk or visualize the lazy graph.
+        """
+        field_names: dict[str, Any] | None = getattr(self, "__dataclass_fields__", None)
+        if not field_names:
+            return []
+        found: list[Resolver[Any]] = []
+        for name in field_names:
+            value = getattr(self, name)
+            if isinstance(value, Resolver):
+                found.append(value)
+            elif isinstance(value, (tuple, list)):
+                found.extend(item for item in value if isinstance(item, Resolver))
+        return found

fungeom/primitives/__init__.py

@@ -0,0 +1,164 @@
+"""Geometric primitives, each a submodule with the same shape.
+
+Every primitive is one **facade class** (the resolver) with classmethod
+constructors and fluent combinators; its resolved value is reachable as
+``<Primitive>.Value``. Concrete resolvers live behind the facade (one file each
+under ``<primitive>/resolvers/``) and are not part of the public surface.
+
+Submodules: ``boolean``, ``scalar``, ``vec2``, ``vec3``, ``direction3``, ``transform``,
+``frame``, ``point3``, plus the temporal ``duration`` / ``instant`` / ``interval``
+/ ``coverage`` / ``timemap`` / ``timeline`` / ``sampling`` and the ``signals``
+package (scalar / vec3 / direction3 / transform / point3, over one generic core).
+"""
+
+from fungeom.primitives.boolean import Bool
+from fungeom.primitives.coverage import Coverage, CoverageValue
+from fungeom.primitives.direction2 import Direction2, Direction2Value
+from fungeom.primitives.direction3 import Direction3, Direction3Value
+from fungeom.primitives.duration import Duration
+from fungeom.primitives.frame import WORLD_FRAME, CoordinateFrame, Frame
+from fungeom.primitives.frame2 import WORLD_FRAME2, CoordinateFrame2, Frame2
+from fungeom.primitives.instant import Instant
+from fungeom.primitives.interval import Interval, IntervalValue
+from fungeom.primitives.line import Line, LineValue
+from fungeom.primitives.line2 import Line2, Line2Value
+from fungeom.primitives.plane import Plane, PlaneValue
+from fungeom.primitives.point2 import Point2, Point2Value
+from fungeom.primitives.point3 import Point3, Point3Value
+from fungeom.primitives.ray import Ray, RayValue
+from fungeom.primitives.ray2 import Ray2, Ray2Value
+from fungeom.primitives.roster import Roster, RosterValue
+from fungeom.primitives.rostermap import KeyCorrespondence, RosterMap
+from fungeom.primitives.sampling import Sampling, SamplingValue
+from fungeom.primitives.segment import Segment, SegmentValue
+from fungeom.primitives.segment2 import Segment2, Segment2Value
+from fungeom.primitives.scalar import Scalar
+from fungeom.primitives.signals import (
+    BoolSignal,
+    Boundary,
+    Direction3Signal,
+    Interpolation,
+    PlaneSignal,
+    Point3BundleSignal,
+    ScalarBundleSignal,
+    Point3Signal,
+    BoolSeries,
+    SampledSeries,
+    ScalarSignal,
+    TransformBundleSignal,
+    TransformSignal,
+    Vec3Signal,
+)
+from fungeom.primitives.timeline import MASTER_CLOCK, Clock, Timeline
+from fungeom.primitives.bundle import (
+    BoolBundle,
+    Bundle,
+    BundleValue,
+    Direction3Bundle,
+    Point2Bundle,
+    Point3Bundle,
+    ScalarBundle,
+    TransformBundle,
+    Vec3Bundle,
+)
+from fungeom.primitives.region2 import Region2, Region2Value
+from fungeom.primitives.face import Face, FaceValue
+from fungeom.primitives.timemap import AffineTimeMap, TimeMap
+from fungeom.primitives.timewarp import PiecewiseLinearWarp, TimeWarp
+from fungeom.primitives.transform import Mat3, Mat4, RigidTransform, Transform
+from fungeom.primitives.transform2 import Mat2, RigidTransform2, Transform2
+from fungeom.primitives.vec2 import Float2, Vec2
+from fungeom.primitives.vec3 import Float3, Vec3
+
+__all__ = [
+    # facades
+    "Bool",
+    "Scalar",
+    "Vec2",
+    "Vec3",
+    "Direction2",
+    "Direction3",
+    "Transform",
+    "Transform2",
+    "Frame",
+    "Frame2",
+    "Point2",
+    "Point3",
+    "Plane",
+    "Region2",
+    "Face",
+    "Line",
+    "Line2",
+    "Ray",
+    "Ray2",
+    "Segment",
+    "Segment2",
+    # temporal
+    "Duration",
+    "Instant",
+    "Interval",
+    "Coverage",
+    "TimeMap",
+    "TimeWarp",
+    "Timeline",
+    "Sampling",
+    "Bundle",
+    "BoolBundle",
+    "ScalarBundle",
+    "Vec3Bundle",
+    "Direction3Bundle",
+    "TransformBundle",
+    "Point2Bundle",
+    "Point3Bundle",
+    "PlaneSignal",
+    "Point3BundleSignal",
+    "ScalarBundleSignal",
+    "TransformBundleSignal",
+    "BoolSignal",
+    "Roster",
+    "RosterMap",
+    "Interpolation",
+    "Boundary",
+    "ScalarSignal",
+    "Vec3Signal",
+    "Direction3Signal",
+    "TransformSignal",
+    "Point3Signal",
+    # value types
+    "IntervalValue",
+    "CoverageValue",
+    "AffineTimeMap",
+    "PiecewiseLinearWarp",
+    "Clock",
+    "MASTER_CLOCK",
+    "SamplingValue",
+    "BoolSeries",
+    "SampledSeries",
+    "BundleValue",
+    "RosterValue",
+    "KeyCorrespondence",
+    "Float2",
+    "Float3",
+    "Mat2",
+    "Mat3",
+    "Mat4",
+    "RigidTransform",
+    "RigidTransform2",
+    "CoordinateFrame",
+    "WORLD_FRAME",
+    "CoordinateFrame2",
+    "WORLD_FRAME2",
+    "Point2Value",
+    "Region2Value",
+    "FaceValue",
+    "Point3Value",
+    "PlaneValue",
+    "LineValue",
+    "Line2Value",
+    "RayValue",
+    "Ray2Value",
+    "SegmentValue",
+    "Segment2Value",
+    "Direction2Value",
+    "Direction3Value",
+]

fungeom/primitives/boolean/__init__.py

@@ -0,0 +1,8 @@
+from fungeom.primitives.boolean.resolvers.base import Bool
+from fungeom.primitives.boolean.resolvers.literal import LiteralBool
+
+# The truth-value constants, as resolvers (see ``Bool.true`` / ``Bool.false``).
+Bool.true = LiteralBool(value=True)
+Bool.false = LiteralBool(value=False)
+
+__all__ = ["Bool"]

fungeom/primitives/boolean/decidability.py

@@ -0,0 +1,14 @@
+"""Resolvability aliases for booleans."""
+
+from __future__ import annotations
+
+from fungeom.core.resolvability import Resolvability, Resolvable, Unresolvable
+
+type BoolResolvable = Resolvable[bool]
+"""A boolean decision that succeeded — carries the truth value."""
+
+type BoolUnresolvable = Unresolvable
+"""A boolean decision that failed — carries the reason (e.g. an unresolvable operand)."""
+
+type BoolDecision = Resolvability[bool]
+"""The result of deciding a ``Bool``."""