curve: add ParamCurveTangent for pointwise tangents

Add `ParamCurveTangent` as an additive companion to `ParamCurveDeriv` for code that needs a tangent vector at a parameter value without requiring a derivative curve object.

Place the new trait alongside the other curve traits in `param_curve.rs`, implement it for `Line`, `ConstPoint`, `QuadBez`, `CubicBez`, `Arc`, and `PathSeg`, and use it in internal call sites that were spelling pointwise tangent queries via `deriv().eval(t).to_vec2()`.

Add tests that check the new tangent API against the existing derivative-curve behavior, cover degenerate normalization cases, and validate `Arc`'s tangent formula and reversed-sweep behavior.

Author: waywardmonkeys

CHANGELOG.md

@@ -21,6 +21,7 @@ This release has an [MSRV][] of 1.85.
 - Component-wise `Insets::min/max` methods. ([#548][] by [@xStrom][])
 - Ability to add and subtract `Insets` from other `Insets`. ([#549][] by [@xStrom][])
 - `Arc` now implements `ParamCurve`. ([#378][] by [@waywardmonkeys][])
+- Add `ParamCurveTangent` for pointwise tangents. ([#556][] by [@waywardmonkeys][])
 
 ## Changed
 
@@ -288,6 +289,7 @@ Note: A changelog was not kept for or before this release
 [#545]: https://github.com/linebender/kurbo/pull/545
 [#548]: https://github.com/linebender/kurbo/pull/548
 [#549]: https://github.com/linebender/kurbo/pull/549
+[#556]: https://github.com/linebender/kurbo/pull/556
 
 [Unreleased]: https://github.com/linebender/kurbo/compare/v0.13.0...HEAD
 [0.13.0]: https://github.com/linebender/kurbo/releases/tag/v0.13.0

kurbo/src/arc.rs

@@ -3,7 +3,7 @@
 
 //! An ellipse arc.
 
-use crate::{Affine, Ellipse, ParamCurve, PathEl, Point, Rect, Shape, Vec2};
+use crate::{Affine, Ellipse, ParamCurve, ParamCurveTangent, PathEl, Point, Rect, Shape, Vec2};
 use core::{
     f64::consts::{FRAC_PI_2, PI},
     iter,
@@ -193,6 +193,12 @@ impl ParamCurve for Arc {
     }
 }
 
+impl ParamCurveTangent for Arc {
+    fn tangent(&self, t: f64) -> Vec2 {
+        self.sweep_angle * sample_ellipse(self.radii, self.x_rotation, self.angle_at(t) + FRAC_PI_2)
+    }
+}
+
 impl Shape for Arc {
     type PathElementsIter<'iter> = iter::Chain<iter::Once<PathEl>, ArcAppendIter>;
 
@@ -248,7 +254,7 @@ impl Mul<Arc> for Affine {
 mod tests {
     use core::f64::consts::{FRAC_PI_4, FRAC_PI_6};
 
-    use crate::ParamCurve;
+    use crate::{ParamCurve, ParamCurveTangent};
 
     use super::*;
 
@@ -321,6 +327,21 @@ mod tests {
         assert_point_near(reversed.eval(0.5), arc.eval(0.5));
     }
 
+    #[test]
+    fn tangent_circle_matches_closed_form() {
+        let arc = Arc::new((0.0, 0.0), (2.0, 2.0), 0.0, PI / 2.0, 0.0);
+        assert!((arc.tangent(0.0) - Vec2::new(0.0, PI)).hypot() <= 1e-12);
+        assert!(
+            (arc.tangent(0.5) - Vec2::new(-PI / 2.0_f64.sqrt(), PI / 2.0_f64.sqrt())).hypot()
+                <= 1e-12
+        );
+        assert!((arc.tangent(1.0) - Vec2::new(-PI, 0.0)).hypot() <= 1e-12);
+
+        let reversed = arc.reversed();
+        assert!((reversed.tangent(0.0) - Vec2::new(PI, 0.0)).hypot() <= 1e-12);
+        assert!((reversed.tangent(1.0) - Vec2::new(0.0, -PI)).hypot() <= 1e-12);
+    }
+
     #[test]
     fn subsegment_matches_original() {
         let arc = Arc::new((1.0, -4.0), (3.0, 2.0), -FRAC_PI_4, PI, FRAC_PI_6);

kurbo/src/bezpath.rs

@@ -17,7 +17,8 @@ use crate::common::{solve_cubic, solve_quadratic};
 use crate::MAX_EXTREMA;
 use crate::{
     Affine, CubicBez, Line, Nearest, ParamCurve, ParamCurveArclen, ParamCurveArea,
-    ParamCurveExtrema, ParamCurveNearest, Point, QuadBez, Rect, Shape, TranslateScale, Vec2,
+    ParamCurveExtrema, ParamCurveNearest, ParamCurveTangent, Point, QuadBez, Rect, Shape,
+    TranslateScale, Vec2,
 };
 
 #[cfg(not(feature = "std"))]
@@ -913,6 +914,16 @@ impl ParamCurve for PathSeg {
     }
 }
 
+impl ParamCurveTangent for PathSeg {
+    fn tangent(&self, t: f64) -> Vec2 {
+        match *self {
+            PathSeg::Line(line) => line.tangent(t),
+            PathSeg::Quad(quad) => quad.tangent(t),
+            PathSeg::Cubic(cubic) => cubic.tangent(t),
+        }
+    }
+}
+
 impl ParamCurveArclen for PathSeg {
     fn arclen(&self, accuracy: f64) -> f64 {
         match *self {

kurbo/src/cubicbez.rs

@@ -17,7 +17,8 @@ use crate::common::{
 };
 use crate::{
     Affine, Nearest, ParamCurve, ParamCurveArclen, ParamCurveArea, ParamCurveCurvature,
-    ParamCurveDeriv, ParamCurveExtrema, ParamCurveNearest, PathEl, Point, QuadBez, Rect, Shape,
+    ParamCurveDeriv, ParamCurveExtrema, ParamCurveNearest, ParamCurveTangent, PathEl, Point,
+    QuadBez, Rect, Shape,
 };
 
 #[cfg(not(feature = "std"))]
@@ -441,9 +442,11 @@ impl CubicBez {
             let nearest = q.nearest(Point::ORIGIN, 1e-9);
             // detect whether curvature at minimum derivative exceeds 1/dimension,
             // without division.
-            let d = q.eval(nearest.t);
-            let d2 = q.deriv().eval(nearest.t);
-            let cross = d.to_vec2().cross(d2.to_vec2());
+            let d = q.eval(nearest.t).to_vec2();
+            // `q` is the first-derivative curve of `self`, so `q.tangent(t)`
+            // is the second derivative of `self` at `t`.
+            let d2 = q.tangent(nearest.t);
+            let cross = d.cross(d2);
             if nearest.distance_sq.powi(3) <= (cross * dimension).powi(2) {
                 let a = 3. * det_012 + det_023 - 2. * det_013;
                 let b = -3. * det_012 + det_013;
@@ -560,10 +563,9 @@ impl ParamCurve for CubicBez {
         let (t0, t1) = (range.start, range.end);
         let p0 = self.eval(t0);
         let p3 = self.eval(t1);
-        let d = self.deriv();
         let scale = (t1 - t0) * (1.0 / 3.0);
-        let p1 = p0 + scale * d.eval(t0).to_vec2();
-        let p2 = p3 - scale * d.eval(t1).to_vec2();
+        let p1 = p0 + scale * self.tangent(t0);
+        let p2 = p3 - scale * self.tangent(t1);
         CubicBez { p0, p1, p2, p3 }
     }
 
@@ -613,6 +615,17 @@ impl ParamCurveDeriv for CubicBez {
     }
 }
 
+impl ParamCurveTangent for CubicBez {
+    #[inline]
+    fn tangent(&self, t: f64) -> Vec2 {
+        let mt = 1.0 - t;
+        let d01 = self.p1 - self.p0;
+        let d12 = self.p2 - self.p1;
+        let d23 = self.p3 - self.p2;
+        3.0 * (d01 * (mt * mt) + d12 * (2.0 * mt * t) + d23 * (t * t))
+    }
+}
+
 fn arclen_quadrature_core(coeffs: &[(f64, f64)], dm: Vec2, dm1: Vec2, dm2: Vec2) -> f64 {
     coeffs
         .iter()
@@ -832,8 +845,8 @@ pub fn cubics_to_quadratic_splines(curves: &[CubicBez], accuracy: f64) -> Option
 mod tests {
     use crate::{
         cubics_to_quadratic_splines, Affine, CubicBez, Nearest, ParamCurve, ParamCurveArclen,
-        ParamCurveArea, ParamCurveDeriv, ParamCurveExtrema, ParamCurveNearest, Point, QuadBez,
-        QuadSpline,
+        ParamCurveArea, ParamCurveDeriv, ParamCurveExtrema, ParamCurveNearest, ParamCurveTangent,
+        Point, QuadBez, QuadSpline,
     };
 
     #[test]
@@ -856,6 +869,7 @@ mod tests {
             let d_approx = (p1 - p) * delta.recip();
             let d = deriv.eval(t).to_vec2();
             assert!((d - d_approx).hypot() < delta * 2.0);
+            assert!((c.tangent(t) - d).hypot() < 1e-12);
         }
     }
 

kurbo/src/lib.rs

@@ -168,7 +168,7 @@ pub use crate::line::{ConstPoint, Line, LinePathIter};
 pub use crate::moments::{Moments, ParamCurveMoments};
 pub use crate::param_curve::{
     Nearest, ParamCurve, ParamCurveArclen, ParamCurveArea, ParamCurveCurvature, ParamCurveDeriv,
-    ParamCurveExtrema, ParamCurveNearest, DEFAULT_ACCURACY, MAX_EXTREMA,
+    ParamCurveExtrema, ParamCurveNearest, ParamCurveTangent, DEFAULT_ACCURACY, MAX_EXTREMA,
 };
 pub use crate::point::Point;
 pub use crate::quadbez::{QuadBez, QuadBezIter};

kurbo/src/line.rs

@@ -9,8 +9,8 @@ use arrayvec::ArrayVec;
 
 use crate::{
     Affine, Nearest, ParamCurve, ParamCurveArclen, ParamCurveArea, ParamCurveCurvature,
-    ParamCurveDeriv, ParamCurveExtrema, ParamCurveNearest, PathEl, Point, Rect, Shape, Vec2,
-    DEFAULT_ACCURACY, MAX_EXTREMA,
+    ParamCurveDeriv, ParamCurveExtrema, ParamCurveNearest, ParamCurveTangent, PathEl, Point, Rect,
+    Shape, Vec2, DEFAULT_ACCURACY, MAX_EXTREMA,
 };
 
 /// A single line.
@@ -138,6 +138,13 @@ impl ParamCurveDeriv for Line {
     }
 }
 
+impl ParamCurveTangent for Line {
+    #[inline]
+    fn tangent(&self, _t: f64) -> Vec2 {
+        self.p1 - self.p0
+    }
+}
+
 impl ParamCurveArclen for Line {
     #[inline]
     fn arclen(&self, _accuracy: f64) -> f64 {
@@ -244,6 +251,13 @@ impl ParamCurveDeriv for ConstPoint {
     }
 }
 
+impl ParamCurveTangent for ConstPoint {
+    #[inline]
+    fn tangent(&self, _t: f64) -> Vec2 {
+        Vec2::ZERO
+    }
+}
+
 impl ParamCurveArclen for ConstPoint {
     #[inline(always)]
     fn arclen(&self, _accuracy: f64) -> f64 {

kurbo/src/param_curve.rs

@@ -7,7 +7,7 @@ use core::ops::Range;
 
 use arrayvec::ArrayVec;
 
-use crate::{common, Point, Rect};
+use crate::{common, Point, Rect, Vec2};
 
 #[cfg(not(feature = "std"))]
 use crate::common::FloatFuncs;
@@ -51,6 +51,9 @@ pub trait ParamCurve: Sized {
 // TODO: I might not want to have separate traits for all these.
 
 /// A differentiable parameterized curve.
+///
+/// For code that only needs the tangent vector at a parameter value, see
+/// [`ParamCurveTangent`].
 pub trait ParamCurveDeriv {
     /// The parametric curve obtained by taking the derivative of this one.
     type DerivResult: ParamCurve;
@@ -78,6 +81,29 @@ pub trait ParamCurveDeriv {
     }
 }
 
+/// A parameterized curve with a tangent vector.
+///
+/// This trait complements [`ParamCurveDeriv`] by exposing the most common
+/// derivative query directly as a vector-valued operation.
+pub trait ParamCurveTangent: ParamCurve {
+    /// Evaluate the tangent vector at parameter `t`.
+    ///
+    /// Generally `t` is in the range `[0, 1]`.
+    ///
+    /// Degenerate curves may return the zero vector.
+    fn tangent(&self, t: f64) -> Vec2;
+
+    /// Evaluate the tangent vector at parameter `t` and normalize it.
+    ///
+    /// Returns `None` when the tangent has zero length and therefore does
+    /// not admit a unit-length normalization.
+    fn unit_tangent(&self, t: f64) -> Option<Vec2> {
+        let tangent = self.tangent(t);
+        let norm = tangent.hypot();
+        (norm > 0.0).then_some(tangent / norm)
+    }
+}
+
 /// A parameterized curve that can have its arc length measured.
 pub trait ParamCurveArclen: ParamCurve {
     /// The arc length of the curve.
@@ -219,3 +245,59 @@ pub trait ParamCurveExtrema: ParamCurve {
         bbox
     }
 }
+
+#[cfg(test)]
+mod tangent_tests {
+    use crate::{CubicBez, Line, ParamCurve, ParamCurveDeriv, QuadBez, Vec2};
+
+    use super::ParamCurveTangent;
+
+    fn assert_vec_near(actual: Vec2, expected: Vec2) {
+        let epsilon = 1e-12;
+        assert!(
+            (actual - expected).hypot() <= epsilon,
+            "expected {expected:?}, got {actual:?}"
+        );
+    }
+
+    #[test]
+    fn line_tangent_matches_displacement() {
+        let line = Line::new((1.0, 2.0), (4.0, 6.0));
+        let expected = Vec2::new(3.0, 4.0);
+        assert_vec_near(line.tangent(0.0), expected);
+        assert_vec_near(line.tangent(0.5), expected);
+        assert_vec_near(line.tangent(1.0), expected);
+        assert_vec_near(line.tangent(0.25), expected);
+        assert_vec_near(line.unit_tangent(0.25).unwrap(), expected.normalize());
+    }
+
+    #[test]
+    fn degenerate_line_has_no_unit_tangent() {
+        let line = Line::new((1.0, 2.0), (1.0, 2.0));
+        assert_eq!(line.tangent(0.5), Vec2::ZERO);
+        assert_eq!(line.unit_tangent(0.5), None);
+    }
+
+    #[test]
+    fn const_point_has_no_unit_tangent() {
+        let point = Line::new((2.0, -3.0), (5.0, 1.0)).deriv();
+        assert_eq!(point.tangent(0.5), Vec2::ZERO);
+        assert_eq!(point.unit_tangent(0.5), None);
+    }
+
+    #[test]
+    fn quad_tangent_matches_derivative_curve() {
+        let quad = QuadBez::new((0.0, 0.0), (2.0, 3.0), (4.0, 0.0));
+        for t in [0.0, 0.25, 0.5, 1.0] {
+            assert_vec_near(quad.tangent(t), quad.deriv().eval(t).to_vec2());
+        }
+    }
+
+    #[test]
+    fn cubic_tangent_matches_derivative_curve() {
+        let cubic = CubicBez::new((0.0, 0.0), (1.0, 2.0), (3.0, 2.0), (4.0, 0.0));
+        for t in [0.0, 0.25, 0.5, 1.0] {
+            assert_vec_near(cubic.tangent(t), cubic.deriv().eval(t).to_vec2());
+        }
+    }
+}

kurbo/src/quadbez.rs

@@ -11,8 +11,8 @@ use crate::common::{solve_cubic, solve_quadratic};
 use crate::MAX_EXTREMA;
 use crate::{
     Affine, CubicBez, Line, Nearest, ParamCurve, ParamCurveArclen, ParamCurveArea,
-    ParamCurveCurvature, ParamCurveDeriv, ParamCurveExtrema, ParamCurveNearest, PathEl, Point,
-    Rect, Shape,
+    ParamCurveCurvature, ParamCurveDeriv, ParamCurveExtrema, ParamCurveNearest, ParamCurveTangent,
+    PathEl, Point, Rect, Shape, Vec2,
 };
 
 #[cfg(not(feature = "std"))]
@@ -262,6 +262,14 @@ impl ParamCurveDeriv for QuadBez {
     }
 }
 
+impl ParamCurveTangent for QuadBez {
+    #[inline]
+    fn tangent(&self, t: f64) -> Vec2 {
+        let mt = 1.0 - t;
+        2.0 * (((self.p1 - self.p0) * mt) + ((self.p2 - self.p1) * t))
+    }
+}
+
 impl ParamCurveArclen for QuadBez {
     /// Arclength of a quadratic Bézier segment.
     ///
@@ -426,7 +434,7 @@ impl Mul<QuadBez> for Affine {
 mod tests {
     use crate::{
         Affine, Nearest, ParamCurve, ParamCurveArclen, ParamCurveArea, ParamCurveDeriv,
-        ParamCurveExtrema, ParamCurveNearest, Point, QuadBez,
+        ParamCurveExtrema, ParamCurveNearest, ParamCurveTangent, Point, QuadBez,
     };
 
     fn assert_near(p0: Point, p1: Point, epsilon: f64) {
@@ -447,6 +455,7 @@ mod tests {
             let d_approx = (p1 - p) * delta.recip();
             let d = deriv.eval(t).to_vec2();
             assert!((d - d_approx).hypot() < delta * 2.0);
+            assert!((q.tangent(t) - d).hypot() < 1e-12);
         }
     }