javadocs

Author: micycle1

pom.xml

@@ -4,7 +4,7 @@
 	<modelVersion>4.0.0</modelVersion>
 	<groupId>micycle</groupId>
 	<artifactId>clipper2</artifactId>
-	<version>1.2.4-SNAPSHOT</version>
+	<version>1.2.4</version>
 	<name>Clipper2</name>
 	<properties>
 		<jmh.version>1.36</jmh.version>

src/main/java/clipper2/Clipper.java

@@ -31,6 +31,64 @@
 import clipper2.rectclip.RectClip64;
 import clipper2.rectclip.RectClipLines64;
 
+/**
+ * Line and polygon clipping, and offsetting.
+ * <p>
+ * This unit has been designed to hide the library's complexities behind a
+ * number of simple functions. However, not all of the library's features are
+ * accessible here. Less commonly needed features that provide more flexibility
+ * can still be accessed from the other units.
+ * <p>
+ * <h2>Boolean operations for polygon clipping:</h2>
+ * <ul>
+ * <li><b>AND (intersection)</b> - regions covered by both subject and clip
+ * polygons</li>
+ * <li><b>OR (union)</b> - regions covered by subject or clip polygons, or both
+ * polygons</li>
+ * <li><b>NOT (difference)</b> - regions covered by subject, but not clip
+ * polygons</li>
+ * <li><b>XOR (exclusive or)</b> - regions covered by subject or clip polygons,
+ * but not both</li>
+ * </ul>
+ * Of these four operations, only <code>difference</code> is non-commutative.
+ * This means that <code>subject</code> and <code>clip</code> paths are
+ * interchangeable except when performing difference operations (and as long as
+ * subject paths are closed).
+ * <p>
+ * All polygon clipping is performed with a Clipper object with the specific
+ * boolean operation indicated by the <code>ClipType</code> parameter passed in
+ * its Execute method. With regard to <b>open</b> paths (polylines), clipping
+ * rules generally match those of closed paths (polygons). However, when there
+ * are both polyline and polygon subjects, the following clipping rules apply:
+ * </p>
+ * 
+ * <ul>
+ * <li><b>union operations</b> - polylines will be clipped by <b>any</b>
+ * overlapping polygons so that only non-overlapped portions will be returned in
+ * the solution, together with solution polygons</li>
+ * <li><b>intersection, difference and xor operations</b> - polylines will be
+ * clipped by 'clip' polygons, and there will be no interaction between
+ * polylines and any subject polygons</li>
+ * </ul>
+ * 
+ * <h2>Polygon Offsetting:</h2>
+ * <p>
+ * Geometric offsetting refers to the process of creating parallel curves that
+ * are offset a specified distance from their starting positions.
+ * <p>
+ * While all offsetting is performed by the <code>ClipperOffset</code> class in
+ * the <code>Clipper.Offset</code> unit, the complexities of constructing and
+ * using this class can usually be avoided by using instead the
+ * {@link #InflatePaths(PathsD, double, JoinType, EndType, double, double, int)
+ * InflatePaths()} function in this class. This function can both inflate and
+ * shrink polygons (using positive and negative offsets respectively).
+ * Offsetting can be performed using a number of JoinTypes and EndTypes. While
+ * both open paths and closed paths can be offset, logically only closed paths
+ * can be shrunk (ie with negative offsets).
+ * <p>
+ * Note: Offsetting shouldn't be confused with the process of polygon
+ * <i>translation</i>.
+ */
 public final class Clipper {
 
 	public static final Rect64 InvalidRect64 = new Rect64(false);
@@ -107,6 +165,10 @@ public static Paths64 BooleanOp(ClipType clipType, Paths64 subject, Paths64 clip
 		return solution;
 	}
 
+	/**
+	 * This function is a generic alternative to the Intersect, Difference, Union
+	 * and XOR functions.
+	 */
 	public static void BooleanOp(ClipType clipType, @Nullable Paths64 subject, @Nullable Paths64 clip, PolyTree64 polytree, FillRule fillRule) {
 		if (subject == null) {
 			return;
@@ -123,6 +185,16 @@ public static PathsD BooleanOp(ClipType clipType, PathsD subject, PathsD clip, F
 		return BooleanOp(clipType, subject, clip, fillRule, 2);
 	}
 
+	/**
+	 * This function is a generic alternative to the Intersect, Difference, Union
+	 * and XOR functions.
+	 * 
+	 * @param clipType
+	 * @param subject
+	 * @param clip
+	 * @param fillRule
+	 * @param precision The desired coordinate precision (up to 8 decimal places).
+	 */
 	public static PathsD BooleanOp(ClipType clipType, PathsD subject, @Nullable PathsD clip, FillRule fillRule, int precision) {
 		PathsD solution = new PathsD();
 		ClipperD c = new ClipperD(precision);

src/main/java/clipper2/offset/ClipperOffset.java

@@ -24,22 +24,51 @@
 import tangible.RefObject;
 
 /**
- * Geometric offsetting refers to the process of creating parallel curves that
- * are offset a specified distance from their primary curves.
+ * Manages the process of offsetting (inflating/deflating) both open and closed
+ * paths using different join types and end types.
  * <p>
- * The ClipperOffset class manages the process of offsetting
- * (inflating/deflating) both open and closed paths using a number of different
- * join types and end types. The library user will rarely need to access this
- * unit directly since it will generally be easier to use the
- * {@link Clipper#InflatePaths(Paths64, double, JoinType, EndType)
- * InflatePaths()} function when doing polygon offsetting.
+ * Geometric <b>offsetting</b> refers to the process of creating <b>parallel
+ * curves</b> that are offset a specified distance from their primary curves.
  * <p>
- * Caution: Offsetting self-intersecting polygons may produce unexpected
- * results.
+ * Library users will rarely need to access this class directly since it's
+ * generally easier to use the {@link Clipper#InflatePaths(Paths64, double, JoinType, EndType)
+ * InflatePaths()} function for polygon
+ * offsetting.
  * <p>
- * Note: When inflating polygons, it's important that you select
- * {@link EndType#Polygon}. If you select one of the open path end types instead
- * (including EndType.Join), you'll simply inflate the polygon's outline.
+ * <b>Notes:</b>
+ * <ul>
+ * <li>When offsetting <i>closed</i> paths (polygons), a positive offset delta
+ * specifies how much outer polygon contours will expand and inner "hole"
+ * contours will contract. The converse occurs with negative deltas.</li>
+ * <li>You cannot offset <i>open</i> paths (polylines) with negative deltas
+ * because it's not possible to contract/shrink open paths.</li>
+ * <li>When offsetting, it's important not to confuse <b>EndType.Polygon</b>
+ * with <b>EndType.Joined</b>. <b>EndType.Polygon</b> should be used when
+ * offsetting polygons (closed paths). <b>EndType.Joined</b> should be used with
+ * polylines (open paths).</li>
+ * <li>Offsetting should <b>not</b> be performed on <b>intersecting closed
+ * paths</b>, as doing so will almost always produce undesirable results.
+ * Intersections must be removed before offsetting, which can be achieved
+ * through a <b>Union</b> clipping operation.</li>
+ * <li>It is OK to offset self-intersecting open paths (polylines), though the
+ * intersecting (overlapping) regions will be flattened in the solution
+ * polygon.</li>
+ * <li>When offsetting closed paths (polygons), the <b>winding direction</b> of
+ * paths in the solution will match that of the paths prior to offsetting.
+ * Polygons with hole regions should comply with <b>NonZero filling</b>.</li>
+ * <li>When offsetting open paths (polylines), the solutions will always have
+ * <b>Positive orientation</b>.</li>
+ * <li>Path <b>order</b> following offsetting very likely <i>won't</i> match
+ * path order prior to offsetting.</li>
+ * <li>While the ClipperOffset class itself won't accept paths with floating
+ * point coordinates, the <b>InflatePaths</b> function will accept paths with
+ * floating point coordinates.</li>
+ * <li>Redundant segments should be removed before offsetting (see
+ * {@link Clipper#SimplifyPaths(Paths64, double)
+ * SimplifyPaths()}), and between offsetting operations too. These redundant
+ * segments not only slow down offsetting, but they can cause unexpected
+ * blemishes in offset solutions.</li>
+ * </ul>
  */
 public class ClipperOffset {