Viewer¶
tesseract_robotics.viewer draws a tesseract environment in your browser and animates planned trajectories. It is built on viser. Tesseract owns the kinematics: every link is one viser frame posed from env.getState(...), so rails, positioners and attached objects need no separate handling. After a command that adds or removes links, call update_environment again; until then pose updates raise StaleSceneError.
Basic usage¶
Build an Environment, then hand it to the viewer. The viewer serves from construction until close(), at http://127.0.0.1:8000 by default:
t_env = Environment()
# locator must be kept alive by maintaining a reference
locator = GeneralResourceLocator(paths=[get_tesseract_resource_path()])
if not t_env.init(shapes_urdf, locator):
raise EnvironmentInitError("failed to initialize the shapes environment")
with TesseractViewer() as viewer:
viewer.update_environment(results["env"])
print(f"Viewer at {viewer.url}")
input("Press Enter to exit...")
TesseractViewer(port=...) picks another port; port=0 lets the OS choose and viewer.url reports it. A taken port raises ViewerPortInUseError instead of moving on, because a URL you were given should stay true. TesseractViewer(host="0.0.0.0") exposes the viewer to your network; it has no authentication.
Visualizing a robot¶
Load a URDF/SRDF pair via GeneralResourceLocator, then push the environment into the viewer:
# Load robot
locator = GeneralResourceLocator(paths=[get_tesseract_resource_path()])
abb_irb2400_urdf_package_url = "package://tesseract/support/urdf/abb_irb2400.urdf"
abb_irb2400_srdf_package_url = "package://tesseract/support/urdf/abb_irb2400.srdf"
abb_irb2400_urdf_fname = locate(locator, abb_irb2400_urdf_package_url)
abb_irb2400_srdf_fname = locate(locator, abb_irb2400_srdf_package_url)
t_env = Environment()
if not t_env.init(abb_irb2400_urdf_fname, abb_irb2400_srdf_fname, locator):
raise EnvironmentInitError(
f"failed to initialize the environment from {abb_irb2400_urdf_fname}"
)
manip_info = ManipulatorInfo()
manip_info.tcp_frame = "tool0"
manip_info.manipulator = "manipulator"
manip_info.working_frame = "base_link"
Animating a planned trajectory¶
After running a motion planner, feed the resulting CompositeInstruction to update_trajectory:
# OMPL planning
plan_profile = OMPLRealVectorMoveProfile()
profiles = ProfileDictionary()
profiles.addProfile(OMPL_DEFAULT_NAMESPACE, "DEFAULT", plan_profile)
request = PlannerRequest()
request.instructions = program
request.env = t_env
request.profiles = profiles
ompl_planner = OMPLMotionPlanner(OMPL_DEFAULT_NAMESPACE)
response = ompl_planner.solve(request)
require_success(response, "OMPL")
results_instruction = response.results
interpolated_results_instruction = generateInterpolatedProgram(
results_instruction,
t_env,
INTERP_STATE_LVS,
INTERP_TRANSLATION_LVS_M,
INTERP_ROTATION_LVS_RAD,
INTERP_MIN_STEPS,
)
Then push the result into the viewer (from the same example):
viewer.update_environment(results["env"])
viewer.update_trajectory(results["trajectory"])
viewer.plot_trajectory(results["trajectory"], results["manip_info"], axes_length=0.05)
Waypoint times decide the playback speed:
| Waypoints | Time used |
|---|---|
| State waypoints with times (time-parameterized) | their own times |
State waypoints all at t = 0 (not time-parameterized) |
their index, one waypoint per second |
| Joint waypoints (they carry no time) | their index, one waypoint per second |
A trajectory you computed yourself goes through Trajectory:
from tesseract_robotics.viewer import Trajectory
viewer.update_trajectory(Trajectory.build(joint_names, positions, times_s))
# or rows of [q_1, ..., q_J, t]
viewer.update_trajectory(Trajectory.from_rows(joint_names, rows))
Playback controls¶
The Playback folder in the viewer's control panel exists from construction, so it is there for a browser that connects late.
| Control | Effect |
|---|---|
| Play | Run or pause. update_trajectory turns it on, update_joint_positions off |
| Time [s] | Dragging pauses playback and scrubs |
| Speed | Time multiplier; 0 holds the current time |
| Loop | Restart at the end, or stop on the last waypoint |
Re-pushing an environment that still has the trajectory's joints keeps it playing. An environment without them drops the trajectory with a logged warning.
TCP path¶
plot_trajectory draws the path the program commands, chosen per move by the type of the instruction arriving at each waypoint. MoveL and MoveJ have different true paths, so neither a fitted curve nor straight lines everywhere can draw both. It is the commanded path, not a prediction of the machine's: a controller's blending zones are not in the program and do not appear.
| Move | Drawn between two waypoints |
|---|---|
LINEAR (MoveL) |
The straight line between the two TCP positions |
FREESPACE (MoveJ) |
FK along the synchronized joint interpolation q(s) = q_a + s (q_b - q_a), uniform in s, without angle wrapping |
CIRCULAR |
Raises UnsupportedMoveTypeError |
No program (Trajectory.build, from_rows) |
As FREESPACE: joint values alone say nothing more |
Axes triads sit on the waypoints only, so a MoveJ sample never looks like a planned pose. The TCP is tcp_frame with tcp_offset applied, since a MoveL's line belongs to the TCP and not the flange.
A MoveJ is drawn in n = max(ceil(max|dtheta| / 1 deg), ceil(max|dd| / 50 mm)) pieces, over its revolute and prismatic joints. Without revolute motion one piece is exact.
| Measurement | Result |
|---|---|
| Drawn MoveJ against FK sampled 16x finer, 300 random full-range moves (IRB2400, 8-DOF rail gantry) | 0.102 mm worst |
| One straight chord for those IRB2400 moves | 589 mm median, 2280 mm worst |
| Move types through planning, 11 examples (TrajOpt, OMPL, Descartes, pipelines) | Kept |
TCP at MoveL waypoints leaving the run's line: basic_cartesian, raster, pick_and_place |
0.000 mm |
Same for glass_upright, whose MoveL targets constrain orientation |
88 mm: the plan's waypoints are off the line, and the plot shows it |
Playback does not follow a MoveL's line
The player interpolates joints on every move, so between MoveL waypoints the animated TCP leaves the plotted line: 4.1 mm at most on basic_cartesian's 125 mm moves, 1.6 mm on raster's 100 mm. The waypoints themselves coincide.
Moving working frames
A MoveL is straight in its working_frame. If the group moves that frame (a part on a positioner), its world path is not a line, and plot_trajectory raises MovingWorkingFrameError rather than draw one. MoveJ draws normally there.
Markers and custom scene content¶
The viewer draws links, visuals and plot_trajectory. Anything else goes straight to viser through viewer.server. See the viser documentation:
viewer.server.scene.add_icosphere(
"/markers/target", radius=0.02, color=(255, 0, 0), position=(0.8, 0.0, 0.8)
)
viewer.server.gui.add_button("Replan")
Keep markers out of /links/, which update_environment replaces.
Look¶
The live viewer looks like the docs' demo players: dark theme, no viser logo, an orange TCP path, and a floor grid (/floor) with a soft contact shadow. update_environment lays the floor under the scene's footprint at its current state: square, 1 m sections over 0.25 m cells, at least 6 m across, with 1 m to spare on every side and its lines on whole metres. Adding your own /floor through viewer.server.scene replaces it, which is what the demo recorder does to give each entry its reviewed size.
Shading¶
| Geometry | Shading |
|---|---|
| Mesh whose file has smooth normals | The file's normals, corrected for a non-uniform URDF scale |
| Mesh with facet-only or no normals (STL) | Auto-smoothed: neighbouring faces under 30 degrees share a normal, sharper edges stay creased |
| Textured mesh | The file's normals; never auto-smoothed, since merging vertices would orphan its UVs |
| Sphere, cylinder, capsule, cone | Auto-smoothed, so caps keep their edge |
| Box, octree voxels | Flat |
All materials are double-sided: sheet-metal meshes often mix face windings, which would otherwise show as holes. Colour comes from the URDF <material> on the visual, then the mesh's own material or texture, then tesseract's default grey.
Industrial workcells¶
twc_workcell_positioner_viewer, tesseract_robotics 0.35.0.9.dev774
The Tesseract Robotics Workcell Collection (TWC) ships rail and positioner cells. Trajectories over any subset of joints, in any order, pose by their own joint names:
urdf_path = support_path / config.urdf
srdf_path = support_path / config.srdf
print(f"Using twc_support from: {support_path}")
print(f"Workcell: {workcell}")
print(f"Loading URDF: {urdf_path}")
print(f"Loading SRDF: {srdf_path}")
# Create resource locator (must keep reference alive!)
locator = TwcResourceLocator(support_path)
# Load and patch URDF for Tesseract 0.33+ compatibility
urdf_content = locator.load_urdf(urdf_path)
# Initialize environment from URDF string
t_env = Environment()
if srdf_path.exists():
srdf_content = srdf_path.read_text()
success = t_env.init(urdf_content, srdf_content, locator)
else:
print("SRDF not found, loading URDF only")
success = t_env.init(urdf_content, locator)
if not success:
raise WorkcellInitError(f"failed to initialize the {workcell} workcell")
Submodule Required
TWC workcell assets ship as a git submodule. Initialize with:
Recording¶
record writes the scene and its motion to a .viser file, which viser's static client plays in a browser with no Python running. The demos in these docs are made this way.
from pathlib import Path
from tesseract_robotics.viewer import RecordingPhase, TesseractViewer
with TesseractViewer(port=0) as viewer:
viewer.update_environment(robot.env)
data = viewer.record([RecordingPhase(robot.env, result.raw_results)])
Path("plan.viser").write_bytes(data)
Each RecordingPhase pairs a trajectory with the environment it runs in, so a recording can join a pick, with the part on the table, to a place, with the part on the tool. Add plot_trajectory paths first: record keeps what is already in the scene. With no phases it records the scene as it stands, and the client shows no timeline.
API quick reference¶
| Member | Purpose |
|---|---|
TesseractViewer(host="127.0.0.1", port=8000) |
Start serving; also a context manager that calls close() |
url |
Address to open in a browser |
server |
The viser.ViserServer, for markers and GUI |
update_environment(env) |
Replace the scene with env at its current state, and lay the floor under it |
update_joint_positions(joint_names, q) |
Show a stationary pose; stops playback |
update_trajectory(trajectory) |
Animate a CompositeInstruction or Trajectory from its start |
show_time(t_s) |
Pose the scene at one trajectory time |
plot_trajectory(trajectory, manip_info, axes_length=0.1, color=(255, 170, 0)) |
Draw the commanded TCP path with an axes triad per waypoint |
record(phases, *, fps=30.0) |
The .viser bytes of the scene playing phases; see Recording |
close() |
Stop playback and serving, release the port; idempotent |
serve_forever() |
Block until Ctrl-C, then close() |
Failures raise named errors from tesseract_robotics.viewer.errors:
| Error | When |
|---|---|
ViewerPortInUseError |
The requested port is taken |
NoEnvironmentError |
update_joint_positions, update_trajectory or plot_trajectory before update_environment |
NoTrajectoryError |
show_time before update_trajectory |
UnknownJointError |
A joint name the environment lacks |
StaleSceneError |
The environment gained or lost links since update_environment |
EmptyTrajectoryError |
A trajectory without waypoints |
TrajectoryShapeError |
Names, positions, times and move types disagree, times decrease, or a program's waypoints name different joints |
UnplannedWaypointError |
A program still has a Cartesian waypoint |
UnsupportedGeometryError |
A visual with no mesh form (Plane, ...) |
UnsupportedMoveTypeError |
plot_trajectory with a move that is neither LINEAR nor FREESPACE |
MovingWorkingFrameError |
plot_trajectory with a LINEAR move in a working frame the group moves |
NamedTcpOffsetError |
plot_trajectory with a tcp_offset that names a link |
RecordingFpsError |
record with an fps that is not positive |
ViewerCloseTimeoutError |
The playback thread did not stop in close() |
A failure during playback has no caller to raise to: it logs the traceback and pauses. Play or update_trajectory try again.
Examples¶
shapes_viewer.py— primitivestesseract_material_mesh_viewer.py— materials + meshesabb_irb2400_viewer.py— robot + planned trajectorytwc_workcell_positioner_viewer.py— industrial workcell (requiresgit submodule update --init)