cartesian-tree 0.2.1__cp313-cp313-win_amd64.whl

cartesian_tree/__init__.py

@@ -0,0 +1,12 @@
+"""A library for calculating Cartesian poses in different coordinate systems."""
+
+from .helper import RPY, Position, Quaternion
+from .lib import Frame, Pose
+
+__all__ = [
+    "RPY",
+    "Frame",
+    "Pose",
+    "Position",
+    "Quaternion",
+]

cartesian_tree/helper.py

@@ -0,0 +1,194 @@
+"""Defines helper classes for a more pythonic API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cartesian_tree import _cartesian_tree as _core  # type: ignore[attr-defined]
+
+
+class RPY:
+    """Defines a roll-pitch-yaw angle representation."""
+
+    def __init__(self, roll: float, pitch: float, yaw: float) -> None:
+        """Initializes the roll-pitch-yaw angles.
+
+        Args:
+            roll: The roll angle in radians.
+            pitch: The pitch angle in radians.
+            yaw: The yaw angle in radians
+        """
+        self._core_rpy = _core.RPY(roll, pitch, yaw)
+
+    @property
+    def roll(self) -> float:
+        """The roll angle in radians."""
+        return self._core_rpy.roll
+
+    @property
+    def pitch(self) -> float:
+        """The pitch angle in radians."""
+        return self._core_rpy.pitch
+
+    @property
+    def yaw(self) -> float:
+        """The yaw angle in radians."""
+        return self._core_rpy.yaw
+
+    @property
+    def _binding_structure(self) -> Any:
+        return self._core_rpy
+
+    def to_list(self) -> list[float]:
+        """Returns the angles as list.
+
+        Returns:
+            The angle as list.
+        """
+        return [self.roll, self.pitch, self.yaw]
+
+    def to_tuple(self) -> tuple[float, float, float]:
+        """Returns the angles as tuple.
+
+        Returns:
+            The angles as tuple.
+        """
+        return (self.roll, self.pitch, self.yaw)
+
+    def to_quaternion(self) -> Quaternion:
+        """Returns the angles as quaternion.
+
+        Returns:
+            The angles as quaternion.
+        """
+        return Quaternion(*self._core_rpy.to_quaternion().to_tuple())
+
+    def __str__(self) -> str:
+        return self._core_rpy.__str__()
+
+    def __repr__(self) -> str:
+        return self._core_rpy.__repr__()
+
+
+class Quaternion:
+    """Defines a quaternion."""
+
+    def __init__(self, x: float, y: float, z: float, w: float) -> None:
+        """Initializes the quaternion.
+
+        Args:
+            x: The x value.
+            y: The y value.
+            z: The z value.
+            w: The w value.
+        """
+        self._core_quaternion = _core.Quaternion(x, y, z, w)
+
+    @property
+    def x(self) -> float:
+        """The x value."""
+        return self._core_quaternion.x
+
+    @property
+    def y(self) -> float:
+        """The y value."""
+        return self._core_quaternion.y
+
+    @property
+    def z(self) -> float:
+        """The z value."""
+        return self._core_quaternion.z
+
+    @property
+    def w(self) -> float:
+        """The z value."""
+        return self._core_quaternion.w
+
+    @property
+    def _binding_structure(self) -> Any:
+        return self._core_quaternion
+
+    def to_list(self) -> list[float]:
+        """Returns the quaternion as list in the form x,y,z and w.
+
+        Returns:
+            The quaternion as list.
+        """
+        return [self.x, self.y, self.z, self.w]
+
+    def to_tuple(self) -> tuple[float, float, float, float]:
+        """Returns the quaternion as tuple in the form x,y,z and w.
+
+        Returns:
+            The quaternion as tuple.
+        """
+        return (self.x, self.y, self.z, self.w)
+
+    def to_rpy(self) -> RPY:
+        """Returns the angles as quaternion.
+
+        Returns:
+            The angles as quaternion.
+        """
+        return RPY(*self._core_quaternion.to_rpy().to_tuple())
+
+    def __str__(self) -> str:
+        return self._core_quaternion.__str__()
+
+    def __repr__(self) -> str:
+        return self._core_quaternion.__repr__()
+
+
+class Position:
+    """Defines a position."""
+
+    def __init__(self, x: float, y: float, z: float) -> None:
+        """Initializes the position in meter.
+
+        Args:
+            x: The x value in meter.
+            y: The y value in meter.
+            z: The z value in meter.
+        """
+        self._core_position = _core.Position(x, y, z)
+
+    @property
+    def x(self) -> float:
+        """The x value in meter."""
+        return self._core_position.x
+
+    @property
+    def y(self) -> float:
+        """The y value in meter."""
+        return self._core_position.y
+
+    @property
+    def z(self) -> float:
+        """The z value in meter."""
+        return self._core_position.z
+
+    @property
+    def _binding_structure(self) -> Any:
+        return self._core_position
+
+    def to_list(self) -> list[float]:
+        """Returns the position as list.
+
+        Returns:
+            The position as list.
+        """
+        return [self.x, self.y, self.z]
+
+    def to_tuple(self) -> tuple[float, float, float]:
+        """Returns the position as tuple.
+
+        Returns:
+            The position as tuple.
+        """
+        return (self.x, self.y, self.z)
+
+    def __str__(self) -> str:
+        return self._core_position.__str__()
+
+    def __repr__(self) -> str:
+        return self._core_position.__repr__()

cartesian_tree/lib.py

@@ -0,0 +1,258 @@
+"""Defines a the main lib classes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .helper import RPY, Position, Quaternion
+from cartesian_tree import _cartesian_tree as _core  # type: ignore[attr-defined]
+
+
+class Frame:
+    """Defines a coordinate frame in a Cartesian tree structure.
+
+    Each frame can have one parent and multiple children. The frame stores its
+    transformation (position and orientation) relative to its parent.
+    """
+
+    def __init__(self, name: str) -> None:
+        """Initializes a new root frame (origin) with the given name.
+
+        Args:
+            name: The name of the root frame.
+        """
+        self._core_frame = _core.Frame(name)
+
+    @property
+    def name(self) -> str:
+        """The name of the frame."""
+        return self._core_frame.name
+
+    @property
+    def depth(self) -> int:
+        """The depth from the frame to its root."""
+        return self._core_frame.depth
+
+    def add_child(self, name: str, position: Position, orientation: RPY | Quaternion) -> Frame:
+        """Adds a new child frame to the current frame.
+
+        Args:
+            name: The name of the new child frame.
+            position: The translational offset from the parent.
+            orientation: The orientational offset from the parent.
+
+        Returns:
+            The newly created child frame.
+
+        Raises:
+            ValueError: If a child with the same name already exists.
+        """
+        if isinstance(orientation, RPY):
+            orientation = orientation.to_quaternion()
+
+        binding_frame = self._core_frame.add_child(name, position._binding_structure, orientation._binding_structure)
+        return Frame._from_rust(binding_frame)
+
+    def calibrate_child(
+        self, name: str, desired_position: Position, desired_orientation: RPY | Quaternion, reference_pose: Pose
+    ) -> Frame:
+        """Adds a child frame such that a reference pose, expressed in the new frame, matches the desired isometry.
+
+        Args:
+            name: The name of the new child frame.
+            desired_position: The desired position of the reference pose in the new frame.
+            desired_orientation: The desired orientation of the reference pose in the new frame.
+            reference_pose: The reference pose for calibration.
+
+        Returns:
+            The newly created child frame.
+
+        Raises:
+            ValueError: If a child with the same name already exists.
+        """
+        if isinstance(desired_orientation, RPY):
+            desired_orientation = desired_orientation.to_quaternion()
+
+        binding_frame = self._core_frame.calibrate_child(
+            name,
+            desired_position._binding_structure,
+            desired_orientation._binding_structure,
+            reference_pose._binding_structure,
+        )
+        return Frame._from_rust(binding_frame)
+
+    def add_pose(self, position: Position, orientation: RPY | Quaternion) -> Pose:
+        """Adds a pose to the current frame.
+
+        Args:
+            position: The translational part of the pose.
+            orientation: The orientational part of the pose.
+
+        Returns:
+            The newly created pose.
+        """
+        if isinstance(orientation, RPY):
+            orientation = orientation.to_quaternion()
+
+        binding_pose = self._core_frame.add_pose(position._binding_structure, orientation._binding_structure)
+        return Pose._from_rust(binding_pose)
+
+    def transformation_to_parent(self) -> tuple[Position, Quaternion]:
+        """Returns the transformation from this frame to its parent frame.
+
+        Returns:
+            The transformation from this frame to its parent frame (Position, Quaternion(x, y, z, w)).
+
+        Raises:
+            ValueError: If the frame has no parent.
+        """
+        binding_position, binding_quat = self._core_frame.transformation_to_parent()
+        return (
+            Position(*binding_position.to_tuple()),
+            Quaternion(*binding_quat.to_tuple()),
+        )
+
+    def update_transformation(self, position: Position, orientation: RPY | Quaternion) -> None:
+        """Updates the frames transformation relative to its parent.
+
+        Args:
+            position: The translational offset from the parent.
+            orientation: The orientational offset from the parent.
+
+        Raises:
+            ValueError: If the frame has no parent or invalid dimensions.
+        """
+        if isinstance(orientation, RPY):
+            orientation = orientation.to_quaternion()
+        self._core_frame.update_transformation(position._binding_structure, orientation._binding_structure)
+
+    def to_json(self) -> str:
+        """Serializes the frame tree to a JSON string.
+
+        Returns:
+            The JSON representation of the tree.
+
+        Raises:
+            ValueError: On serialization failure.
+        """
+        return self._core_frame.to_json()
+
+    def apply_config(self, config_json: str) -> None:
+        """Applies a JSON config to update matching transforms in the tree.
+
+        Deserializes the JSON to a temporary structure, then recursively updates transforms to the
+        parent frames where names match (partial apply; ignores unmatched frames in config).
+        It is assumed this frame is the root.
+
+        Args:
+            config_json: The JSON string to apply.
+
+        Raises:
+            ValueError: On deserialization or mismatch errors (e.g. if this frame is not the root).
+        """
+        self._core_frame.apply_config(config_json)
+
+    def parent(self) -> Frame | None:
+        """Returns the parent of the frame.
+
+        Returns:
+            The parent of the frame.
+        """
+        binding_parent = self._core_frame.parent()
+        if binding_parent is None:
+            return None
+        return Frame._from_rust(binding_parent)
+
+    def root(self) -> Frame:
+        """Returns the root frame of the tree.
+
+        Returns:
+            The root frame of the tree.
+        """
+        binding_root = self._core_frame.root()
+        return Frame._from_rust(binding_root)
+
+    def children(self) -> list[Frame]:
+        """Returns the children of the frame.
+
+        Returns:
+            The children of the frame.
+        """
+        return [Frame._from_rust(binding_child) for binding_child in self._core_frame.children()]
+
+    def __str__(self) -> str:
+        return self._core_frame.__str__()
+
+    def __repr__(self) -> str:
+        return self._core_frame.__repr__()
+
+    @property
+    def _binding_structure(self) -> Any:
+        return self._core_frame
+
+    @classmethod
+    def _from_rust(cls, rust_frame: _core.Frame) -> Frame:
+        instance = cls.__new__(cls)
+        instance._core_frame = rust_frame
+        return instance
+
+
+class Pose:
+    """Defines a Cartesian pose."""
+
+    _core_pose: _core.Pose
+
+    def frame(self) -> Frame:
+        """Returns the frame of the pose."""
+        return Frame._from_rust(self._core_pose.frame())
+
+    def transformation(self) -> tuple[Position, Quaternion]:
+        """Returns the transformation of the pose to its parent frame.
+
+        Returns:
+            The transformation from this frame to its parent frame (position, quaternion(x, y, z, w)).
+        """
+        binding_position, binding_quat = self._core_pose.transformation()
+        return (
+            Position(*binding_position.to_tuple()),
+            Quaternion(*binding_quat.to_tuple()),
+        )
+
+    def update(self, position: Position, orientation: RPY | Quaternion) -> None:
+        """Updates the pose's transformation.
+
+        Args:
+            position: The translational part of the pose.
+            orientation: The orientational part of the pose.
+        """
+        if isinstance(orientation, RPY):
+            orientation = orientation.to_quaternion()
+        self._core_pose.update(position._binding_structure, orientation._binding_structure)
+
+    def in_frame(self, target_frame: Frame) -> Pose:
+        """Transforms this pose into the coordinate system of the given target frame.
+
+        Args:
+            target_frame: The frame to express this pose in.
+
+        Returns:
+            This pose in the new frame.
+        """
+        binding_pose = self._core_pose.in_frame(target_frame._binding_structure)
+        return Pose._from_rust(binding_pose)
+
+    @property
+    def _binding_structure(self) -> Any:
+        return self._core_pose
+
+    @classmethod
+    def _from_rust(cls, rust_pose: _core.Pose) -> Pose:
+        instance = cls.__new__(cls)
+        instance._core_pose = rust_pose
+        return instance
+
+    def __str__(self) -> str:
+        return self._core_pose.__str__()
+
+    def __repr__(self) -> str:
+        return self._core_pose.__repr__()

cartesian_tree-0.2.1.dist-info/METADATA

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: cartesian-tree
+Version: 0.2.1
+Classifier: Programming Language :: Python
+Requires-Dist: cartesian-tree[lint] ; extra == 'dev'
+Requires-Dist: cartesian-tree[test] ; extra == 'dev'
+Requires-Dist: cartesian-tree[build] ; extra == 'dev'
+Requires-Dist: ruff==0.12.4 ; extra == 'lint'
+Requires-Dist: mypy==1.17.0 ; extra == 'lint'
+Requires-Dist: pytest==8.4.1 ; extra == 'test'
+Requires-Dist: maturin==1.8.6 ; extra == 'build'
+Provides-Extra: dev
+Provides-Extra: lint
+Provides-Extra: test
+Provides-Extra: build
+License-File: license-mit
+Summary: Build hierarchical Cartesian coordinate systems to easily transform poses.
+Keywords: Cartesian,coordinate systems,transform,poses
+Home-Page: https://github.com/Kn0g/cartesian-tree
+Author: Kn0g
+Maintainer: Kn0g
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# cartesian-tree
+
+A simple project for me to learn Rust and the binding process.
+
+Useful for converting Cartesian poses from one coordinate system into another.

cartesian_tree-0.2.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+cartesian_tree-0.2.1.dist-info/METADATA,sha256=horSd_5vR-PEYtHaiKFlmvrH371lDpXwXlEk7enEQjI,1035
+cartesian_tree-0.2.1.dist-info/WHEEL,sha256=TJQY77QRLvXq32tEs9ATmwKO6NAOtuKOAw50eyiSmWU,96
+cartesian_tree-0.2.1.dist-info/licenses/license-mit,sha256=13YSIF32H4sbmK-1C4usuKbV7rOjXHJmkwMW7hGM3qA,1084
+cartesian_tree/__init__.py,sha256=Nnetfz3mSo_OkN6AJfOfy-vmw7-cSfjLb2x7GUhcceA,254
+cartesian_tree/_cartesian_tree.cp313-win_amd64.pyd,sha256=voD8JBUmepfJy_D7NFikzJQhTJBoGt3JhiTF8HcKRNw,476160
+cartesian_tree/helper.py,sha256=IFNIJAM2wLKtQk_7fwGh8Ha6XwS5UnAoLNYWaOacY_E,5045
+cartesian_tree/lib.py,sha256=4VN7R-Hi_a6vdsRYnD7XEaCy0pIb-ilYk8DB5WlxUmI,8952
+cartesian_tree/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cartesian_tree-0.2.1.dist-info/RECORD,,

cartesian_tree-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.9.6)
+Root-Is-Purelib: false
+Tag: cp313-cp313-win_amd64

cartesian_tree-0.2.1.dist-info/licenses/license-mit

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2025] [Kn0g]
+
+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.