Expand description
§knipsa
knipsa is a Rust polygon toolkit for boolean operations, offsets, point
queries, and triangulation. The safe API works with ordinary Rust vectors and
returns crate::Error instead of panicking on malformed geometry.
§Quick start
use knipsa::{PointD, intersection_path_d};
let subject = vec![
PointD::new(0.0, 0.0),
PointD::new(10.0, 0.0),
PointD::new(10.0, 10.0),
PointD::new(0.0, 10.0),
];
let clip = vec![
PointD::new(5.0, 5.0),
PointD::new(15.0, 5.0),
PointD::new(15.0, 15.0),
PointD::new(5.0, 15.0),
];
let result = intersection_path_d(&subject, &clip)?;
assert_eq!(result.len(), 1);Use crate::intersection for exact integer output. The convenience
operations and single-ring _path variants use crate::FillRule::EvenOdd;
use crate::boolean_op or crate::boolean_op_d when another fill rule is
required. Their shared generic crate::BooleanRequest accepts both closed
and open subjects and their crate::BooleanOutput keeps closed rings and
open polylines separate. Clips are always closed. Use
crate::offset_path_d for one polygon or polyline offset,
crate::offset_paths_d for offset collections, and crate::triangulate_d
for counter-clockwise triangles.
Use crate::build_polygons64 or crate::build_polygons_d when flat ring
output must retain explicit hole ownership. The same validated nesting model is
shared with triangulation; outer rings are counter-clockwise, holes are
clockwise, and nested islands become separate polygons.
Integer topology classification is exact across the complete i64 coordinate
domain and does not round-trip through floating point.
Every Boolean request, offset, polygon-builder, and triangulation call is
bounded by crate::ComplexityLimits. Start with
crate::ComplexityLimits::DEFAULT to reject oversized requests before
quadratic intersection validation begins; there is no unbounded public path.
Use crate::validate_paths_d_located or
crate::validate_paths64_located when validation diagnostics must include
the failing path and coordinate indices.
The optional serde feature implements Serialize and Deserialize for the
public value types without adding Serde to the default dependency graph. Enum
variants use explicit snake_case wire names.
Coordinate-specific helper names use 64 for exact integer geometry and _d
for floating-point geometry. Each operation has one canonical public name;
the pre-1.0 API does not retain duplicate aliases.
The repository contains a longer runnable tour in
crates/knipsa/examples/quickstart.rs.
Modules§
- geo_
types - Optional conversions between Knipsa paths and
geo-typesgeometry.
Structs§
- Boolean
Output - Separate closed and open outputs from a Boolean operation.
- Boolean
Request - Borrowed paths and options for one bounded Boolean operation.
- Complexity
Limits - Explicit input-complexity limits for polygon topology analysis.
- Offset
Options - Options controlling an offset operation.
- Path
Validation Error - A path-collection validation error with stable input coordinates.
- Point64
- An integer point used by the exact-coordinate API.
- PointD
- A double-precision point used by the floating-point API.
- Polygon64
- One integer polygon with explicit ownership of its holes.
- PolygonD
- One floating-point polygon with explicit ownership of its holes.
- Rect64
- An axis-aligned integer rectangle.
- RectD
- An axis-aligned floating-point rectangle.
Enums§
- Clip
Type - A boolean operation over filled paths.
- Complexity
Resource - Resources bounded before polygon topology analysis begins.
- EndType
- The treatment of the ends of an open path.
- Error
- An error produced while validating or executing a geometry operation.
- Fill
Rule - A winding/fill rule used to interpret input paths.
- Join
Type - The treatment of corners when a path is offset.
- Orientation
- The orientation of three points in Cartesian coordinates.
- Path
Kind - Describes whether a path’s final point connects back to its first point.
- Point
Location - The result of testing a point against a closed path.
Functions§
- boolean_
op - Executes an exact integer boolean request.
- boolean_
op_ d - Executes a floating-point boolean request.
- build_
polygons64 - Builds polygons with explicit hole ownership from integer rings.
- build_
polygons_ d - Builds polygons with explicit hole ownership from floating-point rings.
- clip_
to_ rect64 - Clips integer paths to an axis-aligned rectangle.
- clip_
to_ rect_ d - Clips floating-point paths to an axis-aligned rectangle.
- difference
- Subtracts integer
clipsfromsubjectsusingFillRule::EvenOdd. - difference_
d - Subtracts floating-point
clipsfromsubjectsusingFillRule::EvenOdd. - difference_
path - Subtracts one integer ring from another using
FillRule::EvenOdd. - difference_
path_ d - Subtracts one floating-point ring from another using
FillRule::EvenOdd. - intersection
- Intersects integer path collections using the orientation-independent
FillRule::EvenOddrule. - intersection_
d - Intersects floating-point path collections using
FillRule::EvenOdd. - intersection_
path - Intersects two integer rings using
FillRule::EvenOdd. - intersection_
path_ d - Intersects two floating-point rings using
FillRule::EvenOdd. - normalize_
path64 - Removes consecutive duplicates and, for closed paths, a repeated closing point. The input is never modified.
- normalize_
path_ d - Removes consecutive duplicate floating-point points and a repeated closing point for closed paths.
- offset_
path64 - Offsets one integer-coordinate path.
- offset_
path_ d - Offsets one floating-point path.
- offset_
paths64 - Offsets integer-coordinate paths and rounds the resulting vertices to integer coordinates.
- offset_
paths_ d - Offsets floating-point paths and returns floating-point polygon outlines.
- orientation
- Returns the orientation of three integer points.
- point_
in_ polygon - Classifies an integer point against a closed path using the even-odd rule.
- reverse_
path64 - Returns a reversed copy of an integer path.
- reverse_
path_ d - Returns a reversed copy of a floating-point path.
- signed_
area2 - Returns twice the signed area of an integer path using checked
i128arithmetic. - simplify_
paths64 - Simplifies integer paths by applying a union with the selected fill rule.
- simplify_
paths_ d - Simplifies floating-point paths by applying a union with the selected fill rule.
- translate_
path64 - Translates an integer path with checked coordinate arithmetic.
- translate_
path_ d - Translates a floating-point path.
- triangulate64
- Triangulates a collection of integer-coordinate rings using a fill rule.
- triangulate_
d - Triangulates a collection of floating-point rings using a fill rule.
- triangulate_
path64 - Triangulates one simple integer polygon with the non-zero fill rule.
- triangulate_
path_ d - Triangulates one simple floating-point polygon with the non-zero fill rule.
- trim_
collinear64 - Removes redundant collinear vertices from an integer path.
- trim_
collinear_ d - Removes redundant collinear vertices from a floating-point path.
- union
- Unites two integer path collections using
FillRule::EvenOdd. - union_d
- Unites two floating-point path collections using
FillRule::EvenOdd. - union_
path - Unites two integer rings using
FillRule::EvenOdd. - union_
path_ d - Unites two floating-point rings using
FillRule::EvenOdd. - validate_
path64 - Validates an integer path’s shape contract and coordinate type.
- validate_
path_ d - Validates a floating-point path’s shape and finiteness.
- validate_
paths64 - Validates every integer path in a collection.
- validate_
paths64_ located - Validates integer paths and reports the index of the first failing path.
- validate_
paths_ d - Validates every floating-point path in a collection.
- validate_
paths_ d_ located - Validates floating-point paths with stable path and vertex locations.
- xor
- Computes integer symmetric difference using
FillRule::EvenOdd. - xor_d
- Computes floating-point symmetric difference using
FillRule::EvenOdd. - xor_
path - Computes the symmetric difference of two integer rings using
FillRule::EvenOdd. - xor_
path_ d - Computes the symmetric difference of two floating-point rings using
FillRule::EvenOdd.
Type Aliases§
- Path64
- A sequence of points describing one path.
- PathD
- A floating-point sequence of points.
- Paths64
- A collection of integer paths, usually polygon rings.
- PathsD
- A collection of floating-point paths, usually polygon rings.
- Triangle64
- A triangle with integer vertices.
- TriangleD
- A triangle with floating-point vertices.