repository·master·Indexed 42 days ago
https://github.com/jbuckmccready/cavalier_contoursA Rust-based geometric library for high-performance 2D polyline operations. It provides tools for parallel offsetting, boolean operations (Union, Intersection, Difference, XOR), spatial indexing, and geometric analysis such as area and winding number calculations. The library supports polylines defined by line and arc segments and includes C FFI bindings for integration with C/C++ projects.
The cavalier_contours_ui package is a user interface application designed for visualizing, testing, and demonstrating the core cavalier_contours crate.
It is built using the following technologies:
egui.Cavalier Contours provides a suite of 2D geometric algorithms for polylines defined by line and arc segments (arcs are not approximated as line segments):
The project is organized into several crates depending on your integration needs:
cavalier_contours: The core Rust library containing the primary polyline algorithms and API.cavalier_contours_ffi: C FFI bindings for integration with C, C++, and other languages.cavalier_contours_ui: A WebAssembly-based UI demo built with egui.examples: A collection of examples demonstrating library functionality.The shared library files (.so, .dylib, or .dll) are produced by building the cavalier_contours_ffi crate with Cargo in release mode.
Note: Run this command from the root of the cavalier_contours repository/workspace.
cargo build -p cavalier_contours_ffi --releaseYou can run specific examples from the cavalier_contours_examples package using cargo run. To build all examples without running them, use cargo build --examples.
# Run a specific example
cargo run --example <example_name>
# Build all examples
cargo build --examplesTo use the FFI in a C/C++ project, you need a header file. You can generate cavalier_contours.h using cbindgen.
Note: Run this command from the root of the cavalier_contours repository/workspace.
cbindgen --crate cavalier_contours_ffi --output cavalier_contours.hcargo runTo run the web version of the UI locally, you must have trunk installed and the wasm32-unknown-unknown Rust target added.
trunk:cargo install trunk --lockedrustup target add wasm32-unknown-unknowntrunk servehttp://localhost:8080/#dev.Note: The /#dev suffix is required to prevent the browser from loading a stale cached version of the application.
cargo install trunk --locked
rustup target add wasm32-unknown-unknown
trunk serveCavalier Contours is a 2D geometry library for polylines and shapes. It provides functionality for offsetting, combining shapes, computing areas, path lengths, and winding numbers. The library is organized into several key modules:
core: Contains the fundamental geometric primitives and types.polyline: Provides tools specifically for working with polylines.shape_algorithms: Contains advanced geometric algorithms for shape manipulation.Note: The library forbids unsafe_code to ensure memory safety.
Beyond simple boolean results, you can analyze how two polylines interact by using internal processing functions (typically accessed via the process_for_boolean workflow). This is useful for debugging or custom geometric analysis.
Analysis often involves creating an AABB (Axis-Aligned Bounding Box) index for the first polyline to accelerate intersection lookups via create_approx_aabb_index() before calling process_for_boolean.
A PlineView is a lightweight, non-copying representation of a subpart or selection of a source polyline. It borrows the source polyline to provide access to vertex data and geometric operations without the overhead of duplicating the underlying data.
To use a view, you follow a two-step process:
PlineViewData: This structure holds the minimum metadata (indices, start/end points, bulge adjustments) required to define a contiguous subpart of a polyline. It is detached from the source and can be serialized.PlineView: Call PlineViewData::view(&source) to create an active view that borrows the source polyline. The resulting PlineView implements the PlineSource trait, allowing you to use it in any function that accepts a polyline source.When you are finished with the view, you can call .detach() to consume the view and retrieve the underlying PlineViewData, releasing the borrow on the source polyline.
// 1. Create view data (e.g., from slice points)
let view_data = PlineViewData::from_slice_points(
&polyline,
start_point,
start_index,
end_point,
end_index,
1e-5
).expect("slice not collapsed");
// 2. Create the active view by borrowing the source
let view = view_data.view(&polyline);
// 3. Use the view as a polyline source
let length = view.path_length();
// 4. Detach to release the borrow
let detached_data = view.detach();The LineLineIntr<T> enum categorizes the relationship between two line segments:
| Variant | Description |
|---|---|
NoIntersect | The segments are parallel and not collinear, or they are distinct points. |
TrueIntersect | The segments intersect at exactly one point within their bounds. Contains seg1_t and seg2_t (parametric values for both segments). |
FalseIntersect | The infinite lines intersect, but at least one segment must be extended to reach the intersection point. Contains seg1_t and seg2_t. |
Overlapping | The segments are collinear and overlap. Contains seg2_t0 and seg2_t1, representing the start and end parametric values of the coincidence along the second segment. |
#[derive(Debug, Copy, Clone)]
pub enum LineLineIntr<T> where T: Real {
NoIntersect,
TrueIntersect {
seg1_t: T,
seg2_t: T,
},
Overlapping {
seg2_t0: T,
seg2_t1: T,
},
FalseIntersect {
seg1_t: T,
seg2_t: T,
},
}