deke_linear/lib.rs
1//! Constant-TCP-speed Cartesian polyline following for serial manipulators.
2//!
3//! Where the `deke-topp*` retimers are time-optimal (maximise speed under caps),
4//! `deke-linear` holds a *constant* TCP travel speed — the requirement for
5//! welding and similar process motions — and degrades gracefully near
6//! singularities. It is a CNC-style constant-feedrate interpolator in three
7//! stages:
8//!
9//! - **Stage A** ([`path`]) conditions the raw polyline into smooth, arc-length
10//! parameterised [`CartesianRun`]s, splitting at sharp corners.
11//! - **Stage B** ([`planner`]) resolves each run to a continuous joint path by
12//! analytic-IK branch tracking, steering away from singularities
13//! ([`CartesianLinearPlanner`], implements [`deke_types::Planner`]).
14//! - **Stage C** ([`retimer`]) holds the commanded speed wherever the joint
15//! v/a/j limits allow and dips smoothly where they don't
16//! ([`ConstantSpeedRetimer`], implements [`deke_types::Retimer`]).
17//!
18//! [`LinearFollower`] runs all three and stitches the per-run trajectories.
19//!
20//! ```no_run
21//! # use deke_linear::*;
22//! # use deke_types::glam::DAffine3;
23//! # fn run<FK: deke_types::ContinuousFKChain<6, f64> + deke_types::IkSolver<6, f64>>(
24//! # fk: &FK, poses: &[DAffine3], cfg: &FollowConfig<6>) {
25//! let follower = LinearFollower::new(fk);
26//! // `NoopValidator` plans without obstacle checks; pass a real `Validator`
27//! // (and its context) to route the arm around obstacles inside the planner.
28//! let (traj, diag) = follower.follow(poses, cfg, &NoopValidator::<6>, &()).unwrap();
29//! # let _ = (traj, diag);
30//! # }
31//! ```
32//!
33//! For a symmetric welding torch, declare the free tool-axis on
34//! [`FollowConfig::redundant`] and the [`RedundantLinearPlanner`] resolves the yaw
35//! globally to dodge singularities — and, with a real `Validator`, obstacles.
36
37pub mod constraints;
38pub mod diagnostic;
39pub mod error;
40pub mod follower;
41pub mod path;
42pub mod planner;
43pub mod redundant;
44pub mod retimer;
45mod util;
46
47pub use constraints::{
48 FollowConfig, JointLimits, LinearConstraints, PathConditioning, PlannerOptions,
49};
50pub use diagnostic::{
51 LinearFollowDiagnostic, LinearPlannerDiagnostic, LinearRetimerDiagnostic, RedundantDiagnostic,
52};
53pub use error::LinearError;
54pub use follower::{LinearFollower, NoopValidator};
55pub use path::{CartesianRun, condition};
56pub use planner::CartesianLinearPlanner;
57pub use redundant::{RedundantAxis, RedundantLinearPlanner, RedundantOptions};
58pub use retimer::ConstantSpeedRetimer;