cartesian-tree 0.1.0__tar.gz → 0.2.0__tar.gz

{cartesian_tree-0.1.0 → cartesian_tree-0.2.0}/.github/workflows/ci.yaml

@@ -15,18 +15,36 @@ env:
 
 jobs:
   test:
-    name: Test on Python ${{ matrix.python-version }} and Rust
-    runs-on: ubuntu-latest
+    name: Test (${{ matrix.os }} / py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.11", "3.12"]
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
 
     steps:
       - uses: actions/checkout@v4
 
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      
+      - name: Cache cargo
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Cache pip
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}
 
       - name: Run Rust fmt
         run: cargo fmt --check
@@ -69,4 +87,5 @@ jobs:
       - name: Run Python tests
         run: |
           source .venv/bin/activate
-          pytest python/tests
+          pytest python/tests
+          

cartesian_tree-0.2.0/.github/workflows/publish.yaml

@@ -0,0 +1,61 @@
+name: Publish
+
+on:
+  workflow_call:
+    secrets:
+      CARGO_REGISTRY_TOKEN:
+        required: true
+      PYPI_TOKEN:
+        required: true
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  publish-rust:
+    name: Publish Rust Crate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+      
+      - name: Publish to crates.io
+        run: cargo publish --token ${{ secrets.CARGO_REGISTRY_TOKEN }}
+
+  publish-python:
+    name: Publish Python Package
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Build and publish wheels
+        uses: messense/maturin-action@v1
+        with:
+          maturin-version: latest
+          command: publish
+          args: --username __token__ --password ${{ secrets.PYPI_TOKEN }} --skip-existing
+          manylinux: auto
+    
+  publish-sdist:
+    name: Publish sdist (source)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build and publish sdist
+        run: maturin publish --sdist --username __token__ --password ${{ secrets.PYPI_TOKEN }} --skip-existing

{cartesian_tree-0.1.0 → cartesian_tree-0.2.0}/.gitignore

@@ -19,4 +19,7 @@ target/
 # Python eco-system
 venv
 **/*/__pycache__
-**/*/cartesian_tree.cpython-*.so
+**/*/*cartesian_tree.cpython-*.so
+
+# VS Code
+.vscode/

{cartesian_tree-0.1.0 → cartesian_tree-0.2.0}/Cargo.lock

@@ -4,10 +4,12 @@ version = 4
 
 [[package]]
 name = "CartesianTree"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
  "nalgebra",
  "pyo3",
+ "serde",
+ "serde_json",
  "thiserror",
 ]
 
@@ -44,6 +46,12 @@ version = "2.0.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f4c7245a08504955605670dbf141fceab975f15ca21570696aebe9d2e71576bd"
 
+[[package]]
+name = "itoa"
+version = "1.0.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4a5f13b858c8d314ee3e8f639011f7ccefe71f97f96e50151fb991f267928e2c"
+
 [[package]]
 name = "libc"
 version = "0.2.172"
@@ -60,6 +68,12 @@ dependencies = [
  "rawpointer",
 ]
 
+[[package]]
+name = "memchr"
+version = "2.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f52b00d39961fc5b2736ea853c9cc86238e165017a493d1d5c8eac6bdc4cc273"
+
 [[package]]
 name = "memoffset"
 version = "0.9.1"
@@ -81,6 +95,7 @@ dependencies = [
  "num-complex",
  "num-rational",
  "num-traits",
+ "serde",
  "simba",
  "typenum",
 ]
@@ -113,6 +128,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495"
 dependencies = [
  "num-traits",
+ "serde",
 ]
 
 [[package]]
@@ -248,6 +264,12 @@ version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "60a357793950651c4ed0f3f52338f53b2f809f32d83a07f72909fa13e4c6c1e3"
 
+[[package]]
+name = "ryu"
+version = "1.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "28d3b2b1366ec20994f1fd18c3c594f05c5dd4bc44d8bb0c1c632c8d6829481f"
+
 [[package]]
 name = "safe_arch"
 version = "0.7.4"
@@ -257,6 +279,49 @@ dependencies = [
  "bytemuck",
 ]
 
+[[package]]
+name = "serde"
+version = "1.0.225"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fd6c24dee235d0da097043389623fb913daddf92c76e9f5a1db88607a0bcbd1d"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.225"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "659356f9a0cb1e529b24c01e43ad2bdf520ec4ceaf83047b83ddcc2251f96383"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.225"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ea936adf78b1f766949a4977b91d2f5595825bd6ec079aa9543ad2685fc4516"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.145"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "402a6f66d8c709116cf22f558eab210f5a50187f702eb4d7e5ef38d9a7f1c79c"
+dependencies = [
+ "itoa",
+ "memchr",
+ "ryu",
+ "serde",
+ "serde_core",
+]
+
 [[package]]
 name = "simba"
 version = "0.9.0"

{cartesian_tree-0.1.0 → cartesian_tree-0.2.0}/Cargo.toml

@@ -1,20 +1,22 @@
 [package]
 authors = ["Kn0g"]
 name = "CartesianTree"
-version = "0.1.0"
+version = "0.2.0"
 edition = "2024"
 description = "Build hierarchical Cartesian coordinate systems to easily transform poses."
 homepage = "https://github.com/Kn0g/cartesian-tree"
 readme = "README.md"
 repository = "https://github.com/Kn0g/cartesian-tree"
 license = "MIT"
-keywords = ["Cartesian", "coordinate systems", "transform", "poses"]
-categories = ["coordinate transformation"]
+keywords = ["Cartesian", "coordinate-systems", "transform", "poses"]
+categories = ["mathematics", "data-structures"]
 
 [dependencies]
-nalgebra = "0.33.2"
+nalgebra = { version = "0.33.2", features = ["serde-serialize"] }
 pyo3 = { version = "0.25.0", features = ["extension-module"] , optional = true}
 thiserror = "2.0.12"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
 
 [features]
 bindings = ["dep:pyo3"]

{cartesian_tree-0.1.0 → cartesian_tree-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cartesian-tree
-Version: 0.1.0
+Version: 0.2.0
 Classifier: Programming Language :: Python
 Requires-Dist: cartesian-tree[lint] ; extra == 'dev'
 Requires-Dist: cartesian-tree[test] ; extra == 'dev'

{cartesian_tree-0.1.0 → cartesian_tree-0.2.0}/pyproject.toml

@@ -30,6 +30,7 @@ build = ["maturin==1.8.6"]
 [tool.maturin]
 bindings = "pyo3"
 python-source = "python"
+module-name = "cartesian_tree._cartesian_tree"
 features = ["bindings"]
 exclude = ["tests"]
 

{cartesian_tree-0.1.0 → cartesian_tree-0.2.0}/python/cartesian_tree/helper.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from typing import Any
 
-from cartesian_tree import cartesian_tree as _core  # type: ignore[attr-defined]
+from cartesian_tree import _cartesian_tree as _core  # type: ignore[attr-defined]
 
 
 class RPY:

{cartesian_tree-0.1.0 → cartesian_tree-0.2.0}/python/cartesian_tree/lib.py

@@ -5,7 +5,7 @@ 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]
+from cartesian_tree import _cartesian_tree as _core  # type: ignore[attr-defined]
 
 
 class Frame:
@@ -53,6 +53,34 @@ class Frame:
         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.
 
@@ -98,6 +126,28 @@ class Frame:
             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.
+
+        Args:
+            config_json: The JSON string to apply.
+
+        Raises:
+            ValueError: On deserialization or mismatch errors.
+        """
+        self._core_frame.apply_config(config_json)
+
     def parent(self) -> Frame | None:
         """Returns the parent of the frame.
 
@@ -109,6 +159,15 @@ class Frame:
             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.
 
@@ -139,10 +198,9 @@ class Pose:
 
     _core_pose: _core.Pose
 
-    @property
-    def frame_name(self) -> str:
-        """Returns the name of the frame of the pose."""
-        return self._core_pose.frame_name
+    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.
@@ -179,6 +237,10 @@ class Pose:
         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)

{cartesian_tree-0.1.0 → cartesian_tree-0.2.0}/python/tests/test_lib.py

@@ -14,6 +14,19 @@ def test_create_root_frame() -> None:
     assert frame.depth == 0
 
 
+def test_tree_structure() -> None:
+    frame = Frame("root")
+    pos = Position(1.0, 2.0, 3.0)
+    quat = Quaternion(0.0, 0.0, 0.0, 1.0)
+    child = frame.add_child("child", pos, quat)
+    grandchild = child.add_child("grandchild", pos, quat)
+    assert grandchild.depth == 2  # noqa: PLR2004
+    parent = grandchild.parent()
+    assert parent is not None
+    assert parent.name == "child"
+    assert grandchild.root().name == "root"
+
+
 def test_add_child_frame_with_quaternion() -> None:
     root = Frame("base")
     pos = Position(1.0, 2.0, 3.0)
@@ -80,6 +93,12 @@ def test_add_pose_and_update() -> None:
     up_pos, _ = pose.transformation()
     assert up_pos.to_tuple() == pytest.approx((4.0, 5.0, 6.0), abs=1e-5)
 
+    # Access frame
+    frame_of_pose = pose.frame()
+    assert frame_of_pose.name == "base"
+    frame_of_pose.add_child("child_of_pose_frame", pos, quat)
+    assert len(frame_of_pose.children()) == 1
+
 
 def test_pose_in_frame() -> None:
     base = Frame("base")
@@ -93,3 +112,36 @@ def test_pose_in_frame() -> None:
 
     assert pos.to_tuple() == pytest.approx((1.0, -3.0, 1.0), abs=1e-5)
     assert quat.to_rpy().to_tuple() == pytest.approx((0.0, 0.0, -radians(90)), abs=1e-5)
+
+
+def test_calibrate_frame() -> None:
+    base = Frame("base")
+    reference_frame = base.add_child("reference", Position(1, 1, 1), Quaternion(0, 0, 0, 1))
+    reference_pose = reference_frame.add_pose(Position(1, 1, 1), Quaternion(0, 0, 0, 1))
+
+    calibrated_frame = base.calibrate_child("calibrated", Position(0, 0, 0), RPY(0, 0, 0), reference_pose)
+
+    pos, quat = calibrated_frame.transformation_to_parent()
+
+    assert pos.to_tuple() == pytest.approx((2.0, 2.0, 2.0), abs=1e-5)
+    assert quat.to_tuple() == pytest.approx((0.0, 0.0, 0.0, 1.0), abs=1e-5)
+
+
+def test_serialization() -> None:
+    root = Frame("root")
+    child1 = root.add_child("child1", Position(1, 0, 0), Quaternion(0, 0, 0, 1))
+    child2 = child1.add_child("child2", Position(0, 1, 0), RPY(0, 0, radians(90)))
+    child2.add_pose(Position(0, 0, 1), Quaternion(0, 0, 0, 1))
+
+    json_str = root.to_json()
+
+    default_root = Frame("root")
+    default_child1 = default_root.add_child("child1", Position(2, 0, 0), Quaternion(0, 0, 0, 1))
+    default_child2 = default_child1.add_child("child2", Position(0, 2, 0), RPY(0, 0, radians(90)))
+
+    default_root.apply_config(json_str)
+
+    position, _ = default_child1.transformation_to_parent()
+    assert position.to_tuple() == pytest.approx((1.0, 0.0, 0.0), abs=1e-5)  # Updated back to '1'
+    position, _ = default_child2.transformation_to_parent()
+    assert position.to_tuple() == pytest.approx((0.0, 1.0, 0.0), abs=1e-5)  # Updated back to '1'

{cartesian_tree-0.1.0 → cartesian_tree-0.2.0}/src/bindings/frame.rs

@@ -26,7 +26,7 @@ impl PyFrame {
     }
 
     #[getter]
-    fn name(&self) -> String {
+    pub(crate) fn name(&self) -> String {
         self.rust_frame.name()
     }
 
@@ -45,6 +45,25 @@ impl PyFrame {
         })
     }
 
+    #[pyo3(signature = (name, desired_position, desired_quaternion, reference_pose))]
+    fn calibrate_child(
+        &self,
+        name: String,
+        desired_position: PyPosition,
+        desired_quaternion: PyQuaternion,
+        reference_pose: &PyPose,
+    ) -> PyResult<PyFrame> {
+        let new_rust_frame = self.rust_frame.calibrate_child(
+            name,
+            desired_position.position,
+            desired_quaternion.quat,
+            &reference_pose.rust_pose,
+        )?;
+        Ok(PyFrame {
+            rust_frame: new_rust_frame,
+        })
+    }
+
     #[pyo3(signature = (position, quaternion))]
     fn add_pose(&self, position: PyPosition, quaternion: PyQuaternion) -> PyPose {
         let rust_pose = self.rust_frame.add_pose(position.position, quaternion.quat);
@@ -74,11 +93,27 @@ impl PyFrame {
         Ok(())
     }
 
+    fn to_json(&self) -> PyResult<String> {
+        Ok(self.rust_frame.to_json()?)
+    }
+
+    #[pyo3(signature = (json))]
+    fn apply_config(&self, json: String) -> PyResult<()> {
+        self.rust_frame.apply_config(&json)?;
+        Ok(())
+    }
+
     #[getter]
     fn depth(&self) -> usize {
         self.rust_frame.depth()
     }
 
+    fn root(&self) -> PyFrame {
+        PyFrame {
+            rust_frame: self.rust_frame.root(),
+        }
+    }
+
     fn parent(&self) -> Option<PyFrame> {
         self.rust_frame
             .parent()

{cartesian_tree-0.1.0 → cartesian_tree-0.2.0}/src/bindings/pose.rs

@@ -1,6 +1,5 @@
 use pyo3::prelude::*;
 
-// Import your existing Frame, Pose, CartesianTreeError, IntoOrientation
 use crate::{
     Pose as RustPose,
     bindings::{
@@ -17,9 +16,10 @@ pub struct PyPose {
 
 #[pymethods]
 impl PyPose {
-    #[getter]
-    fn frame_name(&self) -> Option<String> {
-        self.rust_pose.frame_name()
+    fn frame(&self) -> Option<PyFrame> {
+        self.rust_pose
+            .frame()
+            .map(|frame| PyFrame { rust_frame: frame })
     }
 
     fn transformation(&self) -> (PyPosition, PyQuaternion) {
@@ -69,7 +69,9 @@ impl PyPose {
         let quaternion = isometry.rotation.coords;
         format!(
             "'{}', ({:.2}, {:.2}, {:.2})({:.4}, {:.4}, {:.4}, {:.4}))",
-            self.frame_name().unwrap_or_else(|| "Unknown".to_string()),
+            self.frame()
+                .map(|frame| frame.name())
+                .unwrap_or_else(|| "Unknown".to_string()),
             position.x,
             position.y,
             position.z,

{cartesian_tree-0.1.0 → cartesian_tree-0.2.0}/src/errors.rs

@@ -14,4 +14,8 @@ pub enum CartesianTreeError {
     IsNoAncestor(String, String),
     #[error("Internal error: Weak pointer upgrade failed")]
     WeakUpgradeFailed(),
+    #[error("Serialization/Deserialization error: {0}")]
+    SerdeError(#[from] serde_json::Error),
+    #[error("Tree structure mismatch during config apply: {0}")]
+    Mismatch(String),
 }

{cartesian_tree-0.1.0 → cartesian_tree-0.2.0}/src/frame.rs

@@ -1,12 +1,17 @@
 use crate::CartesianTreeError;
 use crate::Pose;
 use crate::orientation::IntoOrientation;
+use crate::tree::Walking;
 use crate::tree::{HasChildren, HasParent, NodeEquality};
 
+use nalgebra::UnitQuaternion;
 use nalgebra::{Isometry3, Translation3, Vector3};
 use std::cell::RefCell;
 use std::rc::{Rc, Weak};
 
+use serde::{Deserialize, Serialize};
+use serde_json;
+
 /// Represents a coordinate frame in a Cartesian tree structure.
 ///
 /// Each frame can have one parent and multiple children. The frame stores its
@@ -30,6 +35,14 @@ pub(crate) struct FrameData {
     children: Vec<Frame>,
 }
 
+#[derive(Serialize, Deserialize, Debug, Clone)]
+struct SerialFrame {
+    name: String,
+    position: Vector3<f64>,
+    orientation: UnitQuaternion<f64>,
+    children: Vec<SerialFrame>,
+}
+
 impl Frame {
     /// Creates a new root frame (origin) with the given name.
     ///
@@ -54,11 +67,11 @@ impl Frame {
         }
     }
 
-    pub(crate) fn borrow(&self) -> std::cell::Ref<FrameData> {
+    pub(crate) fn borrow(&self) -> std::cell::Ref<'_, FrameData> {
         self.data.borrow()
     }
 
-    fn borrow_mut(&self) -> std::cell::RefMut<FrameData> {
+    fn borrow_mut(&self) -> std::cell::RefMut<'_, FrameData> {
         self.data.borrow_mut()
     }
 
@@ -217,6 +230,74 @@ impl Frame {
         Ok(child)
     }
 
+    /// Adds a new child frame calibrated such that a reference pose, when expressed in the new frame,
+    /// matches the desired position and orientation.
+    ///
+    /// # Arguments
+    /// - `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 existing pose (in some frame A) used as the calibration reference.
+    ///
+    /// # Returns
+    /// - `Ok(Frame)` the new child frame if successful.
+    /// - `Err(CartesianTreeError)` if the reference frame is invalid, no common ancestor exists,
+    ///   or a child name conflict occurs.
+    ///
+    /// # Example
+    /// ```
+    /// use cartesian_tree::Frame;
+    /// use nalgebra::{Vector3, UnitQuaternion};
+    ///
+    /// let root = Frame::new_origin("root");
+    /// let reference_pose = root.add_pose(Vector3::new(1.0, 0.0, 0.0), UnitQuaternion::identity());
+    /// let calibrated_child = root.calibrate_child(
+    ///     "calibrated",
+    ///     Vector3::zeros(),
+    ///     UnitQuaternion::identity(),
+    ///     &reference_pose,
+    /// ).unwrap();
+    /// ```
+    pub fn calibrate_child<O>(
+        &self,
+        name: impl Into<String>,
+        desired_position: Vector3<f64>,
+        desired_orientation: O,
+        reference_pose: &Pose,
+    ) -> Result<Frame, CartesianTreeError>
+    where
+        O: IntoOrientation,
+    {
+        let reference_frame = reference_pose.frame().ok_or_else(|| {
+            CartesianTreeError::FrameDropped("Reference pose frame has been dropped".to_string())
+        })?;
+
+        let ancestor = self.lca_with(&reference_frame).ok_or_else(|| {
+            CartesianTreeError::NoCommonAncestor(self.name(), reference_frame.name())
+        })?;
+
+        let t_reference_to_ancestor = reference_frame.walk_up_and_transform(&ancestor)?;
+        let t_pose_to_reference = reference_pose.transformation();
+        let t_pose_to_ancestor = t_reference_to_ancestor * t_pose_to_reference;
+
+        let t_parent_to_ancestor = self.walk_up_and_transform(&ancestor)?;
+        let t_ancestor_to_parent = t_parent_to_ancestor.inverse();
+
+        let desired_pose = Isometry3::from_parts(
+            Translation3::from(desired_position),
+            desired_orientation.into_orientation(),
+        );
+
+        let t_calibrated_to_parent =
+            t_pose_to_ancestor * desired_pose.inverse() * t_ancestor_to_parent;
+
+        self.add_child(
+            name,
+            t_calibrated_to_parent.translation.vector,
+            t_calibrated_to_parent.rotation,
+        )
+    }
+
     /// Adds a pose to the current frame.
     ///
     /// # Arguments
@@ -240,6 +321,82 @@ impl Frame {
     {
         Pose::new(self.downgrade(), position, orientation)
     }
+
+    /// Serializes the frame tree to a JSON string.
+    ///
+    /// This recursively serializes the hierarchy starting from this frame (ideally the root).
+    /// Transforms for root frames are set to identity.
+    ///
+    /// # Returns
+    /// - `Ok(String)` the pretty-printed JSON.
+    /// - `Err(CartesianTreeError)` on serialization failure.
+    pub fn to_json(&self) -> Result<String, CartesianTreeError> {
+        let serial = self.to_serial();
+        Ok(serde_json::to_string_pretty(&serial)?)
+    }
+
+    /// Helper function to convert the frame and its children recursively into a serializable structure.
+    ///
+    /// This is used internally for JSON serialization.
+    fn to_serial(&self) -> SerialFrame {
+        let (position, orientation) = if self.parent().is_some() {
+            let iso = self.transform_to_parent().unwrap_or(Isometry3::identity());
+            (iso.translation.vector, iso.rotation)
+        } else {
+            (Vector3::zeros(), UnitQuaternion::identity())
+        };
+
+        SerialFrame {
+            name: self.name(),
+            position,
+            orientation,
+            children: self.children().into_iter().map(|c| c.to_serial()).collect(),
+        }
+    }
+
+    /// Applies a JSON config to this frame tree by updating matching transforms.
+    ///
+    /// Deserializes the JSON to a temporary structure, then recursively updates transforms
+    /// where names match (partial apply; ignores unmatched nodes in config).
+    /// Skips updating root frames (identity assumed) - assumes this frame is the root.
+    ///
+    /// # Arguments
+    /// - `json`: The JSON string to apply.
+    ///
+    /// # Returns
+    /// - `Ok(())` if applied successfully (even if partial).
+    /// - `Err(CartesianTreeError)` on deserialization or mismatch (e.g., root names differ).
+    pub fn apply_config(&self, json: &str) -> Result<(), CartesianTreeError> {
+        let serial: SerialFrame = serde_json::from_str(json)?;
+        self.apply_serial(&serial)
+    }
+
+    fn apply_serial(&self, serial: &SerialFrame) -> Result<(), CartesianTreeError> {
+        if self.name() != serial.name {
+            return Err(CartesianTreeError::Mismatch(format!(
+                "Frame names do not match: {} vs {}",
+                self.name(),
+                serial.name
+            )));
+        }
+
+        // only update if frame has parent
+        if self.parent().is_some() {
+            self.update_transform(serial.position, serial.orientation)?;
+        }
+
+        for potential_child in &serial.children {
+            if let Some(child) = self
+                .children()
+                .into_iter()
+                .find(|c| c.name() == potential_child.name)
+            {
+                child.apply_serial(potential_child)?;
+            }
+        }
+
+        Ok(())
+    }
 }
 
 impl HasParent for Frame {
@@ -403,7 +560,7 @@ mod tests {
         let frame = Frame::new_origin("dummy");
         let pose = frame.add_pose(Vector3::new(1.0, 2.0, 3.0), UnitQuaternion::identity());
 
-        assert_eq!(pose.frame_name().as_deref(), Some("dummy"));
+        assert_eq!(pose.frame().unwrap().name(), "dummy");
     }
 
     #[test]
@@ -459,4 +616,131 @@ mod tests {
         // Total offset should be: f2 (0,2,0) + pose (1,1,0) + f1 (1,0,0)
         assert!((pos - Vector3::new(2.0, 3.0, 0.0)).norm() < 1e-6);
     }
+
+    #[test]
+    fn test_calibrate_child() {
+        let root = Frame::new_origin("root");
+
+        let reference_pose = root.add_pose(
+            Vector3::new(1.0, 2.0, 3.0),
+            UnitQuaternion::from_euler_angles(0.0, 0.0, std::f64::consts::FRAC_PI_2),
+        );
+
+        // Calibrate a child where the reference pose should appear at (0,0,0) with identity orientation.
+        let calibrated_frame = root
+            .calibrate_child(
+                "calibrated",
+                Vector3::zeros(),
+                UnitQuaternion::identity(),
+                &reference_pose,
+            )
+            .unwrap();
+
+        let pose_in_calibrated = reference_pose.in_frame(&calibrated_frame).unwrap();
+        let transformation = pose_in_calibrated.transformation();
+
+        assert!((transformation.translation.vector - Vector3::zeros()).norm() < 1e-6);
+        assert!((transformation.rotation.angle() - 0.0).abs() < 1e-6);
+
+        // Verify the child's transform matches the reference pose's original transform.
+        let calibrated_transformation = calibrated_frame.transform_to_parent().unwrap();
+        assert!(
+            (calibrated_transformation.translation.vector - Vector3::new(1.0, 2.0, 3.0)).norm()
+                < 1e-6
+        );
+        assert!(
+            (calibrated_transformation.rotation.angle() - std::f64::consts::FRAC_PI_2).abs() < 1e-6
+        );
+    }
+
+    #[test]
+    fn test_to_json_and_apply_config() {
+        let root = Frame::new_origin("root");
+        let _ = root
+            .add_child(
+                "child",
+                Vector3::new(1.0, 2.0, 3.0),
+                UnitQuaternion::from_euler_angles(0.1, 0.2, 0.3),
+            )
+            .unwrap();
+
+        let json = root.to_json().unwrap();
+        // roughly verify JSON structure
+        assert!(json.contains(r#""name": "root""#));
+        assert!(json.contains(r#""name": "child""#));
+
+        // Create a default tree with different transforms
+        let default_root = Frame::new_origin("root");
+        default_root
+            .add_child(
+                "child",
+                Vector3::new(0.0, 0.0, 0.0),
+                UnitQuaternion::identity(),
+            )
+            .unwrap();
+
+        // Apply config
+        default_root.apply_config(&json).unwrap();
+
+        // Verify child transform updated
+        let updated_child = default_root
+            .children()
+            .into_iter()
+            .find(|c| c.name() == "child")
+            .unwrap();
+        let iso = updated_child.transform_to_parent().unwrap();
+        assert_eq!(iso.translation.vector, Vector3::new(1.0, 2.0, 3.0));
+        let (r, p, y) = iso.rotation.euler_angles();
+        assert!((r - 0.1).abs() < 1e-6);
+        assert!((p - 0.2).abs() < 1e-6);
+        assert!((y - 0.3).abs() < 1e-6);
+
+        // Test partial: If config has extra, ignore it
+        let partial_json = r#"
+        {
+            "name": "root",
+            "position": [0.0, 0.0, 0.0],
+            "orientation": [0.0, 0.0, 0.0, 1.0],
+            "children": [
+                {
+                    "name": "child",
+                    "position": [4.0, 5.0, 6.0],
+                    "orientation": [0.0, 0.0, 0.0, 1.0],
+                    "children": []
+                },
+                {
+                    "name": "extra",
+                    "position": [0.0, 0.0, 0.0],
+                    "orientation": [0.0, 0.0, 0.0, 1.0],
+                    "children": []
+                }
+            ]
+        }
+        "#;
+        default_root.apply_config(partial_json).unwrap();
+        let updated_child = default_root
+            .children()
+            .into_iter()
+            .find(|c| c.name() == "child")
+            .unwrap();
+        assert_eq!(
+            updated_child
+                .transform_to_parent()
+                .unwrap()
+                .translation
+                .vector,
+            Vector3::new(4.0, 5.0, 6.0)
+        );
+
+        // Test mismatch
+        let mismatch_json = r#"
+        {
+            "name": "wrong_root",
+            "position": [0.0, 0.0, 0.0],
+            "orientation": [0.0, 0.0, 0.0, 1.0],
+            "children": []
+        }
+        "#;
+        assert!(default_root.apply_config(mismatch_json).is_err());
+    }
 }

{cartesian_tree-0.1.0 → cartesian_tree-0.2.0}/src/lib.rs

@@ -23,7 +23,7 @@ use pyo3::prelude::*;
 
 #[cfg(feature = "bindings")]
 #[pymodule]
-#[pyo3(name = "cartesian_tree")]
+#[pyo3(name = "_cartesian_tree")]
 fn cartesian_tree(_py: Python, m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<bindings::frame::PyFrame>()?;
     m.add_class::<bindings::pose::PyPose>()?;

{cartesian_tree-0.1.0 → cartesian_tree-0.2.0}/src/pose.rs

@@ -37,27 +37,23 @@ impl Pose {
         }
     }
 
-    /// Returns the name of the frame in which this pose is defined.
+    /// Returns the parent frame of this pose.
     ///
     /// # Returns
-    ///
-    /// `Some(String)` if the parent frame is still valid, or `None` if the frame
+    /// `Some(Frame)` if the parent frame is still valid, or `None` if the frame
     /// has been dropped or no longer exists.
     ///
     /// # Example
-    ///
     /// ```
     /// use cartesian_tree::Frame;
     /// use nalgebra::{Vector3, UnitQuaternion};
     ///
     /// let frame = Frame::new_origin("base");
     /// let pose = frame.add_pose(Vector3::new(0.0, 0.0, 0.0), UnitQuaternion::identity());
-    /// assert_eq!(pose.frame_name().as_deref(), Some("base"));
+    /// assert_eq!(pose.frame().unwrap().name(), "base");
     /// ```
-    pub fn frame_name(&self) -> Option<String> {
-        self.parent
-            .upgrade()
-            .map(|frame| frame.borrow().name.clone())
+    pub fn frame(&self) -> Option<Frame> {
+        self.parent.upgrade().map(|data| Frame { data })
     }
 
     /// Returns the transformation from this pose to its parent frame.

{cartesian_tree-0.1.0 → cartesian_tree-0.2.0}/src/tree/traits.rs

@@ -54,6 +54,15 @@ pub trait Walking: HasParent<Node = Self> + NodeEquality + Clone {
         Some(current)
     }
 
+    /// Finds the root of this node.
+    ///
+    /// # Returns
+    ///
+    /// The root Node.
+    fn root(&self) -> Self {
+        self.walk_up(self.depth()).unwrap_or_else(|| self.clone())
+    }
+
     /// Finds the lowest common ancestor with another Node.
     ///
     /// # Arguments.
@@ -126,6 +135,21 @@ mod tests {
         assert!(grandchild.walk_up(3).is_none());
     }
 
+    #[test]
+    fn test_root() {
+        let root = Frame::new_origin("root");
+        let child = root
+            .add_child("child", Vector3::zeros(), UnitQuaternion::identity())
+            .unwrap();
+        let grandchild = child
+            .add_child("grandchild", Vector3::zeros(), UnitQuaternion::identity())
+            .unwrap();
+
+        assert!(root.root().is_same(&root));
+        assert!(child.root().is_same(&root));
+        assert!(grandchild.root().is_same(&root));
+    }
+
     #[test]
     fn test_lca_with() {
         let root = Frame::new_origin("root");

cartesian_tree-0.1.0/.github/workflows/publish.yaml

@@ -1,40 +0,0 @@
-name: Publish
-
-on:
-  workflow_call:
-    secrets:
-      CARGO_REGISTRY_TOKEN:
-        required: true
-      PYPI_TOKEN:
-        required: true
-
-env:
-  CARGO_TERM_COLOR: always
-
-jobs:
-  publish-rust:
-    name: Publish Rust Crate
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@stable
-      
-      - name: Publish to crates.io
-        run: cargo publish --token ${{ secrets.CARGO_REGISTRY_TOKEN }}
-
-  publish-python:
-    name: Publish Python Package
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - name: Setup Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.x"
-
-      - name: Install maturin
-        run: pip install maturin
-
-      - name: Build and publish to PyPI
-        run: maturin publish --username __token__ --password ${{ secrets.PYPI_TOKEN }}