1 | // Copyright 2018 the Kurbo Authors |
2 | // SPDX-License-Identifier: Apache-2.0 OR MIT |
3 | |
4 | //! 2D geometry, with a focus on curves. |
5 | //! |
6 | //! The kurbo library contains data structures and algorithms for curves and |
7 | //! vector paths. It was designed to serve the needs of 2D graphics applications, |
8 | //! but it is intended to be general enough to be useful for other applications. |
9 | //! It can be used as "vocabulary types" for representing curves and paths, and |
10 | //! also contains a number of computational geometry methods. |
11 | //! |
12 | //! # Examples |
13 | //! |
14 | //! Basic UI-style geometry: |
15 | //! ``` |
16 | //! use kurbo::{Insets, Point, Rect, Size, Vec2}; |
17 | //! |
18 | //! let pt = Point::new(10.0, 10.0); |
19 | //! let vector = Vec2::new(5.0, -5.0); |
20 | //! let pt2 = pt + vector; |
21 | //! assert_eq!(pt2, Point::new(15.0, 5.0)); |
22 | //! |
23 | //! let rect = Rect::from_points(pt, pt2); |
24 | //! assert_eq!(rect, Rect::from_origin_size((10.0, 5.0), (5.0, 5.0))); |
25 | //! |
26 | //! let insets = Insets::uniform(1.0); |
27 | //! let inset_rect = rect - insets; |
28 | //! assert_eq!(inset_rect.size(), Size::new(3.0, 3.0)); |
29 | //! ``` |
30 | //! |
31 | //! Finding the closest position on a [`Shape`]'s perimeter to a [`Point`]: |
32 | //! |
33 | //! ``` |
34 | //! use kurbo::{Circle, ParamCurve, ParamCurveNearest, Point, Shape}; |
35 | //! |
36 | //! const DESIRED_ACCURACY: f64 = 0.1; |
37 | //! |
38 | //! /// Given a shape and a point, returns the closest position on the shape's |
39 | //! /// perimeter, or `None` if the shape is malformed. |
40 | //! fn closest_perimeter_point(shape: impl Shape, pt: Point) -> Option<Point> { |
41 | //! let mut best: Option<(Point, f64)> = None; |
42 | //! for segment in shape.path_segments(DESIRED_ACCURACY) { |
43 | //! let nearest = segment.nearest(pt, DESIRED_ACCURACY); |
44 | //! if best.map(|(_, best_d)| nearest.distance_sq < best_d).unwrap_or(true) { |
45 | //! best = Some((segment.eval(nearest.t), nearest.distance_sq)) |
46 | //! } |
47 | //! } |
48 | //! best.map(|(point, _)| point) |
49 | //! } |
50 | //! |
51 | //! let circle = Circle::new((5.0, 5.0), 5.0); |
52 | //! let hit_point = Point::new(5.0, -2.0); |
53 | //! let expectation = Point::new(5.0, 0.0); |
54 | //! let hit = closest_perimeter_point(circle, hit_point).unwrap(); |
55 | //! assert!(hit.distance(expectation) <= DESIRED_ACCURACY); |
56 | //! ``` |
57 | //! |
58 | //! # Features |
59 | //! |
60 | //! This crate either uses the standard library or the [`libm`] crate for |
61 | //! math functionality. The `std` feature is enabled by default, but can be |
62 | //! disabled, as long as the `libm` feature is enabled. This is useful for |
63 | //! `no_std` environments. However, note that the `libm` crate is not as |
64 | //! efficient as the standard library, and that this crate still uses the |
65 | //! `alloc` crate regardless. |
66 | //! |
67 | //! [`libm`]: https://docs.rs/libm |
68 | |
69 | #![forbid (unsafe_code)] |
70 | #![deny (missing_docs, clippy::trivially_copy_pass_by_ref)] |
71 | #![warn (clippy::doc_markdown, rustdoc::broken_intra_doc_links)] |
72 | #![warn (clippy::semicolon_if_nothing_returned)] |
73 | #![warn (unused_qualifications)] |
74 | #![allow ( |
75 | clippy::unreadable_literal, |
76 | clippy::many_single_char_names, |
77 | clippy::excessive_precision, |
78 | clippy::bool_to_int_with_if |
79 | )] |
80 | #![cfg_attr (docsrs, feature(doc_auto_cfg))] |
81 | #![cfg_attr (all(not(feature = "std" ), not(test)), no_std)] |
82 | |
83 | #[cfg (not(any(feature = "std" , feature = "libm" )))] |
84 | compile_error!("kurbo requires either the `std` or `libm` feature" ); |
85 | |
86 | extern crate alloc; |
87 | |
88 | mod affine; |
89 | mod arc; |
90 | mod bezpath; |
91 | mod circle; |
92 | pub mod common; |
93 | mod cubicbez; |
94 | mod ellipse; |
95 | mod fit; |
96 | mod insets; |
97 | mod line; |
98 | mod mindist; |
99 | pub mod offset; |
100 | mod param_curve; |
101 | mod point; |
102 | mod quadbez; |
103 | mod quadspline; |
104 | mod rect; |
105 | mod rounded_rect; |
106 | mod rounded_rect_radii; |
107 | mod shape; |
108 | pub mod simplify; |
109 | mod size; |
110 | mod stroke; |
111 | mod svg; |
112 | mod translate_scale; |
113 | mod vec2; |
114 | |
115 | pub use crate::affine::Affine; |
116 | pub use crate::arc::{Arc, ArcAppendIter}; |
117 | pub use crate::bezpath::{ |
118 | flatten, segments, BezPath, LineIntersection, MinDistance, PathEl, PathSeg, PathSegIter, |
119 | Segments, |
120 | }; |
121 | pub use crate::circle::{Circle, CirclePathIter, CircleSegment}; |
122 | pub use crate::cubicbez::{cubics_to_quadratic_splines, CubicBez, CubicBezIter, CuspType}; |
123 | pub use crate::ellipse::Ellipse; |
124 | pub use crate::fit::{ |
125 | fit_to_bezpath, fit_to_bezpath_opt, fit_to_cubic, CurveFitSample, ParamCurveFit, |
126 | }; |
127 | pub use crate::insets::Insets; |
128 | pub use crate::line::{ConstPoint, Line, LinePathIter}; |
129 | pub use crate::param_curve::{ |
130 | Nearest, ParamCurve, ParamCurveArclen, ParamCurveArea, ParamCurveCurvature, ParamCurveDeriv, |
131 | ParamCurveExtrema, ParamCurveNearest, DEFAULT_ACCURACY, MAX_EXTREMA, |
132 | }; |
133 | pub use crate::point::Point; |
134 | pub use crate::quadbez::{QuadBez, QuadBezIter}; |
135 | pub use crate::quadspline::QuadSpline; |
136 | pub use crate::rect::{Rect, RectPathIter}; |
137 | pub use crate::rounded_rect::{RoundedRect, RoundedRectPathIter}; |
138 | pub use crate::rounded_rect_radii::RoundedRectRadii; |
139 | pub use crate::shape::Shape; |
140 | pub use crate::size::Size; |
141 | pub use crate::stroke::{ |
142 | dash, stroke, Cap, DashIterator, Dashes, Join, Stroke, StrokeOptLevel, StrokeOpts, |
143 | }; |
144 | pub use crate::svg::{SvgArc, SvgParseError}; |
145 | pub use crate::translate_scale::TranslateScale; |
146 | pub use crate::vec2::Vec2; |
147 | |