smplfitter 0.3.2.dev0__tar.gz → 0.4.0__tar.gz

{smplfitter-0.3.2.dev0 → smplfitter-0.4.0}/.gitignore

@@ -129,3 +129,14 @@ dmypy.json
 .pyre/
 
 docs/_build/
+_version.py
+
+# Experimental backends (not yet public)
+src/smplfitter/cy/
+src/smplfitter/cuda/
+src/smplfitter/cuda2/
+setup_cy.py
+setup_cuda.py
+setup_cuda2.py
+test_cuda2_vs_pt.py
+tests/test_cuda/

{smplfitter-0.3.2.dev0 → smplfitter-0.4.0}/.readthedocs.yaml

@@ -5,6 +5,7 @@ build:
   tools:
     python: "3.10"
   commands:
+    - python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
     - python -m pip install ".[docs]"
     - python -m sphinx -E -b html docs $READTHEDOCS_OUTPUT/html
 

{smplfitter-0.3.2.dev0 → smplfitter-0.4.0}/PKG-INFO

@@ -1,30 +1,9 @@
 Metadata-Version: 2.4
 Name: smplfitter
-Version: 0.3.2.dev0
+Version: 0.4.0
 Summary: Fast inverse kinematics and shape fitting for SMPL-family models in NumPy, PyTorch, TensorFlow, JAX, and Numba
 Author-email: István Sárándi <istvan.sarandi@uni-tuebingen.de>
-License: MIT License
-        
-        Copyright (c) 2024 István Sárándi
-        
-        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.
-        
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/isarandi/smplfitter
 Project-URL: Repository, https://github.com/isarandi/smplfitter
 Project-URL: Documentation, https://smplfitter.readthedocs.io/
@@ -34,7 +13,6 @@ Project-URL: Author, https://istvansarandi.com
 Keywords: smpl,smplx,smplh,3d-human,body-model,ik,inverse-kinematics,parametric-model,pose-estimation,differentiable,gpu,tensorflow,pytorch,jax,numba,numpy,batch-processing
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.8
@@ -52,6 +30,7 @@ License-File: LICENSE
 Requires-Dist: numpy
 Requires-Dist: scipy
 Requires-Dist: chumpy
+Requires-Dist: platformdirs
 Provides-Extra: tensorflow
 Requires-Dist: tensorflow; extra == "tensorflow"
 Provides-Extra: pytorch
@@ -61,6 +40,13 @@ Requires-Dist: jax; extra == "jax"
 Requires-Dist: jaxlib; extra == "jax"
 Provides-Extra: numba
 Requires-Dist: numba; extra == "numba"
+Provides-Extra: viz
+Requires-Dist: moderngl; extra == "viz"
+Requires-Dist: glfw; extra == "viz"
+Requires-Dist: poseviz; extra == "viz"
+Requires-Dist: framepump; extra == "viz"
+Requires-Dist: torch; extra == "viz"
+Requires-Dist: deltacamera; extra == "viz"
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Requires-Dist: pytest-cov; extra == "test"
@@ -77,6 +63,11 @@ Requires-Dist: sphinx-codeautolink; extra == "docs"
 Requires-Dist: pydata-sphinx-theme; extra == "docs"
 Requires-Dist: setuptools-scm; extra == "docs"
 Requires-Dist: toml; extra == "docs"
+Requires-Dist: torch; extra == "docs"
+Requires-Dist: tensorflow; extra == "docs"
+Requires-Dist: jax; extra == "docs"
+Requires-Dist: jaxlib; extra == "docs"
+Requires-Dist: numba; extra == "docs"
 Provides-Extra: dev
 Requires-Dist: smplfitter[docs,lint,pytorch,test]; extra == "dev"
 Dynamic: license-file

{smplfitter-0.3.2.dev0 → smplfitter-0.4.0}/benchmark/bench_bodymodel.py

@@ -4,18 +4,21 @@ import numpy as np
 import time
 
 
-def benchmark(func, inputs, n_warmup=3, n_iter=50):
-    """Run benchmark and return mean time in ms."""
+def benchmark(func, inputs, n_warmup=20, n_iter=50):
+    """Run benchmark and return median time in ms."""
     # Warmup
     for _ in range(n_warmup):
         func(**inputs)
 
-    # Timed runs
-    start = time.perf_counter()
+    # Timed runs (individual)
+    times = []
     for _ in range(n_iter):
+        start = time.perf_counter()
         func(**inputs)
-    elapsed = time.perf_counter() - start
-    return elapsed / n_iter * 1000  # ms
+        elapsed = time.perf_counter() - start
+        times.append(elapsed * 1000)
+    times.sort()
+    return times[n_iter // 2]  # median
 
 
 def main():

{smplfitter-0.3.2.dev0 → smplfitter-0.4.0}/benchmark/plot_results.py

@@ -23,6 +23,10 @@ def query_throughput(conn, backend, model, mode):
 STYLE = {
     'NumPy': dict(color='C0', linestyle='--', marker='o'),
     'Numba': dict(color='C1', linestyle='--', marker='s'),
+    'PT eager CPU': dict(color='C2', linestyle='--', marker='o'),
+    'PT eager GPU': dict(color='C2', linestyle='-', marker='o'),
+    'PT script CPU': dict(color='C6', linestyle='--', marker='s'),
+    'PT script GPU': dict(color='C6', linestyle='-', marker='s'),
     'PT compile CPU': dict(color='C2', linestyle='--', marker='^'),
     'PT compile GPU': dict(color='C2', linestyle='-', marker='^'),
     'TF function CPU': dict(color='C3', linestyle='--', marker='D'),

{smplfitter-0.3.2.dev0 → smplfitter-0.4.0}/benchmark/run_benchmark.py

@@ -98,23 +98,24 @@ def make_backends(model_name='smpl', return_vertices=True, which=None):
         try:
             import torch
 
-            backends.append(
-                PyTorchBackend(
-                    model_name=model_name,
-                    gpu=False,
-                    compile_mode='compile',
-                    return_vertices=return_vertices,
-                )
-            )
-            if torch.cuda.is_available():
+            for compile_mode in [None, 'script', 'compile']:
                 backends.append(
                     PyTorchBackend(
                         model_name=model_name,
-                        gpu=True,
-                        compile_mode='compile',
+                        gpu=False,
+                        compile_mode=compile_mode,
                         return_vertices=return_vertices,
                     )
                 )
+                if torch.cuda.is_available():
+                    backends.append(
+                        PyTorchBackend(
+                            model_name=model_name,
+                            gpu=True,
+                            compile_mode=compile_mode,
+                            return_vertices=return_vertices,
+                        )
+                    )
         except ImportError:
             pass
 
@@ -304,10 +305,15 @@ class PyTorchBackend(Backend):
             model = model.cuda()
         if compile_mode == 'compile':
             model = torch.compile(model)
+        elif compile_mode == 'script':
+            model = torch.jit.script(model)
         self.model = model
 
         suffix = ' GPU' if gpu else ' CPU'
-        self.name = ('PT compile' if compile_mode == 'compile' else 'PyTorch') + suffix
+        mode_name = {'compile': 'PT compile', 'script': 'PT script', None: 'PT eager'}[
+            compile_mode
+        ]
+        self.name = mode_name + suffix
 
     def prepare(self, pose, shape, trans):
         inputs = dict(

{smplfitter-0.3.2.dev0 → smplfitter-0.4.0}/docs/conf.py

@@ -139,17 +139,25 @@ python_display_short_literal_types = True
 
 
 def autodoc_skip_member(app, what, name, obj, skip, options):
-    """Skip members (functions, classes, modules) without docstrings."""
+    """Skip members without docstrings or from undocumented modules."""
     if not getattr(obj, 'docstring', None):
         return True
     elif what in ('class', 'function', 'attribute'):
-        # Check if the module of the class has a docstring
         module_name = '.'.join(name.split('.')[:-1])
         try:
-            module = importlib.import_module(module_name)
-            return not getattr(module, '__doc__', None)
+            mod = importlib.import_module(module_name)
+            if not getattr(mod, '__doc__', None):
+                return True  # Module has no docstring, skip its members
         except ModuleNotFoundError:
+            # Import failed (e.g. attribute path like Class.attr, or missing dep).
+            # Defer to AutoAPI default.
             return None
+        # For private names, defer to AutoAPI default (which skips them).
+        # For public names, force-include (overrides the imported-members default).
+        short_name = name.split('.')[-1]
+        if short_name.startswith('_') and not short_name.startswith('__'):
+            return None
+        return False
     return skip
 
 
@@ -157,14 +165,25 @@ def linkcode_resolve(domain, info):
     if domain != 'py':
         return None
 
+    fullname = info['fullname']
     try:
-        obj = eval(info['fullname'], module.__dict__)
-        file, start, end = get_line_numbers(obj)
-        relpath = os.path.relpath(file, os.path.dirname(module.__file__))
-        return f'{repo_url}/blob/v{release}/src/{main_module_name}/{relpath}#L{start}-L{end}'
-    except Exception:
+        file, start, end = get_line_numbers(eval(fullname))
+    except AttributeError:
+        # Instance attribute (dataclass field or self.x = ... in __init__)
+        parts = fullname.rsplit('.', 1)
+        if len(parts) != 2:
+            return None
+        try:
+            file, start, end = get_attr_line_numbers(eval(parts[0]), parts[1])
+        except Exception:
+            return None
+    except Exception as e:
+        print(f'linkcode_resolve failed: {info} — {e}')
         return None
 
+    relpath = os.path.relpath(file, os.path.dirname(module.__file__))
+    return f'{repo_url}/blob/v{release}/src/{main_module_name}/{relpath}#L{start}-L{end}'
+
 
 def get_line_numbers(obj):
     if isinstance(obj, property):
@@ -196,6 +215,22 @@ def get_enum_member_line_numbers(obj):
             raise ValueError(f'Enum member {obj.name} not found in {class_}')
 
 
+def get_attr_line_numbers(class_, attr_name):
+    with module_restored(class_):
+        source_lines, start_line = inspect.getsourcelines(class_)
+        for i, line in enumerate(source_lines):
+            stripped = line.strip()
+            if (
+                stripped.startswith(f'{attr_name}:')
+                or stripped.startswith(f'{attr_name} :')
+                or f'self.{attr_name} =' in stripped
+                or f'self.{attr_name}=' in stripped
+            ):
+                return inspect.getsourcefile(class_), start_line + i, start_line + i
+        else:
+            raise ValueError(f'Attribute {attr_name} not found in {class_}')
+
+
 def get_member_line_numbers(obj: types.MemberDescriptorType):
     class_ = obj.__objclass__
     with module_restored(class_):

{smplfitter-0.3.2.dev0 → smplfitter-0.4.0}/docs/howto.rst

@@ -20,23 +20,34 @@ https://smpl.is.tue.mpg.de/ first), then download SMPL, SMPL-X, SMPL+H, and
 MANO model files.
 
 By default, files are saved to the location given by the ``SMPLFITTER_BODY_MODELS``
-environment variable, or ``$DATA_ROOT/body_models``, or
-``~/.local/share/smplfitter/body_models``. You can also pass a path directly:
+environment variable, or ``$DATA_ROOT/body_models``, or the platform default data
+directory (e.g. ``~/.local/share/smplfitter/body_models`` on Linux).
+You can also pass a path directly:
 
 .. code-block:: bash
 
    python -m smplfitter.download /path/to/body_models
 
-To tell SMPLFitter where to find the models at runtime:
+At runtime, SMPLFitter checks the same locations automatically (in order):
+
+1. ``$SMPLFITTER_BODY_MODELS/``
+2. ``$DATA_ROOT/body_models/``
+3. ``./body_models/``
+4. The platform default data directory (via ``platformdirs``)
+
+If you downloaded to a custom location, set an environment variable or pass the path
+directly:
 
 .. code-block:: bash
 
-   # Option 1: package-specific variable (recommended)
+   # Option 1: package-specific variable
    export SMPLFITTER_BODY_MODELS=/path/to/body_models
 
    # Option 2: generic data root
    export DATA_ROOT=/path/to/data   # looks for $DATA_ROOT/body_models/
 
+.. code-block:: python
+
    # Option 3: pass directly in code
    body_model = BodyModel('smpl', 'neutral', model_root='/path/to/body_models/smpl')
 
@@ -309,26 +320,55 @@ The converter also supports:
 * ``known_output_shape_betas``: If shape is already known, only fit pose
 
 
-Use the Convenience Functions
------------------------------
+Rotate and Translate Body Parameters
+-------------------------------------
 
-For one-off fitting without manually creating model and fitter objects:
+Rotating a parametric body is nontrivial because the global orientation rotates around
+the pelvis joint, not the coordinate origin. Use
+:meth:`~smplfitter.pt.BodyModel.rototranslate` to apply a rotation and translation
+to body parameters correctly:
 
 .. code-block:: python
 
-   from smplfitter.pt import fit
+   import torch
+   from smplfitter.pt import BodyModel
 
-   result = fit(
-       verts=vertices,
-       joints=joints,
-       body_model_name='smpl',
-       gender='neutral',
-       num_betas=10,
-       num_iter=3,
+   body_model = BodyModel('smpl', 'neutral', num_betas=10).cuda()
+
+   # Apply a rotation R and translation t such that:
+   #   new_mesh = R @ old_mesh + t
+   R = torch.eye(3).cuda()       # (3, 3) rotation matrix
+   t = torch.zeros(3).cuda()     # (3,) translation vector
+
+   new_pose, new_trans = body_model.rototranslate(
+       R=R, t=t,
+       pose_rotvecs=pose,         # (num_joints * 3,)
+       shape_betas=betas,         # (num_betas,)
+       trans=trans,                # (3,)
    )
 
-For repeated fitting (e.g., in a training loop), use a cached and JIT-compiled
-fitter:
+Set ``post_translate=False`` to subtract ``t`` *before* rotation instead of adding it
+after (useful for camera-centric transformations).
+
+
+Cache Body Models
+-----------------
+
+If you create the same :class:`~smplfitter.pt.BodyModel` in multiple places (e.g.,
+in a training loop, across files, or when using both a fitter and a converter),
+use :func:`~smplfitter.pt.get_cached_body_model` to avoid loading the model files
+repeatedly:
+
+.. code-block:: python
+
+   from smplfitter.pt import get_cached_body_model
+
+   # First call loads from disk; subsequent calls return the cached instance
+   body_model = get_cached_body_model('smpl', 'neutral')
+
+The cached instance is shared, so do not modify it in place.
+
+For repeated fitting with a cached and JIT-compiled fitter:
 
 .. code-block:: python
 

{smplfitter-0.3.2.dev0 → smplfitter-0.4.0}/docs/index.rst

@@ -12,7 +12,9 @@ Example use cases:
 * You extracted nonparametric vertex and joint estimates from an RGB image, e.g. using `Neural Localizer Fields (NLF) <https://virtualhumans.mpi-inf.mpg.de/nlf>`_, and want to express this estimate in parametric form, for example to feed it to another model that expects body model parameters.
 * You want to convert between body models. For example, you have SMPL parameters from some dataset but need SMPL-X parameters as input to some pretrained model (or vice versa).
 
-We provide the implementation in **PyTorch, TensorFlow and NumPy**.
+We provide the implementation in **PyTorch, TensorFlow, NumPy, JAX, and Numba**.
+Import from the backend submodule you need: ``from smplfitter.pt import ...`` for PyTorch,
+``from smplfitter.np import ...`` for NumPy, etc.
 
 The algorithm is **fast**, optimized for **batch** processing, can run on the **GPU** and is **differentiable**. There are no learnable parameters here, nor sensitivity to initialization. Just solving equation systems.
 
@@ -29,7 +31,19 @@ Installation
 Download Body Model Files
 --------------------------
 
-You need to download the body model data files from the corresponding websites for this code to work. You only need the ones that you plan to use. There should be a ``DATA_ROOT`` environment variable under which a ``body_models`` directory should look like this:
+You need to download the body model data files from the corresponding websites for this code to work. You only need the ones that you plan to use.
+
+Set one of the following environment variables to tell SMPLFitter where to find them:
+
+.. code-block:: bash
+
+   # Option 1: package-specific variable (recommended)
+   export SMPLFITTER_BODY_MODELS=/path/to/body_models
+
+   # Option 2: generic data root
+   export DATA_ROOT=/path/to/data   # looks for $DATA_ROOT/body_models/
+
+The ``body_models`` directory should look like this:
 
 .. code-block:: text
 
@@ -69,15 +83,15 @@ Basic Fitting
    import torch
    from smplfitter.pt import BodyModel, BodyFitter
 
-   body_model = BodyModel('smpl', 'neutral').cuda()
-   fitter = BodyFitter(body_model, num_betas=10).cuda()
+   body_model = BodyModel('smpl', 'neutral', num_betas=10).cuda()
+   fitter = BodyFitter(body_model).cuda()
    fitter = torch.jit.script(fitter)
 
    batch_size = 30
    vertices = torch.rand((batch_size, 6890, 3)).cuda()
    joints = torch.rand((batch_size, 24, 3)).cuda()
 
-   fit_res = fitter.fit(vertices, joints, n_iter=3, beta_regularizer=1)
+   fit_res = fitter.fit(target_vertices=vertices, target_joints=joints, num_iter=3, beta_regularizer=1)
    fit_res['pose_rotvecs'], fit_res['shape_betas'], fit_res['trans']
 
 Body Model Conversion (Transfer)
@@ -86,7 +100,7 @@ Body Model Conversion (Transfer)
 .. code-block:: python
 
    import torch
-   from smplfitter.pt import BodyConverter
+   from smplfitter.pt import BodyModel, BodyConverter
 
    bm_in = BodyModel('smpl', 'neutral')
    bm_out = BodyModel('smplx', 'neutral')
@@ -123,6 +137,7 @@ This algorithm was developed for and described in the following paper:
    :caption: Contents
 
    howto
+   smpl_to_smplx
    API Reference <api/smplfitter/index>
 
 Indices and tables

smplfitter-0.4.0/docs/smpl_to_smplx.rst

@@ -0,0 +1,83 @@
+SMPL-to-SMPL-X Conversion Benchmark
+====================================
+
+:class:`~smplfitter.pt.BodyConverter` was benchmarked against the official
+`SMPL-X transfer tool <https://github.com/vchoutas/smplx/tree/main/transfer_model>`_
+on 33 sample meshes from the official SMPL-X repository (the same evaluation setup as
+Table 10 in the `NLF paper <https://arxiv.org/abs/2407.07532>`_).
+
+Error is measured as per-vertex Euclidean distance (mm) between the ground-truth SMPL-X
+mesh and the converted mesh.
+
+Official SMPL-X Converter
+-------------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 30 20
+
+   * - Iterations
+     - Time
+     - Error (mm)
+   * - 25
+     - 3 min 18 s
+     - 14.0
+   * - 50
+     - 16 min 35 s
+     - 6.2
+   * - 100
+     - 33 min
+     - 5.0
+
+SMPLFitter (PyTorch, GPU)
+-------------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 30 20
+
+   * - Iterations
+     - Time (33 meshes)
+     - Error (mm)
+   * - 1
+     - 43 ms
+     - 8.3
+   * - 2
+     - 75 ms
+     - 8.0
+   * - 3
+     - 110 ms
+     - 8.0
+   * - 5
+     - 190 ms
+     - 8.1
+
+SMPLFitter (TensorFlow, GPU)
+-----------------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 30 20
+
+   * - Iterations
+     - Time (33 meshes)
+     - Error (mm)
+   * - 1
+     - 25 ms
+     - 8.3
+   * - 2
+     - 35 ms
+     - 8.0
+   * - 3
+     - 50 ms
+     - 8.0
+   * - 5
+     - 78 ms
+     - 8.1
+
+Reproducing
+-----------
+
+.. code-block:: bash
+
+   python benchmark/bench_converter.py --backends pt tf

{smplfitter-0.3.2.dev0 → smplfitter-0.4.0}/pyproject.toml

@@ -8,7 +8,7 @@ dynamic = ["version"]
 description = "Fast inverse kinematics and shape fitting for SMPL-family models in NumPy, PyTorch, TensorFlow, JAX, and Numba"
 readme = "README.md"
 requires-python = ">=3.8"
-license = { file = "LICENSE" }
+license = "MIT"
 
 authors = [
     { name = "István Sárándi", email = "istvan.sarandi@uni-tuebingen.de" }
@@ -37,7 +37,6 @@ keywords = [
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Science/Research",
-    "License :: OSI Approved :: MIT License",
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.8",
@@ -55,6 +54,7 @@ dependencies = [
     "numpy",
     "scipy",
     "chumpy",
+    "platformdirs",
 ]
 
 [project.optional-dependencies]
@@ -62,6 +62,7 @@ tensorflow = ["tensorflow"]
 pytorch = ["torch"]
 jax = ["jax", "jaxlib"]
 numba = ["numba"]
+viz = ["moderngl", "glfw", "poseviz", "framepump", "torch", "deltacamera"]
 test = ["pytest>=7.0", "pytest-cov"]
 lint = ["ruff", "pre-commit"]
 docs = [
@@ -74,6 +75,11 @@ docs = [
     "pydata-sphinx-theme",
     "setuptools-scm",
     "toml",
+    "torch",
+    "tensorflow",
+    "jax",
+    "jaxlib",
+    "numba",
 ]
 dev = ["smplfitter[test,lint,docs,pytorch]"]
 

{smplfitter-0.3.2.dev0 → smplfitter-0.4.0}/src/smplfitter/__init__.py

@@ -10,11 +10,12 @@ Main submodules:
 
 from __future__ import annotations
 
-from .common import ModelData, initialize
+from .common import _set_module_for_docs
 
 try:
     from ._version import version as __version__
 except ImportError:
     __version__ = '0.0.0'
 
-__all__ = ['ModelData', 'initialize', '__version__']
+__all__ = ['__version__']
+_set_module_for_docs(__name__, globals(), __all__)

{smplfitter-0.3.2.dev0 → smplfitter-0.4.0}/src/smplfitter/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.3.2.dev0'
-__version_tuple__ = version_tuple = (0, 3, 2, 'dev0')
+__version__ = version = '0.4.0'
+__version_tuple__ = version_tuple = (0, 4, 0)
 
-__commit_id__ = commit_id = 'gbb6c267c5'
+__commit_id__ = commit_id = 'g2fe42baa8'