sheafrelgeom 0.1.0a1__tar.gz

sheafrelgeom-0.1.0a1/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/

sheafrelgeom-0.1.0a1/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: sheafrelgeom
+Version: 0.1.0a1
+Summary: Small reference-frame transformations for relative geometric measurements.
+Project-URL: Repository, https://github.com/SheafLab/sheafrelgeom-python
+Author: SheafLab
+License: MIT
+Keywords: coordinates,geometry,reference-frames,relative,sheaflab
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# sheafrelgeom
+
+`sheafrelgeom` provides a tiny typed core for measurements expressed relative
+to named reference frames. It deliberately handles translation only, keeping
+the semantics explicit while leaving rotations, projections, and units to
+specialized packages.
+
+```python
+from sheafrelgeom import Frame, Point, reframe
+
+world = Frame("world")
+camera = Frame("camera", parent=world, origin=(2.0, 1.0))
+pixel_origin = Point("camera", (0.0, 0.0))
+
+assert reframe(pixel_origin, camera, world) == Point("world", (2.0, 1.0))
+```
+
+Frames form an acyclic parent chain. `reframe` resolves a point through that
+chain and returns it in any related target frame. The package has no runtime
+dependencies and supports coordinates of any matching dimension.

sheafrelgeom-0.1.0a1/README.md

@@ -0,0 +1,20 @@
+# sheafrelgeom
+
+`sheafrelgeom` provides a tiny typed core for measurements expressed relative
+to named reference frames. It deliberately handles translation only, keeping
+the semantics explicit while leaving rotations, projections, and units to
+specialized packages.
+
+```python
+from sheafrelgeom import Frame, Point, reframe
+
+world = Frame("world")
+camera = Frame("camera", parent=world, origin=(2.0, 1.0))
+pixel_origin = Point("camera", (0.0, 0.0))
+
+assert reframe(pixel_origin, camera, world) == Point("world", (2.0, 1.0))
+```
+
+Frames form an acyclic parent chain. `reframe` resolves a point through that
+chain and returns it in any related target frame. The package has no runtime
+dependencies and supports coordinates of any matching dimension.

sheafrelgeom-0.1.0a1/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sheafrelgeom"
+version = "0.1.0a1"
+description = "Small reference-frame transformations for relative geometric measurements."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "SheafLab" }]
+keywords = ["geometry", "reference-frames", "relative", "coordinates", "sheaflab"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+
+[project.urls]
+Repository = "https://github.com/SheafLab/sheafrelgeom-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sheafrelgeom"]

sheafrelgeom-0.1.0a1/src/sheafrelgeom/__init__.py

@@ -0,0 +1,4 @@
+from .frames import Frame, Point, displacement, reframe
+
+__all__ = ["Frame", "Point", "displacement", "reframe"]
+__version__ = "0.1.0a1"

sheafrelgeom-0.1.0a1/src/sheafrelgeom/frames.py

@@ -0,0 +1,75 @@
+"""Translation-only relationships between named coordinate frames."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Frame:
+    name: str
+    parent: Frame | None = None
+    origin: tuple[float, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not self.name.strip():
+            raise ValueError("frames require a non-empty name")
+        if self.parent is None and self.origin:
+            raise ValueError("root frames must have an empty origin")
+        if self.parent is not None and not self.origin:
+            raise ValueError("child frames require an origin in their parent")
+        cursor = self.parent
+        while cursor is not None:
+            if cursor.name == self.name:
+                raise ValueError("frame parent chain contains a repeated name")
+            cursor = cursor.parent
+
+
+@dataclass(frozen=True, slots=True)
+class Point:
+    frame: str
+    coordinates: tuple[float, ...]
+
+    def __post_init__(self) -> None:
+        if not self.frame.strip() or not self.coordinates:
+            raise ValueError("points require a frame and at least one coordinate")
+
+
+def _world_coordinates(point: Point, frame: Frame) -> tuple[float, ...]:
+    if point.frame != frame.name:
+        raise ValueError("point does not belong to the supplied frame")
+    values = point.coordinates
+    cursor = frame
+    while cursor.parent is not None:
+        if len(values) != len(cursor.origin):
+            raise ValueError("point and frame dimensions must match")
+        values = tuple(value + offset for value, offset in zip(values, cursor.origin))
+        cursor = cursor.parent
+    return values
+
+
+def _root(frame: Frame) -> Frame:
+    cursor = frame
+    while cursor.parent is not None:
+        cursor = cursor.parent
+    return cursor
+
+
+def reframe(point: Point, source: Frame, target: Frame) -> Point:
+    """Express ``point`` from ``source`` in a related ``target`` frame."""
+
+    if _root(source).name != _root(target).name:
+        raise ValueError("source and target frames do not share a root")
+    world = _world_coordinates(point, source)
+    target_origin = _world_coordinates(Point(target.name, (0.0,) * len(world)), target)
+    if len(world) != len(target_origin):
+        raise ValueError("source and target dimensions must match")
+    return Point(target.name, tuple(value - offset for value, offset in zip(world, target_origin)))
+
+
+def displacement(start: Point, end: Point) -> tuple[float, ...]:
+    """Return the vector from ``start`` to ``end`` in their shared frame."""
+
+    if start.frame != end.frame or len(start.coordinates) != len(end.coordinates):
+        raise ValueError("displacement requires points in the same dimension and frame")
+    return tuple(right - left for left, right in zip(start.coordinates, end.coordinates))

sheafrelgeom-0.1.0a1/tests/test_frames.py

@@ -0,0 +1,28 @@
+import unittest
+
+from sheafrelgeom import Frame, Point, displacement, reframe
+
+
+class FrameTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.world = Frame("world")
+        self.camera = Frame("camera", self.world, (2.0, 1.0))
+        self.sensor = Frame("sensor", self.camera, (0.5, -1.0))
+
+    def test_reframe_walks_parent_chain(self) -> None:
+        point = reframe(Point("sensor", (1.0, 2.0)), self.sensor, self.world)
+        self.assertEqual(point, Point("world", (3.5, 2.0)))
+
+    def test_reframe_can_target_an_ancestor(self) -> None:
+        point = reframe(Point("sensor", (1.0, 2.0)), self.sensor, self.camera)
+        self.assertEqual(point, Point("camera", (1.5, 1.0)))
+
+    def test_displacement_requires_shared_frame(self) -> None:
+        self.assertEqual(displacement(Point("world", (1.0, 2.0)), Point("world", (3.0, 1.0))), (2.0, -1.0))
+        with self.assertRaises(ValueError):
+            displacement(Point("world", (1.0,)), Point("camera", (1.0,)))
+
+    def test_reframe_rejects_unrelated_roots(self) -> None:
+        other = Frame("other")
+        with self.assertRaises(ValueError):
+            reframe(Point("camera", (0.0, 0.0)), self.camera, other)