Refactor offset configuration: replace debug flags with svg flags for original and final outputs in offset examples and core logic.

Author: radevgit

examples/offset_arcline.rs

@@ -7,9 +7,9 @@ fn main() {
     let mut svg = SVG::new(300.0, 300.0, "/tmp/arcline.svg");
     cfg.svg = Some(&mut svg);
     // Show original arcline in SVG output
-    cfg.debug_orig = true;
+    cfg.svg_orig = true;
     // Show final offset arclines in SVG output
-    cfg.debug_final = true;
+    cfg.svg_final = true;
 
     let arc0 = arc_circle_parametrization(point(0.0, 0.0), point(100.0, 100.0), 0.0);
     let arc1 = arc_circle_parametrization(point(100.0, 100.0), point(200.0, 0.0), 0.5);

examples/offset_pline1.rs

@@ -6,8 +6,8 @@ fn main() {
     // This will create an SVG file at /tmp/pline1.svg
     let mut svg = SVG::new(300.0, 300.0, "/tmp/pline1.svg");
     cfg.svg = Some(&mut svg);
-    cfg.debug_orig = true;
-    cfg.debug_prune = true;
+    cfg.svg_orig = true;
+    cfg.svg_prune = true;
 
     let poly_orig = pline_01()[0].clone();
     // Translate to fit in the SVG viewport

examples/offset_polyline.rs

@@ -7,9 +7,9 @@ fn main() {
     let mut svg = SVG::new(300.0, 300.0, "/tmp/polyline.svg");
     cfg.svg = Some(&mut svg);
     // Show original polyline in SVG output
-    cfg.debug_orig = true;
+    cfg.svg_orig = true;
     // Show final offset polylines in SVG output
-    cfg.debug_final = true;
+    cfg.svg_final = true;
 
     let poly_orig = vec![
         pvertex(point(0.0, 0.0), 0.0),
@@ -33,8 +33,5 @@ fn main() {
         // Write svg to file
         svg.write_stroke_width(0.1);
     }
-    assert!(
-        offset_polylines.len() == 2,
-        "Wrong number of offset polylines generated"
-    );
+    assert!(offset_polylines.len() == 2);
 }

src/lib.rs

@@ -4,7 +4,29 @@
 //!
 //! # Examples
 //!
-//! Check "examples" directory for usage examples.
+//! ```rust
+//! use geom::prelude::*;
+//! use offroad::prelude::{OffsetCfg, offset_polyline_to_polyline};
+//!
+//! // Create a simple L-shaped polyline
+//! let poly = vec![
+//!     pvertex(point(0.0, 0.0), 0.0),    // Start point
+//!     pvertex(point(10.0, 0.0), 0.0),   // Horizontal line
+//!     pvertex(point(10.0, 10.0), 0.0),  // Vertical line
+//! ];
+//!
+//! // Create default configuration
+//! let mut cfg = OffsetCfg::default();
+//!
+//! // Offset by 2.0 units to the right
+//! let offset_polylines = offset_polyline_to_polyline(&poly, 2.0, &mut cfg);
+//!
+//! // The function returns a vector of polylines
+//! assert!(offset_polylines.len() == 1);
+//! assert!(offset_polylines[0].len() == 6);
+//! ```
+//!
+//! Check "examples" directory for more usage examples.
 
 
 // Offsetting algorithm components

src/offset.rs

@@ -12,33 +12,42 @@ use crate::{
     offset_split_arcs::offset_split_arcs
 };
 
+/// Configuration options for offsetting operations.
 pub struct OffsetCfg<'a> {
-    pub svg: Option<&'a mut SVG>, // Optional SVG context for rendering
-    pub reconnect: bool,          // Flag to indicate if reconnecting arcs is needed
-    pub debug_orig: bool,         // Flag to enable debug original polyline
-    pub debug_row: bool,          // Flag to enable debug row offsets
-    pub debug_connect: bool,      // Flag to enable debug connect offsets
-    pub debug_split: bool,        // Flag to enable debug split offsets
-    pub debug_prune: bool,        // Flag to enable debug pruned offsets
-    pub debug_final: bool,        // Flag to enable debug final offsets
+    /// Optional SVG context for rendering
+    pub svg: Option<&'a mut SVG>, 
+    /// Flag to indicate if reconnecting arcs is needed
+    pub reconnect: bool,
+    /// Flag to enable writing in svg original polyline
+    pub svg_orig: bool,
+    /// Flag to enable writing in svg raw offsets
+    pub svg_raw: bool,
+    /// Flag to enable writing in svg connect offsets
+    pub svg_connect: bool,
+    /// Flag to enable writing in svg split offsets
+    pub svg_split: bool,
+    /// Flag to enable writing in svg pruned offsets
+    pub svg_prune: bool,
+    /// Flag to enable writing in svg final offsets
+    pub svg_final: bool,
 }
 
 impl<'a> Default for OffsetCfg<'a> {
     fn default() -> Self {
         OffsetCfg {
-            svg: None,            // SVG context can be set later
-            reconnect: true,      // Default to reconnecting arcs
-            debug_orig: false,    // Debugging flags are off by default
-            debug_row: false,     // Debugging flags are off by default
-            debug_connect: false, // Debugging flags are off by default
-            debug_split: false,   // Debugging flags are off by default
-            debug_prune: false,   // Debugging flags are off by default
-            debug_final: false,   // Debugging reconnect arcs
+            svg: None,
+            reconnect: true,
+            svg_orig: false,
+            svg_raw: false,
+            svg_connect: false,
+            svg_split: false,
+            svg_prune: false,
+            svg_final: false,
         }
     }
 }
 
-/// Computes the offset of a polyline and returns result as simplified polylines.
+/// Computes the offset of a polyline and returns result as multiple polylines.
 ///
 /// This is the main entry point for polyline offsetting. It takes an input polyline,
 /// applies the specified offset distance, and returns a vector of output polylines.
@@ -98,7 +107,7 @@ pub fn offset_polyline_to_polyline(
     cfg: &mut OffsetCfg,
 ) -> Vec<Polyline> {
     if let Some(svg) = cfg.svg.as_deref_mut()
-        && cfg.debug_orig
+        && cfg.svg_orig
     {
         svg.polyline(poly, "red");
     }
@@ -117,15 +126,15 @@ pub fn offset_polyline_to_polyline(
     let final_poly = arcs_to_polylines(&reconnect_arcs);
 
     if let Some(svg) = cfg.svg.as_deref_mut() {
-        if cfg.debug_final {
+        if cfg.svg_final {
             svg.polylines(&final_poly, "violet");
         }
     }
 
     final_poly
 }
 
-/// Computes the offset of an Arcline and returns result as Arcline-s.
+/// Computes the offset of an Arcline and returns result as multiple Arcline-s.
 ///
 /// This function is similar to `offset_polyline_to_polyline` but operates on arclines
 /// (sequences of arcs). This is useful when
@@ -185,7 +194,7 @@ pub fn offset_polyline_to_polyline(
 ///
 pub fn offset_arcline_to_arcline(arcs: &Arcline, off: f64, cfg: &mut OffsetCfg) -> Vec<Arcline> {
     if let Some(svg) = cfg.svg.as_deref_mut()
-        && cfg.debug_orig
+        && cfg.svg_orig
     {
         svg.arcline(arcs, "red");
     }
@@ -212,7 +221,7 @@ pub fn offset_arcline_to_arcline(arcs: &Arcline, off: f64, cfg: &mut OffsetCfg)
     }
 
     if let Some(svg) = cfg.svg.as_deref_mut() {
-        if cfg.debug_final {
+        if cfg.svg_final {
             svg.arclines(&final_arcs, "violet");
         }
     }
@@ -236,6 +245,8 @@ fn offset_arcline_to_arcline_impl(arcs: &Arcline, off: f64, cfg: &mut OffsetCfg)
     offset_arcs
 }
 
+#[doc(hidden)]
+/// Converts a vector of arcs into a vector of polylines.
 pub fn arcs_to_polylines(reconnect_arcs: &Vec<Vec<Arc>>) -> Vec<Polyline> {
     let mut polylines = Vec::with_capacity(reconnect_arcs.len());
     for arcs in reconnect_arcs.iter() {
@@ -245,9 +256,10 @@ pub fn arcs_to_polylines(reconnect_arcs: &Vec<Vec<Arc>>) -> Vec<Polyline> {
     polylines
 }
 
-// function to convert from Vec<Arc> to Polyline
-// Note: arcs is a loop of arcs and when converting to PVertex,
-// some Arc can be either "a" to "b" or "b" to "a" oriented
+#[doc(hidden)]
+/// function to convert from Vec<Arc> to Polyline
+/// Note: arcs is a loop of arcs and when converting to PVertex,
+/// some Arc can be either "a" to "b" or "b" to "a" oriented
 pub fn arcs_to_polylines_single(arcs: &Vec<Arc>) -> Polyline {
     let mut polyline = Vec::new();
 
@@ -384,6 +396,8 @@ mod test_arcs_to_polylines {
     }
 }
 
+
+#[doc(hidden)]
 pub fn offset_polyline_multiple(
     poly: &Polyline,
     step: f64,
@@ -404,21 +418,21 @@ pub fn offset_polyline_multiple(
 fn offset_single(poly_raws: &Vec<Vec<OffsetRaw>>, off: f64, cfg: &mut OffsetCfg) -> Vec<Arc> {
     let offset_raw = offset_polyline_raw::offset_polyline_raw(&poly_raws, off);
     if let Some(svg) = cfg.svg.as_deref_mut()
-        && cfg.debug_row
+        && cfg.svg_raw
     {
         svg_offset_raws(svg, &offset_raw, "blue");
     }
 
     let offset_connect = offset_connect_raw(&offset_raw, off);
     if let Some(svg) = cfg.svg.as_deref_mut()
-        && cfg.debug_connect
+        && cfg.svg_connect
     {
         svg.arclines(&offset_connect, "violet");
     }
 
     let mut offset_split = offset_split_arcs(&offset_raw, &offset_connect);
     if let Some(svg) = cfg.svg.as_deref_mut()
-        && cfg.debug_split
+        && cfg.svg_split
     {
         svg.arcline(&offset_split, "violet");
         svg.offset_segments_single_points(&offset_split, "violet");
@@ -427,14 +441,16 @@ fn offset_single(poly_raws: &Vec<Vec<OffsetRaw>>, off: f64, cfg: &mut OffsetCfg)
     let offset_prune = offset_prune_invalid(&poly_raws, &mut offset_split, off);
 
     if let Some(svg) = cfg.svg.as_deref_mut()
-        && cfg.debug_prune
+        && cfg.svg_prune
     {
         svg.arcline(&offset_prune, "violet");
         svg.offset_segments_single_points(&offset_prune, "violet");
     }
     offset_prune
 }
 
+
+#[doc(hidden)]
 pub fn svg_offset_raws(svg: &mut SVG, offset_raws: &Vec<Vec<OffsetRaw>>, color: &str) {
     for raw in offset_raws {
         for seg in raw {
@@ -1585,6 +1601,7 @@ pub fn check_if_segments_intersect(off0: OffsetSegment, off1: OffsetSegment) ->
 // }
 
 /// Test polyline for offseting.
+/// Has a mix of positive and negative offsets.
 pub fn pline_01() -> Vec<Polyline> {
     let pline = vec![
         pvertex(point(100.0, 100.0), 1.5),
@@ -1617,6 +1634,8 @@ pub fn pline_01() -> Vec<Polyline> {
     return plines;
 }
 
+
+/// Test polyline for offseting.
 pub fn pline_02() -> Polyline {
     let pline = vec![
         pvertex(point(50.0, 50.0), ZERO),
@@ -2016,6 +2035,7 @@ pub fn pline_04() -> Vec<Polyline> {
 
 // }
 
+#[doc(hidden)]
 pub fn polyline_to_arcs(plines: &Vec<Polyline>) -> Vec<Vec<Arc>> {
     let mut varcs: Vec<Vec<Arc>> = Vec::new();
     for pline in plines {
@@ -2024,6 +2044,7 @@ pub fn polyline_to_arcs(plines: &Vec<Polyline>) -> Vec<Vec<Arc>> {
     varcs
 }
 
+#[doc(hidden)]
 fn polyline_to_arcs_single(pline: &Polyline) -> Vec<Arc> {
     let mut arcs = Vec::with_capacity(pline.len() + 1);
     let last = pline.len() - 1;

src/offset_reconnect_arcs.rs

@@ -353,13 +353,6 @@ pub fn remove_bridge_arcs(arcs: &mut Vec<Arc>) {
 /// - Prefers shortest cycles when multiple cycles share vertices
 /// - Reference: "Introduction to Algorithms" by Cormen et al., Chapter 22 (Graph Algorithms)
 /// 
-/// # Examples
-/// ```rust
-/// use offroad::find_connected_components;
-/// let graph = vec![(0, 1), (1, 2), (2, 0), (3, 4)];
-/// let components = find_connected_components(&graph);
-/// // Returns cycles like [[0, 1, 2]] for triangle and potentially isolated vertices
-/// ```
 pub fn find_connected_components(graph: &[(usize, usize)]) -> Vec<Vec<usize>> {
     // Optimized for graphs where each vertex has degree 1-4 only
     // This is typical for arc connection graphs in geometric applications