Skip to main content

Crate knipsa

Crate knipsa 

Source
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-types geometry.

Structs§

BooleanOutput
Separate closed and open outputs from a Boolean operation.
BooleanRequest
Borrowed paths and options for one bounded Boolean operation.
ComplexityLimits
Explicit input-complexity limits for polygon topology analysis.
OffsetOptions
Options controlling an offset operation.
PathValidationError
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§

ClipType
A boolean operation over filled paths.
ComplexityResource
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.
FillRule
A winding/fill rule used to interpret input paths.
JoinType
The treatment of corners when a path is offset.
Orientation
The orientation of three points in Cartesian coordinates.
PathKind
Describes whether a path’s final point connects back to its first point.
PointLocation
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 clips from subjects using FillRule::EvenOdd.
difference_d
Subtracts floating-point clips from subjects using FillRule::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::EvenOdd rule.
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 i128 arithmetic.
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.