Skip to content

Viewer

tesseract_robotics.viewer provides a web-based 3D viewer for scenes and trajectories, backed by Three.js. It started life as a standalone package and is now a first-class submodule of tesseract_robotics.

Installation

The viewer ships with the main package. No separate install step.

Python
from tesseract_robotics.viewer import TesseractViewer

Basic Usage

Build an Environment, then hand it to the viewer and start the background HTTP server at http://localhost:8000:

Python
    t_env = Environment()

    # locator must be kept alive by maintaining a reference
    locator = TesseractSupportResourceLocator()
    t_env.init(shapes_urdf, locator)
Python
        viewer = TesseractViewer()
        viewer.update_environment(t_env, [0, 0, 0])
        viewer.start_serve_background()

Visualizing a Robot

Load a URDF/SRDF pair via GeneralResourceLocator, then push the environment into the viewer:

Python
    # Load robot
    locator = GeneralResourceLocator()
    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 = FilesystemPath(
        locator.locateResource(abb_irb2400_urdf_package_url).getFilePath()
    )
    abb_irb2400_srdf_fname = FilesystemPath(
        locator.locateResource(abb_irb2400_srdf_package_url).getFilePath()
    )

    t_env = Environment()
    assert t_env.init(abb_irb2400_urdf_fname, abb_irb2400_srdf_fname, locator)

    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. The viewer animates the robot using the timestamps baked into the trajectory:

Python
    # OMPL planning
    plan_profile = OMPLRealVectorPlanProfile()
    profiles = ProfileDictionary()
    ProfileDictionary_addOMPLProfile(profiles, 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)
    assert response.successful
    results_instruction = response.results

    interpolated_results_instruction = generateInterpolatedProgram(
        results_instruction, t_env, 3.14, 1.0, 3.14, 10
    )

Then push the result into the viewer (from the same example):

Python
viewer.update_trajectory(final_results_instruction)
viewer.plot_trajectory(final_results_instruction, manip_info, axes_length=0.05)

Industrial Workcells

The Tesseract Robotics Workcell Collection (TWC) ships multi-robot positioner cells. The viewer supports both rail and positioner workcell topologies:

Python
    urdf_path = TWC_SUPPORT_PATH / config["urdf"]
    srdf_path = TWC_SUPPORT_PATH / config["srdf"]

    print(f"Using twc_support from: {TWC_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(TWC_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.initFromUrdfSrdf(urdf_content, srdf_content, locator)
    else:
        print("SRDF not found, loading URDF only")
        success = t_env.initFromUrdf(urdf_content, locator)

    if not success:
        print("ERROR: Failed to initialize environment")
        sys.exit(1)

Submodule Required

TWC workcell assets ship as a git submodule. Initialize with:

Bash
git submodule update --init

API Quick Reference

Method Purpose
TesseractViewer(server_address=("127.0.0.1", 8000)) Create viewer instance; spawns background event loop thread
update_environment(tesseract_env, origin_offset=[0, 0, 0]) Load or reload a scene
update_joint_positions(joint_names, joint_positions) Set stationary joint state (stops any animation)
update_trajectory(tesseract_trajectory) Animate a CompositeInstruction trajectory
update_trajectory_list(joint_names, trajectory) Animate a raw list-of-waypoints trajectory
plot_trajectory(tesseract_trajectory, manipulator_info) Draw trajectory path + waypoint axes in the scene
start_serve_background() Start HTTP server on server_address
close() Stop the server and join the background thread
add_axes_marker / add_arrow_marker / add_box_marker / add_sphere_marker / add_cylinder_marker / add_capsule_marker / add_lines_marker Add geometric markers to the scene
clear_all_markers / clear_markers_by_tags / clear_markers_by_name Remove markers
save(directory) / save_scene_gltf(fname) / save_scene_glb(fname) Export the scene for offline viewing

For the full API, see tesseract_robotics.viewer source.

Examples