Skip to content

Serialization

Save programs, environments and scene states to XML or binary, and load them back in another process. Use it to cache a planned trajectory, to ship a scene to a worker, or to reproduce a failed plan exactly. The archives are tesseract's own (cereal), so a C++ program built on the same tesseract version reads what Python writes.

Overview

Three root types are serializable:

Type Contents Use Case
CompositeInstruction Motion program (waypoints, instructions, profiles) Cache planned trajectories
Environment Scene via command history replay Save/restore full scene state
SceneState Joint positions + link transforms Checkpoint robot state

Nested types serialize with their root; only the three root types have calls of their own.

CompositeInstruction

Save and load planned trajectories:

Python
from tesseract_robotics.serialization import (
    composite_instruction_to_xml,
    composite_instruction_from_xml,
    composite_instruction_to_file,
    composite_instruction_from_file,
    composite_instruction_to_binary,
    composite_instruction_from_binary,
)

# After planning
result = composer.plan(robot, program, "TrajOptPipeline")

# Save to file
composite_instruction_to_file(result.raw_results, "trajectory.xml")

# Or get XML string (for DB storage, network transfer)
xml = composite_instruction_to_xml(result.raw_results)

# Load next session
program = composite_instruction_from_file("trajectory.xml")

# Binary format
binary = composite_instruction_to_binary(result.raw_results)
program = composite_instruction_from_binary(binary)

Environment

Save and restore complete scene state including all applied commands:

Python
from tesseract_robotics.serialization import (
    environment_to_xml,
    environment_from_xml,
    environment_to_file,
    environment_from_file,
)

# After modifying environment
env.applyCommand(AddLinkCommand(obstacle_link, obstacle_joint))
env.applyCommand(ModifyAllowedCollisionsCommand(acm, ModifyAllowedCollisionsType.ADD))

# Save entire environment
environment_to_file(env, "scene.xml")

# Load in new session - commands replayed automatically
env = environment_from_file("scene.xml")

Environment returns shared_ptr

Due to C++ implementation details, environment_from_* functions return a shared pointer. In Python this behaves identically to a regular object.

Runs without the GIL

The environment_to_* and environment_from_* functions release the GIL: serializing or rebuilding a mesh-heavy scene can take seconds, and other Python threads keep running meanwhile. See Threading and the GIL.

SceneState

Checkpoint joint positions and link transforms:

Python
from tesseract_robotics.serialization import (
    scene_state_to_xml,
    scene_state_from_xml,
    scene_state_to_file,
    scene_state_from_file,
)

# Get current state
state = env.getState()

# Save state snapshot
scene_state_to_file(state, "state.xml")

# Restore later
state = scene_state_from_file("state.xml")

Format comparison

Format Human Readable
XML Yes
Binary No

Use XML for debugging and interoperability. Binary archives are the compact choice for caching; measure both on your own data, as their relative speed and size depend on what is archived.