pyframetree 0.3.0__tar.gz

pyframetree-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyframetree-0.3.0/MANIFEST.in

@@ -0,0 +1,3 @@
+recursive-include examples *.py
+recursive-include performance *.py
+recursive-include tests *.py

pyframetree-0.3.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: pyframetree
+Version: 0.3.0
+Summary: Nested 3D coordinate frames with physical units and vectorized transformations
+Author-email: Gabriel Lefloch <gabriel.lefloch@kit.edu>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/gabs1234/QuaternionFrame
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: quantities>=0.16
+Provides-Extra: visualization
+Requires-Dist: pyvista>=0.43; extra == "visualization"
+Requires-Dist: matplotlib>=3.6; extra == "visualization"
+Dynamic: license-file
+
+# PyFrameTree
+
+Nested 3D coordinate frames and point-cloud transformations, with physical units.
+
+## Installation
+
+From the repository:
+
+```bash
+uv sync --extra visualization
+```
+
+## Usage
+
+```bash
+uv run --extra visualization python examples/simple_transform.py --show
+```
+
+```python
+from pyframetree import CoordinateSystem
+import quantities as pq
+import numpy as np
+import pyvista as pv
+```
+
+```python
+plotter = pv.Plotter()
+
+# Create a random point cloud
+N = 100
+points = np.random.rand(N, 3)
+
+# Create a reference coordinate system
+Reference = CoordinateSystem()
+
+# Create a main coordinate system
+Main = CoordinateSystem()
+
+# Create a child coordinate system
+Child = CoordinateSystem(parent=Main, name='Child')
+Child.add_points(points, 'points')
+Child.translate([2, 2, 0]*pq.m)
+Child.rotate([0, 1, 1], 30*pq.deg)
+
+Main.scale(3, inherit=False) # Scale the main coordinate system, but not its children
+Main.rotate([1, 0, 0], 30*pq.deg, inherit=True)
+
+Reference.visualize(plotter=plotter, children=False, cmap='gray')
+Main.visualize(plotter=plotter, children=False, cmap='plasma')
+Child.visualize(plotter=plotter, children=False, cmap='viridis')
+
+plotter.save_graphic('assets/frames.svg')
+```
+
+![example](assets/frames.svg)

pyframetree-0.3.0/README.md

@@ -0,0 +1,55 @@
+# PyFrameTree
+
+Nested 3D coordinate frames and point-cloud transformations, with physical units.
+
+## Installation
+
+From the repository:
+
+```bash
+uv sync --extra visualization
+```
+
+## Usage
+
+```bash
+uv run --extra visualization python examples/simple_transform.py --show
+```
+
+```python
+from pyframetree import CoordinateSystem
+import quantities as pq
+import numpy as np
+import pyvista as pv
+```
+
+```python
+plotter = pv.Plotter()
+
+# Create a random point cloud
+N = 100
+points = np.random.rand(N, 3)
+
+# Create a reference coordinate system
+Reference = CoordinateSystem()
+
+# Create a main coordinate system
+Main = CoordinateSystem()
+
+# Create a child coordinate system
+Child = CoordinateSystem(parent=Main, name='Child')
+Child.add_points(points, 'points')
+Child.translate([2, 2, 0]*pq.m)
+Child.rotate([0, 1, 1], 30*pq.deg)
+
+Main.scale(3, inherit=False) # Scale the main coordinate system, but not its children
+Main.rotate([1, 0, 0], 30*pq.deg, inherit=True)
+
+Reference.visualize(plotter=plotter, children=False, cmap='gray')
+Main.visualize(plotter=plotter, children=False, cmap='plasma')
+Child.visualize(plotter=plotter, children=False, cmap='viridis')
+
+plotter.save_graphic('assets/frames.svg')
+```
+
+![example](assets/frames.svg)

pyframetree-0.3.0/examples/geometry.py

@@ -0,0 +1,150 @@
+import marimo
+
+__generated_with = '0.25.2'
+app = marimo.App(width='medium')
+
+
+@app.cell
+def _():
+    import marimo as mo
+    import numpy as np
+    import quantities as pq
+    from geometry_viewer import GeometryViewer
+
+    from pyframetree import CoordinateSystem
+
+    mo.output.clear()  # Hide fastplotlib's optional Jupyter logo/device banner.
+    return CoordinateSystem, GeometryViewer, mo, np, pq
+
+
+@app.cell(hide_code=True)
+def _(mo):
+    mo.md(r"""
+    # See how a parent frame moves its child
+
+    The **Reference** frame stays fixed. **Main** is the parent of **Child**,
+    which carries a point cloud. Axis labels identify each frame and its local
+    **u**, **v**, and **w** directions. Labels stay upright as the camera moves.
+    All positions are in metres.
+
+    Drag the 3D view to rotate it; scroll to zoom. Change the angles below to
+    update the geometry without resetting your camera. The defaults reproduce
+    the original Jupyter example.
+
+    Open this notebook with `uv run --group notebook marimo edit examples/geometry.py`.
+    """)
+    return
+
+
+@app.cell(hide_code=True)
+def _(mo):
+    parent_angle = mo.ui.slider(
+        -180,
+        180,
+        value=30,
+        step=5,
+        show_value=True,
+        label='Parent rotation (deg)',
+    )
+    child_angle = mo.ui.slider(
+        -180,
+        180,
+        value=30,
+        step=5,
+        show_value=True,
+        label='Child rotation (deg)',
+    )
+    parent_scale = mo.ui.slider(
+        1,
+        4,
+        value=3,
+        step=0.25,
+        show_value=True,
+        label='Parent axis scale',
+    )
+    inherit_scale = mo.ui.checkbox(value=False, label='Scale the child with its parent')
+    mo.vstack([parent_angle, child_angle, parent_scale, inherit_scale])
+    return child_angle, inherit_scale, parent_angle, parent_scale
+
+
+@app.cell
+def _(np):
+    # Keep the same cloud when a control changes, so only the geometry moves.
+    points = np.random.default_rng(0).random((100, 3))
+    return (points,)
+
+
+@app.cell
+def _(CoordinateSystem, child_angle, inherit_scale, parent_angle, parent_scale, points, pq):
+    reference = CoordinateSystem(name='Reference')
+    main = CoordinateSystem(name='Main')
+    child = CoordinateSystem(parent=main, name='Child')
+    child.add_points(points, 'cloud')
+    child.translate([2, 2, 0] * pq.m)
+    child.rotate([0, 1, 1], child_angle.value * pq.deg)
+
+    main.scale(parent_scale.value, inherit=inherit_scale.value)
+    _ = main.rotate([1, 0, 0], parent_angle.value * pq.deg)
+    return child, main, reference
+
+
+@app.cell
+def _(GeometryViewer, points):
+    viewer = GeometryViewer(points)
+    viewer.canvas
+    return (viewer,)
+
+
+@app.cell
+def _(child, main, reference, viewer):
+    viewer.update(reference, main, child)
+    return
+
+
+@app.cell(hide_code=True)
+def _(mo):
+    reset_view = mo.ui.run_button(label='Reset view')
+    reset_view
+    return (reset_view,)
+
+
+@app.cell
+def _(reset_view, viewer):
+    if reset_view.value:
+        viewer.reset_view()
+    return
+
+
+@app.cell(hide_code=True)
+def _(child, main, mo, pq, reference):
+    _rows = []
+    for _frame in (reference, main, child):
+        _position = _frame.origin.rescale(pq.m).magnitude
+        _rows.append(
+            {
+                'Frame': _frame.name,
+                'Parent': _frame.parent.name if _frame.parent else '—',
+                'x (m)': round(float(_position[0]), 4),
+                'y (m)': round(float(_position[1]), 4),
+                'z (m)': round(float(_position[2]), 4),
+            }
+        )
+    mo.vstack(
+        [
+            mo.md('### World positions'),
+            mo.ui.table(_rows, selection=None, pagination=False, show_column_summaries=False),
+            mo.md("""
+        The parent rotates about the world x-axis. The child rotates about its
+        own origin, around its parent's axis `(0, 1, 1)`.
+
+        With **Scale the child with its parent** unchecked, `inherit=False`
+        changes the parent's axes while holding the child and its points fixed.
+        Rotation keeps the default `inherit=True`, so the child follows its parent.
+        """),
+        ]
+    )
+    return
+
+
+if __name__ == '__main__':
+    app.run()

pyframetree-0.3.0/examples/geometry_viewer.py

@@ -0,0 +1,187 @@
+"""Fastplotlib rendering for the coordinate-frame notebook."""
+
+import weakref
+
+import fastplotlib as fpl
+import numpy as np
+import pygfx
+import quantities as pq
+from rendercanvas.anywidget import RenderCanvas
+
+
+def _unit_arrow_geometry():
+    """A unit arrow along +z, with a short head joined to a slender shaft."""
+    # Fastplotlib 0.7 misplaces the shaft when its height differs from the cone's.
+    # Assemble the two standard primitives explicitly, with tail=0 and tip=1.
+    shaft = pygfx.cylinder_geometry(
+        radius_bottom=0.012,
+        radius_top=0.012,
+        height=0.82,
+        radial_segments=16,
+    )
+    head = pygfx.cone_geometry(radius=0.045, height=0.18, radial_segments=16)
+    shaft.positions.data[:, 2] += 0.41
+    head.positions.data[:, 2] += 0.91
+    return pygfx.Geometry(
+        positions=np.concatenate([shaft.positions.data, head.positions.data]),
+        normals=np.concatenate([shaft.normals.data, head.normals.data]),
+        indices=np.concatenate(
+            [
+                shaft.indices.data,
+                head.indices.data + len(shaft.positions.data),
+            ]
+        ),
+    )
+
+
+def _arrow_transform(origin, axis):
+    """Place a unit arrow along ``axis``, keeping its proportions for any axis length."""
+    length = np.linalg.norm(axis)
+    direction = axis / length
+    helper = np.eye(3)[np.argmin(np.abs(direction))]
+    side = np.cross(helper, direction)
+    side /= np.linalg.norm(side)
+    matrix = np.eye(4)
+    matrix[:3, :3] = np.column_stack([side, np.cross(direction, side), direction]) * length
+    matrix[:3, 3] = origin
+    return matrix
+
+
+class NotebookCanvas(RenderCanvas):
+    """Guard rendercanvas 2.7's recursive close notification, without patching it globally."""
+
+    def close(self):
+        if getattr(self, '_closing', False) or getattr(self, '_is_closed', False):
+            return
+        self._closing = True
+        try:
+            self._rfb_cancel_lossless_draw()
+            super().close()
+        finally:
+            self._closing = False
+
+
+class GeometryViewer:
+    """Keep the notebook's three frames and child point cloud in one live scene.
+
+    Render positions are metres. Only the display buffers use float32;
+    CoordinateSystem continues to calculate its transforms at its own precision.
+    """
+
+    def __init__(self, points, *, size=(900, 600), canvas=None):
+        self.canvas = NotebookCanvas(size=size, max_fps=60) if canvas is None else canvas
+        camera = pygfx.OrthographicCamera(8, 6)
+        camera.local.position = (6, 6, 6)
+        camera.look_at((0, 0, 0))
+
+        # Scope the frame styling to this figure, then restore the caller's defaults.
+        config = fpl.layouts.Subplot.config.init
+        previous = config.frame_kwargs
+        config.frame_kwargs = {
+            'spacing': dict(x0=0, sides=0, title_flanks=0, resize_handle_space=0, bottom=0),
+            'title_kwargs': dict(font_size=0),
+        }
+        try:
+            self.figure = fpl.Figure(
+                cameras=camera,
+                controller_types='orbit',
+                canvas=self.canvas,
+                size=size,
+            )
+        finally:
+            config.frame_kwargs = previous
+
+        self.plot = self.figure[0, 0]
+        self.plot.background_color = ('white',)
+        self.arrows, self.labels = [], []
+        arrow_geometry = _unit_arrow_geometry()
+        for name, color in [
+            ('Reference', '#666666'),
+            ('Main', '#4e79a7'),
+            ('Child', '#b86b16'),
+        ]:
+            arrows = self.plot.add_vectors(
+                np.zeros((3, 3), dtype=np.float32),
+                np.eye(3, dtype=np.float32),
+                color='white',
+                size=1,
+            )
+            arrows.world_object.geometry = arrow_geometry
+            arrows.world_object.material.color = color
+            self.arrows.append(arrows)
+            labels = [
+                self.plot.add_text(
+                    f'{name}.{axis}',
+                    font_size=14,
+                    face_color='#222222',
+                    screen_space=True,
+                    outline_color='white',
+                    outline_thickness=0.15,
+                )
+                for axis in ('u', 'v', 'w')
+            ]
+            for label in labels:
+                label.world_object.material.depth_test = False
+            self.labels.append(labels)
+
+        self.cloud = self.plot.add_scatter(
+            np.asarray(points, dtype=np.float32),
+            colors='#b86b16',
+            sizes=7,
+            edge_width=0,
+        )
+        self.link = self.plot.add_line(
+            np.zeros((2, 3), dtype=np.float32),
+            colors='#666666',
+            thickness=1,
+        )
+        self.figure.show(autoscale=False, axes_visible=False)
+        self._bounds = None
+        self._cleanup = weakref.finalize(self, self.canvas.close)
+
+    def update(self, reference, main, child):
+        """Update poses and local geometry while preserving the user's camera."""
+        bounds = []
+        for frame, arrows, labels in zip((reference, main, child), self.arrows, self.labels):
+            matrix = frame.world_transform.as_unit(pq.m).matrix
+            origin, basis = matrix[:3, 3], matrix[:3, :3].T
+            bounds.extend([origin, *(origin + 1.12 * basis)])
+            for i, (label, axis) in enumerate(zip(labels, basis)):
+                arrows.world_object.set_matrix_at(i, _arrow_transform(origin, axis))
+                label.offset = origin + 1.12 * axis
+
+        local = (child.get_points('cloud') * child.unit).rescale(pq.m).magnitude
+        local = np.asarray(local, dtype=np.float32).reshape(-1, 3)
+        if not np.array_equal(local, self.cloud.data[:]):
+            self.cloud.data = local
+        matrix = child.world_transform.as_unit(pq.m).matrix
+        self.cloud.world_object.local.matrix = matrix
+        self.link.data[:] = np.array(
+            [main.origin.rescale(pq.m).magnitude, child.origin.rescale(pq.m).magnitude],
+            dtype=np.float32,
+        )
+        if local.size:
+            bounds.extend(local @ matrix[:3, :3].T + matrix[:3, 3])
+        first_update = self._bounds is None
+        self._bounds = np.array([np.min(bounds, axis=0), np.max(bounds, axis=0)])
+        if first_update:
+            self.reset_view()
+        self.canvas.request_draw()
+
+    def reset_view(self):
+        """Fit the current geometry and restore the initial viewing angle."""
+        if self._bounds is None:
+            return
+        center = self._bounds.mean(axis=0)
+        radius = max(float(np.linalg.norm(self._bounds[1] - center)), 1e-6)
+        self.plot.camera.show_object(
+            (*center, radius),
+            view_dir=(-1, 1, -0.8),
+            up=(0, 0, 1),
+            scale=1.15,
+        )
+        self.plot.camera.zoom = 1
+        self.canvas.request_draw()
+
+    def close(self):
+        self._cleanup()

pyframetree-0.3.0/examples/simple_transform.py

@@ -0,0 +1,38 @@
+"""A CPU example; pass --show to visualize with the optional plotting extra."""
+
+import argparse
+import sys
+from pathlib import Path
+
+if __package__ in (None, ''):
+    sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+import numpy as np
+import quantities as q
+
+from pyframetree import CoordinateSystem
+
+
+def make_scene():
+    root = CoordinateSystem(name='root')
+    child = CoordinateSystem(parent=root, name='cloud')
+    child.add_points(np.random.default_rng(0).random((1000, 3)), 'points')
+    child.translate([2, 2, 0] * q.m)
+    child.rotate([0, 1, 1], 30 * q.deg)
+    root.rotate([1, 0, 0], 30 * q.deg)
+    return root, child
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--show', action='store_true')
+    args = parser.parse_args(argv)
+    root, child = make_scene()
+    print(child)
+    print(f'World point array: {child.get_points("points", space="world").shape}')
+    if args.show:
+        root.visualize().show()
+
+
+if __name__ == '__main__':
+    main()

pyframetree-0.3.0/performance/__init__.py

@@ -0,0 +1 @@
+# Tests package initialization

pyframetree-0.3.0/performance/benchmark_frames.py

@@ -0,0 +1,58 @@
+"""Per-call cost of frame operations, in microseconds."""
+
+import sys
+from pathlib import Path
+from timeit import Timer
+
+if __package__ in (None, ''):
+    sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+import numpy as np
+import quantities as q
+
+from pyframetree import CoordinateSystem
+
+
+def make_chain(depth):
+    root = leaf = CoordinateSystem()
+    for _ in range(depth):
+        leaf = CoordinateSystem([1, 0, 0], parent=leaf)
+        leaf.rotate([0, 0, 1], 0.1)
+    return root, leaf
+
+
+def microseconds(operation, min_time=0.05):
+    timer = Timer(operation)
+    count, _ = timer.autorange()
+    count = max(1, int(count * min_time / 0.2))
+    return min(timer.repeat(repeat=3, number=count)) / count * 1e6
+
+
+def run_benchmarks(depths=(1, 10, 100), min_time=0.05):
+    """Return rows of (operation, depth, microseconds per call)."""
+    point = np.array([1.0, 2.0, 3.0])
+    rows = [('create a frame', 0, microseconds(CoordinateSystem, min_time))]
+    for depth in depths:
+        root, leaf = make_chain(depth)
+        operations = {
+            'origin (cached)': lambda: leaf.origin,
+            'origin after root moved': lambda: (root.translate([0, 0, 0]), leaf.origin),
+            'translate': lambda: leaf.translate([0, 0, 0]),
+            'translate (quantity)': lambda: leaf.translate([0, 0, 0] * q.cm),
+            'translate (world)': lambda: leaf.translate([0, 0, 0], relative_to='world'),
+            'rotate': lambda: leaf.rotate([0, 0, 1], 0.0),
+            'to_world (one point)': lambda: leaf.to_world(point),
+        }
+        for name, operation in operations.items():
+            rows.append((name, depth, microseconds(operation, min_time)))
+    return rows
+
+
+def print_results(rows):
+    print(f'{"operation":<26} {"depth":>5} {"µs/call":>9}')
+    for name, depth, time in rows:
+        print(f'{name:<26} {depth:>5} {time:9.2f}')
+
+
+if __name__ == '__main__':
+    print_results(run_benchmarks())

pyframetree-0.3.0/performance/benchmark_operations.py

@@ -0,0 +1,22 @@
+"""Translation, rotation and scaling, using the shared benchmark methodology."""
+
+import sys
+from pathlib import Path
+
+if __package__ in (None, ''):
+    sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from performance.benchmark_transformations import print_results, run_benchmarks
+
+
+def benchmark_operations(nmin=100, nmax=1000000, num_runs=5, *, cpu_only=False):
+    import numpy as np
+
+    counts = np.unique(np.geomspace(nmin, nmax, num=6, dtype=int))
+    return run_benchmarks(
+        counts, num_runs, cpu_only=cpu_only, operations=('Translation', 'Rotation', 'Scaling')
+    )
+
+
+if __name__ == '__main__':
+    print_results(benchmark_operations())