Binding API audit¶

Accepted deviation rules

• boost-graph-property-tag: Boost Graph property tags (vertex_link_t, …) select the properties SceneGraph stores; Python reaches the properties through SceneGraph methods.
• bound-in-other-module: The class is bound in another extension module, which defines its Python type once for every module; its members are compared against that module's stub.
• byte-buffer: A (const uint8_t* bytes, size_t len) pair is one Python bytes argument: the binding passes the buffer and its size (createMeshFromBytes, BytesResource).
• container-protocol: size() is bound as __len__ and operator[] as __getitem__/__setitem__, the Python container protocol.
• copied-vector-field-mutator: A std::vector field converts to a fresh Python list on each access, so obj.field.append(x) edits a copy; add…/clear… methods mutate the C++ vector.
• derived-element-container: An overload taking a container of a derived class only upcasts into its base-element sibling (CompoundMesh(vector<ConvexMesh>) → CompoundMesh(vector<PolygonMesh>), compound_mesh.cpp:59-63); Python passes a list of any subclass to the bound base-element overload.
• eigen-default-precision: EIGEN_DEFAULT_PREC re-exports Eigen::NumTraits<double>::dummy_precision() (1e-12) so Python compares with Eigen's own default tolerance instead of a duplicated literal.
• eigen-template-instance: Eigen::Hyperplane<double, 3> and Eigen::ParametrizedLine<double, 3> have no Eigen typedef; the class takes Eigen's own …3d naming (Vector3d, Quaterniond).
• iterator-pair: A begin()/end() pair (and cbegin/cend) is bound as __iter__.
• module-getattr: A package __init__.py defines a PEP 562 module __getattr__ to re-export a name lazily (an eager import would be an import cycle); it is an attribute-lookup hook, not API.
• out-param: A non-const lvalue-reference out-param (or a by-value Eigen::Ref of a non-const matrix) is returned in a tuple with the result (Phase A precedent: checkTrajectory), or alone when the C++ returns void.
• presentation-dunder: __repr__ and __str__ are Python presentation and need no C++ counterpart.
• quaternion-rpy: Quaterniond.from_rpy/to_rpy convert roll-pitch-yaw in the ROS/tf2 convention, which Eigen spells as three composed AngleAxisd rotations; to_rpy returns tf2's canonical ranges, which eulerAngles does not guarantee.
• scalar-last-quaternion: Quaterniond takes (x, y, z, w), the project-wide scalar-last order; Eigen's constructor is (w, x, y, z).
• serialization-default-ctor: The default constructor of a class that befriends cereal serialize and declares another public constructor exists for deserialization only.
• stream-insertion: A free operator<<(std::ostream&, const T&) is bound as T.__str__ (T a class or an enum).
• stringstream: A std::stringstream& parameter the C++ writes into is returned as str.
• template-instance-name: Python cannot spell a C++ template argument, so each instance of a function template gets its own function named after the type (createMeshFromPath<ConvexMesh> → createConvexMeshFromPath, Serialization::toArchiveStringXML<Environment> → environment_to_xml).
• value-equality-unhashable: __hash__ = None next to a bound __eq__ makes a mutable value type unhashable, as Python does for any class that defines __eq__; it needs no C++ counterpart.
• yaml-node: An overload taking a YAML::Node has no Python form (no Python type converts to one); the sibling overloads taking a config file path or YAML text load the same config.

Unaudited headers

• test_suite/*: gtest and Google Benchmark sources installed for plugin authors' tests.
• *_impl.hpp: cereal implementation fragment, valid only after its cereal_serialization.h.
• bullet/*: Bullet backend internals, loaded as a contact manager plugin; Python reaches them through the DiscreteContactManager/ContinuousContactManager interfaces.
• fcl/*: FCL backend internals, loaded as a contact manager plugin; Python reaches them through the DiscreteContactManager interface.
• bullet/convex_decomposition_hacd.h: Declared but not built in 0.35.0: no HACD symbol in any collision library and no CMake target.
• cereal_make_array.h: cereal text-I/O helper for serialization, not API.
• serialization_extensions.h: Macros and SFINAE checks behind TESSERACT_CLASS_EXTENSION, not API.
• sfinae_utils.h: Compile-time member-detection templates, not API.
• unit_test_utils.h: gtest serialization helpers for plugin authors' tests.
• environment_cache.h: No consumer: only fwd.h names EnvironmentCache, and no installed tesseract library uses it.
• environment_monitor.h: Abstract ROS-side interface; no implementation in the installed tesseract libraries.
• environment_monitor_interface.h: Abstract ROS-side interface; no implementation in the installed tesseract libraries.
• ikfast/*: IKFast solver plugin template, loaded by KinematicsPluginFactory.
• kdl/*: KDL solver plugins, loaded by KinematicsPluginFactory.
• opw/*: OPW solver plugin, loaded by KinematicsPluginFactory.
• ur/*: Universal Robots solver plugin, loaded by KinematicsPluginFactory.
• rep_*: Robot-with-external-positioner solver plugin, loaded by KinematicsPluginFactory.
• rop_*: Robot-on-positioner solver plugin, loaded by KinematicsPluginFactory.
• ofkt/ofkt_node*.h: Optimized forward kinematics tree nodes, internal to OFKTStateSolver.
• A header its prefix owner's binding does not #include, but another binding does, is audited with the first such module by name; each module's section lists those headers.

Third-party headers (never audited, even when #included directly)

• vhacd/VHACD.h: Vendored third-party V-HACD library (namespace VHACD). The collision binding #includes it directly only so that convex_decomposition_vhacd.h does not compile a second copy of its implementation (#179).