sstsr 2.0.0__py3-none-any.whl

sstsr-2.0.0.dist-info/METADATA

@@ -0,0 +1,318 @@
+Metadata-Version: 2.5
+Name: sstsr
+Version: 2.0.0
+Summary: Task Space Regions for grasp and placement planning (import as `tsr`)
+Project-URL: Homepage, https://github.com/personalrobotics/tsr
+Project-URL: Repository, https://github.com/personalrobotics/tsr
+Project-URL: Issues, https://github.com/personalrobotics/tsr/issues
+Author-email: Siddhartha Srinivasa <siddhartha.srinivasa@gmail.com>
+Maintainer-email: Siddhartha Srinivasa <siddhartha.srinivasa@gmail.com>
+License-Expression: BSD-2-Clause
+License-File: LICENSE
+Keywords: motion-planning,robotics,task-space-regions,tsr
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: scipy>=1.10.0
+Provides-Extra: test
+Requires-Dist: build>=1.0.0; extra == 'test'
+Requires-Dist: hypothesis>=6.112; extra == 'test'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
+Requires-Dist: pytest>=7.0.0; extra == 'test'
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.8.0; extra == 'viz'
+Requires-Dist: pillow>=10.3.0; extra == 'viz'
+Requires-Dist: pyvista>=0.43.0; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# Task Space Regions (TSR)
+
+A Python library for pose-constrained manipulation planning using Task Space Regions.
+
+TSRs encode *any* manipulation constraint as a bounded region in SE(3): grasping,
+placing, transporting, pouring, tool use, and more. A planner samples from a TSR
+to get valid end-effector poses satisfying the constraint.
+
+Based on the IJRR paper ["Task Space Regions: A Framework for Pose-Constrained Manipulation Planning"](https://www.ri.cmu.edu/pub_files/2011/10/dmitry_ijrr10-1.pdf) by Berenson, Srinivasa, and Kuffner.
+
+## Gallery
+
+### Grasps
+
+![TSR Grasp Templates](assets/tsr_grasps.png)
+
+### Stable placements
+
+![Stable Placements — primitives](assets/stable_placements.png)
+
+*Cylinder, box, sphere, and torus in every stable pose on a table surface.*
+
+![Stable Placements — non-convex meshes](assets/mesh_placements.png)
+
+*L-shape, T-shape, and a mug (cylinder + handle) — `place_mesh` applied to arbitrary vertex clouds. Each object is shown in all stable orientations above the 5° margin threshold.*
+
+## Installation
+
+The distribution is named **`sstsr`** on PyPI; the import name is `tsr`.
+
+```bash
+pip install sstsr      # or: uv add sstsr
+```
+```python
+import tsr             # the import name is unchanged
+```
+
+For visualization support:
+```bash
+pip install "sstsr[viz]"     # or: uv add "sstsr[viz]"
+```
+
+For development:
+```bash
+git clone https://github.com/personalrobotics/tsr.git
+cd tsr
+uv sync --extra test
+```
+
+## Quick Start
+
+### Load templates for a full manipulation task
+
+Templates are YAML files that encode pose constraints for each step of a task.
+The library ships with two narratives:
+
+```python
+from tsr import load_package_template
+import numpy as np
+
+# --- Tool use: screwdriver ---
+grasp = load_package_template("grasps", "screwdriver_grasp.yaml")
+drive = load_package_template("tasks",  "drive_screw.yaml")
+drop  = load_package_template("places", "toolchest_drop.yaml")
+
+screwdriver_pose = np.eye(4)
+screwdriver_pose[:3, 3] = [0.4, 0.1, 0.02]
+
+gripper_poses = grasp.sample(screwdriver_pose)
+
+# --- Everyday manipulation: mug of water ---
+pick      = load_package_template("grasps", "mug_handle_grasp.yaml")
+carry     = load_package_template("tasks",  "mug_transport_upright.yaml")
+pour      = load_package_template("tasks",  "mug_pour_into_sink.yaml")
+place     = load_package_template("places", "mug_on_table.yaml")
+```
+
+### Generate templates from object geometry
+
+#### Grasping
+
+`ParallelJawGripper` generates TSR templates directly from shape parameters.
+Pre-configured subclasses are provided for common grippers:
+
+| Class | `finger_length` | `max_aperture` | Notes |
+|---|---|---|---|
+| `Robotiq2F140` | 55 mm | 140 mm | Robotiq 2F-140 parallel gripper |
+| `FrankaHand` | 44.5 mm | 80 mm | Franka Emika Panda hand |
+
+```python
+import numpy as np
+from tsr.hands import ParallelJawGripper, Robotiq2F140, FrankaHand
+
+# Use a pre-configured gripper for a known hardware platform
+gripper = Robotiq2F140()
+gripper = FrankaHand()
+
+# Or configure manually for custom hardware
+gripper = ParallelJawGripper(finger_length=0.055, max_aperture=0.140)
+
+# Cylinder — side + top + bottom: 4*k templates (default k=3: 12 total)
+templates = gripper.grasp_cylinder(
+    cylinder_radius=0.040,   # 4 cm radius
+    cylinder_height=0.120,   # 12 cm tall
+    reference="mug",
+)
+
+# Box — all six faces, two finger orientations per face: up to 2*6*k templates
+templates = gripper.grasp_box(box_x=0.08, box_y=0.06, box_z=0.18, reference="box")
+
+# Sphere — full SO(3) approach: k templates
+templates = gripper.grasp_sphere(object_radius=0.040, reference="ball")
+
+# Torus — side (all minor angles) + span (if aperture allows)
+templates = gripper.grasp_torus(
+    torus_radius=0.035,   # major radius R: center to tube center
+    tube_radius=0.015,    # minor radius r: tube cross-section
+    reference="handle",
+)
+
+# Instantiate at a specific object pose and sample
+mug_pose = np.eye(4)
+mug_pose[:3, 3] = [0.5, 0.0, 0.0]   # mug at x=0.5m
+
+grasp_poses = [t.sample(mug_pose) for t in templates]
+```
+
+#### Placing
+
+`StablePlacer` generates one TSR template per stable resting pose on a flat surface:
+
+```python
+import numpy as np
+from tsr.placement import StablePlacer
+
+placer = StablePlacer(table_x=0.60, table_y=0.40)
+
+# Analytic primitives
+templates = placer.place_cylinder(cylinder_radius=0.040, cylinder_height=0.120, subject="mug")
+templates = placer.place_box(lx=0.08, ly=0.06, lz=0.18, subject="box")   # up to 3 poses
+templates = placer.place_sphere(radius=0.040, subject="ball")
+templates = placer.place_torus(major_radius=0.035, minor_radius=0.015, subject="ring")
+
+# Arbitrary mesh — pass any (N, 3) vertex cloud + centre of mass
+vertices = np.array([...])   # (N, 3) points
+com      = np.array([cx, cy, cz])
+templates = placer.place_mesh(vertices, com, subject="widget",
+                              min_margin_deg=5.0)  # discard marginal poses
+
+# Each template encodes one stable orientation; sample a table pose for it
+table_pose = np.eye(4)
+table_pose[2, 3] = 0.75   # table surface at z = 0.75 m
+
+for t in templates:
+    pose = t.sample(table_pose)
+    print(t, "→ COM z =", pose[2, 3])
+```
+
+Stability is determined by the COM-projection criterion: a face is stable if the
+centre of mass projects inside the support polygon formed by that face's contact
+region. The stability margin is `arctan(d_min / h_com)` where `d_min` is the
+minimum distance from the COM projection to any edge of the polygon.
+
+### Work directly with TSRs
+
+```python
+from tsr import TSR
+import numpy as np
+
+# A TSR is defined by three components:
+#   T0_w : 4×4 transform — world frame to TSR frame
+#   Tw_e : 4×4 transform — TSR frame to end-effector at Bw=0
+#   Bw   : 6×2 bounds — [x, y, z, roll, pitch, yaw]
+
+# Example: keep a mug upright — free xy/yaw, small pitch/roll
+T0_w = np.eye(4)
+Tw_e = np.eye(4)
+Bw   = np.zeros((6, 2))
+Bw[0, :] = [-2.0,  2.0]       # x: anywhere in workspace
+Bw[1, :] = [-2.0,  2.0]       # y: anywhere in workspace
+Bw[2, :] = [ 0.5,  1.5]       # z: transport height
+Bw[3, :] = [-0.26, 0.26]      # roll:  ±15°
+Bw[4, :] = [-0.26, 0.26]      # pitch: ±15°
+Bw[5, :] = [-np.pi, np.pi]    # yaw: free
+
+tsr = TSR(T0_w=T0_w, Tw_e=Tw_e, Bw=Bw)
+
+pose     = tsr.sample()             # random SE(3) pose in the region
+distance, _ = tsr.distance(pose)   # distance to nearest valid pose
+is_valid = tsr.contains(pose)      # containment check
+```
+
+### Save and load templates
+
+```python
+from tsr import TSRTemplate, save_template, load_template
+import numpy as np
+
+template = TSRTemplate(
+    T_ref_tsr=np.eye(4),
+    Tw_e=Tw_e,
+    Bw=Bw,
+    task="transport",
+    subject="mug",
+    reference="world",
+    name="Mug Transport Upright",
+    description="Keep mug upright during transport, ±15° tilt tolerance",
+)
+
+save_template(template, "my_template.yaml")
+template = load_template("my_template.yaml")
+
+# Bind to an object pose at runtime
+tsr = template.instantiate(np.eye(4))
+```
+
+## End-effector frame convention
+
+All templates in this library use a canonical end-effector frame:
+
+```
+z = approach direction  (toward contact surface)
+y = opening / spread direction  (finger opening for grippers, tool axis for others)
+x = right-hand normal   (x = y × z)
+```
+
+AnyGrasp / GraspNet uses `x = approach` — convert with:
+```python
+R_convert = np.array([[0, 0, -1], [0, 1, 0], [1, 0, 0]])
+```
+
+## TSR Chains
+
+For coupled multi-body constraints (e.g., door opening, bimanual transport):
+
+```python
+from tsr import TSRChain
+
+chain = TSRChain(TSRs=[hinge_tsr, handle_tsr])
+pose  = chain.sample()
+```
+
+## Visualization
+
+```python
+from tsr.viz import TSRVisualizer, cylinder_renderer, parallel_jaw_renderer, plasma_colors
+
+poses  = [t.sample(mug_pose) for t in templates]
+colors = plasma_colors(len(templates))
+
+TSRVisualizer(
+    title="Cylinder Grasp Templates",
+    focus=(0., 0., 0.06),
+).render(
+    reference_renderer=cylinder_renderer(radius=0.04, height=0.12),
+    subject_renderer=parallel_jaw_renderer(finger_length=0.055, half_aperture=0.07),
+    poses=poses,
+    colors=colors,
+    out="grasp_viz.png",
+)
+```
+
+Requires the `viz` extra: `uv sync --extra viz`.
+
+## Documentation
+
+- **[Tutorial](docs/tutorial.md)** — TSR theory, math, and worked examples
+- **[Examples](examples/)** — Runnable scripts (`uv run python examples/<script>.py`)
+
+## Testing
+
+```bash
+uv run pytest tests/ -v
+```
+
+## License
+
+BSD-2-Clause — see LICENSE file.

sstsr-2.0.0.dist-info/RECORD

@@ -0,0 +1,31 @@
+tsr/__init__.py,sha256=DyDsghINgL32BvUXfpL4ha5REqDv2m65d6Vot5q4tao,3123
+tsr/io.py,sha256=Idz-WTx9S6vHgDhDtKfxPQ-zKX1aS32zaXIgOpxbYlE,3641
+tsr/sampling.py,sha256=OAd4HuHXB2K0oBCfPlgWAefVtSBNmR_BLVYluFattI4,9330
+tsr/template.py,sha256=6AGX4_VTq_Kx3dtSPoSgQV5DAiLSUCyGdFIb3JeEx5c,5491
+tsr/tsr.py,sha256=shVgAeoVZOjhYSG0ni8BvHTMl1fwW7ZjbfP6nUeeYCc,370
+tsr/tsr_chain.py,sha256=a8XR1-MB7uQHTo1NFj5X6C-fGxxZq4nJAPdOzrKVDuY,392
+tsr/utils.py,sha256=jYBOmGBG8SJlM9DNDz8H5tVhrCOdSgJ_pAXMKAaGnyA,546
+tsr/viz.py,sha256=fnQ71qFDE8DSXPhoMOzAagyQzxWDMxhMRmHQDrIqoMs,23026
+tsr/core/__init__.py,sha256=diN8q5DK-IXMaHd-ujTZ-g6NluvCNikR6QuVJ0-WHu0,952
+tsr/core/tsr.py,sha256=b_aXQlhmdEVvN9ZJF2g6soCDWE2G1gf2FdBcrksDNdk,21775
+tsr/core/tsr_chain.py,sha256=aZYAIZWyFr9Q2hVtBzqldDj_mZJS6vcfodwwdrOKBDA,8655
+tsr/core/utils.py,sha256=eTePgeaCP31A_gN1G54xhFfluv7K8jLhORHb5NkB1x0,3467
+tsr/hands/__init__.py,sha256=4Tu3eae6Y8pGyVQ_Jcgqq55UDJNAA4L2dnNqCWY8JFY,891
+tsr/hands/base.py,sha256=pYJBruv2NB1lq4blfO07BvLygwKP046ILErkhG-2WWM,25992
+tsr/hands/parallel_jaw.py,sha256=mvwewuVHHucqCh5uoI_s5m-xsWWO6FBU_JXHjm2BXzE,48753
+tsr/hands/registry.py,sha256=W_NW5oH3lIEZ--uB8OrFH6-e08qsTxUVmbwqTVTumec,3881
+tsr/placement/__init__.py,sha256=Hyg0YXIACgIAp9oXKunKpJodNt_97WEi8HMXhKGjjjo,579
+tsr/placement/_stable_poses.py,sha256=nchSC2FygISBKyCd2T7066DLi6vr1Cd9-ykT9vgJIi0,6471
+tsr/placement/stable_placer.py,sha256=Xpg_9jVehcj7gXiF6ddaldB99m6YxurRHq0m4Yo02zI,11682
+tsr/templates/README.md,sha256=6g96Okg29hed0tZBsYx3C0gnsQhVG3lutelmvKFLLp0,2059
+tsr/templates/grasps/mug_handle_grasp.yaml,sha256=5cTgOjvHJe0__ktKZSyQZ0VoNq8An6klws9Jr8Y5vuU,546
+tsr/templates/grasps/screwdriver_grasp.yaml,sha256=H75b_HUETx0LXmVnR--YvtW0qu7AOUdMMWA97mFEEIQ,572
+tsr/templates/places/mug_on_table.yaml,sha256=1VoKshxoZT7yiG9L1PMqJLWXdGD1ikGzjDbwLkv1ies,519
+tsr/templates/places/toolchest_drop.yaml,sha256=gu81vy5OcxtWoe40xSd_u7sIQT5ZwM53JJecDhMQNG8,761
+tsr/templates/tasks/drive_screw.yaml,sha256=rh6U3GkXJ-Ng_ZtX4xXq3XNfYA_enstrY9Tm7dgIqo4,697
+tsr/templates/tasks/mug_pour_into_sink.yaml,sha256=BOwNwpnUkcMMk9c8QibMC5q86Vx4kqGc4IMH7iwvig8,714
+tsr/templates/tasks/mug_transport_upright.yaml,sha256=wM2Ns3L84Qyn_f6vLeKhOLK3cLpJH_-dgdRJWvMi_F0,751
+sstsr-2.0.0.dist-info/METADATA,sha256=dok81wfFTioCoWWbHnfE4NPUbB5VHRJ8GR8X08VI8UM,10181
+sstsr-2.0.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+sstsr-2.0.0.dist-info/licenses/LICENSE,sha256=IJQAUlQgzVn5wagmuyH6I6-iEjAMVWMNqN1sNJmh0LY,1333
+sstsr-2.0.0.dist-info/RECORD,,

sstsr-2.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.3
+Root-Is-Purelib: true
+Tag: py3-none-any

sstsr-2.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2025, Siddhartha Srinivasa and contributors to TSR
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

tsr/__init__.py

@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: BSD-2-Clause
+# Authors: Siddhartha Srinivasa and contributors to TSR
+
+"""TSR — Task Space Regions for robotics.
+
+Robot-agnostic Task Space Region (TSR) functionality for pose-constrained
+manipulation planning. The package is layered:
+
+* **core** — the pure-math heart: :class:`TSR`, :class:`TSRChain`, and SE(3)
+  helpers. Robot-agnostic, NumPy/SciPy only.
+* **template** — :class:`TSRTemplate`: a reusable, serialisable, scene-agnostic
+  recipe that instantiates to a concrete TSR at a reference pose.
+* **factories** — domain knowledge that *produces* templates:
+  :class:`ParallelJawGripper` (and ready-made hands) for grasps, and
+  :class:`StablePlacer` for placements.
+* **services** — :mod:`tsr.io` (persistence), sampling helpers, and the
+  optional :mod:`tsr.viz` renderer (install with the ``viz`` extra).
+
+The spine: a factory produces recipes; a recipe instantiates to math::
+
+    from tsr import ParallelJawGripper
+    gripper   = ParallelJawGripper(finger_length=0.055, max_aperture=0.140)
+    templates = gripper.grasp_cylinder(cylinder_radius=0.04, cylinder_height=0.12)
+    tsr       = templates[0].instantiate(object_pose_in_world)
+    pose      = tsr.sample()              # a valid grasp pose
+    assert tsr.contains(pose)
+"""
+
+# --- Layer 0: core math -------------------------------------------------------
+from .core import (
+    EPSILON,
+    TSR,
+    TSRChain,
+    geodesic_distance,
+    geodesic_error,
+    rotation_angle,
+    wrap_to_interval,
+)
+
+# --- Layer 1: the reusable recipe ---------------------------------------------
+from .template import TSRTemplate
+
+# --- Layer 2: factories (domain knowledge -> recipes) -------------------------
+from .hands import FrankaHand, GripperBase, ParallelJawGripper, Robotiq2F85, Robotiq2F140
+from .placement import StablePlacer
+
+# --- Layer 3: services --------------------------------------------------------
+from .io import (
+    get_package_templates,
+    list_available_templates,
+    load_package_template,
+    load_package_templates_by_category,
+    load_template,
+    load_template_collection,
+    save_template,
+    save_template_collection,
+)
+from .sampling import (
+    choose_tsr,
+    choose_tsr_index,
+    instantiate_templates,
+    sample_from_templates,
+    sample_from_tsrs,
+    weights_from_tsrs,
+)
+
+__version__ = "2.0.0"
+
+__all__ = [
+    # core
+    "TSR",
+    "TSRChain",
+    "wrap_to_interval",
+    "rotation_angle",
+    "geodesic_error",
+    "geodesic_distance",
+    "EPSILON",
+    # template
+    "TSRTemplate",
+    # factories
+    "GripperBase",
+    "ParallelJawGripper",
+    "Robotiq2F85",
+    "Robotiq2F140",
+    "FrankaHand",
+    "StablePlacer",
+    # sampling helpers
+    "choose_tsr",
+    "choose_tsr_index",
+    "instantiate_templates",
+    "sample_from_tsrs",
+    "sample_from_templates",
+    "weights_from_tsrs",
+    # template I/O
+    "save_template",
+    "save_template_collection",
+    "load_template",
+    "load_template_collection",
+    "load_package_template",
+    "load_package_templates_by_category",
+    "list_available_templates",
+    "get_package_templates",
+    "__version__",
+]

tsr/core/__init__.py

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: BSD-2-Clause
+# Authors: Siddhartha Srinivasa and contributors to TSR
+
+"""tsr.core — the pure-math heart of the package.
+
+Layer 0 of the architecture: robot-agnostic SE(3) geometry with no dependencies
+beyond NumPy (and SciPy for the optional optimiser paths). Nothing in this
+subpackage imports from the convenience layers above it (templates, factories,
+io, sampling, viz); that invariant is enforced by
+``tests/tsr/test_architecture.py``.
+
+The public symbols are re-exported at the top level (``from tsr import TSR``);
+import them from here when you want only the kernel.
+"""
+
+from .tsr import NANBW, TSR
+from .tsr_chain import TSRChain
+from .utils import (
+    EPSILON,
+    geodesic_distance,
+    geodesic_error,
+    rotation_angle,
+    wrap_to_interval,
+)
+
+__all__ = [
+    "TSR",
+    "TSRChain",
+    "NANBW",
+    "EPSILON",
+    "wrap_to_interval",
+    "rotation_angle",
+    "geodesic_error",
+    "geodesic_distance",
+]