API reference

compas_fab_native is a compas_fab backend: you use it through the regular compas_fab planner API (set_robot_cell, inverse_kinematics, check_collision, plan_cartesian_motion, plan_motion, ...). The pages of compas_fab document those calls; this page covers what is specific to the native backend: its constructor options and the planner options it understands.

compas_fab_native.NativePlanner

NativePlanner(kinematics_solver=None, sphere_options: Optional[dict] = None, exact: bool = True, obstacles: str = 'boxes', esdf_options: Optional[dict] = None, exact_links=None)

Bases: SetRobotCell, SetRobotCellState, ForwardKinematics, InverseKinematics, CheckCollision, PlanCartesianMotion, PlanMotion, PlannerInterface

Planner backed by the native (Rust) motion core.

Parameters:

• kinematics_solver –

  compas_fab analytical solver of the robot (e.g. UR5Kinematics()); its parameters are handed to the core's closed-form IK.

• sphere_options (Optional[dict], default: None ) –

  Sphere fitting options (see model.fit_sphere_sets).

• exact (bool, default: True ) –

  Keep the exact collision meshes in the core. Planned Cartesian paths are then validated on the meshes (parry3d) after the sphere search, and the search continues until the path is collision-free under both models. Default True.

• obstacles (str, default: 'boxes' ) –

  How the sphere search sees static rigid bodies: "boxes" (oriented bounding boxes, default) or "esdf" (a signed distance field of their meshes; bodies with touch links, like a floor, stay boxes).

• esdf_options (Optional[dict], default: None ) –

  voxel (0.02 m), truncation (0.3 m) and margin (0.01 m) of the ESDF.

• exact_links –

  Links to check on their exact geometry inside planning too, not only in the final exact check: None (default), "auto" (the links spheres represent poorly, see poorly_fitted_links) or a list of link names. They are tested as convex hulls (conservative) against each other and the scene's boxes, on every configuration the spheres find free. Useful when the final check keeps rejecting paths near large flat links (a gantry carriage); it slows planning down, and the hulls take free space away. Needs exact=True.

poorly_fitted_links property

poorly_fitted_links

Links whose collision spheres miss their mesh by more than model.EXACT_LINK_MISS (95th percentile): the spheres cannot represent them (a gantry carriage, a tall base), so collisions with them are only caught by the exact check. See the exact_links option.

check_collision

check_collision(robot_cell_state, options=None)

Collision check on the sphere model, or on the exact meshes with options["exact"].

iter_inverse_kinematics

iter_inverse_kinematics(target, robot_cell_state=None, group=None, options=None)

IK solutions of a FrameTarget or PointAxisTarget, collision-free unless options["check_collision"] is False.

Robots with a closed form (kinematics_solver, or a spherical wrist the core derives one for) get all of its solutions; for a PointAxisTarget, those of axis_samples rotations about the axis. Other robots (redundant arms, external axes) use the core's numerical IK, which treats the rotation about a point-axis target's axis as free.

Options

check_collision : bool Only collision-free solutions (sphere model). Default True. ik : str "auto" (default: closed form if there is one), "numeric" or "analytic". max_results : int Numerical IK: distinct solutions at most. Default 8. seed : int Numerical IK: offset of the random seeds. Default 0. The state's configuration is always tried first. axis_samples : int Closed form, point-axis targets: rotations sampled about the axis. Default 16.

plan_cartesian_motion

plan_cartesian_motion(waypoints, start_state, group=None, options=None)

Cartesian path through FrameWaypoints or PointAxisWaypoints.

The tool moves in straight lines between waypoints: frames are interpolated every max_step metres and max_step_angle radians (like MoveIt and PyBullet), and the trajectory has one point per interpolated frame, passing through every waypoint.

Robots with a closed form plan over all IK branches at once (layered graph search). Other robots (redundant arms, external axes) follow the path with numerical IK from several starting solutions and keep the cheapest that stays collision-free. Point-axis waypoints leave the rotation about the axis free: continuously with numerical IK, sampled (free_axis_samples) with the closed form.

Options

max_step : float Largest distance between interpolated frames, metres. Default 0.01. 0 or None: the waypoints only. max_step_distance is accepted as an alias. max_step_angle : float Largest rotation between interpolated frames, radians. Default 0.1. free_axis_samples : int Closed form: rotations about the tool axis sampled per waypoint. Default 1 for frame waypoints (the frames as given), 16 for point-axis waypoints. free_axis_range : float Half-range of that rotation in radians. Default pi. ik : str "auto" (default: closed form if there is one), "numeric" or "analytic". tracks : int Numerical IK: starting solutions followed along the path. Default 8. seed : int Numerical IK: offset of the random seeds. Default 0. max_joint_step : float Largest joint change between consecutive frames (rad, or m for prismatic joints). Default 0.5. start_from_state : bool Begin the path at start_state's configuration. Default False (any IK branch). exact_check : bool Validate the path on the exact meshes (needs NativePlanner(exact=True)). Default True.

plan_motion

plan_motion(target, start_state, group=None, options=None)

Collision-free joint-space motion from start_state to target.

The straight joint-space motion is tried first, then RRT-Connect from the start and from every goal at once, then shortcutting and B-spline smoothing. The result is checked on the exact meshes and re-planned with another seed if it touches them.

Targets

ConfigurationTarget One goal. FrameTarget Every IK solution is a goal; the planner picks whichever it reaches. PointAxisTarget IK solutions of axis_samples rotations about the axis.

Options

range : float Longest tree extension, in joint-space distance. Default 1.0. resolution : float Collision checks per unit of joint-space distance. Default: enough that no robot sphere moves more than about 2 cm between checks (core.default_resolution). max_iterations : int Default 100000. seed : int Sampling sequence offset, for different (reproducible) paths. Default 0. simplify : bool Shortcut and smooth the path. Default True. exact_check : bool Validate the path on the exact meshes. Default True. exact_step : float Largest joint change between exact checks (rad). Default 0.02. axis_samples : int Rotations sampled about a PointAxisTarget's axis. Default 16. time_parameterization : bool Time the path under joint velocity and acceleration limits (TOPP-RA), with blended corners, starting and ending at rest. Points then carry time_from_start, velocities and accelerations. Default True. velocity_scaling, acceleration_scaling : float Fractions of the limits to use. Default 1.0. max_acceleration : float or list Joint acceleration limits (URDFs carry none). Default: twice each joint's velocity limit, i.e. full speed in half a second. blend_tolerance : float Largest joint-space deviation of a blended corner from the planned path. Blends that collide shrink, down to a stop at that corner. Default 0.05. time_step : float Sampling period of the timed trajectory in seconds. Default 0.01. max_joint_step : float Without time parameterization: interpolate the path so no joint moves more than this between points. Default: the path's vertices only.

compas_fab_native.NativeClient

NativeClient()

Bases: ClientInterface

Holds the robot cell, its state and the Rust core built from them.