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):
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:
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:
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:
// 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:
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)¶
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:
# 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:
# 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:
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):
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():
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: