From ef07e9de3eb3b99d032e45b41f834e49a4bd3912 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20S=C3=B6derstr=C3=B6m?= Date: Mon, 13 May 2024 23:47:51 +0200 Subject: [PATCH] docs: improve docs and examples --- README.md | 18 ++++++++++-------- examples/difference-and-inflate.rs | 5 +---- examples/inflate.rs | 10 +++++++++- src/clipper.rs | 8 ++++---- src/lib.rs | 5 +++-- src/operations/inflate.rs | 11 +++++++++-- src/operations/union.rs | 3 ++- src/path.rs | 11 ++++++++++- src/paths.rs | 11 ++++++++++- 9 files changed, 58 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index b6a7072..4a384ab 100644 --- a/README.md +++ b/README.md @@ -26,18 +26,20 @@ use macroquad::prelude::*; mod helpers; #[macroquad::main("Difference and inflate")] -async fn main() { +async fn main() -> Result<(), ClipperError> { let circle = circle_path((5.0, 5.0), 3.0, 32); + let circle2 = circle_path((6.0, 6.0), 2.0, 32); let rectangle = vec![(0.0, 0.0), (5.0, 0.0), (5.0, 6.0), (0.0, 6.0)]; - let circle2 = circle_path((7.0, 7.0), 1.0, 32); - let result = difference(circle, rectangle, FillRule::default()) - .expect("Failed to run boolean operation"); + let result = circle + .to_clipper_subject() + .add_clip(circle2) + .add_clip(rectangle) + .difference(FillRule::default())?; - let result = difference(result.clone(), circle2, FillRule::default()) - .expect("Failed to run boolean operation"); - - let result2 = inflate(result.clone(), 1.0, JoinType::Round, EndType::Polygon, 0.0); + let result2 = result + .inflate(1.0, JoinType::Round, EndType::Polygon, 0.0) + .simplify(0.01, false); loop { clear_background(BLACK); diff --git a/examples/difference-and-inflate.rs b/examples/difference-and-inflate.rs index 9b76753..5417b52 100644 --- a/examples/difference-and-inflate.rs +++ b/examples/difference-and-inflate.rs @@ -7,13 +7,11 @@ mod helpers; #[macroquad::main("Difference and inflate")] async fn main() -> Result<(), ClipperError> { let circle = circle_path((5.0, 5.0), 3.0, 32); - let circle2 = circle_path((6.0, 6.0), 2.0, 32); - let circle3 = circle_path((7.0, 7.0), 1.0, 32); + let circle2 = circle_path((7.0, 7.0), 1.0, 32); let rectangle = vec![(0.0, 0.0), (5.0, 0.0), (5.0, 6.0), (0.0, 6.0)]; // Functional API let _result = difference(circle.clone(), circle2.clone(), FillRule::default())?; - let _result = difference(_result, circle3.clone(), FillRule::default())?; let _result = difference(_result, rectangle.clone(), FillRule::default())?; let _result2 = inflate(_result, 1.0, JoinType::Round, EndType::Polygon, 0.0); @@ -23,7 +21,6 @@ async fn main() -> Result<(), ClipperError> { let result = circle .to_clipper_subject() .add_clip(circle2) - .add_clip(circle3) .add_clip(rectangle) .difference(FillRule::default())?; diff --git a/examples/inflate.rs b/examples/inflate.rs index ed32c81..591a4fa 100644 --- a/examples/inflate.rs +++ b/examples/inflate.rs @@ -10,9 +10,17 @@ async fn main() { // Functional API let _result = inflate(path.clone(), 1.0, JoinType::Round, EndType::Polygon, 0.0); + let _result = simplify(_result, 0.01, false); // Alternative paths API - let result = path.inflate(1.0, JoinType::Round, EndType::Polygon, 0.0); + let result = path + .inflate(1.0, JoinType::Round, EndType::Polygon, 0.0) + .simplify(0.01, false); + + // NOTE: It is recommented to run simplify after each inflate call as extra + // closely positioned points are likely to be added on each inflate + // call that needs cleanup to reduce the amount of points and + // distortion. loop { clear_background(BLACK); diff --git a/src/clipper.rs b/src/clipper.rs index 9b228c6..d6f317b 100644 --- a/src/clipper.rs +++ b/src/clipper.rs @@ -213,7 +213,7 @@ impl Clipper { /// let path: Paths = vec![(0.2, 0.2), (6.0, 0.2), (6.0, 6.0), (0.2, 6.0)].into(); /// let path2: Paths = vec![(1.2, 1.2), (4.0, 1.2), (1.2, 4.0)].into(); /// - /// let clipper = Clipper::new().add_subject(path).add_clip(path2).union(FillRule::NonZero); + /// let result = Clipper::new().add_subject(path).add_clip(path2).union(FillRule::NonZero); /// ``` /// /// For more details see the original [union](https://www.angusj.com/clipper2/Docs/Units/Clipper/Functions/Union.htm) docs. @@ -231,7 +231,7 @@ impl Clipper { /// let path: Paths = vec![(0.2, 0.2), (6.0, 0.2), (6.0, 6.0), (0.2, 6.0)].into(); /// let path2: Paths = vec![(1.2, 1.2), (4.0, 1.2), (1.2, 4.0)].into(); /// - /// let clipper = Clipper::new().add_subject(path).add_clip(path2).difference(FillRule::NonZero); + /// let result = Clipper::new().add_subject(path).add_clip(path2).difference(FillRule::NonZero); /// ``` /// /// For more details see the original [difference](https://www.angusj.com/clipper2/Docs/Units/Clipper/Functions/Difference.htm) docs. @@ -249,7 +249,7 @@ impl Clipper { /// let path: Paths = vec![(0.2, 0.2), (6.0, 0.2), (6.0, 6.0), (0.2, 6.0)].into(); /// let path2: Paths = vec![(1.2, 1.2), (4.0, 1.2), (1.2, 4.0)].into(); /// - /// let clipper = Clipper::new().add_subject(path).add_clip(path2).intersect(FillRule::NonZero); + /// let result = Clipper::new().add_subject(path).add_clip(path2).intersect(FillRule::NonZero); /// ``` /// /// For more details see the original [intersect](https://www.angusj.com/clipper2/Docs/Units/Clipper/Functions/Intersect.htm) docs. @@ -267,7 +267,7 @@ impl Clipper { /// let path: Paths = vec![(0.2, 0.2), (6.0, 0.2), (6.0, 6.0), (0.2, 6.0)].into(); /// let path2: Paths = vec![(1.2, 1.2), (4.0, 1.2), (1.2, 4.0)].into(); /// - /// let clipper = Clipper::new().add_subject(path).add_clip(path2).xor(FillRule::NonZero); + /// let result = Clipper::new().add_subject(path).add_clip(path2).xor(FillRule::NonZero); /// ``` /// /// For more details see the original [xor](https://www.angusj.com/clipper2/Docs/Units/Clipper/Functions/XOR.htm) docs. diff --git a/src/lib.rs b/src/lib.rs index 2fdf3df..4de3e2f 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -50,8 +50,9 @@ //! let output: Vec> = path_a //! .to_clipper_subject() //! .add_clip(path_b) -//! .difference(FillRule::default())?. -//! into(); +//! .difference(FillRule::default()) +//! .expect("Failed difference operation") +//! .into(); //! //! dbg!(output); //! ``` diff --git a/src/operations/inflate.rs b/src/operations/inflate.rs index e8b7785..e4a4893 100644 --- a/src/operations/inflate.rs +++ b/src/operations/inflate.rs @@ -2,8 +2,14 @@ use clipper2c_sys::{clipper_delete_paths64, clipper_paths64_inflate, clipper_pat use crate::{malloc, EndType, JoinType, Paths, PointScaler}; -/// These functions encapsulate ClipperOffset, the class that performs both -/// polygon and open path offsetting. +/// This function performs both closed path and open path offsetting. +/// +/// For closed paths passing a positive delta number will inflate the path +/// where passing a negative number will shrink the path. +/// +/// **NOTE:** Inflate calls will frequently generate a large amount of very +/// close extra points and it is therefore recommented to almost always call +/// [`simplify`](./fn.simplify.html) on the path after inflating/shrinking it. /// /// # Example /// @@ -13,6 +19,7 @@ use crate::{malloc, EndType, JoinType, Paths, PointScaler}; /// let paths: Paths = vec![(2.0, 2.0), (6.0, 2.0), (6.0, 10.0), (2.0, 6.0)].into(); /// /// let output = inflate(paths, 1.0, JoinType::Round, EndType::Polygon, 0.0); +/// let output = simplify(output, 0.01, false); /// /// dbg!(output); /// ``` diff --git a/src/operations/union.rs b/src/operations/union.rs index ec68ef5..e118295 100644 --- a/src/operations/union.rs +++ b/src/operations/union.rs @@ -1,6 +1,7 @@ use crate::{Clipper, ClipperError, FillRule, Paths, PointScaler}; -/// This function 'unions' closed subject paths, with and without clip paths. +/// This function joins a set of closed subject paths, with and without clip +/// paths. /// /// # Examples /// diff --git a/src/path.rs b/src/path.rs index 118271a..825e881 100644 --- a/src/path.rs +++ b/src/path.rs @@ -161,13 +161,22 @@ impl Path

{ /// Construct a new path offset from this one by a delta distance. /// + /// For closed paths passing a positive delta number will inflate the path + /// where passing a negative number will shrink the path. + /// + /// **NOTE:** Inflate calls will frequently generate a large amount of very + /// close extra points and it is therefore recommented to almost always call + /// [`Path::simplify`] on the path after inflating/deflating it. + /// /// # Examples /// /// ```rust /// use clipper2::*; /// /// let path: Path = vec![(0.0, 0.0), (5.0, 0.0), (5.0, 6.0), (0.0, 6.0)].into(); - /// let inflated = path.inflate(1.0, JoinType::Square, EndType::Polygon, 2.0); + /// let inflated = path + /// .inflate(1.0, JoinType::Square, EndType::Polygon, 2.0) + /// .simplify(0.01, false); /// ``` /// /// For more details see the original [inflate paths](https://www.angusj.com/clipper2/Docs/Units/Clipper/Functions/InflatePaths.htm) docs. diff --git a/src/paths.rs b/src/paths.rs index 62ed2f0..f9e62fd 100644 --- a/src/paths.rs +++ b/src/paths.rs @@ -134,13 +134,22 @@ impl Paths

{ /// Construct a new set of paths offset from this one by a delta distance. /// + /// For closed paths passing a positive delta number will inflate the path + /// where passing a negative number will shrink the path. + /// + /// **NOTE:** Inflate calls will frequently generate a large amount of very + /// close extra points and it is therefore recommented to almost always call + /// [`Paths::simplify`] on the path after inflating/shrinking it. + /// /// # Examples /// /// ```rust /// use clipper2::*; /// /// let paths: Paths = vec![vec![(0.0, 0.0), (5.0, 0.0), (5.0, 6.0), (0.0, 6.0)]].into(); - /// let inflated = paths.inflate(1.0, JoinType::Square, EndType::Polygon, 2.0); + /// let inflated = paths + /// .inflate(1.0, JoinType::Square, EndType::Polygon, 2.0) + /// .simplify(0.01, false); /// ``` /// /// For more details see the original [inflate paths](https://www.angusj.com/clipper2/Docs/Units/Clipper/Functions/InflatePaths.htm) docs.