spatial-reasoner 0.1.0__tar.gz

spatial_reasoner-0.1.0/LICENSE

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

spatial_reasoner-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: spatial-reasoner
+Version: 0.1.0
+Summary: A flexible 3D spatial reasoning library for Python
+Author: Steven Häsler, Philipp Ackermann
+License-Expression: CC0-1.0
+Project-URL: Documentation, https://github.com/metason/SpatialReasoner
+Project-URL: Issues, https://github.com/metason/SRpy/issues
+Project-URL: Paper, https://doi.org/10.1109/ICVARS66454.2025.11198690
+Project-URL: Repository, https://github.com/metason/SRpy
+Keywords: 3d,inference,reasoning,spatial,xr
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Provides-Extra: export
+Requires-Dist: usd-core>=25.2; extra == "export"
+Provides-Extra: test
+Requires-Dist: coverage[toml]<8,>=7; extra == "test"
+Requires-Dist: pytest<9,>=8; extra == "test"
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.3; extra == "dev"
+Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
+Requires-Dist: twine<7,>=6.2; extra == "dev"
+Dynamic: license-file
+
+# Spatial Reasoner for Python
+
+`spatial-reasoner` is a 3D spatial-reasoning library derived from the CC0
+[SRSwift reference implementation](https://github.com/metason/SpatialReasoner). It models
+oriented spatial objects and evaluates explicit pipelines for topology, directionality,
+visibility, connectivity, comparison, and similarity predicates.
+
+This is an alpha release. Version 0.1.x preserves the SRSwift-facing camelCase API and
+reasoning behavior, but the Python package API may still evolve before 1.0.
+
+## Installation
+
+Spatial Reasoner supports Python 3.11 through 3.14.
+
+```bash
+python -m pip install spatial-reasoner
+```
+
+OpenUSD scene export is optional:
+
+```bash
+python -m pip install "spatial-reasoner[export]"
+```
+
+## Quick start
+
+The principal classes are available directly from `spatial_reasoner`:
+
+```python
+from spatial_reasoner import SpatialObject, SpatialReasoner, Vector3
+
+crate = SpatialObject(
+    "crate",
+    position=Vector3(0.0, 0.0, 0.0),
+    width=2.0,
+    height=2.0,
+    depth=2.0,
+)
+marker = SpatialObject(
+    "marker",
+    position=Vector3(3.0, 0.0, 0.0),
+    width=0.1,
+    height=0.1,
+    depth=0.1,
+)
+
+reasoner = SpatialReasoner()
+reasoner.load([crate, marker])
+assert reasoner.run("filter(volume > 0.5)")
+assert [obj.id for obj in reasoner.result()] == ["crate"]
+```
+
+Pipeline predicates may be addressed by their SRSwift-compatible enum names. For example,
+`seenleft` selects the predicate whose readable value is `"seen left"`.
+
+> [!WARNING]
+> Pipeline filter, select, map, calculate, and produce expressions use dynamic evaluation.
+> Never accept pipeline text or expression fragments from an untrusted source without an
+> external validator and a strict allowlist.
+
+## OpenUSD export
+
+Import the exporter from its optional module so normal package imports never require OpenUSD:
+
+```python
+from spatial_reasoner import SpatialObject
+from spatial_reasoner.exporter import SceneExporter
+
+objects = [SpatialObject("box")]
+SceneExporter("exports").exportUSDZ(objects, "scene.usdz")
+```
+
+The exporter uses OpenUSD's packaging API and does not require an external `usdzip` executable.
+
+## Status and parity
+
+- The reasoning classes, method names, predicates, formulas, and pipeline behavior track SRSwift.
+- CamelCase methods are retained deliberately for cross-language parity.
+- The experimental font-based 3D utility is not distributed.
+- Type annotations are incomplete; this distribution does not claim PEP 561 typed-package status.
+
+Full conceptual documentation lives in the
+[SpatialReasoner repository](https://github.com/metason/SpatialReasoner).
+
+## Development
+
+```bash
+python -m pip install -e ".[test,dev]"
+ruff check src tests
+ruff format --check src tests
+coverage run -m pytest -m "not export and not distribution"
+coverage report
+```
+
+To run the optional exporter test, install `.[export,test]` and run
+`pytest -m export`. Function-length and complexity checks are intentionally not part of the
+style policy because the reasoning implementation follows its reference implementation.
+
+## Citation
+
+If this software supports your research, cite Häsler and Ackermann, “Spatial Reasoner: A 3D
+Inference Pipeline for XR Applications” (2025),
+[doi:10.1109/ICVARS66454.2025.11198690](https://doi.org/10.1109/ICVARS66454.2025.11198690).
+
+## License
+
+Spatial Reasoner for Python is released under [CC0-1.0](LICENSE).

spatial_reasoner-0.1.0/README.md

@@ -0,0 +1,107 @@
+# Spatial Reasoner for Python
+
+`spatial-reasoner` is a 3D spatial-reasoning library derived from the CC0
+[SRSwift reference implementation](https://github.com/metason/SpatialReasoner). It models
+oriented spatial objects and evaluates explicit pipelines for topology, directionality,
+visibility, connectivity, comparison, and similarity predicates.
+
+This is an alpha release. Version 0.1.x preserves the SRSwift-facing camelCase API and
+reasoning behavior, but the Python package API may still evolve before 1.0.
+
+## Installation
+
+Spatial Reasoner supports Python 3.11 through 3.14.
+
+```bash
+python -m pip install spatial-reasoner
+```
+
+OpenUSD scene export is optional:
+
+```bash
+python -m pip install "spatial-reasoner[export]"
+```
+
+## Quick start
+
+The principal classes are available directly from `spatial_reasoner`:
+
+```python
+from spatial_reasoner import SpatialObject, SpatialReasoner, Vector3
+
+crate = SpatialObject(
+    "crate",
+    position=Vector3(0.0, 0.0, 0.0),
+    width=2.0,
+    height=2.0,
+    depth=2.0,
+)
+marker = SpatialObject(
+    "marker",
+    position=Vector3(3.0, 0.0, 0.0),
+    width=0.1,
+    height=0.1,
+    depth=0.1,
+)
+
+reasoner = SpatialReasoner()
+reasoner.load([crate, marker])
+assert reasoner.run("filter(volume > 0.5)")
+assert [obj.id for obj in reasoner.result()] == ["crate"]
+```
+
+Pipeline predicates may be addressed by their SRSwift-compatible enum names. For example,
+`seenleft` selects the predicate whose readable value is `"seen left"`.
+
+> [!WARNING]
+> Pipeline filter, select, map, calculate, and produce expressions use dynamic evaluation.
+> Never accept pipeline text or expression fragments from an untrusted source without an
+> external validator and a strict allowlist.
+
+## OpenUSD export
+
+Import the exporter from its optional module so normal package imports never require OpenUSD:
+
+```python
+from spatial_reasoner import SpatialObject
+from spatial_reasoner.exporter import SceneExporter
+
+objects = [SpatialObject("box")]
+SceneExporter("exports").exportUSDZ(objects, "scene.usdz")
+```
+
+The exporter uses OpenUSD's packaging API and does not require an external `usdzip` executable.
+
+## Status and parity
+
+- The reasoning classes, method names, predicates, formulas, and pipeline behavior track SRSwift.
+- CamelCase methods are retained deliberately for cross-language parity.
+- The experimental font-based 3D utility is not distributed.
+- Type annotations are incomplete; this distribution does not claim PEP 561 typed-package status.
+
+Full conceptual documentation lives in the
+[SpatialReasoner repository](https://github.com/metason/SpatialReasoner).
+
+## Development
+
+```bash
+python -m pip install -e ".[test,dev]"
+ruff check src tests
+ruff format --check src tests
+coverage run -m pytest -m "not export and not distribution"
+coverage report
+```
+
+To run the optional exporter test, install `.[export,test]` and run
+`pytest -m export`. Function-length and complexity checks are intentionally not part of the
+style policy because the reasoning implementation follows its reference implementation.
+
+## Citation
+
+If this software supports your research, cite Häsler and Ackermann, “Spatial Reasoner: A 3D
+Inference Pipeline for XR Applications” (2025),
+[doi:10.1109/ICVARS66454.2025.11198690](https://doi.org/10.1109/ICVARS66454.2025.11198690).
+
+## License
+
+Spatial Reasoner for Python is released under [CC0-1.0](LICENSE).

spatial_reasoner-0.1.0/pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spatial-reasoner"
+version = "0.1.0"
+description = "A flexible 3D spatial reasoning library for Python"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "CC0-1.0"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Steven Häsler" },
+  { name = "Philipp Ackermann" },
+]
+keywords = ["3d", "inference", "reasoning", "spatial", "xr"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Scientific/Engineering",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["numpy>=1.26"]
+
+[project.optional-dependencies]
+export = ["usd-core>=25.2"]
+test = [
+  "coverage[toml]>=7,<8",
+  "pytest>=8,<9",
+]
+dev = [
+  "build>=1.3,<2",
+  "ruff>=0.16,<0.17",
+  "twine>=6.2,<7",
+]
+
+[project.urls]
+Documentation = "https://github.com/metason/SpatialReasoner"
+Issues = "https://github.com/metason/SRpy/issues"
+Paper = "https://doi.org/10.1109/ICVARS66454.2025.11198690"
+Repository = "https://github.com/metason/SRpy"
+
+[tool.setuptools]
+include-package-data = false
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["spatial_reasoner*"]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+testpaths = ["tests"]
+markers = [
+  "distribution: artifact-content tests run after building the package",
+  "export: tests requiring the optional OpenUSD exporter dependency",
+]
+
+[tool.coverage.run]
+branch = true
+source = ["spatial_reasoner"]
+
+[tool.coverage.report]
+fail_under = 70
+show_missing = true
+skip_covered = false
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I", "B", "UP", "RUF012"]
+
+[tool.ruff.format]
+docstring-code-format = true

spatial_reasoner-0.1.0/setup.cfg

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

spatial_reasoner-0.1.0/src/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",
+]