Struct Region 

pub struct Region { /* private fields */ }

A validated planar region: a normalised set of polygons with holes, whose holes lie apart inside their outer rings and whose polygons do not overlap (#448).

Construction validates; operations preserve validity: a boolean or a morphology returns the faces of an exact arrangement, apart and nested by construction, and Region::translate, which rounds each vertex on its own, checks its result. Ring ordering is canonical (outer counter-clockwise, holes clockwise, each rotated to its lexicographically smallest vertex) and polygons are sorted, so equal regions compare equal regardless of how they were built.

A region built by Region::new or by a boolean on regions carries the proof that its rings are valid under that call’s tolerance (#341), and a boolean on it under the same tolerance does not validate them again. The proof is not part of equality.

Implementations

impl Region

pub fn minkowski_sum( &self, ring: &Ring, tolerance: Tolerance, ) -> Result<Region, MinkowskiError>

The Minkowski sum with a polygon ring: every point of the region moved by every point of the polygon. The polygon may be non-convex.

Decided exactly (ADR 0070), with each vertex sum a + k rounded once to f64 and output vertices rounded once. A convex polygon is summed whole; a non-convex one is cut into convex pieces (its own vertices, the cut certified to tile it) whose sums are united in the same arrangement.

Errors

MinkowskiError::Overlay for a polygon the overlay refuses or a refusal of the arrangement.

pub fn minkowski_erosion( &self, ring: &Ring, tolerance: Tolerance, ) -> Result<Region, MinkowskiError>

The Minkowski erosion by a polygon ring, convex or not: the points x for which the polygon moved by x lies within the region.

Errors

As Self::minkowski_sum.

pub fn minkowski_sum_region( &self, other: &Region, tolerance: Tolerance, ) -> Result<Region, MinkowskiError>

The Minkowski sum with another region – both may be non-convex, have holes and several components: every point of one moved by every point of the other. Symmetric in the two regions.

The region with fewer vertices is cut into convex pieces and the other summed with each, all in one exact arrangement, rounded as Self::minkowski_sum rounds.

Errors

MinkowskiError::Overlay for a refusal of the arrangement.

pub fn minkowski_erosion_region( &self, other: &Region, tolerance: Tolerance, ) -> Result<Region, MinkowskiError>

The Minkowski erosion by another region: the points x for which the other region moved by x lies within this one.

Errors

MinkowskiError::EmptyStructuring for an empty other (every point would qualify), and as Self::minkowski_sum_region.

impl Region

pub fn dilate_inner( &self, radius: f64, tolerance: Tolerance, ) -> Result<Region, OverlayError>

Dilation by a disc of radius, contained in the exact one: the sum with an inscribed polygon, drawn in by a margin.

Errors

OverlayError::InvalidOffsetDistance for a radius that is not finite and nonnegative, and overlay refusals.

pub fn dilate_outer( &self, radius: f64, tolerance: Tolerance, ) -> Result<Region, OverlayError>

Dilation by a disc of radius, containing the exact one: the sum with a circumscribed polygon, pushed out by a margin.

Errors

As Self::dilate_inner.

pub fn erode_inner( &self, radius: f64, tolerance: Tolerance, ) -> Result<Region, OverlayError>

Erosion by a disc of radius, contained in the exact one: eroded by a circumscribed polygon, pushed out by a margin. A route found in it proves reachability.

Errors

As Self::dilate_inner.

pub fn erode_outer( &self, radius: f64, tolerance: Tolerance, ) -> Result<Region, OverlayError>

Erosion by a disc of radius, containing the exact one: eroded by an inscribed polygon, drawn in by a margin. No route in it proves unreachability.

Errors

As Self::dilate_inner.

pub fn dilate_inner_with( &self, radius: f64, tolerance: Tolerance, mode: MorphologyMode, ) -> Result<Region, OverlayError>

Self::dilate_inner in the given mode: MorphologyMode::Exact gives the same result, MorphologyMode::Fast one whose MorphologyBound (still Inner) carries the excess too.

Errors

As Self::dilate_inner, and OverlayError::InvalidOffsetDistance for a fast mode’s budget that is not finite and nonnegative.

pub fn dilate_outer_with( &self, radius: f64, tolerance: Tolerance, mode: MorphologyMode, ) -> Result<Region, OverlayError>

Self::dilate_outer in the given mode, as Self::dilate_inner_with.

Errors

As Self::dilate_inner_with.

pub fn erode_inner_with( &self, radius: f64, tolerance: Tolerance, mode: MorphologyMode, ) -> Result<Region, OverlayError>

Self::erode_inner in the given mode, as Self::dilate_inner_with.

Errors

As Self::dilate_inner_with.

pub fn erode_outer_with( &self, radius: f64, tolerance: Tolerance, mode: MorphologyMode, ) -> Result<Region, OverlayError>

Self::erode_outer in the given mode, as Self::dilate_inner_with.

Errors

As Self::dilate_inner_with.

impl Region

pub fn empty() -> Region

The empty region. Not a failure: the identity for union.

pub fn new( polygons: Vec<Polygon>, tolerance: Tolerance, ) -> Result<Region, OverlayError>

Build a region from polygons, validating every ring and where the rings lie.

Each ring is validated as crate::overlay validates an operand’s, so the two cannot disagree about what a well-formed ring is. Then, decided exactly and with no tolerance, every hole must lie inside its own outer ring and in no other of its holes, and no point may lie in two polygons (#448). Rings may touch at points, and along a stretch they run with the polygons’ insides on opposite sides, as settled outputs do. An overlay operand is not held to this: its rings may overlap, read by its fill rule.

Errors

A ring’s own refusal (OverlayError::RingTooShort and the others crate::overlay gives); OverlayError::HoleOutsideOuter for a hole crossing or leaving its outer ring; OverlayError::HolesOverlap for holes of one polygon that cross, nest or repeat; OverlayError::PolygonsOverlap for polygons that overlap. With several defects, one is named.

pub const fn bound(&self) -> Option<MorphologyBound>

For a result of Self::dilate_inner, Self::dilate_outer, Self::erode_inner or Self::erode_outer: which side of the exact disc morphology it lies on and how far from it it can be. None for every other region, including Self::dilate and Self::erode, whose side is not stated.

pub const fn excess(&self) -> Option<f64>

For a result of Self::erode_inner_with and its siblings in crate::MorphologyMode::Fast: how much larger the filled notches made the sum, at most the mode’s budget, zero where no notch was filled (#330). It is part of MorphologyBound::deviation, which states the whole distance from the exact result. None for every other region, the exact mode’s results included.

pub fn polygons(&self) -> &[Polygon]

The region’s polygons, in canonical order.

pub const fn evidence(&self) -> RegionEvidence

What the producing operation did.

pub fn is_empty(&self) -> bool

True when the region covers no area.

pub fn area(&self) -> f64

Total covered area. Holes subtract.

pub fn component_count(&self) -> usize

Number of disjoint connected components.

One polygon is one component: Self::new refuses polygons that overlap (#448) and every operation returns polygons that do not, so counting them is the component count rather than an approximation of it. Polygons touching at a point or along an edge count apart.

pub fn boundary_rings(&self) -> Vec<Ring>

Every boundary ring, outer boundaries first then holes.

pub fn union( &self, other: &Region, tolerance: Tolerance, ) -> Result<Region, OverlayError>

Set union.

pub fn intersection( &self, other: &Region, tolerance: Tolerance, ) -> Result<Region, OverlayError>

Set intersection.

pub fn difference( &self, other: &Region, tolerance: Tolerance, ) -> Result<Region, OverlayError>

Set difference: this region minus other.

pub fn dilate( &self, radius: f64, tolerance: Tolerance, ) -> Result<Region, OverlayError>

Dilate by radius: the Minkowski sum with a disc, approximated by round joins on an unstated side of the exact result. Where a verdict must be proven, use Self::dilate_inner or Self::dilate_outer.

This is the disc-expansion form used for clearance envelopes. A zero radius is the identity.

pub fn erode( &self, radius: f64, tolerance: Tolerance, ) -> Result<Region, OverlayError>

Erode by radius: the Minkowski erosion by a disc, approximated on an unstated side of the exact result. Where a verdict must be proven, use Self::erode_inner (a route found proves reachability) or Self::erode_outer (no route proves unreachability).

A region thinner than 2 * radius anywhere is cut there, which is how a corridor narrower than a body radius becomes impassable. If that removes everything the result is empty and RegionEvidence::emptied is set.

pub fn translate(&self, offset: DVec2) -> Result<Region, OverlayError>

Translate by offset. Rigid: area and component count are preserved.

Errors

OverlayError::NonFinitePoint for a non-finite offset. Each vertex moves by its own rounding, which can turn a contact into a crossing, so the result is checked as Region::new checks its rings: the refusals of Region::new for rings crossing into each other (#448). That arranges a region of more than one ring, as Region::new does: 0.34 s for a floor of 100,000 corners with 200 holes.

pub fn sweep( &self, direction: DVec2, tolerance: Tolerance, ) -> Result<Region, OverlayError>

Sweep along direction: the union of the region with every translate of itself along the vector.

Equivalent to the Minkowski sum with the segment [0, direction]. Built as the union of the region and its translate plus the hull swept between them, which for a polygon set is exactly the union of the two end positions with the stroke of each boundary edge; using the union of endpoints alone would miss the swept middle whenever the translation exceeds the region’s own extent.

impl Region

pub fn visibility_polygon( &self, viewpoint: DVec2, tolerance: Tolerance, ) -> Result<Region, VisibilityError>

The part of the region in sight of viewpoint: every point the straight segment from the viewpoint reaches without leaving the region. Walls and holes cast shadows.

Errors

VisibilityError::NotInside for a viewpoint on the boundary or outside.

Trait Implementations

impl Clone for Region

fn clone(&self) -> Region

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Region

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Region

fn default() -> Region

Returns the “default value” for a type.

impl PartialEq for Region

fn eq(&self, other: &Region) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.