imt-ring 1.6.39__py3-none-any.whl → 1.6.45__py3-none-any.whl

{imt_ring-1.6.39.dist-info → imt_ring-1.6.45.dist-info}/METADATA

@@ -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.dist-info → imt_ring-1.6.45.dist-info}/RECORD

@@ -15,7 +15,7 @@ ring/algorithms/custom_joints/rr_joint.py,sha256=jnRtjtOCALMaq2_0bcu2d7qgfQ6etXp
 ring/algorithms/custom_joints/rsaddle_joint.py,sha256=QoMo6NXdYgA9JygSzBvr0eCdd3qKhUgCrGPNO2Qdxko,1200
 ring/algorithms/custom_joints/suntay.py,sha256=TZG307NqdMiXnNY63xEx8AkAjbQBQ4eO6DQ7R4j4D08,16726
 ring/algorithms/generator/__init__.py,sha256=bF-CW3x2x-o6KWESKy-DuxzZPh3UNSjJb_MaAcSHGsQ,277
-ring/algorithms/generator/base.py,sha256=klWYt6TlMluLu0ihGzmmPXBm47DOTpjXJylZVNXHVEk,22419
+ring/algorithms/generator/base.py,sha256=yPH_RIQPU_nlq58HyZ6T3RUm1S5chA3-Ro__-ArYTq0,22669
 ring/algorithms/generator/batch.py,sha256=xp1X8oYtwI6l2cH4GRu9zw-P8dnh-X1FWTSyixEfgr8,2652
 ring/algorithms/generator/finalize_fns.py,sha256=ty1NaU-Mghx1RL-voivDjS0TWSKNtjTmbdmBnShhn7k,10398
 ring/algorithms/generator/motion_artifacts.py,sha256=2VJbldVDbI3PSyboshIbtYvSAKzBBwGV7cQfYjqvluM,9167
@@ -52,7 +52,7 @@ ring/io/xml/test_from_xml.py,sha256=bckVrVVmEhCwujd_OF9FGYnX3zU3BgztpqGxxmd0htM,
 ring/io/xml/test_to_xml.py,sha256=NGn4VSiFdwhYN5YTBduWMiY9B5dwtxZhCQAR_PXeqKU,946
 ring/io/xml/to_xml.py,sha256=Wo4iySLw9nM-iVW42AGvMRqjtU2qRc2FD_Zlc7w1IrE,3438
 ring/ml/__init__.py,sha256=nbh48gaswWeY4S4vT1sply_3ROj2DQ7agjoLR4Ho3T8,1517
-ring/ml/base.py,sha256=phBUfTpP1Mqt8lvtilSavT7ypkaeaF1oh7nCMjV0dqg,10046
+ring/ml/base.py,sha256=HAAM6ehXiyV53cvh1bLvPHIrlM7S4pgN-xcGTI8Mvsw,10238
 ring/ml/callbacks.py,sha256=oCPXl4_Zcw3g0KRgyyUDmdiGxV0phnDVc_t8rEG4Lls,13737
 ring/ml/ml_utils.py,sha256=hu189AnHcmkhkpEPZZ19O0gWz3T-YKpWQW9buqDTMow,10915
 ring/ml/optimizer.py,sha256=TZF0_LmnewzmGVso-zIQJtpWguUW0fW3HeRpIdG_qoI,4763
@@ -68,7 +68,7 @@ ring/rendering/mujoco_render.py,sha256=HMvZc04I0-lXPBL3hcnBzV2bNiXQAQM7QcHlG_Obm
 ring/rendering/vispy_render.py,sha256=6Z6S5LNZ7iy9BN1GVb9EDe-Tix5N_SQ1s7ZsfiTSDEA,10261
 ring/rendering/vispy_visuals.py,sha256=ooBZqppnebeL0ANe6V6zUgnNTtDcdkOsa4vZuM4sx-I,7873
 ring/sim2real/__init__.py,sha256=gCLYg8IoMdzUagzhCFcfjZ5GavtIU772L7HR0G5hUtM,251
-ring/sim2real/sim2real.py,sha256=B4nqBBnjGXhM-7PfTyxEq44ZidGNghqaq--qdFILX5A,9675
+ring/sim2real/sim2real.py,sha256=4MtxsyQmfnSi9llzL0ZB5wmJ5zfAXBv705RbSpI26gY,10373
 ring/sys_composer/__init__.py,sha256=5J_JJJIHfTPcpxh0v4FqiOs81V1REPUd7pgiw2nAN5E,193
 ring/sys_composer/delete_sys.py,sha256=cIM9KbyLfg7B9121g7yjzuFbjeNu9cil1dPavAYEgzk,3408
 ring/sys_composer/inject_sys.py,sha256=PLuxLbXU7hPtAsqvpsEim9hkoVE26ddrg3OipZNvnhU,3504
@@ -86,7 +86,8 @@ ring/utils/randomize_sys.py,sha256=G_vBIo0OwQkXL2u0djwbaoaeb02C4LQCTNNloOYIU2M,3
 ring/utils/utils.py,sha256=gKwOXLxWraeZfX6EbBcg3hkq30DcXN0mcRUeOSTNiMo,7336
 ring/utils/register_gym_envs/__init__.py,sha256=PtPIRBQJ16339xZ9G9VpvqrvcGbQ_Pk_SUz4tQPa9nQ,94
 ring/utils/register_gym_envs/saddle.py,sha256=tA5CyW_akSXyDm0xJ83CtOrUMVElH0f9vZtEDDJQalI,4422
-imt_ring-1.6.39.dist-info/METADATA,sha256=v0rBTnCQP-SWJU153byfX31HUCcrWHhCg_EmecLbLf4,4251
-imt_ring-1.6.39.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-imt_ring-1.6.39.dist-info/top_level.txt,sha256=EiT790-lAyi8iwTzJArH3f2k77rwhDn00q-4PlmvDQo,5
-imt_ring-1.6.39.dist-info/RECORD,,
+imt_ring-1.6.45.dist-info/METADATA,sha256=gjZdACsiCHmMA8kB0eRzjI2QIKoP6BgUVzYaVznaNTc,5708
+imt_ring-1.6.45.dist-info/WHEEL,sha256=jB7zZ3N9hIM9adW7qlTAyycLYW9npaWKLRzaoVcLKcM,91
+imt_ring-1.6.45.dist-info/entry_points.txt,sha256=npNqSOvNiBR0BNa_GL3J66q8Gky3h0G_PHzHzk8oyE0,66
+imt_ring-1.6.45.dist-info/top_level.txt,sha256=EiT790-lAyi8iwTzJArH3f2k77rwhDn00q-4PlmvDQo,5
+imt_ring-1.6.45.dist-info/RECORD,,

{imt_ring-1.6.39.dist-info → imt_ring-1.6.45.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.8.0)
+Generator: setuptools (75.8.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

imt_ring-1.6.45.dist-info/entry_points.txt

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

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 = []

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
 

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)