imt-ring 1.6.39__tar.gz → 1.6.45__tar.gz

{imt_ring-1.6.39 → imt_ring-1.6.45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: imt-ring
-Version: 1.6.39
+Version: 1.6.45
 Summary: RING: Recurrent Inertial Graph-based Estimator
 Author-email: Simon Bachhuber <simon.bachhuber@fau.de>
 Project-URL: Homepage, https://github.com/SimiPixel/ring
@@ -32,12 +32,15 @@ Requires-Dist: pytest-xdist; extra == "dev"
 Requires-Dist: nbmake; extra == "dev"
 
 <p align="center">
-<img src="https://raw.githubusercontent.com/simon-bachhuber/ring/main/docs/img/icon.svg" height="200" />
+<img src="https://raw.githubusercontent.com/simon-bachhuber/ring/main/docs/img/concept_v4.png" height="200" />
 </p>
 
+
 # Recurrent Inertial Graph-based Estimator (RING)
 <img src="https://raw.githubusercontent.com/simon-bachhuber/ring/main/docs/img/coverage_badge.svg" height="20" />
 
+RING provides a pluripotent, problem-unspecific plug-and-play IMT solution that, in contrast to conventional IMT solutions, eliminates the need for expert knowledge to identify, select, and parameterize the appropriate method. RING's pluripotency is enabled by a novel online-capable neural network architecture that uses a decentralized network of message-passing, parameter-sharing recurrent neural networks, which map local IMU measurements and nearest-neighbour messages to local orientations. This architecture enables RING to address a broad range of IMT problems that vary greatly in aspects such as the number of attached sensors, or the number of segments in the kinematic chain, and even generalize to previously unsolved IMT problems, including the challenging combination of magnetometer-free and sparse sensing with unknown sensor-to-segment parameters. Remarkably, RING is trained solely on simulated data, yet evaluated on experimental data, which indicates its exceptional ability to zero-shot generalize from simulation to experiment, while outperforming several state-of-the-art problem-specific solutions. For example, RING can, for the first time, accurately track a four-segment kinematic chain (which requires estimating four orientations) using only two magnetometer-free inertial measurement units.
+
 > **ℹ️ Tip:**
 > 
 > Check out my new plug-and-play interface for inertial motion tracking (RING included) [here](https://github.com/simon-bachhuber/imt.git).
@@ -50,26 +53,23 @@ Install with `pip` using
 
 `pip install imt-ring`
 
-Typically, this will install `jax` as cpu-only version. Afterwards, gpu-enabled version can be installed with
-```bash
-pip install --upgrade "jax[cuda12_pip]" -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html
-```
+Typically, this will install `jax` as cpu-only version. For GPU install instructions for `jax` see https://github.com/jax-ml/jax?tab=readme-ov-file#instructions.
 
 ## Documentation
 
-Available [here](https://simipixel.github.io/ring/).
+Available [here](https://simon-bachhuber.github.io/ring/).
 
 ## Quickstart Example
 ```python
 import ring
 import numpy as np
 
-T  : int       = 30        # sequence length     [s]
-Ts : float     = 0.01      # sampling interval   [s]
-B  : int       = 1         # batch size
-lam: list[int] = [0, 1, 2] # parent array
-N  : int       = len(lam)  # number of bodies
-T_i: int       = int(T/Ts) # number of timesteps
+T  : int       = 30         # sequence length     [s]
+Ts : float     = 0.01       # sampling interval   [s]
+B  : int       = 1          # batch size
+lam: list[int] = [-1, 0, 1] # parent array
+N  : int       = len(lam)   # number of bodies
+T_i: int       = int(T/Ts)  # number of timesteps
 
 X              = np.zeros((B, T_i, N, 9))
 # where X is structured as follows:
@@ -112,7 +112,11 @@ Solution:
 
 ## Publications
 
-The following publications utilize this software library, and refer to it as the *Random Chain Motion Generator (RCMG)* (more specifically the function `ring.RCMG`):
+The main publication is:
+
+- [*Recurrent Inertial Graph-Based Estimator (RING): A Single Pluripotent Inertial Motion Tracking Solution*](https://openreview.net/pdf?id=h2C3rkn0zR)
+
+The following publications also utilize this software library, and refer to it as the *Random Chain Motion Generator (RCMG)* (more specifically the function `ring.RCMG`):
 
 - [*RNN-based Observability Analysis for Magnetometer-Free Sparse Inertial Motion Tracking*](https://ieeexplore.ieee.org/document/9841375)
 - [*Plug-and-Play Sparse Inertial Motion Tracking With Sim-to-Real Transfer*](https://ieeexplore.ieee.org/document/10225275)

{imt_ring-1.6.39 → imt_ring-1.6.45}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "imt-ring"
-version = "1.6.39"
+version = "1.6.45"
 authors = [
   { name="Simon Bachhuber", email="simon.bachhuber@fau.de" },
 ]
@@ -57,3 +57,6 @@ where = ["src"]
 [tool.setuptools.package-data]
 "ring.io.examples" = ["**/*.xml"]
 "ring.ml.params" = ["**/*.pickle"]
+
+[project.scripts]
+ring-view = "ring.extras.interactive_viewer:main"

{imt_ring-1.6.39 → imt_ring-1.6.45}/readme.md

@@ -1,10 +1,13 @@
 <p align="center">
-<img src="https://raw.githubusercontent.com/simon-bachhuber/ring/main/docs/img/icon.svg" height="200" />
+<img src="https://raw.githubusercontent.com/simon-bachhuber/ring/main/docs/img/concept_v4.png" height="200" />
 </p>
 
+
 # Recurrent Inertial Graph-based Estimator (RING)
 <img src="https://raw.githubusercontent.com/simon-bachhuber/ring/main/docs/img/coverage_badge.svg" height="20" />
 
+RING provides a pluripotent, problem-unspecific plug-and-play IMT solution that, in contrast to conventional IMT solutions, eliminates the need for expert knowledge to identify, select, and parameterize the appropriate method. RING's pluripotency is enabled by a novel online-capable neural network architecture that uses a decentralized network of message-passing, parameter-sharing recurrent neural networks, which map local IMU measurements and nearest-neighbour messages to local orientations. This architecture enables RING to address a broad range of IMT problems that vary greatly in aspects such as the number of attached sensors, or the number of segments in the kinematic chain, and even generalize to previously unsolved IMT problems, including the challenging combination of magnetometer-free and sparse sensing with unknown sensor-to-segment parameters. Remarkably, RING is trained solely on simulated data, yet evaluated on experimental data, which indicates its exceptional ability to zero-shot generalize from simulation to experiment, while outperforming several state-of-the-art problem-specific solutions. For example, RING can, for the first time, accurately track a four-segment kinematic chain (which requires estimating four orientations) using only two magnetometer-free inertial measurement units.
+
 > **ℹ️ Tip:**
 > 
 > Check out my new plug-and-play interface for inertial motion tracking (RING included) [here](https://github.com/simon-bachhuber/imt.git).
@@ -17,26 +20,23 @@ Install with `pip` using
 
 `pip install imt-ring`
 
-Typically, this will install `jax` as cpu-only version. Afterwards, gpu-enabled version can be installed with
-```bash
-pip install --upgrade "jax[cuda12_pip]" -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html
-```
+Typically, this will install `jax` as cpu-only version. For GPU install instructions for `jax` see https://github.com/jax-ml/jax?tab=readme-ov-file#instructions.
 
 ## Documentation
 
-Available [here](https://simipixel.github.io/ring/).
+Available [here](https://simon-bachhuber.github.io/ring/).
 
 ## Quickstart Example
 ```python
 import ring
 import numpy as np
 
-T  : int       = 30        # sequence length     [s]
-Ts : float     = 0.01      # sampling interval   [s]
-B  : int       = 1         # batch size
-lam: list[int] = [0, 1, 2] # parent array
-N  : int       = len(lam)  # number of bodies
-T_i: int       = int(T/Ts) # number of timesteps
+T  : int       = 30         # sequence length     [s]
+Ts : float     = 0.01       # sampling interval   [s]
+B  : int       = 1          # batch size
+lam: list[int] = [-1, 0, 1] # parent array
+N  : int       = len(lam)   # number of bodies
+T_i: int       = int(T/Ts)  # number of timesteps
 
 X              = np.zeros((B, T_i, N, 9))
 # where X is structured as follows:
@@ -79,7 +79,11 @@ Solution:
 
 ## Publications
 
-The following publications utilize this software library, and refer to it as the *Random Chain Motion Generator (RCMG)* (more specifically the function `ring.RCMG`):
+The main publication is:
+
+- [*Recurrent Inertial Graph-Based Estimator (RING): A Single Pluripotent Inertial Motion Tracking Solution*](https://openreview.net/pdf?id=h2C3rkn0zR)
+
+The following publications also utilize this software library, and refer to it as the *Random Chain Motion Generator (RCMG)* (more specifically the function `ring.RCMG`):
 
 - [*RNN-based Observability Analysis for Magnetometer-Free Sparse Inertial Motion Tracking*](https://ieeexplore.ieee.org/document/9841375)
 - [*Plug-and-Play Sparse Inertial Motion Tracking With Sim-to-Real Transfer*](https://ieeexplore.ieee.org/document/10225275)

{imt_ring-1.6.39 → imt_ring-1.6.45}/src/imt_ring.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: imt-ring
-Version: 1.6.39
+Version: 1.6.45
 Summary: RING: Recurrent Inertial Graph-based Estimator
 Author-email: Simon Bachhuber <simon.bachhuber@fau.de>
 Project-URL: Homepage, https://github.com/SimiPixel/ring
@@ -32,12 +32,15 @@ Requires-Dist: pytest-xdist; extra == "dev"
 Requires-Dist: nbmake; extra == "dev"
 
 <p align="center">
-<img src="https://raw.githubusercontent.com/simon-bachhuber/ring/main/docs/img/icon.svg" height="200" />
+<img src="https://raw.githubusercontent.com/simon-bachhuber/ring/main/docs/img/concept_v4.png" height="200" />
 </p>
 
+
 # Recurrent Inertial Graph-based Estimator (RING)
 <img src="https://raw.githubusercontent.com/simon-bachhuber/ring/main/docs/img/coverage_badge.svg" height="20" />
 
+RING provides a pluripotent, problem-unspecific plug-and-play IMT solution that, in contrast to conventional IMT solutions, eliminates the need for expert knowledge to identify, select, and parameterize the appropriate method. RING's pluripotency is enabled by a novel online-capable neural network architecture that uses a decentralized network of message-passing, parameter-sharing recurrent neural networks, which map local IMU measurements and nearest-neighbour messages to local orientations. This architecture enables RING to address a broad range of IMT problems that vary greatly in aspects such as the number of attached sensors, or the number of segments in the kinematic chain, and even generalize to previously unsolved IMT problems, including the challenging combination of magnetometer-free and sparse sensing with unknown sensor-to-segment parameters. Remarkably, RING is trained solely on simulated data, yet evaluated on experimental data, which indicates its exceptional ability to zero-shot generalize from simulation to experiment, while outperforming several state-of-the-art problem-specific solutions. For example, RING can, for the first time, accurately track a four-segment kinematic chain (which requires estimating four orientations) using only two magnetometer-free inertial measurement units.
+
 > **ℹ️ Tip:**
 > 
 > Check out my new plug-and-play interface for inertial motion tracking (RING included) [here](https://github.com/simon-bachhuber/imt.git).
@@ -50,26 +53,23 @@ Install with `pip` using
 
 `pip install imt-ring`
 
-Typically, this will install `jax` as cpu-only version. Afterwards, gpu-enabled version can be installed with
-```bash
-pip install --upgrade "jax[cuda12_pip]" -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html
-```
+Typically, this will install `jax` as cpu-only version. For GPU install instructions for `jax` see https://github.com/jax-ml/jax?tab=readme-ov-file#instructions.
 
 ## Documentation
 
-Available [here](https://simipixel.github.io/ring/).
+Available [here](https://simon-bachhuber.github.io/ring/).
 
 ## Quickstart Example
 ```python
 import ring
 import numpy as np
 
-T  : int       = 30        # sequence length     [s]
-Ts : float     = 0.01      # sampling interval   [s]
-B  : int       = 1         # batch size
-lam: list[int] = [0, 1, 2] # parent array
-N  : int       = len(lam)  # number of bodies
-T_i: int       = int(T/Ts) # number of timesteps
+T  : int       = 30         # sequence length     [s]
+Ts : float     = 0.01       # sampling interval   [s]
+B  : int       = 1          # batch size
+lam: list[int] = [-1, 0, 1] # parent array
+N  : int       = len(lam)   # number of bodies
+T_i: int       = int(T/Ts)  # number of timesteps
 
 X              = np.zeros((B, T_i, N, 9))
 # where X is structured as follows:
@@ -112,7 +112,11 @@ Solution:
 
 ## Publications
 
-The following publications utilize this software library, and refer to it as the *Random Chain Motion Generator (RCMG)* (more specifically the function `ring.RCMG`):
+The main publication is:
+
+- [*Recurrent Inertial Graph-Based Estimator (RING): A Single Pluripotent Inertial Motion Tracking Solution*](https://openreview.net/pdf?id=h2C3rkn0zR)
+
+The following publications also utilize this software library, and refer to it as the *Random Chain Motion Generator (RCMG)* (more specifically the function `ring.RCMG`):
 
 - [*RNN-based Observability Analysis for Magnetometer-Free Sparse Inertial Motion Tracking*](https://ieeexplore.ieee.org/document/9841375)
 - [*Plug-and-Play Sparse Inertial Motion Tracking With Sim-to-Real Transfer*](https://ieeexplore.ieee.org/document/10225275)

{imt_ring-1.6.39 → imt_ring-1.6.45}/src/imt_ring.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ setup.cfg
 src/imt_ring.egg-info/PKG-INFO
 src/imt_ring.egg-info/SOURCES.txt
 src/imt_ring.egg-info/dependency_links.txt
+src/imt_ring.egg-info/entry_points.txt
 src/imt_ring.egg-info/requires.txt
 src/imt_ring.egg-info/top_level.txt
 src/ring/__init__.py

imt_ring-1.6.45/src/imt_ring.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ring-view = ring.extras.interactive_viewer:main

{imt_ring-1.6.39 → imt_ring-1.6.45}/src/ring/algorithms/generator/base.py

@@ -1,5 +1,6 @@
 from dataclasses import replace
 from functools import partial
+import logging
 import random
 from typing import Callable, Optional
 import warnings
@@ -20,6 +21,8 @@ from ring.algorithms.generator import motion_artifacts
 from ring.algorithms.generator import setup_fns
 from ring.algorithms.generator import types
 
+logger = logging.getLogger(__name__)
+
 
 class RCMG:
     def __init__(
@@ -237,7 +240,9 @@ class RCMG:
     def _generators_ncalls(self, sizes: int | list[int] = 1):
         "Returns list of unbatched sequences as numpy arrays."
         repeats = self._compute_repeats(sizes)
+        logger.info(f"`repeats` = {repeats}")
         sizes = list(jnp.array(repeats) * jnp.array(self._size_of_generators))
+        logger.info(f"`sizes` = {sizes}")
 
         reduced_repeats = []
         n_calls = []
@@ -246,6 +251,9 @@ class RCMG:
             gcd = utils.gcd(n_call, repeat)
             n_calls.append(gcd)
             reduced_repeats.append(repeat // gcd)
+        logger.info(f"`reduced_repeats` = {reduced_repeats}")
+        logger.info(f"`n_calls` = {n_calls}")
+
         jits = [N > 1 for N in n_calls]
 
         gens = []

{imt_ring-1.6.39 → imt_ring-1.6.45}/src/ring/ml/base.py

@@ -297,8 +297,12 @@ class NoGraph_FilterWrapper(AbstractFilterWrapper):
 
         if self._quat_normalize:
             assert yhat.shape[-1] == 4, f"yhat.shape={yhat.shape}"
-            # yhat = ring.maths.safe_normalize(yhat)
-            yhat = yhat / jnp.linalg.norm(yhat, axis=-1, keepdims=True)
+
+            # for exporting neural networks to ONNX format, you will have to use
+            # the first version, but for neural network training the second version
+            # is required
+            # yhat = yhat / jnp.linalg.norm(yhat, axis=-1, keepdims=True)
+            yhat = ring.maths.safe_normalize(yhat)
 
         return yhat, state
 

{imt_ring-1.6.39 → imt_ring-1.6.45}/src/ring/sim2real/sim2real.py

@@ -1,13 +1,14 @@
 from typing import Optional, Tuple
 
 import jax
+import tree_utils
+
 from ring import algebra
 from ring import base
 from ring import io
 from ring import maths
 from ring.algorithms import generator
 from ring.algorithms import jcalc
-import tree_utils
 
 
 def xs_from_raw(
@@ -189,7 +190,14 @@ def delete_to_world_pos_rot(sys: base.System, xs: base.Transform) -> base.Transf
 
 
 def randomize_to_world_pos_rot(
-    key: jax.Array, sys: base.System, xs: base.Transform, config: jcalc.MotionConfig
+    key: jax.Array,
+    sys: base.System,
+    xs: base.Transform,
+    config: jcalc.MotionConfig,
+    world_joint: str = "free",
+    cor: bool = False,
+    overwrite_q_ref: jax.Array = None,
+    damping=None,
 ) -> base.Transform:
     """Replace the transforms of all links that connect to the worldbody
     by randomize transforms.
@@ -210,14 +218,30 @@ def randomize_to_world_pos_rot(
 <x_xy>
     <options dt="0.01"/>
     <worldbody>
-        <body name="free" joint="free"/>
+        <body name="free" joint="free" damping="15.0 15.0 15.0 25.0 25.0 25.0">
+            <geom type="box" mass="1" dim="0.1 0.1 0.1"/>
+        </body>
     </worldbody>
 </x_xy>
 """
-
     free_sys = io.load_sys_from_str(free_sys_str)
+
+    dynamic_simulation = True if overwrite_q_ref is not None else False
+
+    if world_joint != "free":
+        if dynamic_simulation:
+            assert damping is not None
+        free_sys = free_sys.change_joint_type("free", world_joint, new_damp=damping)
+
     _, xs_free = generator.RCMG(
-        free_sys, config, finalize_fn=lambda key, q, x, sys: (q, x)
+        free_sys,
+        config,
+        finalize_fn=lambda key, q, x, sys: (q, x),
+        cor=cor,
+        dynamic_simulation=dynamic_simulation,
+        dynamic_simulation_kwargs=dict(
+            overwrite_q_ref=(overwrite_q_ref, free_sys.idx_map("q"))
+        ),
     ).to_lazy_gen()(key)
     xs_free = xs_free.take(0, axis=0)
     xs_free = xs_free.take(free_sys.name_to_idx("free"), axis=1)

{imt_ring-1.6.39 → imt_ring-1.6.45}/tests/test_custom_joints.py

@@ -41,7 +41,7 @@ def test_virtual_input_joint_axes_rr_joint():
     X = pipeline_load_data_X(sys)
 
     np.testing.assert_allclose(
-        -X["seg1"]["joint_axes"],
+        X["seg1"]["joint_axes"],
         np.repeat(np.array([[0.0, 1, 0]]), 1000, axis=0),
         atol=2e-6,
     )
@@ -55,7 +55,7 @@ def test_virtual_input_joint_axes_rr_joint():
     X = pipeline_load_data_X(sys_rr)
 
     np.testing.assert_allclose(
-        X["seg1"]["joint_axes"],
+        -X["seg1"]["joint_axes"],
         np.repeat(-joint_axes[1:2], 1000, axis=0),
         atol=2e-6,
         rtol=5e-4,
@@ -83,13 +83,13 @@ def test_virtual_input_joint_axes_rr_imp_joint():
     X = pipeline_load_data_X(sys_rr_imp)
 
     np.testing.assert_allclose(
-        -X["seg1"]["joint_axes"],
+        X["seg1"]["joint_axes"],
         np.repeat(joint_axes[1:2], 1000, axis=0),
         atol=0.01,
         rtol=0.02,
     )
     np.testing.assert_allclose(
-        -X["seg3"]["joint_axes"],
+        X["seg3"]["joint_axes"],
         np.repeat(joint_axes[3:4], 1000, axis=0),
         atol=0.01,
         rtol=0.032,
@@ -101,7 +101,7 @@ def test_virtual_input_joint_axes_rr_imp_joint():
     X = pipeline_load_data_X(sys)
 
     np.testing.assert_allclose(
-        -X["seg1"]["joint_axes"],
+        X["seg1"]["joint_axes"],
         np.repeat(np.array([[0.0, 1, 0]]), 1000, axis=0),
         atol=2e-6,
     )

{imt_ring-1.6.39 → imt_ring-1.6.45}/tests/test_maths.py

@@ -1,9 +1,10 @@
 import jax
 import jax.numpy as jnp
 import numpy as np
-from ring import maths
 import tree_utils
 
+from ring import maths
+
 
 def test_quat_rot_axis_are_inverse():
     q = maths.quat_random(
@@ -12,7 +13,8 @@ def test_quat_rot_axis_are_inverse():
         )
     )
     axis, angle = maths.quat_to_rot_axis(q)
-    assert tree_utils.tree_close(q, maths.quat_rot_axis(axis, angle))
+    # since jax >= v0.5 it (for some reason) returns q -> -q
+    assert tree_utils.tree_close(q, -maths.quat_rot_axis(axis, angle))
 
 
 def test_3x3_are_inverse():
@@ -23,7 +25,8 @@ def test_3x3_are_inverse():
     )
     mat = maths.quat_to_3x3(q)
 
-    np.testing.assert_allclose(q, maths.quat_from_3x3(mat), rtol=1e-5, atol=1e-5)
+    # since jax >= v0.5 it (for some reason) returns q -> -q
+    np.testing.assert_allclose(q, -maths.quat_from_3x3(mat), rtol=1e-5, atol=1e-5)
     np.testing.assert_allclose(
         mat, maths.quat_to_3x3(maths.quat_from_3x3(mat)), rtol=1e-5, atol=1e-5
     )

{imt_ring-1.6.39 → imt_ring-1.6.45}/tests/test_ml_utils.py

@@ -149,7 +149,7 @@ def test_wandb_logger():
     logger.log({"awesome_array": np.array(1.0)})
     logger.log({"awesome_string": "yay"})
 
-    root = Path(__file__).parent.parent.joinpath("test_ml_utils_assets")
+    root = Path(__file__).parent.joinpath("test_ml_utils_assets")
 
     logger.log_image(str(root.joinpath("image1.png")))
     logger.log_image(str(root.joinpath("image2.png")))

{imt_ring-1.6.39 → imt_ring-1.6.45}/tests/test_random.py

@@ -18,7 +18,8 @@ from ring.algorithms._random import _resolve_range_of_motion
 def test_delta_ang_min_max(
     range_of_motion, range_of_motion_method, delta_ang_min, delta_ang_max
 ):
-    max_iter = 100
+    # add more patience if `delta_ang_max` is small (thus very unlikely)
+    max_iter = 200 if delta_ang_max == 0.1 else 100
     t_min, t_max = 0.1, 3.1
     for seed in range(10):
         for prev_phi in [-3.0, 0.0, 3.0]:

{imt_ring-1.6.39 → imt_ring-1.6.45}/tests/test_train.py

@@ -7,6 +7,11 @@ import tree_utils
 import ring
 from ring import ml
 from ring import utils
+import wandb
+
+# make sure that `ml.train_fn` doesn't think wandb is running and automatically
+# add a `WandBLogger`
+wandb.run = None
 
 
 def _load_gen_lam():