Skip to content

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:

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

Python
    # 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:

Python
    # 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):

Python
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:

Python
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:

Python
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:

Python
    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:

Bash
git submodule update --init

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.

Python
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