Skip to content

tesseract_robotics.serialization

XML and binary serialization for root types. The backend switched from Boost.Serialization (0.33) to Cereal (0.34); the Python API is unchanged. See the Serialization User Guide for a walkthrough and the migration notes if you have 0.33 archives.

Free functions

Each supported type exposes paired to_* / from_* functions for the three archive formats:

Type XML Binary File (XML)
CompositeInstruction composite_instruction_to_xml / composite_instruction_from_xml composite_instruction_to_binary / composite_instruction_from_binary composite_instruction_to_file / composite_instruction_from_file
Environment environment_to_xml / environment_from_xml environment_to_binary / environment_from_binary environment_to_file / environment_from_file
SceneState scene_state_to_xml / scene_state_from_xml scene_state_to_binary / scene_state_from_binary scene_state_to_file / scene_state_from_file
TaskComposerLog task_composer_log_to_xml / task_composer_log_from_xml task_composer_log_to_binary / task_composer_log_from_binary task_composer_log_to_file / task_composer_log_from_file

The *_to_file / *_from_file helpers always write and read XML, whatever the path suffix: there is no format detection. For a binary file, write the bytes of *_to_binary yourself.

The *_file helpers take a str or an os.PathLike (pathlib.Path) and write and read exactly that path (upstream appends .tclx to a task composer log path without a suffix; these do not). A *_to_file helper returns None; every one raises OSError (FileNotFoundError, PermissionError, ...) naming the path when the file cannot be written or read. *_to_binary returns bytes and *_from_binary takes them.

A TaskComposerLog can hold planner profiles

This module registers every planner profile type (TrajOpt, TrajOptIfopt, OMPL, Descartes, the simple planner, the task-composer planning profiles and time parameterization), so a log whose initial_data or context holds them round-trips on every platform. A process that loads an archive needs nothing but this module: importing it links the planner libraries.

Reference

Tesseract serialization bindings (XML/binary via Cereal)

composite_instruction_to_xml

Python
composite_instruction_to_xml(instruction: CompositeInstruction) -> str

Serialize CompositeInstruction to XML string. Recursively captures all waypoints, instructions, profiles, and nested composites.

composite_instruction_from_xml

Python
composite_instruction_from_xml(xml: str) -> tesseract_robotics.command_language.CompositeInstruction

Deserialize CompositeInstruction from XML string.

composite_instruction_to_file

Python
composite_instruction_to_file(instruction: CompositeInstruction, path: str | PathLike) -> None

Save CompositeInstruction as XML to path, as named. Raises OSError if it cannot be written.

composite_instruction_from_file

Python
composite_instruction_from_file(path: str | PathLike) -> tesseract_robotics.command_language.CompositeInstruction

Load CompositeInstruction from the XML file path. Raises OSError if it cannot be read.

composite_instruction_to_binary

Python
composite_instruction_to_binary(instruction: CompositeInstruction) -> bytes

Serialize CompositeInstruction to binary data (bytes; faster, smaller than XML).

composite_instruction_from_binary

Python
composite_instruction_from_binary(data: bytes) -> tesseract_robotics.command_language.CompositeInstruction

Deserialize CompositeInstruction from binary data (bytes).

environment_to_xml

Python
environment_to_xml(environment: Environment) -> str

Serialize Environment to XML string. Includes command history - on deserialize, commands are replayed to rebuild scene graph.

environment_from_xml

Python
environment_from_xml(xml: str) -> tesseract_robotics.environment.Environment

Deserialize Environment from XML string. Returns shared_ptr.

environment_to_file

Python
environment_to_file(environment: Environment, path: str | PathLike) -> None

Save Environment as XML to path, as named. Raises OSError if it cannot be written.

environment_from_file

Python
environment_from_file(path: str | PathLike) -> tesseract_robotics.environment.Environment

Load Environment from the XML file path. Raises OSError if it cannot be read.

environment_to_binary

Python
environment_to_binary(environment: Environment) -> bytes

Serialize Environment to binary data (bytes).

environment_from_binary

Python
environment_from_binary(data: bytes) -> tesseract_robotics.environment.Environment

Deserialize Environment from binary data (bytes).

scene_state_to_xml

Python
scene_state_to_xml(state: SceneState) -> str

Serialize SceneState to XML string. Captures joint positions and link transforms.

scene_state_from_xml

Python
scene_state_from_xml(xml: str) -> tesseract_robotics.state_solver.SceneState

Deserialize SceneState from XML string.

scene_state_to_file

Python
scene_state_to_file(state: SceneState, path: str | PathLike) -> None

Save SceneState as XML to path, as named. Raises OSError if it cannot be written.

scene_state_from_file

Python
scene_state_from_file(path: str | PathLike) -> tesseract_robotics.state_solver.SceneState

Load SceneState from the XML file path. Raises OSError if it cannot be read.

scene_state_to_binary

Python
scene_state_to_binary(state: SceneState) -> bytes

Serialize SceneState to binary data (bytes).

scene_state_from_binary

Python
scene_state_from_binary(data: bytes) -> tesseract_robotics.state_solver.SceneState

Deserialize SceneState from binary data (bytes).

task_composer_log_to_xml

Python
task_composer_log_to_xml(log: TaskComposerLog) -> str

Serialize TaskComposerLog to XML string: description, initial data, context and dot graph.

task_composer_log_from_xml

Python
task_composer_log_from_xml(xml: str) -> tesseract_robotics.task_composer.TaskComposerLog

Deserialize TaskComposerLog from XML string.

task_composer_log_to_file

Python
task_composer_log_to_file(log: TaskComposerLog, path: str | PathLike) -> None

Save TaskComposerLog as XML to path, as named. Raises OSError if it cannot be written.

task_composer_log_from_file

Python
task_composer_log_from_file(path: str | PathLike) -> tesseract_robotics.task_composer.TaskComposerLog

Load TaskComposerLog from the XML file path. Raises OSError if it cannot be read.

task_composer_log_to_binary

Python
task_composer_log_to_binary(log: TaskComposerLog) -> bytes

Serialize TaskComposerLog to binary data (bytes).

task_composer_log_from_binary

Python
task_composer_log_from_binary(data: bytes) -> tesseract_robotics.task_composer.TaskComposerLog

Deserialize TaskComposerLog from binary data (bytes).