Skip to main content

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" by Berenson, Srinivasa, and Kuffner.

Grasps

TSR Grasp Templates

Stable placements

Stable Placements — primitives

Cylinder, box, sphere, and torus in every stable pose on a table surface.

Stable Placements — non-convex meshes

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.

Releasing into a container

Releases into a bin's opening

OpeningPlacer over a 0.238 m square bin opening, 26 mm clearance: one region per resting orientation that fits through it. A 0.22 m bottle is released only on an end (lying, it rolls); a box on four of its six faces (lying flat, it is too wide). Each object is shown at its region's centre and, faint, at its corners and other yaws; the green patch is where its origin may slide.

Installation

The distribution is named sstsr on PyPI; the import name is tsr.

pip install sstsr      # or: uv add sstsr
import tsr             # the import name is unchanged

For visualization support:

pip install "sstsr[viz]"     # interactive viewer (Viser); "sstsr[viser]" is the same

For development:

git clone https://github.com/personalrobotics/sstsr.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:

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")

These packaged YAML files are illustrative, hand-authored pose-constraint recipes. They are tested for representation validity, but they do not carry the geometric soundness guarantee of templates produced by the primitive grasp factories below. Users remain responsible for checking them against the intended object and gripper.

Generate templates from object geometry

Grasping

ParallelJawGripper generates TSR templates directly from shape parameters. Pre-configured subclasses are provided for common grippers:

Values match the class constants. finger_length is the graspable depth along the approach axis, from the TSR "palm" to the pad-contact point; the reference point for that measurement is listed explicitly (they are not interchangeable).

Class finger_length max_aperture finger_length reference (palm → pad tip)
Robotiq2F140 114 mm 128 mm palm (grasp_site, base_mount + 100 mm) → pad tip
Robotiq2F85 59 mm 85 mm palm (housing forward edge) → pad tip
FrankaHand 37 mm 80 mm palm (hand-body forward edge) → pad tip
KinovaJaco2TwoFinger 73 mm 73 mm palm (link_6 + 125 mm) → fingertips, closed on nothing

finger_length is the reach with the hand open, but for the JACO2. The two Robotiq hands are four-bar linkages whose pads swing forward as they close, so each also declares its measured reach closed to a width, gripper.reach(width) — 132 mm for the 2F-140 closed on 72 mm — and its templates keep the closed fingertips inside the object as well as the open ones. The JACO2's underactuated fingers wrap around what they close on; fully open they splay with their tips only 37 mm past the palm, so its finger_length is the reach closed on nothing, where the fingertips meet, and its reach(width) rises to 78 mm. Only its cylinder grasps have been closed on in its model, so it is registered for cylinders only; its other generators are unverified.

The Robotiq hands also grip only on their fingertip pads (65 mm long on the 2F-140, 37.5 mm on the 2F-85); inward of them is the linkage. They declare pad_length, and every grasp keeps its contacts on the pads, a margin inside both ends, measured from the closed fingertips. Their templates record provenance.grip == "pad". A custom hand can declare the same with ParallelJawGripper(..., pad_length=..., min_encompassing_diameter=...); without them it grips on the whole finger.

import numpy as np
from tsr.hands import ParallelJawGripper, Robotiq2F85, Robotiq2F140, FrankaHand

# Use a pre-configured gripper for a known hardware platform
gripper = Robotiq2F140()
gripper = FrankaHand()

# Or configure manually for custom hardware (generic 55 mm-fingered gripper)
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. To place an object as it is built, typically its collision model, describe its parts in its own frame and call place; it chooses how to place them:

from tsr.placement import Box, Capsule, Cylinder, Shape, StablePlacer

placer = StablePlacer(table_x=0.60, table_y=0.40)

can = Shape([Cylinder(0.033, 0.123, pose=T_can_cylinder)])     # framed at its base
mug = Shape([Box((0.08, 0.08, 0.10), pose=T_mug_body),
             Capsule(0.008, 0.05, pose=T_mug_handle)], com=com)
templates = placer.place(can)    # placed exactly by place_cylinder, framed at the can's origin
templates = placer.place(mug)    # the hull's faces the true parts support, most stable first

A lone box, cylinder or sphere whose centre of mass is its centre is placed exactly by its own factory, wherever it sits in the object frame. Anything else (several parts, hulls, capsules) rests on the faces of its convex hull that the true parts support: a curved part contributes no rest where it touches along a line or at a point, since the object would roll there. The factories place uses are public too:

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")   # one per face: 6
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, "→ origin z =", pose[2, 3])

Stability is determined by the COM-projection criterion: a face is stable if the centre of mass projects strictly inside the support polygon formed by that face's contact region. Every template reports a stability_margin — the physical tipping angle arctan(d_min / h_com), where d_min is the in-plane distance from the COM projection to the nearest edge of the polygon — and every factory takes min_margin_deg to discard poses below a threshold. A sphere reports 0: it is neutrally stable, so it rolls rather than tipping.

Every template also carries a machine-readable provenance — the resting face's normal, the support_margin and com_height the angle is built from, the footprint_radius behind the sliding bounds — so you read the semantics structurally instead of parsing name:

p = templates[0].provenance
p.face_normal        # (0.0, 0.0, -1.0) in the object frame
p.equilibrium        # 'stable', or 'neutral' for a sphere that rolls
p.footprint_radius   # the inset applied to Bw's xy bounds

Releasing into a container

OpeningPlacer releases an object into a container through its opening, given as a rectangle's extents or a circle's radius with the depth to the floor, framed on the rim plane with z pointing out. Each template is one of the object's resting orientations (StablePlacer.place's rests), with the whole object inside the opening by clearance at every yaw and its lowest point at the heights lowest above the rim plane:

from tsr.placement import OpeningPlacer

placer = OpeningPlacer(size=(0.238, 0.238), depth=0.757)    # or radius=0.08 for a circle
templates = placer.place(bottle, lowest=(0.02, 0.10), clearance=0.026)
pose = templates[0].sample(T_world_opening)

A tall bottle comes back only on an end, its base or its cap: lying, it rolls, so it has no rest on its side. An object with no resting orientation that fits returns [], with exceeds_opening logged. Where the object comes to rest once released is not part of the contract.

Work directly with TSRs

from tsr import TSR, sample_haar
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

# Haar-uniform rotations over the same region, reproducible under an explicit RNG
rng  = np.random.default_rng(42)
pose = sample_haar(tsr, rng)

tsr.sample() draws roll, pitch, and yaw uniformly, which covers the region but is not uniform over rotations. sample_haar samples rotations Haar-uniformly over the same region (for example, approach directions uniform over a sphere grasp).

Save and load templates

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:

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). A chain composes its links serially: the first is placed by its own T0_w, and every later one is placed by the chain, on the previous link's end frame. A later link's T0_w is therefore never read, and append refuses a non-identity one rather than silently dropping the offset — put it in the previous link's Tw_e, which is what moves the end frame the next link hangs off.

from tsr import TSRChain

chain = TSRChain(TSRs=[hinge_tsr, handle_tsr])
pose  = chain.sample()

Membership is where a chain differs from a single TSR. A TSR has a closed-form contains; a chain has to invert a composition, which is a bounded non-convex problem. So sampling hands back the coordinates that built the pose, and those are a constructive witness:

s = chain.sample_with_witness()
chain.validate_witness(s.pose, s.coordinates)   # exact: one bounds check, one composition
chain.contains(s.pose, initial_guess=s.coordinates)   # the same fast path

Without a witness, contains runs a bounded numerical solve. True means one was found; False means none was found within the budget, and is not a proof of non-membership — distance is likewise an upper bound rather than a certified distance. Keep the witness when you have one.

Visualization

The recommended viewer is interactive and browser-based:

pip install "sstsr[viser]"        # or: uv sync --extra viser
uv run python examples/viser_cylinder_grasps.py --explore
from tsr.hands import ParallelJawGripper
from tsr.viser import explore_templates, show_templates

gripper   = ParallelJawGripper(finger_length=0.08, max_aperture=0.14)
templates = gripper.grasp_cylinder_side(0.03, 0.12)

server = show_templates(templates, cylinder=(0.03, 0.12), gripper=gripper, seed=0)
server = explore_templates(templates, cylinder=(0.03, 0.12), gripper=gripper)

For debugging generation itself — change a primitive's dimensions, the gripper, k or the clearance and watch the TSRs change, with the reason shown when a request yields nothing — use the studio:

from tsr.viser import studio
studio().sleep_forever()

Open http://localhost:8080. show_templates draws a reproducibly sampled cloud; explore_templates gives a slider per free Bw coordinate so one grasp can be scrubbed through the region. Over SSH, forward the port: ssh -L 8080:localhost:8080 user@host. Details in docs/VISER.md.

From C++

A planner that evaluates a TSR on every edge sample should not pay a Python call to do it. cpp/ is a second implementation of the region and the chain — standard library only, C++20, no linear-algebra dependency to hold a pose — and the wheel carries its sources, headers and CMake package, so pip install sstsr is all a C++ consumer needs.

Ask the installed package where the CMake package is:

find_package(Python COMPONENTS Interpreter)
execute_process(
  COMMAND "${Python_EXECUTABLE}" -c "import tsr; print(tsr.get_cmake_dir(), end='')"
  OUTPUT_VARIABLE TSR_CMAKE_DIR RESULT_VARIABLE rc ERROR_QUIET)
if(rc EQUAL 0 AND TSR_CMAKE_DIR)
  list(APPEND CMAKE_PREFIX_PATH "${TSR_CMAKE_DIR}")
endif()
find_package(sstsr_cpp CONFIG REQUIRED)
target_link_libraries(my_planner PRIVATE sstsr::sstsr_cpp)
#include "sstsr/tsr_chain.hpp"

// A door handle on a hinge: the first link turns, the second grasps the bar.
const sstsr::TSRChain chain({hinge, handle});

sstsr::Rng rng(7);
const sstsr::ChainSample s = chain.sample_with_witness(rng);

// Sampling hands back the coordinates that built the pose, so membership is one bounds
// check and one composition -- no optimiser at all.
assert(chain.validate_witness(s.pose, s.coordinates));

// And the inverse, for a pose you were handed instead of one you sampled.
const auto [residual, closest] = chain.closest_transform(pose);

get_cmake_dir() raises from an editable install, because only a built wheel carries a relocatable CMake package; point CMake at cpp/ directly in that case, as cpp/examples/consumer does.

The Python is the source of truth for the rules. The C++ is held to them by a checked-in corpus of the Python's own answers, and neither implementation reads the other. Two things are deliberately not shared: the sampling engine, so a seeded sample is reproducible within an implementation rather than across the two; and a chain's cold inverse, which reports the best point a bounded search found and so is specified by properties rather than by recorded numbers. docs/CPP.md has the whole contract.

Documentation

  • Tutorial — TSR theory, math, and worked examples
  • Architecture — the four layers, and the geometric contract every factory is held to
  • The C++ core — using sstsr_cpp, and what the two implementations do and do not agree on
  • Interactive viewer — inspecting templates with Viser
  • Releasing — the tag-driven release pipeline
  • Examples — Runnable scripts (uv run python examples/<script>.py)

Testing

uv run pytest tests/ -v

License

BSD-2-Clause — see LICENSE file.

Metadata

Release files for sstsr 4.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sstsr 4.5.0
File Size Uploaded Provenance Actions
sstsr-4.5.0.tar.gz 1.9 MB With provenance Details for sstsr-4.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sstsr 4.5.0
File Interpreter ABI Platform Actions
sstsr-4.5.0-py3-none-any.whl Python 3 none any Details for sstsr-4.5.0-py3-none-any.whl

Total release size: 2.1 MB

Release files / sstsr-4.5.0.tar.gz

Download URL sstsr-4.5.0.tar.gz
Size 1.9 MB
Tags Source
SHA-256 checksum
How to use checksums
252df03e6f827afc3081dc72888b1a44aea0b5051b431270024d424bc422c140
BLAKE2b-256 checksum
How to use checksums
45c7945bc03165d80656917e945819e72e71e4b00216e1847ef0eb30e9041b5f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / sstsr-4.5.0-py3-none-any.whl

Download URL sstsr-4.5.0-py3-none-any.whl
Size 154.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e81fa581b8de12ce49d25c56923498ea8f9a509ec6481f79e739f97567678ce4
BLAKE2b-256 checksum
How to use checksums
b08bfcb2de4e437af71c46ae103cca701ccb2ebd8535ddba3b39ff3d2720297c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Security for sstsr 4.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for sstsr-4.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page