Binding conventions¶
The rules every nanobind binding in src/bindings/ follows, so a user can predict a name, an
error or a lifetime without reading the C++. Each rule names the code that implements it; a new
binding follows them from its first commit.
Names¶
One rule, applied per name:
- A member that wraps a C++ symbol keeps the C++ name and the C++ semantics.
Environment.getState,PropertyTree.fromYAML,Quaterniond.FromTwoVectors,Hyperplane3d.Through(Eigen's normal sign, not a right-hand-rule variant),parseURDFFile. A port of C++ code reads the same in Python. - A Python-only addition is
snake_case.Environment.link_transforms_batch,Isometry3d.apply_points,Quaterniond.from_xyzw/from_rpy,Profile.from_yaml, theserializationfunctions (environment_to_file, ...),nearest_rotation. - A Python-only helper named after a C++ type keeps the type's spelling after a
snake_caseverb:cast_CommandAppliedEvent,AnyPoly_wrap_CompositeInstruction. - A Python-only member that completes a C++ class's own interface takes the class's
convention, so one class reads in one style:
Link.addVisualbeside upstream'sLink.getName. The same holds for the batch form of a C++ function, which keeps the function's spelling before_each:calcManipulabilityVolume_eachbeside upstream'scalcManipulabilityVolume.
No name has an alias. A C++ overload set is one Python name with @overloads; a Python-only
alias of a native overload (getStateByMap, calcInvKinMultiple, ...) does not exist.
Properties are used for stored scalar components of value types (Quaterniond.x,
Isometry3d.translation); methods for everything that mirrors a C++ method.
Units and frames¶
Units are SI throughout (metres, radians, seconds) and live in the parameter and attribute names
(radius_m, z_m, joint_positions documented in rad) and in the docstrings; frames live in the
names of the frames themselves (working_frame, tcp_frame) and in ManipulatorInfo. They are not
encoded as NewTypes or frame-tagged Pose generics.
Decision (0.36): a Radians / Metres NewType over float makes every literal argument a type
error at the call site (box(0.5, 0.5, 0.5) would need box(Metres(0.5), ...)), arrays cannot
carry a NewType at all, and every value crossing the C++ boundary would need wrapping on the way
back. That is a large ergonomic cost for users, and it would not catch the errors that matter in
practice, which are frame mix-ups, not unit mix-ups. A frame-tagged Pose would catch those, but
it needs every Tesseract API that takes a transform to name its frame in the type, which the C++
does not; the bindings would have to invent it. Where a frame matters at a boundary we own, the
code carries it explicitly instead: the emitters' FramedPose pairs a pose with its
MoveFrames, and an unbound frame raises UnboundFrameError.
Errors¶
- One named exception per failure mode, subclassing the builtin a caller would catch:
PolyTypeError(TypeError),InstructionHeldError(BufferError),NotRotationError(ValueError),DegenerateAxisError(ValueError),URDFWriteError(RuntimeError). The message names the actual value and what was expected. - A lookup by one id or name that misses is a
KeyError:Environment.getLink("x"),getJointGroup("x"),getKinematicGroup("g", "solver"),getDiscreteContactManager("x"). A list argument holding unknown ids is aValueErrornaming every unknown id (setState,getActiveLinkIds(joint_ids)). - A file that cannot be read or written is an
OSError(FileNotFoundErrorfor a missing one) naming the path: theserializationfunctions, every plugin factory's config path (upstream dereferences an unresolved locator result:require_located_file,src/tesseract_nb.h). - Upstream's nested exceptions (
std::throw_with_nested) reach Python with the whole chain in the message (urdf.writeURDFFile). - A precondition upstream only
assert()s is checked by the binding before the call.
Values, references and lifetimes¶
- Scalar-last quaternions everywhere:
[qx, qy, qz, qw].Quaterniondhas no positional four-scalar constructor (Eigen's is scalar-first); useQuaterniond.from_xyzw(...)orQuaterniond([x, y, z, w]). - A rigid-transform type holds a rigid transform:
Isometry3d(matrix)andQuaterniond(rotation_matrix)refuse a non-orthonormal rotation block (NotRotationError); a non-unit quaternion or axis names the rotation of its direction and is normalized; a zero one raisesDegenerateRotationError. Every member that turns aQuaterniondinto a rotation (theIsometry3dconstructors,*,rotate,prerotate,AngleAxisd(q),toRotationMatrix,to_rpy,eulerAngles,q * v) converts the same quaternion, through one helper (unit_quaternion,src/bindings/common_eigen.cpp):qas given when|q.squaredNorm() - 1| <= 6·eps,q / |q|otherwise. 6·eps bounds the squared-norm defect ofq / |q|in float64, so a quaternion unit to rounding is never re-rounded and every member gives it Eigen's own rotation, bit for bit (gh-463). The quaternion algebra (*of two quaternions,conjugate,inverse,dot,slerp,angularDistance,normalized) works on the coefficients as given, as Eigen's does. - A getter returns a copy unless its docstring says "by reference". A reference into a C++
container is kept valid by refusing the calls that would move or free it while Python holds
it (
ContactResultVector,CompositeInstruction:nb::findon the element addresses), not by documentation. - An object handed to a Python callback is valid after the callback returns: environment events
carry their own copy of the history or state;
ContactResultMap.filterpasses a copy that is copied back. Where a copy is impossible (QPProblemin anSQPCallback), the object expires and raises when used later. - An object whose code lives in a plugin library keeps the object that owns that library alive
(
keep_alive<0, 1>onclone(), the contact-manager and kinematics getters): gh-72. - Paths are
str | os.PathLikewhere the argument can only be a path; where astrcould also be content (URDF text, YAML text), the path overload takesos.PathLikeonly (StrictPath). - Binary archives are
bytes. - Containers of Eigen values (
VectorVector3d,VectorIsometry3d) are Python lists.
Threads¶
Threading and the GIL states when a binding releases the GIL; every
Environment method does, so an event callback and a writer on another thread cannot deadlock.
Docstrings and stubs¶
Every public class and method carries an nb::doc string (or a docstring argument), so the
committed .pyi stubs (pixi run stubs) carry it. Defaults restated from upstream are named
constants with units and source; where an upstream object exposes the default
(CollisionCheckConfig().longest_valid_segment_length), it is read from there.