Skip to content

SWIG to nanobind

Cross-Module Inheritance

ProfileDictionary.addProfile - RESOLVED

The cross-module inheritance for Profile types now works. We use nb::class_<DerivedProfile, BaseProfile> in nanobind to register the base class relationship, and nanobind's module import mechanism loads the base type from command_language.

Solution: ProfileDictionary.addProfile takes a profile from any planner module. The per-module ProfileDictionary_add*Profile helpers are removed (#334):

Python
from tesseract_robotics.command_language import ProfileDictionary
from tesseract_robotics.motion_planners_ompl import OMPLRealVectorMoveProfile

plan_profile = OMPLRealVectorMoveProfile()
profiles = ProfileDictionary()
profiles.addProfile("OMPLMotionPlannerTask", "DEFAULT", plan_profile)

InstructionsTrajectory and Time Parameterization

Known Issue: Waypoint Type Mismatch

The InstructionsTrajectory class expects StateWaypointPoly waypoints but motion planners like OMPL return JointWaypointPoly. This causes a type erasure error:

Text Only
RuntimeError: TypeErasureBase, tried to cast 'tesseract_planning::JointWaypointPoly' to 'tesseract_planning::StateWaypointPoly'

Status: This appears to be a limitation in the underlying C++ API design. The SWIG bindings may have used special handling for this.

Workaround: Skip time parameterization when using OMPL directly, or convert JointWaypointPoly to StateWaypointPoly manually before creating InstructionsTrajectory.

Poly Types (Type Erasure)

The command_language uses type-erased "Poly" types (WaypointPoly, InstructionPoly, etc.) for runtime polymorphism. These require careful handling:

  • Cast with the Poly methods: instr.asMoveInstruction(), wp.asStateWaypoint(), …
  • Check waypoint type with isStateWaypoint(), isJointWaypoint(), etc. before casting
  • Type casts will throw RuntimeError if the underlying type doesn't match

InstructionPoly.as() - RESOLVED

The C++ type erasure as<T>() method uses typeid() comparison which fails across shared library boundaries. Even when the underlying type IS MoveInstructionPoly, the cast fails:

Text Only
RuntimeError: TypeErasureBase, tried to cast 'tesseract_planning::MoveInstructionPoly' to 'tesseract_planning::MoveInstructionPoly'

This is an RTTI issue where typeid() in Python bindings generates different type_info than typeid() in the tesseract C++ library.

Root Cause: - as<T>() template instantiated in Python binding module creates different typeid(T) than the one stored in the type erasure - BUT: isMoveInstruction() works because both getType() and typeid(MoveInstructionPoly) are generated within the C++ library

Solution: The RTTI visibility fix (CXX_VISIBILITY_PRESET=default) makes as<T>() work across the boundary, so the bindings call it directly.

Working Methods: - instr.asMoveInstruction() (also asCompositeInstruction, asWaitInstruction, …) - a copy of the stored instruction - wp.asJointWaypoint(), wp.asStateWaypoint(), wp.asCartesianWaypoint() - a reference into the waypoint: edits reach it. copy.copy(wp.asJointWaypoint()) when a copy is meant

The SWIG-era helpers InstructionPoly_as_* and WaypointPoly_as_* are removed (#328).

CompositeInstruction.flatten() - Not Needed

The SWIG bindings had a flatten() method on CompositeInstruction. In nanobind, you can iterate directly over CompositeInstruction using __getitem__ and len().

Cross-Module Type Resolution

When a method returns a type from another module (e.g., Environment.getKinematicGroup() returns KinematicGroup from kinematics), the module containing that type must be imported first.

Solution: src/bindings/environment.cpp imports the kinematics module to ensure KinematicGroup is registered.

Viewer Trajectory Visualization - RESOLVED

tesseract_robotics.viewer.Trajectory.from_composite reads both StateWaypointPoly and JointWaypointPoly waypoints, descending into child composites.

Status: Trajectory visualization works with OMPL planning output. The viewer moved to viser in #367; see Viewer and the changelog for the API changes.

nanobind Reference Leaks

There are reference leaks warnings at exit. These are likely due to: - Module-level singleton objects not being properly cleaned up - Cross-module type references not being released properly

These don't affect functionality but should be investigated and fixed.

TaskComposerPluginFactory and cross-module types

TaskComposerPluginFactory takes a ResourceLocator&, a type bound in common. An earlier binding accepted an nb::handle and checked isinstance against GeneralResourceLocator by hand, behind a free function createTaskComposerPluginFactory. Neither is needed: the module imports common at init, so nanobind resolves the ResourceLocator base across modules, and any subclass (GeneralResourceLocator, a Python subclass) is accepted directly (gh-150). The free function was removed (#338).

C++ Binding:

C++
// In src/bindings/task_composer.cpp: import the module that binds the type first
nb::module_::import_("tesseract_robotics.common._common");

// StrictPath (tesseract_nb.h): an os.PathLike is a config file, a str is YAML text (#337)
.def("__init__", [](Factory* self, const tesseract_nb::StrictPath& config_path, const tc::ResourceLocator& locator) {
    new (self) Factory(config_path.value, locator);
}, "config_path"_a, "locator"_a)

Python Usage:

Python
from pathlib import Path

from tesseract_robotics.common import GeneralResourceLocator
from tesseract_robotics.task_composer import TaskComposerPluginFactory

factory = TaskComposerPluginFactory(Path(task_composer_config_file), GeneralResourceLocator())

General pattern for cross-module types

When a function in module B takes or returns a type bound in module A, import module A in module B's NB_MODULE before defining the function, and bind the C++ base type as the parameter. nanobind then converts subclasses and names the type in the signature.

TrajOpt Planner

TrajOpt bindings are always built; CMake stops if the component is missing.

Usage (0.33 API)

Python
from tesseract_robotics.motion_planners_trajopt import (
    TrajOptMotionPlanner,
    TrajOptDefaultMoveProfile,
    TrajOptDefaultCompositeProfile,
)
from tesseract_robotics.collision import CollisionEvaluatorType

# Create profiles
plan_profile = TrajOptDefaultMoveProfile()
composite_profile = TrajOptDefaultCompositeProfile()
composite_profile.smooth_velocities = True

# Configure collision avoidance (0.33 API)
# collision_cost_config is TrajOptCollisionConfig, not CollisionCostConfig
composite_profile.collision_cost_config.enabled = True
composite_profile.collision_cost_config.collision_check_config.type = CollisionEvaluatorType.LVS_CONTINUOUS
composite_profile.collision_cost_config.contact_manager_config.default_margin = 0.025
composite_profile.collision_cost_config.collision_coeff_data.setDefaultCollisionCoeff(20.0)

# Register profiles
profiles = ProfileDictionary()
profiles.addProfile("TrajOptMotionPlannerTask", "DEFAULT", plan_profile)
profiles.addProfile("TrajOptMotionPlannerTask", "DEFAULT", composite_profile)

# Solve
planner = TrajOptMotionPlanner("TrajOptMotionPlannerTask")
response = planner.solve(request)

Time Parameterization

TrajOpt output uses StateWaypointPoly, which is compatible with time parameterization (unlike OMPL which returns JointWaypointPoly).

C++ Build Issues

The C++ stack is built by scripts/native_stack.py (see The native stack). The colcon build issues recorded during the SWIG migration (Qt6 QT_HOST_PATH under PCL/VTK, a missing libode, TESSERACT_BUILD_TASK_COMPOSER_PLANNING being off by default) do not apply to the vcpkg-based build, which builds the task composer planning factories (libtesseract_task_composer_planning_factories) that the planning pipelines (FreespacePipeline, TrajOptPipeline, OMPLPipeline, …) need.

Task Composer API Differences

unique_ptr Returns - No .get() Needed

In nanobind, createTaskComposerNode() returns the TaskComposerNode directly (not a unique_ptr). Don't call .get() on the result:

Python
# nanobind (correct)
task = factory.createTaskComposerNode("TrajOptPipeline")
future = executor.run(task, task_data)

# SWIG (old style - don't use with nanobind)
# future = executor.run(task.get(), task_data)  # Wrong!

Pipeline Input Keys

Different pipelines have different input key names:

Python
# TrajOptPipeline, FreespacePipeline
input_key = task.getInputPortMappings().single("planning_input")

# OMPLPipeline (direct, without TrajOpt refinement)
input_key = task.getInputPortMappings().single("program")

TrajOpt Profile Configuration (0.33 API)

TrajOptDefaultMoveProfile

Configure waypoint-level TrajOpt behavior via config objects:

Python
from tesseract_robotics.motion_planners_trajopt import (
    TrajOptDefaultMoveProfile,
    TrajOptDefaultCompositeProfile,
)
from tesseract_robotics.collision import CollisionEvaluatorType

# Plan profile - waypoint constraints
trajopt_plan_profile = TrajOptDefaultMoveProfile()
trajopt_plan_profile.joint_cost_config.enabled = False
trajopt_plan_profile.cartesian_cost_config.enabled = False
trajopt_plan_profile.cartesian_constraint_config.enabled = True
trajopt_plan_profile.cartesian_constraint_config.coeff = np.array([10.0, 10.0, 10.0, 10.0, 10.0, 0.0])

# Composite profile - collision/smoothing
# 0.33 API: TrajOptCollisionConfig replaces CollisionCostConfig/CollisionConstraintConfig
trajopt_composite_profile = TrajOptDefaultCompositeProfile()
trajopt_composite_profile.collision_constraint_config.enabled = False
trajopt_composite_profile.collision_cost_config.enabled = True
# contact_manager_config.default_margin replaces safety_margin
trajopt_composite_profile.collision_cost_config.contact_manager_config.default_margin = 0.025
# CollisionEvaluatorType is now in collision; DISCRETE replaces SINGLE_TIMESTEP
trajopt_composite_profile.collision_cost_config.collision_check_config.type = CollisionEvaluatorType.DISCRETE
# collision_coeff_data.setDefaultCollisionCoeff() replaces .coeff
trajopt_composite_profile.collision_cost_config.collision_coeff_data.setDefaultCollisionCoeff(20.0)

# Register profiles
profiles.addProfile("TrajOptMotionPlannerTask", "CARTESIAN", trajopt_plan_profile)
profiles.addProfile("TrajOptMotionPlannerTask", "DEFAULT", trajopt_composite_profile)

0.33 API Changes Summary

TrajOptCollisionConfig (replaces CollisionCostConfig/CollisionConstraintConfig): - contact_manager_config.default_margin - the clearance the term drives toward (replaces safety_margin); the first argument of TrajOptCollisionConfig(margin, coeff) - collision_margin_buffer - extra distance past the margin within which contacts are collected but add no error (replaces safety_margin_buffer) - collision_check_config.type - collision evaluator type - collision_check_config.longest_valid_segment_length - interpolation control - collision_coeff_data.setDefaultCollisionCoeff(coeff) - collision cost coefficient

Porting safety_margin onto collision_margin_buffer leaves the term with no margin

A default-constructed TrajOptCollisionConfig has no margin (default_margin is None), so the contact manager's own margin applies, which is 0 m unless the environment sets one: the term only engages at contact, and the optimizer pulls the path onto the obstacle's surface. The buffer is documented in trajopt_common as "not used when calculating the error", so moving the old margin there changes nothing about where the path settles. The planning factories carried exactly this port until #103: over OMPL seeds 1-100 the freespace example's trajectory passed a median 0.17 mm from its obstacle, and 3 seeds failed the pipeline's contact check at -0.0000 m. With the cost margin set, the closest pass was 4.98 mm and none failed.

CollisionEvaluatorType (moved to collision): - DISCRETE - check at each waypoint (was SINGLE_TIMESTEP) - LVS_DISCRETE - longest valid segment discrete - CONTINUOUS - continuous collision checking - LVS_CONTINUOUS - longest valid segment continuous (was DISCRETE_CONTINUOUS)

TimeParameterization (0.33 API):

Python
from tesseract_robotics.time_parameterization import (
    TimeOptimalTrajectoryGeneration,
    TimeOptimalTrajectoryGenerationCompositeProfile,
)
from tesseract_robotics.command_language import ProfileDictionary

# Create TOTG with profile-based configuration
totg = TimeOptimalTrajectoryGeneration()
totg_profile = TimeOptimalTrajectoryGenerationCompositeProfile()
totg_profile.max_velocity_scaling_factor = 1.0
totg_profile.max_acceleration_scaling_factor = 1.0

time_profiles = ProfileDictionary()
time_profiles.addProfile("TOTG", "DEFAULT", totg_profile)

# compute() now takes (CompositeInstruction, Environment, ProfileDictionary)
success = totg.compute(composite_instruction, env, time_profiles)

Available config classes: - TrajOptCartesianWaypointConfig - cartesian_cost_config, cartesian_constraint_config - TrajOptJointWaypointConfig - joint_cost_config, joint_constraint_config - TrajOptCollisionConfig - collision_cost_config, collision_constraint_config (0.33 API)

Cartesian Path Planning with assignCurrentStateAsSeed

When planning Cartesian paths (CartesianWaypoint), TrajOpt needs seed joint states. Use assignCurrentStateAsSeed():

Python
from tesseract_robotics.motion_planners import assignCurrentStateAsSeed

program = CompositeInstruction("DEFAULT")
# ... add CartesianWaypoint instructions ...
assignCurrentStateAsSeed(program, env)

Known Issues

Reference Leaks at Exit

nanobind reference leak warnings may appear at program exit. These don't affect functionality but indicate cleanup issues with cross-module type references.

OMPL Constrained Planning API Removed

The OMPLPlannerConstrainedConfig class and related constrained planning support has been removed from tesseract's OMPL planner implementation. The header config/ompl_planner_constrained_config.h no longer exists in the installed headers.

Impact: Examples like glass_upright_ompl_example.cpp (which kept a glass upright during motion using ompl::base::Constraint) cannot be ported. The C++ test file still exists in the tesseract source but uses deprecated API.

Current Status: Constrained OMPL planning (custom constraints on end-effector orientation, etc.) is not available through Python bindings. Use TrajOpt with Cartesian constraints as an alternative for orientation-constrained planning.

Workaround: For glass-upright style constraints, use TrajOpt with cartesian_constraint_config.coeff to penalize orientation deviations:

Python
trajopt_plan_profile.cartesian_constraint_config.enabled = True
trajopt_plan_profile.cartesian_constraint_config.coeff = np.array([1.0, 1.0, 1.0, 10.0, 10.0, 0.0])  # High weight on rx, ry