spatial-reasoner 0.1.0__py3-none-any.whl

spatial_reasoner/__init__.py

@@ -0,0 +1,94 @@
+"""Public API for the Spatial Reasoner Python implementation."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .bbox_sector import BBoxSector, BBoxSectorFlags
+from .reasoner import SpatialReasoner
+from .spatial_basics import (
+    MotionState,
+    NearbySchema,
+    ObjectCause,
+    ObjectConfidence,
+    ObjectHandling,
+    ObjectShape,
+    SectorSchema,
+    SpatialAdjustment,
+    SpatialAtribute,
+    SpatialExistence,
+    SpatialPredicateCategories,
+    defaultAdjustment,
+)
+from .spatial_inference import SpatialInference
+from .spatial_object import SpatialObject
+from .spatial_predicate import (
+    PredicateTerm,
+    SpatialPredicate,
+    SpatialTerms,
+    adjacency,
+    assembly,
+    comparability,
+    connectivity,
+    contacts,
+    directionality,
+    geography,
+    orientations,
+    proximity,
+    sectors,
+    similarity,
+    topology,
+    visibility,
+)
+from .spatial_relation import SpatialRelation
+from .spatial_taxonomy import SpatialObjectConcept, SpatialTaxonomy, TaxonomyParser
+from .vector2 import Vector2
+from .vector3 import Vector3
+
+try:
+    __version__ = version("spatial-reasoner")
+except PackageNotFoundError:  # pragma: no cover - direct source-tree import
+    __version__ = "0.1.0"
+
+__all__ = [
+    "BBoxSector",
+    "BBoxSectorFlags",
+    "MotionState",
+    "NearbySchema",
+    "ObjectCause",
+    "ObjectConfidence",
+    "ObjectHandling",
+    "ObjectShape",
+    "PredicateTerm",
+    "SectorSchema",
+    "SpatialAdjustment",
+    "SpatialAtribute",
+    "SpatialExistence",
+    "SpatialInference",
+    "SpatialObject",
+    "SpatialObjectConcept",
+    "SpatialPredicate",
+    "SpatialPredicateCategories",
+    "SpatialReasoner",
+    "SpatialRelation",
+    "SpatialTaxonomy",
+    "SpatialTerms",
+    "TaxonomyParser",
+    "Vector2",
+    "Vector3",
+    "__version__",
+    "adjacency",
+    "assembly",
+    "comparability",
+    "connectivity",
+    "contacts",
+    "defaultAdjustment",
+    "directionality",
+    "geography",
+    "orientations",
+    "proximity",
+    "sectors",
+    "similarity",
+    "topology",
+    "visibility",
+]

spatial_reasoner/bbox_sector.py

@@ -0,0 +1,351 @@
+# src/BBoxSector.py
+
+from __future__ import annotations
+
+from enum import IntFlag
+from typing import Any, ClassVar
+
+from .spatial_predicate import SpatialPredicate
+
+
+class BBoxSectorFlags(IntFlag):
+    none = 0  # no sector specified
+    i = 1 << 0  # i : inside, inner
+    a = 1 << 1  # a : ahead
+    b = 1 << 2  # b : behind
+    l = 1 << 3  # noqa: E741  # SRSwift-compatible short sector code for left
+    r = 1 << 4  # r : right
+    o = 1 << 5  # o : over
+    u = 1 << 6  # u : under
+
+    # Composite sectors
+    al = a | l
+    ar = a | r
+    bl = b | l
+    br = b | r
+    ao = a | o
+    au = a | u
+    bo = b | o
+    bu = b | u
+    lo = l | o
+    lu = l | u
+    ro = r | o
+    ru = r | u
+    alo = a | l | o
+    aro = a | r | o
+    blo = b | l | o
+    bro = b | r | o
+    alu = a | l | u
+    aru = a | r | u
+    blu = b | l | u
+    bru = b | r | u
+
+
+class BBoxSector:
+    """
+    A mutable class that represents spatial sectors using bitmask flags.
+    Mimics Swift's OptionSet behavior.
+    """
+
+    # Predefined descriptions for composite and individual sectors
+    debug_descriptions: ClassVar[dict[BBoxSectorFlags, str]] = {
+        BBoxSectorFlags.i: "i",
+        BBoxSectorFlags.a: "a",
+        BBoxSectorFlags.b: "b",
+        BBoxSectorFlags.l: "l",
+        BBoxSectorFlags.r: "r",
+        BBoxSectorFlags.o: "o",
+        BBoxSectorFlags.u: "u",
+        BBoxSectorFlags.al: "al",
+        BBoxSectorFlags.ar: "ar",
+        BBoxSectorFlags.bl: "bl",
+        BBoxSectorFlags.br: "br",
+        BBoxSectorFlags.ao: "ao",
+        BBoxSectorFlags.au: "au",
+        BBoxSectorFlags.bo: "bo",
+        BBoxSectorFlags.bu: "bu",
+        BBoxSectorFlags.lo: "lo",
+        BBoxSectorFlags.lu: "lu",
+        BBoxSectorFlags.ro: "ro",
+        BBoxSectorFlags.ru: "ru",
+        BBoxSectorFlags.alo: "alo",
+        BBoxSectorFlags.aro: "aro",
+        BBoxSectorFlags.blo: "blo",
+        BBoxSectorFlags.bro: "bro",
+        BBoxSectorFlags.alu: "alu",
+        BBoxSectorFlags.aru: "aru",
+        BBoxSectorFlags.blu: "blu",
+        BBoxSectorFlags.bru: "bru",
+    }
+
+    # Define base flags (individual flags only)
+    base_flags: ClassVar[set[BBoxSectorFlags]] = {
+        BBoxSectorFlags.i,
+        BBoxSectorFlags.a,
+        BBoxSectorFlags.b,
+        BBoxSectorFlags.l,
+        BBoxSectorFlags.r,
+        BBoxSectorFlags.o,
+        BBoxSectorFlags.u,
+    }
+
+    def __init__(self, flags=BBoxSectorFlags.none):
+        """
+        Initialize a BBoxSector instance.
+
+        Args:
+            flags (BBoxSectorFlags, optional): Initial sector flags. Defaults to BBoxSectorFlags.none.
+        """
+        self.flags = flags
+
+    def insert(self, flag: BBoxSectorFlags):
+        """
+        Insert a sector flag.
+
+        Args:
+            flag (BBoxSectorFlags): The flag to insert.
+        """
+        self.flags |= flag
+
+    def remove(self, flag: BBoxSectorFlags):
+        """
+        Remove a sector flag.
+
+        Args:
+            flag (BBoxSectorFlags): The flag to remove.
+        """
+        self.flags &= ~flag
+
+    def contains_flag(self, flag: BBoxSectorFlags) -> bool:
+        """
+        Check if a sector flag is present.
+
+        Args:
+            flag (BBoxSectorFlags): The flag to check.
+
+        Returns:
+            bool: True if the flag is present, False otherwise.
+        """
+        return (self.flags & flag) == flag
+
+    def contains(self, flag: BBoxSectorFlags) -> bool:
+        """
+        Alias for contains_flag to maintain backward compatibility.
+
+        Args:
+            flag (BBoxSectorFlags): The flag to check.
+
+        Returns:
+            bool: True if the flag is present, False otherwise.
+        """
+        return self.contains_flag(flag)
+
+    def divergencies(self) -> int:
+        """
+        Calculate the amount of divergency from the inner zone in all 3 directions.
+
+        Returns:
+            int: 0 if the sector includes 'i' (inside), otherwise the number of set bits.
+        """
+        if self.contains_flag(BBoxSectorFlags.i):
+            return 0
+        return bin(self.flags.value).count("1")
+
+    def list_base_flags(self):
+        """
+        List only the base flags present in the sector.
+        """
+        return [
+            name
+            for name, member in BBoxSectorFlags.__members__.items()
+            if member in self.flags and name != "none" and member in BBoxSector.base_flags
+        ]
+
+    def __str__(self) -> str:
+        """
+        Provide a string representation for the sector.
+
+        Returns:
+            str: The descriptive string of the sector.
+        """
+        # Always list base flags to match test expectations
+        flags = self.list_base_flags()
+        if flags:
+            return "".join(flags)
+        elif self.flags == BBoxSectorFlags.none:
+            return "no sector"
+        else:
+            # If no base flags are set, but some composite flags are, list them
+            # This can happen if only composite flags are set without their base flags
+            composite_flags = [
+                name
+                for name, member in BBoxSectorFlags.__members__.items()
+                if member in self.flags and name != "none" and member not in BBoxSector.base_flags
+            ]
+            if composite_flags:
+                return "".join(composite_flags)
+            return "no sector"
+
+    def __eq__(self, other: Any) -> bool:
+        """
+        Check equality with another BBoxSector instance.
+
+        Args:
+            other (Any): The object to compare.
+
+        Returns:
+            bool: True if equal, False otherwise.
+        """
+        if isinstance(other, BBoxSector):
+            return self.flags == other.flags
+        return False
+
+    def __repr__(self) -> str:
+        """
+        Return the official string representation of the sector.
+
+        Returns:
+            str: The string representation.
+        """
+        return f"BBoxSector(flags={self.flags})"
+
+    def __hash__(self) -> int:
+        """
+        Make BBoxSector hashable (so you can use it in sets/dicts),
+        just like Swift’s Hashable conformance.
+        """
+        return hash(self.flags)
+
+    @classmethod
+    def named(cls, name: str) -> BBoxSector:
+        """
+        Look up a sector by its name (e.g. "alo", "b", "ru").
+        Returns BBoxSector.none if no match found.
+        """
+        for flag, desc in cls.debug_descriptions.items():
+            if desc == name:
+                return cls(flag)
+        return cls()
+
+    def __or__(self, other: Any) -> BBoxSector:
+        """
+        Define the behavior of the | operator.
+
+        Args:
+            other (BBoxSector or BBoxSectorFlags): The other sector or flag to combine.
+
+        Returns:
+            BBoxSector: A new BBoxSector instance with combined flags.
+        """
+        if isinstance(other, BBoxSector):
+            return BBoxSector(self.flags | other.flags)
+        elif isinstance(other, BBoxSectorFlags):
+            return BBoxSector(self.flags | other)
+        else:
+            return NotImplemented
+
+    def __ior__(self, other: Any) -> BBoxSector:
+        """
+        Define the behavior of the |= operator.
+
+        Args:
+            other (BBoxSector or BBoxSectorFlags): The other sector or flag to combine.
+
+        Returns:
+            BBoxSector: The updated BBoxSector instance.
+        """
+        if isinstance(other, BBoxSector):
+            self.flags |= other.flags
+            return self
+        elif isinstance(other, BBoxSectorFlags):
+            self.flags |= other
+            return self
+        else:
+            return NotImplemented
+
+    def __contains__(self, item: Any) -> bool:
+        """
+        Enable the 'in' operator to check for SpatialPredicate or BBoxSectorFlags.
+
+        Args:
+            item (Any): SpatialPredicate or BBoxSectorFlags to check.
+
+        Returns:
+            bool: True if the item is present, False otherwise.
+        """
+        if isinstance(item, SpatialPredicate):
+            # Map SpatialPredicate to BBoxSectorFlags
+            flag_map = {
+                SpatialPredicate.l: BBoxSectorFlags.l,
+                SpatialPredicate.r: BBoxSectorFlags.r,
+                SpatialPredicate.a: BBoxSectorFlags.a,
+                SpatialPredicate.b: BBoxSectorFlags.b,
+                SpatialPredicate.o: BBoxSectorFlags.o,
+                SpatialPredicate.u: BBoxSectorFlags.u,
+                SpatialPredicate.i: BBoxSectorFlags.i,
+                SpatialPredicate.al: BBoxSectorFlags.al,
+                SpatialPredicate.ar: BBoxSectorFlags.ar,
+                SpatialPredicate.bl: BBoxSectorFlags.bl,
+                SpatialPredicate.br: BBoxSectorFlags.br,
+                SpatialPredicate.ao: BBoxSectorFlags.ao,
+                SpatialPredicate.au: BBoxSectorFlags.au,
+                SpatialPredicate.bo: BBoxSectorFlags.bo,
+                SpatialPredicate.bu: BBoxSectorFlags.bu,
+                SpatialPredicate.lo: BBoxSectorFlags.lo,
+                SpatialPredicate.lu: BBoxSectorFlags.lu,
+                SpatialPredicate.ro: BBoxSectorFlags.ro,
+                SpatialPredicate.ru: BBoxSectorFlags.ru,
+                SpatialPredicate.alo: BBoxSectorFlags.alo,
+                SpatialPredicate.aro: BBoxSectorFlags.aro,
+                SpatialPredicate.blo: BBoxSectorFlags.blo,
+                SpatialPredicate.bro: BBoxSectorFlags.bro,
+                SpatialPredicate.alu: BBoxSectorFlags.alu,
+                SpatialPredicate.aru: BBoxSectorFlags.aru,
+                SpatialPredicate.blu: BBoxSectorFlags.blu,
+                SpatialPredicate.bru: BBoxSectorFlags.bru,
+                # Add more mappings as needed
+            }
+            flag = flag_map.get(item, None)
+            if flag is not None:
+                return self.contains_flag(flag)
+        elif isinstance(item, BBoxSectorFlags):
+            return self.contains_flag(item)
+        return False
+
+
+# Example Usage
+
+if __name__ == "__main__":
+    # Initialize with a predefined composite sector
+    sector = BBoxSector(BBoxSectorFlags.alo)
+    print(f"Sector: {sector}")  # Output: Sector: a+l+o
+    print(f"Divergencies: {sector.divergencies()}")  # Output: Divergencies: 3
+
+    # Create an empty sector and insert flags
+    combined_sector = BBoxSector()
+    combined_sector.insert(BBoxSectorFlags.a)
+    combined_sector.insert(BBoxSectorFlags.l)
+    combined_sector.insert(BBoxSectorFlags.o)
+    print(f"Combined Sector: {combined_sector}")  # Output: Combined Sector: a+l+o
+    print(f"Divergencies: {combined_sector.divergencies()}")  # Output: Divergencies: 3
+
+    # Initialize with the 'inside' sector
+    inner_sector = BBoxSector(BBoxSectorFlags.i)
+    print(f"Inner Sector: {inner_sector}")  # Output: Inner Sector: i
+    print(f"Divergencies: {inner_sector.divergencies()}")  # Output: Divergencies: 0
+
+    # Initialize with no sector
+    no_sector = BBoxSector()
+    print(f"No Sector: {no_sector}")  # Output: No Sector: no sector
+    print(f"Divergencies: {no_sector.divergencies()}")  # Output: Divergencies: 0
+
+    # Undefined composite sector example
+    undefined_sector = BBoxSector()
+    undefined_sector.insert(BBoxSectorFlags.a)
+    undefined_sector.insert(BBoxSectorFlags.b)
+    undefined_sector.insert(BBoxSectorFlags.l)
+    undefined_sector.insert(BBoxSectorFlags.r)
+    print(
+        f"Undefined Combined Sector: {undefined_sector}"
+    )  # Output: Undefined Combined Sector: a+b+l+r
+    print(f"Divergencies: {undefined_sector.divergencies()}")  # Output: Divergencies: 4

spatial_reasoner/exporter.py

@@ -0,0 +1,128 @@
+"""Optional OpenUSD scene export support.
+
+Install ``spatial-reasoner[export]`` before importing this module.
+"""
+
+from __future__ import annotations
+
+import math
+import random
+import tempfile
+from pathlib import Path
+
+try:
+    from pxr import Gf, Sdf, Usd, UsdGeom, UsdShade, UsdUtils
+except ModuleNotFoundError as exc:  # pragma: no cover - depends on installation extras
+    raise ModuleNotFoundError(
+        "Scene export requires the optional dependency group; "
+        "install it with `pip install spatial-reasoner[export]`."
+    ) from exc
+
+from .spatial_object import SpatialObject
+
+
+class SceneExporter:
+    """Export spatial-object bounding boxes as USDZ scenes."""
+
+    def __init__(self, root_dir: str | Path):
+        """Create an exporter writing into ``root_dir``."""
+        self.root_dir = Path(root_dir)
+        self.root_dir.mkdir(parents=True, exist_ok=True)
+        self.usd_file_path: Path | None = None
+        self.temp_usd_path: Path | None = None
+        self.stage = None
+
+    def exportUSDZ(self, spatial_objects: list[SpatialObject], filename: str | Path) -> None:
+        """Export ``spatial_objects`` to a USDZ file.
+
+        The method name intentionally follows SRSwift's public API.
+        """
+        output_path = Path(filename)
+        if not output_path.is_absolute():
+            output_path = self.root_dir / output_path
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.unlink(missing_ok=True)
+        self.usd_file_path = output_path
+
+        with tempfile.NamedTemporaryFile(
+            prefix="spatial_reasoner_", suffix=".usd", dir=self.root_dir, delete=False
+        ) as temporary_file:
+            self.temp_usd_path = Path(temporary_file.name)
+        self.temp_usd_path.unlink(missing_ok=True)
+
+        try:
+            self.stage = Usd.Stage.CreateNew(str(self.temp_usd_path))
+            for obj in spatial_objects:
+                prim_path = self._create_obj_cube(obj)
+                self._create_bbox_cube(obj, prim_path)
+
+            self.stage.GetRootLayer().Save()
+            self.stage = None
+            created = UsdUtils.CreateNewUsdzPackage(
+                Sdf.AssetPath(str(self.temp_usd_path)), str(output_path)
+            )
+            if not created or not output_path.exists():
+                raise RuntimeError(f"OpenUSD could not create USDZ package: {output_path}")
+        finally:
+            self.stage = None
+            self.temp_usd_path.unlink(missing_ok=True)
+
+    def _create_obj_cube(self, spatial_object: SpatialObject) -> str:
+        """Add a spatial object and its material to the current USD stage."""
+        prim_path = f"/{spatial_object.id}"
+        xform = UsdGeom.Xform.Define(self.stage, prim_path)
+        xform.AddRotateYOp().Set(math.degrees(spatial_object.angle))
+        xform.AddTranslateOp().Set(
+            Gf.Vec3d(
+                spatial_object.position.x,
+                spatial_object.position.y,
+                spatial_object.position.z,
+            )
+        )
+        xform.AddScaleOp().Set(
+            Gf.Vec3f(spatial_object.width, spatial_object.height, spatial_object.depth)
+        )
+
+        cube = UsdGeom.Cube.Define(self.stage, f"{prim_path}/Cube")
+        material_path = f"{prim_path}/Material"
+        material = UsdShade.Material.Define(self.stage, material_path)
+        color = Gf.Vec3f(random.random(), random.random(), random.random())
+
+        shader = UsdShade.Shader.Define(self.stage, f"{material_path}/Shader")
+        shader.CreateIdAttr("UsdPreviewSurface")
+        shader.CreateInput("diffuseColor", Sdf.ValueTypeNames.Color3f).Set(color)
+        shader.CreateInput("opacity", Sdf.ValueTypeNames.Float).Set(
+            1.0 - spatial_object.transparency
+        )
+        shader.CreateOutput("surface", Sdf.ValueTypeNames.Token)
+        material.CreateSurfaceOutput().ConnectToSource(shader.GetOutput("surface"))
+        UsdShade.MaterialBindingAPI(xform.GetPrim()).Bind(material)
+
+        prim = cube.GetPrim()
+        prim.CreateAttribute("user:transparency", Sdf.ValueTypeNames.Float).Set(
+            spatial_object.transparency
+        )
+        prim.CreateAttribute("user:color", Sdf.ValueTypeNames.Color3f).Set(color)
+        return prim_path
+
+    def _create_bbox_cube(
+        self,
+        obj: SpatialObject,
+        parent_path: str,
+        color: tuple[float, float, float] = (0.0, 0.0, 0.0),
+    ) -> None:
+        """Add the object's nearby-radius sphere below ``parent_path``."""
+        bbox_prim_path = f"{parent_path}/BBox"
+        UsdGeom.Xform.Define(self.stage, bbox_prim_path)
+        sphere_path = f"{bbox_prim_path}/NearbySphere"
+        sphere = UsdGeom.Sphere.Define(self.stage, sphere_path)
+        sphere.GetPrim().CreateAttribute("radius", Sdf.ValueTypeNames.Float).Set(obj.nearbyRadius())
+
+        material = UsdShade.Material.Define(self.stage, f"{sphere_path}/Material")
+        shader = UsdShade.Shader.Define(self.stage, f"{sphere_path}/Material/Shader")
+        shader.CreateIdAttr("UsdPreviewSurface")
+        shader.CreateInput("diffuseColor", Sdf.ValueTypeNames.Color3f).Set(Gf.Vec3f(*color))
+        shader.CreateInput("opacity", Sdf.ValueTypeNames.Float).Set(0.3)
+        shader.CreateOutput("surface", Sdf.ValueTypeNames.Token)
+        material.CreateSurfaceOutput().ConnectToSource(shader.GetOutput("surface"))
+        UsdShade.MaterialBindingAPI(sphere.GetPrim()).Bind(material)