cgmath 1.0.3__tar.gz → 2.0.0__tar.gz

{cgmath-1.0.3/cgmath.egg-info → cgmath-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cgmath
-Version: 1.0.3
+Version: 2.0.0
 Summary: A DCC-agnostic CG math library: batched matrix, quaternion and euler math, mesh topology, deformers, resampling, skeletal hierarchies, SDFs, a software raytracer and asset IO, all numpy-native.
 Author-email: Eric Vignola <eric.vignola@gmail.com>
 License: ## License
@@ -52,12 +52,22 @@ License-File: LICENSE
 Requires-Dist: numpy
 Requires-Dist: scipy
 Requires-Dist: numba
-Requires-Dist: pillow
-Requires-Dist: opencv-python
-Requires-Dist: scikit-image
-Requires-Dist: pygltflib
-Requires-Dist: trimesh
-Requires-Dist: usd-core
+Provides-Extra: image
+Requires-Dist: pillow; extra == "image"
+Requires-Dist: opencv-python; extra == "image"
+Requires-Dist: scikit-image; extra == "image"
+Provides-Extra: gltf
+Requires-Dist: pygltflib; extra == "gltf"
+Requires-Dist: trimesh; extra == "gltf"
+Provides-Extra: usd
+Requires-Dist: usd-core; extra == "usd"
+Provides-Extra: all
+Requires-Dist: pillow; extra == "all"
+Requires-Dist: opencv-python; extra == "all"
+Requires-Dist: scikit-image; extra == "all"
+Requires-Dist: pygltflib; extra == "all"
+Requires-Dist: trimesh; extra == "all"
+Requires-Dist: usd-core; extra == "all"
 Dynamic: license-file
 
 # `cgmath` — a DCC-agnostic CG math library
@@ -123,8 +133,9 @@ for it) and a **CHEATSHEET** (every public name, with a runnable example).
 | `cgmath.constraints` | `ProcrustesData` — rivet a transform to a deforming patch | [README](https://github.com/Eric-Vignola/cgmath/blob/main/constraints/README.md) · [CHEATSHEET](https://github.com/Eric-Vignola/cgmath/blob/main/constraints/CHEATSHEET.md) |
 
 [`REFERENCE.md`](https://github.com/Eric-Vignola/cgmath/blob/main/REFERENCE.md), a flat API listing, also sits in this
-directory. It is generated from the live code by `gen_reference.py` (kept in
-the `tools/` folder beside the packages, not in this repository): every public
+directory. It is generated from the live code by `gen_reference.py` (kept
+outside this repository, in the maintainer's own tools folder; the
+repository's `tools/` holds only the Maya fixture generator): every public
 name with its real signature and first docstring line.
 
 ---
@@ -148,10 +159,8 @@ cgmath/
 │   ├── map.py morph_target.py skin_weights.py    MapData, MorphData, SkinData
 │   ├── bspline.py bspline_patch.py _saddle_surface.py _cdt.py
 │   ├── sdf.py             SDF primitives + dual marching cubes
-│   ├── pack.py resample.py surface_plotting.py
+│   ├── pack.py resample.py
 │   ├── robust_skinweights_transfer_bilinear.py
-│   ├── camera.py delta_mush.py ffd.py patch_relax.py raytracer.py texture.py
-│   │                      one-release deprecation shims -- they warn and re-export
 │   ├── deform/            FFDData, DeltaMushData, PatchRelaxData,
 │   │                      SkinDeformData, WrapData
 │   └── utils/             main.py + _numba/ -- the kernel floor
@@ -160,7 +169,10 @@ cgmath/
 ├── render/                scene.py raytracer.py camera.py frame.py texture.py
 ├── formats/               fbx.py, glb.py, usd/prim.py, usd/stage.py
 ├── rbf/                   _kernels.py + _numba/   (__init__.py is a docstring, on purpose)
-└── constraints/           procrustes.py
+├── constraints/           procrustes.py
+│
+└── _tests/                the test suite + test_assets/, the fixtures it reads;
+                           transforms/_tests/ holds the transforms suite
 ```
 
 The batched matrix / quaternion / euler / axis / vector functions that all
@@ -215,6 +227,13 @@ If you know Maya, nothing below will surprise you.
   face and a raycast miss.
 - **A mesh is a face-vertex stream**, `indices` + `counts` + `points`.
   Mixed triangles, quads and n-gons in one mesh are normal.
+- **Arrays have fixed dtypes.** Indices and counts are `int32`; points,
+  normals, offsets, weights and values are `float64`; masks are `bool`. A
+  value is converted when it is set or loaded.
+- **One saved form.** `.pkl`, `.npz` and `.json` hold the same tree and
+  load as the class they name. A file written by an older cgmath raises
+  `LegacyFileError` — details in
+  [`geometry/README.md`](https://github.com/Eric-Vignola/cgmath/blob/main/geometry/README.md#saving-and-loading).
 - **Camera is OpenGL**: `-Z` forward, `+Y` up, `+X` right. `look_at()`
   and `Frame.camera_matrix` are **column**-major (eye at `M[:3, 3]`)
   while node matrices are row-major (eye at `M[3, :3]`).
@@ -234,13 +253,15 @@ follows — full detail in its [README](https://github.com/Eric-Vignola/cgmath/b
 ### Optional dependencies
 
 Imported lazily behind `try / except ImportError`, so the package loads
-without them and only the paths that need them complain.
+without them and only the paths that need them complain. A plain
+`pip install cgmath` brings in none of them; the PyPI ones come as extras,
+see [Requirements](#requirements).
 
 | Dependency | Used for | Missing behaviour |
 |---|---|---|
 | `pygltflib` | GLB / glTF read | `RuntimeError("pygltflib is not installed")` at call time |
 | Autodesk FBX SDK — not on PyPI, a manual install | FBX read / write | imports fine, with one `UserWarning` naming the SDK and where to get it; every FBX call raises `RuntimeError` with that same message |
-| `pxr`, from `usd-core` — installed with the wheel | `cgmath.formats.usd` stage / prim helpers; `from_prim` / `to_prim` / `load_usd` in `geometry` | always present after `pip install`. Run off `sys.path` without it, `import cgmath.formats.usd.prim` itself raises `ImportError` and the `geometry` paths raise `ImportError` at call time (`geometry.utils.pxr()` is the accessor) |
+| `pxr`, from `usd-core` or the host DCC's own USD | `cgmath.formats.usd` stage / prim helpers; `from_prim` / `to_prim` / `load_usd` in `geometry` | `import cgmath.formats.usd.prim` itself raises `ImportError`, and the `geometry` paths raise `ImportError` at call time (`geometry.utils.pxr()` is the accessor) |
 | `trimesh` | `GlbData.mesh_list` | that attribute is `None` |
 | `PIL` (Pillow) | `Frame.image` / `.save` / `.wireframe` / `.encode_gif`, `to_image`, texture I/O | `RuntimeError("... install Pillow.")` at call time |
 | `cv2` | `imshow()` windows; UV rasterization in `geometry.mesh` | `imshow` raises `RuntimeError`; rasterization falls back to `skimage` |
@@ -263,7 +284,7 @@ Each block below builds on the `cube` from the top of this page.
 ```python
 print(cube.point_count, cube.face_count, cube.edge_count)  # 8 6 12
 print(cube.closed, cube.quads, round(cube.area, 4))        # True 6 6.0
-print(cube.get_border_vertices(flatten=True))              # [] -- closed
+print(cube.get_border_vertices(flatten=True))              # [] -- closed, an empty int32 array
 print(cube.e2v.shape, cube.ue2v.shape)                     # (12, 2) deduped vs (24, 2) raw
 ```
 
@@ -369,15 +390,44 @@ Start with [`CHEATSHEET.md`](https://github.com/Eric-Vignola/cgmath/blob/main/CH
 
 ## Requirements
 
-Numpy, Scipy and Numba python modules.
+Numpy, Scipy and Numba python modules, the only packages a plain
+`pip install cgmath` brings in.
+
+Everything else is optional, per feature (see the table above for how each
+degrades), and comes as a pip extra:
+
+    pip install "cgmath[image]"   Pillow, OpenCV, scikit-image: texture I/O,
+                                  rendered frames, UV rasterization
+    pip install "cgmath[gltf]"    pygltflib, trimesh: glTF / GLB read and write
+    pip install "cgmath[usd]"     usd-core (pxr): USD stage read and write
+    pip install "cgmath[all]"     all of the above
+
+Inside a DCC that ships its own USD (Maya, Houdini), leave `usd` out: a
+second `pxr` on `sys.path` conflicts with the one the host has loaded.
+
+The Autodesk FBX SDK (FBX read and write) is not on PyPI; install it by hand.
+
 
-Optional, per feature (see the table above for how each degrades):
+## Tests
+
+Both test suites ship in the wheel, `cgmath._tests` with the fixtures it
+reads and `cgmath.transforms._tests`, so an installed copy tests itself as a
+checkout does. `run_tests()` with no target runs both suites; a module, a
+class, one test or a filename glob narrows it, found in whichever suite
+holds it:
+
+```python
+from cgmath.utils import run_tests
+
+result = run_tests("test_exports", verbosity=0)   # one module of the transforms suite
+assert result.wasSuccessful()
+```
 
-    Pillow                  texture I/O and rendered frames
-    pygltflib, trimesh      glTF / GLB read and write
-    Autodesk FBX SDK        FBX read and write
-    pxr (USD)               USD stage read and write
-    scikit-image or OpenCV  UV rasterization
+From a shell, `python -m cgmath.utils` runs everything and exits 0 when it
+all passes. A test that needs an optional dependency the install lacks,
+such as the FBX SDK, `pxr`, Pillow or pygltflib, is skipped, so a plain
+`pip install cgmath` passes too, with more tests skipped than under
+`cgmath[all]`.
 
 
 ## Author

{cgmath-1.0.3 → cgmath-2.0.0}/README.md

@@ -61,8 +61,9 @@ for it) and a **CHEATSHEET** (every public name, with a runnable example).
 | `cgmath.constraints` | `ProcrustesData` — rivet a transform to a deforming patch | [README](https://github.com/Eric-Vignola/cgmath/blob/main/constraints/README.md) · [CHEATSHEET](https://github.com/Eric-Vignola/cgmath/blob/main/constraints/CHEATSHEET.md) |
 
 [`REFERENCE.md`](https://github.com/Eric-Vignola/cgmath/blob/main/REFERENCE.md), a flat API listing, also sits in this
-directory. It is generated from the live code by `gen_reference.py` (kept in
-the `tools/` folder beside the packages, not in this repository): every public
+directory. It is generated from the live code by `gen_reference.py` (kept
+outside this repository, in the maintainer's own tools folder; the
+repository's `tools/` holds only the Maya fixture generator): every public
 name with its real signature and first docstring line.
 
 ---
@@ -86,10 +87,8 @@ cgmath/
 │   ├── map.py morph_target.py skin_weights.py    MapData, MorphData, SkinData
 │   ├── bspline.py bspline_patch.py _saddle_surface.py _cdt.py
 │   ├── sdf.py             SDF primitives + dual marching cubes
-│   ├── pack.py resample.py surface_plotting.py
+│   ├── pack.py resample.py
 │   ├── robust_skinweights_transfer_bilinear.py
-│   ├── camera.py delta_mush.py ffd.py patch_relax.py raytracer.py texture.py
-│   │                      one-release deprecation shims -- they warn and re-export
 │   ├── deform/            FFDData, DeltaMushData, PatchRelaxData,
 │   │                      SkinDeformData, WrapData
 │   └── utils/             main.py + _numba/ -- the kernel floor
@@ -98,7 +97,10 @@ cgmath/
 ├── render/                scene.py raytracer.py camera.py frame.py texture.py
 ├── formats/               fbx.py, glb.py, usd/prim.py, usd/stage.py
 ├── rbf/                   _kernels.py + _numba/   (__init__.py is a docstring, on purpose)
-└── constraints/           procrustes.py
+├── constraints/           procrustes.py
+│
+└── _tests/                the test suite + test_assets/, the fixtures it reads;
+                           transforms/_tests/ holds the transforms suite
 ```
 
 The batched matrix / quaternion / euler / axis / vector functions that all
@@ -153,6 +155,13 @@ If you know Maya, nothing below will surprise you.
   face and a raycast miss.
 - **A mesh is a face-vertex stream**, `indices` + `counts` + `points`.
   Mixed triangles, quads and n-gons in one mesh are normal.
+- **Arrays have fixed dtypes.** Indices and counts are `int32`; points,
+  normals, offsets, weights and values are `float64`; masks are `bool`. A
+  value is converted when it is set or loaded.
+- **One saved form.** `.pkl`, `.npz` and `.json` hold the same tree and
+  load as the class they name. A file written by an older cgmath raises
+  `LegacyFileError` — details in
+  [`geometry/README.md`](https://github.com/Eric-Vignola/cgmath/blob/main/geometry/README.md#saving-and-loading).
 - **Camera is OpenGL**: `-Z` forward, `+Y` up, `+X` right. `look_at()`
   and `Frame.camera_matrix` are **column**-major (eye at `M[:3, 3]`)
   while node matrices are row-major (eye at `M[3, :3]`).
@@ -172,13 +181,15 @@ follows — full detail in its [README](https://github.com/Eric-Vignola/cgmath/b
 ### Optional dependencies
 
 Imported lazily behind `try / except ImportError`, so the package loads
-without them and only the paths that need them complain.
+without them and only the paths that need them complain. A plain
+`pip install cgmath` brings in none of them; the PyPI ones come as extras,
+see [Requirements](#requirements).
 
 | Dependency | Used for | Missing behaviour |
 |---|---|---|
 | `pygltflib` | GLB / glTF read | `RuntimeError("pygltflib is not installed")` at call time |
 | Autodesk FBX SDK — not on PyPI, a manual install | FBX read / write | imports fine, with one `UserWarning` naming the SDK and where to get it; every FBX call raises `RuntimeError` with that same message |
-| `pxr`, from `usd-core` — installed with the wheel | `cgmath.formats.usd` stage / prim helpers; `from_prim` / `to_prim` / `load_usd` in `geometry` | always present after `pip install`. Run off `sys.path` without it, `import cgmath.formats.usd.prim` itself raises `ImportError` and the `geometry` paths raise `ImportError` at call time (`geometry.utils.pxr()` is the accessor) |
+| `pxr`, from `usd-core` or the host DCC's own USD | `cgmath.formats.usd` stage / prim helpers; `from_prim` / `to_prim` / `load_usd` in `geometry` | `import cgmath.formats.usd.prim` itself raises `ImportError`, and the `geometry` paths raise `ImportError` at call time (`geometry.utils.pxr()` is the accessor) |
 | `trimesh` | `GlbData.mesh_list` | that attribute is `None` |
 | `PIL` (Pillow) | `Frame.image` / `.save` / `.wireframe` / `.encode_gif`, `to_image`, texture I/O | `RuntimeError("... install Pillow.")` at call time |
 | `cv2` | `imshow()` windows; UV rasterization in `geometry.mesh` | `imshow` raises `RuntimeError`; rasterization falls back to `skimage` |
@@ -201,7 +212,7 @@ Each block below builds on the `cube` from the top of this page.
 ```python
 print(cube.point_count, cube.face_count, cube.edge_count)  # 8 6 12
 print(cube.closed, cube.quads, round(cube.area, 4))        # True 6 6.0
-print(cube.get_border_vertices(flatten=True))              # [] -- closed
+print(cube.get_border_vertices(flatten=True))              # [] -- closed, an empty int32 array
 print(cube.e2v.shape, cube.ue2v.shape)                     # (12, 2) deduped vs (24, 2) raw
 ```
 
@@ -307,15 +318,44 @@ Start with [`CHEATSHEET.md`](https://github.com/Eric-Vignola/cgmath/blob/main/CH
 
 ## Requirements
 
-Numpy, Scipy and Numba python modules.
+Numpy, Scipy and Numba python modules, the only packages a plain
+`pip install cgmath` brings in.
+
+Everything else is optional, per feature (see the table above for how each
+degrades), and comes as a pip extra:
+
+    pip install "cgmath[image]"   Pillow, OpenCV, scikit-image: texture I/O,
+                                  rendered frames, UV rasterization
+    pip install "cgmath[gltf]"    pygltflib, trimesh: glTF / GLB read and write
+    pip install "cgmath[usd]"     usd-core (pxr): USD stage read and write
+    pip install "cgmath[all]"     all of the above
+
+Inside a DCC that ships its own USD (Maya, Houdini), leave `usd` out: a
+second `pxr` on `sys.path` conflicts with the one the host has loaded.
+
+The Autodesk FBX SDK (FBX read and write) is not on PyPI; install it by hand.
+
 
-Optional, per feature (see the table above for how each degrades):
+## Tests
+
+Both test suites ship in the wheel, `cgmath._tests` with the fixtures it
+reads and `cgmath.transforms._tests`, so an installed copy tests itself as a
+checkout does. `run_tests()` with no target runs both suites; a module, a
+class, one test or a filename glob narrows it, found in whichever suite
+holds it:
+
+```python
+from cgmath.utils import run_tests
+
+result = run_tests("test_exports", verbosity=0)   # one module of the transforms suite
+assert result.wasSuccessful()
+```
 
-    Pillow                  texture I/O and rendered frames
-    pygltflib, trimesh      glTF / GLB read and write
-    Autodesk FBX SDK        FBX read and write
-    pxr (USD)               USD stage read and write
-    scikit-image or OpenCV  UV rasterization
+From a shell, `python -m cgmath.utils` runs everything and exits 0 when it
+all passes. A test that needs an optional dependency the install lacks,
+such as the FBX SDK, `pxr`, Pillow or pygltflib, is skipped, so a plain
+`pip install cgmath` passes too, with more tests skipped than under
+`cgmath[all]`.
 
 
 ## Author

{cgmath-1.0.3 → cgmath-2.0.0}/__init__.py

@@ -4,4 +4,4 @@ The underlying matrix, quaternion, euler and vector math lives in
 :mod:`cgmath.transforms`.
 """
 
-__version__ = "1.0.3"
+__version__ = "2.0.0"

cgmath-2.0.0/_tests/__init__.py

@@ -0,0 +1 @@
+"""Unit tests for the :mod:`cgmath` package."""

cgmath-2.0.0/_tests/_examples_curves.py

@@ -0,0 +1,198 @@
+"""
+Round-trip builders for the curve and surface data: BSplineData and its
+sample, BSplinePatchData and its sample and raycast, the saddle surface's
+sample and raycast, and ProcrustesData.
+
+Each builder makes a new object the way users do, through the public
+constructors, fit, sample and raycast, with every saved field away from its
+default where that is valid. ``test_roundtrip`` saves and loads each one.
+None of these classes has a name or nested data. Their arrays share one
+length, so an empty one leaves them all empty: ``test_curves_empty`` round
+trips those.
+"""
+
+import numpy as np
+from cgmath.constraints.procrustes import ProcrustesData
+from cgmath.geometry._saddle_surface import RaycastData as SaddleRaycastData
+from cgmath.geometry._saddle_surface import SampleData as SaddleSampleData
+from cgmath.geometry.bspline import BSplineData
+from cgmath.geometry.bspline import SampleData as CurveSampleData
+from cgmath.geometry.bspline_patch import (
+    BSplinePatchData,
+    PatchRaycastData,
+    PatchSampleData,
+)
+from cgmath.geometry.mesh import MeshData
+
+# ---------------------------------- SHAPES ---------------------------------- #
+
+
+def arm(n=6):
+    """the joint positions of a bending arm chain"""
+    t = np.linspace(0.0, 1.0, n)
+    return np.column_stack([t * 10.0, np.sin(t * 3.0) * 2.0, np.cos(t * 2.0)])
+
+
+def ring(n=8):
+    """a closed loop of n points, an ellipse that rises and falls twice"""
+    a = np.linspace(0.0, 2.0 * np.pi, n, endpoint=False)
+    return np.column_stack([np.cos(a) * 4.0, np.sin(a) * 2.5, np.sin(a * 2.0) * 0.5])
+
+
+def tube(nu=6, nv=5):
+    """the control grid of a tube: u closes around it, v runs along it"""
+    a      = np.linspace(0.0, 2.0 * np.pi, nu, endpoint=False)[:, None]
+    height = np.linspace(0.0, 6.0, nv)[None, :]
+    radius = 2.0 + 0.3 * np.sin(height)
+    return np.stack(
+        np.broadcast_arrays(np.cos(a) * radius, np.sin(a) * radius, height), axis=-1
+    )
+
+
+def sheet(nu=5, nv=6):
+    """the control grid of a wavy sheet in the xy plane, facing +z"""
+    u, v = np.meshgrid(np.linspace(-4, 4, nu), np.linspace(-5, 5, nv), indexing="ij")
+    return np.stack([u, v, np.sin(u * 0.5) * np.cos(v * 0.5)], axis=-1)
+
+
+def strip():
+    """a mesh of one quad and two triangles, facing +z"""
+    points = np.array(
+        [
+            [0.0, 0.0, 0.0],
+            [1.0, 0.0, 0.0],
+            [2.0, 0.0, 0.2],
+            [0.0, 1.0, 0.0],
+            [1.0, 1.0, 0.0],
+            [2.0, 1.0, 0.2],
+        ]
+    )
+    return MeshData(
+        points  = points,
+        indices = np.array([0, 1, 4, 3, 1, 2, 5, 1, 5, 4]),
+        counts  = np.array([4, 3, 3]),
+    )
+
+
+# --------------------------------- BUILDERS --------------------------------- #
+
+
+def curve() -> BSplineData:
+    """a closed quadratic through a ring of edit points, every setting changed"""
+    return BSplineData.from_edit_points(
+        ring(),
+        degree             = 2,
+        periodic           = True,
+        uniform            = True,
+        registered         = True,
+        use_numba          = False,
+        arc_length_samples = 257,
+    )
+
+
+def curve_sample() -> CurveSampleData:
+    """points beside a spine with stacked ends and Maya's knots, projected onto it"""
+    spine = BSplineData.from_edit_points(arm(), collapse=(2, 2))
+    offsets = np.array(
+        [
+            [0.0, 0.5, 0.0],
+            [0.2, -0.4, 0.3],
+            [0.0, 0.0, -0.6],
+            [-0.3, 0.2, 0.1],
+            [0.4, 0.4, 0.4],  # past the stacked end, where there is no tangent
+        ]
+    )
+    return spine.sample(arm(5) + offsets)
+
+
+def patch() -> BSplinePatchData:
+    """a tube closed in u, open in v, every setting changed"""
+    return BSplinePatchData(
+        points             = tube(),
+        degree_u           = 2,
+        degree_v           = 3,
+        periodic_u         = True,
+        periodic_v         = False,
+        uniform_u          = True,
+        uniform_v          = True,
+        use_numba          = False,
+        registered_u       = True,
+        registered_v       = True,
+        arc_length_samples = 300,
+    )
+
+
+def patch_sample() -> PatchSampleData:
+    """points inside and outside a tube, projected onto it"""
+    surface = BSplinePatchData(
+        points=tube(), degree_u=2, degree_v=3, periodic_u=True, periodic_v=False
+    )
+    queries = np.array(
+        [[3.0, 0.0, 1.0], [0.0, 1.0, 2.5], [-2.5, -2.5, 4.0], [0.5, -3.0, 5.5]]
+    )
+    return surface.sample(queries)
+
+
+def patch_raycast() -> PatchRaycastData:
+    """rays down onto a sheet, one up into it from below, and one that misses (NaN)"""
+    surface = BSplinePatchData(
+        points=sheet(), degree_u=3, degree_v=3, periodic_u=False, periodic_v=False
+    )
+    origins = np.array(
+        [[0.0, 0.0, 5.0], [1.0, -2.0, 5.0], [-1.0, 1.0, -5.0], [40.0, 40.0, 5.0]]
+    )
+    directions = np.array(
+        [[0.0, 0.0, -1.0], [0.0, 0.0, -1.0], [0.0, 0.0, 1.0], [0.0, 0.0, -1.0]]
+    )
+    return surface.raycast(origins, directions, forward_only=False)
+
+
+def saddle_sample() -> SaddleSampleData:
+    """points above, below and on a quad-and-triangles mesh, sampled on it"""
+    queries = np.array(
+        [
+            [0.5, 0.5, 0.5],  # above the quad
+            [0.3, 0.6, -0.4],  # below it: occluded
+            [1.6, 0.4, 0.3],  # above a triangle: its geometry is -1 padded
+            [2.0, 1.0, 0.2],  # on a vertex: matched exactly
+        ]
+    )
+    return strip().sample(queries)
+
+
+def saddle_raycast() -> SaddleRaycastData:
+    """a ray down onto a quad, one up into a triangle, and one that misses (NaN, -1)"""
+    origins    = np.array([[0.5, 0.5, 2.0], [1.7, 0.5, -2.0], [9.0, 9.0, 2.0]])
+    directions = np.array([[0.0, 0.0, -1.0], [0.0, 0.0, 1.0], [0.0, 0.0, -1.0]])
+    return strip().raycast(origins, directions, forward_only=False)
+
+
+def procrustes() -> ProcrustesData:
+    """a cube held by two clusters, one of half its points, no scale offset"""
+    cube = np.array(
+        [[x, y, z] for z in (0.5, -0.5) for y in (-0.5, 0.5) for x in (-0.5, 0.5)]
+    )
+    lid        = np.eye(4)
+    lid[3, :3] = [0.0, 0.5, 0.0]
+
+    constraint = ProcrustesData(cube)
+    constraint.attach(lid, [2, 3, 4, 5])  # the shorter cluster is -1 padded
+    constraint.attach(np.eye(4))
+    constraint.scale_offset = False
+
+    moved = cube * 1.2
+    moved[:2, 2] += 0.3
+    constraint.update(moved)  # the per-frame target and results are not saved
+    return constraint
+
+
+EXAMPLES = {
+    BSplineData:       curve,
+    CurveSampleData:   curve_sample,
+    BSplinePatchData:  patch,
+    PatchSampleData:   patch_sample,
+    PatchRaycastData:  patch_raycast,
+    SaddleSampleData:  saddle_sample,
+    SaddleRaycastData: saddle_raycast,
+    ProcrustesData:    procrustes,
+}

cgmath-2.0.0/_tests/_examples_deform.py

@@ -0,0 +1,171 @@
+"""Filled-in deformers, for test_roundtrip.
+
+Each builder makes a deformer the way a user does -- from a mesh, a skin, a
+rig or a lattice -- changes every setting from its default and binds it, so
+every saved field holds a value of its own. The meshes are small: a few dozen
+points.
+"""
+
+import numpy as np
+from cgmath.geometry.deform import (
+    DeltaMushData,
+    FFDData,
+    PatchRelaxData,
+    SkinDeformData,
+    WrapData,
+)
+from cgmath.geometry.mesh import MeshData
+from cgmath.geometry.skin_weights import SkinData
+from cgmath.hierarchy import HierarchyData, TransformData
+
+
+def _grid(n: int = 6, height: float = 0.3, name: str = "grid") -> MeshData:
+    """an open quad grid on XY with a sine bump in Z: it has a border"""
+    t            = np.linspace(0.0, 1.0, n)
+    points       = np.array([[x, y, 0.0] for y in t for x in t])
+    points[:, 2] = height * np.sin(np.pi * points[:, 0]) * np.sin(np.pi * points[:, 1])
+
+    indices = []
+    for j in range(n - 1):
+        for i in range(n - 1):
+            a = j * n + i
+            indices.extend([a, a + 1, a + n + 1, a + n])
+
+    return MeshData(
+        points  = points,
+        indices = np.asarray(indices, dtype=np.int32),
+        counts  = np.full((n - 1) ** 2, 4, dtype=np.int32),
+        name    = name,
+    )
+
+
+def _torus(around: int = 8, across: int = 6, name: str = "torus") -> MeshData:
+    """a closed quad torus: it has no border"""
+    u = np.linspace(0.0, 2.0 * np.pi, around, endpoint=False)
+    v = np.linspace(0.0, 2.0 * np.pi, across, endpoint=False)
+    uu, vv = np.meshgrid(u, v, indexing="ij")
+    ring = 1.0 + 0.35 * np.cos(vv)
+    points = np.stack(
+        [ring * np.cos(uu), ring * np.sin(uu), 0.35 * np.sin(vv)], axis=-1
+    ).reshape(-1, 3)
+
+    indices = []
+    for i in range(around):
+        for j in range(across):
+            k, l = (i + 1) % around, (j + 1) % across
+            indices.extend(
+                [i * across + j, k * across + j, k * across + l, i * across + l]
+            )
+
+    return MeshData(
+        points  = points,
+        indices = np.asarray(indices, dtype=np.int32),
+        counts  = np.full(around * across, 4, dtype=np.int32),
+        name    = name,
+    )
+
+
+def delta_mush() -> DeltaMushData:
+    """bound with DDM on an open mesh; pinning turned off after the border was read"""
+    mush = DeltaMushData(
+        _grid(),
+        smooth_iterations = 6,
+        smooth_step_size  = 0.4,
+        weight            = 0.7,
+        method            = "ddm",
+    )
+    # the border read at construction stays saved, pinned or not
+    mush.pin_borders = False
+    mush.bind()
+    return mush
+
+
+def patch_relax() -> PatchRelaxData:
+    """bound on a closed mesh, so its border is an empty array, with a painted mask"""
+    mesh = _torus()
+    relaxer = PatchRelaxData(
+        mesh,
+        iterations    = 12,
+        alpha         = 0.8,
+        surface_blend = 0.3,
+        step_size     = 0.4,
+        pin_borders   = False,
+        mask          = np.linspace(0.0, 1.0, len(mesh.points)),
+    )
+    relaxer.bind()
+    return relaxer
+
+
+def ffd() -> FFDData:
+    """a lattice over part of a mesh, bound, with falloff past its edge"""
+    lattice = FFDData.create_lattice(
+        (3, 4, 3), bbox_min=[-0.1, -0.1, -0.5], bbox_max=[0.7, 1.1, 0.5], name="ffd_box"
+    )
+    ffd                 = FFDData.from_mesh(lattice, divisions=(3, 4, 3))
+    ffd.local_influence = (3, 4, 2)
+    ffd.outside         = "falloff"
+    ffd.falloff_radius  = 1.5
+
+    # the grid runs to x = 1, past the lattice: those points fall off
+    ffd.bind(_grid())
+
+    deformed = ffd.lattice.copy()
+    deformed[:, :, -1, 2] += 0.4
+    ffd.update(deformed)
+    return ffd
+
+
+def skin_deform() -> SkinDeformData:
+    """dual quaternion, bound, its matrices from a bind rig, joints reordered"""
+    root  = TransformData(name="A:root", translate=(0.0, 0.0, 0.0))
+    spine = TransformData(name="A:spine", translate=(0.5, 0.0, 0.0))
+    tip   = TransformData(name="A:tip", translate=(0.5, 0.0, 0.0), rotate=(0.0, 0.0, 15.0))
+    rig   = HierarchyData([root, spine, tip])
+
+    spine.parent_uuid = root.uuid
+    tip.parent_uuid   = spine.uuid
+
+    mesh = _grid(name="A:body")
+    x    = mesh.points[:, 0]
+    # at most two influences per vertex: root fades into spine, spine into tip
+    weights = np.zeros((len(x), 3))
+    low, high = x <= 0.5, x > 0.5
+    weights[low, 0]  = 1.0 - 2.0 * x[low]
+    weights[low, 1]  = 2.0 * x[low]
+    weights[high, 1] = 2.0 - 2.0 * x[high]
+    weights[high, 2] = 2.0 * x[high] - 1.0
+    skin             = SkinData(weights=weights, influences=["A:root", "A:spine", "A:tip"], name="A:skin")
+
+    deformer = SkinDeformData(
+        mesh,
+        skin,
+        bind_rig = rig,
+        joints   = ["A:tip", "A:root", "A:spine"],
+        method   = "dqs",
+        name     = "A:body_skin",
+    )
+    deformer.bind()
+    return deformer
+
+
+def wrap() -> WrapData:
+    """a geodesic cage wrap with a compact kernel, solved, so its pseudo-inverse is saved"""
+    cage  = _grid(4, height=0.4, name="cage")
+    moved = cage.points + np.random.default_rng(5).normal(scale=0.05, size=cage.points.shape)
+
+    wrap  = WrapData(kernel="wendland_c2", name="cage_wrap")
+    wrap.set_source(cage)
+    wrap.set_target(moved)
+    wrap.set_radius(0.9)
+    wrap.set_geodesic_radius(1.0)
+    wrap.deform(_grid().points)
+    return wrap
+
+
+EXAMPLES = {
+    DeltaMushData:  delta_mush,
+    FFDData:        ffd,
+    PatchRelaxData: patch_relax,
+    SkinDeformData: skin_deform,
+    WrapData:       wrap,
+}