Crate rectgrid 

Boundary box operations on rectilinear grids with arbitrary unit systems.

A rectilinear grid is an orthogonal grid whose axes each have an independent increment function. RectGrid defines such a grid by an origin and one IncrementFunction per axis, both expressed in the base unit Px. Coordinates on the grid are Unit values, and a BBox is a boundary box between two points in unit coordinates. For a single boundary box, RectGrid::get_parameter converts a point into the local unit system Parameter, in which each side of the boundary box has length 1; this makes boundary tests against arbitrary geometry possible (see the geometry module).

The base unit system is the unit system whose origin lies at (0, …, 0) and whose per-axis increment functions all return the constant 1. Its unit is named Px (pixel: picture element).

Coordinate system

• When treating x and y as 2D coordinates, x is the axis that becomes the width in the viewport, y is the height direction, and the origin (0, 0) is the top-left corner.
• Px passed into a function from outside this crate is global: an external coordinate not yet corrected for the origin, e.g. a viewport coordinate. Each function subtracts the origin internally to make it local. Px derived from a boundary box, such as the return value of RectGrid::unit_to_px and anything built on it (hit_test, *_as_px), is always local: the origin is at 0. If such a value is passed back across a RectGrid boundary, treat it as local Px.

Feature flags

• geometry: enables the geometry module, which gives the signed distance from a point to a line, circle, ellipse or polygon in unit coordinates.

Modules

geometry

Signed distance from a point to a line, circle, ellipse or polygon, in unit coordinates.

Structs

BBox

Boundary box between base and base + offset, in unit coordinates.

ParameterTag

Tag of Parameter.

PxTag

Tag of Px.

RectGrid

Rectilinear grid with an independent accumulator per axis. Px passed in from outside is global (origin not yet subtracted) and each method subtracts origin itself; Px derived from a boundary box (unit_to_px and what is built on it) is local.

UnitTag

Tag of Unit.

Value

An f64 tagged with its unit system at the type level. The tag prevents mixing values of different unit systems; see Px, Unit and Parameter.

Enums

Accumulator

Forward/inverse coordinate conversion for a single axis, built from an IncrementFunction.

Error

Error of this crate. Every fallible function returns one of these variants.

IncrementFunction

Definition of one axis of a grid: where its unit coordinates lie in px. Built into an Accumulator by IncrementFunction::accumulate. P is the pointer to the step closure of ForwardDifference (see StepFn); it defaults to DefaultSteps.

Traits

StepFn

A pointer to a step closure Fn(u32) -> Result<Px, Error>; implemented for every such Deref. The caller picks the pointer: Rc, Arc<dyn Fn(..) + Send + Sync>, Box, &F.

Functions

corner_test

For a boundary box with area, determines per axis whether point is near an edge (within threshold). Returns (each axis’s parameter, corner result). A corner element is Some(true) near the base-side edge ([0, threshold]), Some(false) near the offset-side edge ([1 - threshold, 1]) and None otherwise. If any axis is Some it is a handle hit (all axes Some = corner, one = edge); all None returns None (the caller falls back to e.g. a move drag). extend (as in hit_test) is converted to a parameter-space margin per axis (extend / offset). parameter is None when the boundary box has no size, an axis is unevaluable, or point is outside bx (extend included).

drag_resize

Updates the boundary box’s base/offset via a corner-handle drag. corner[d] = Some(base_side): true moves the base-side edge, false the offset-side edge. The new offset is at least 1.0 unit (base/offset never cross).

drag_translate

Computes base’s px position during a move drag. A boundary box keeps base in Unit, so the px position is only returned; it is committed to the boundary box by snap_bbox_to_unit (or snap_point_to_unit) at drag end.

snap_bbox_to_unit

At drag end, snaps the move-drag result of a boundary box with area to the Unit grid and returns the updated boundary box. drag_offset must be the value passed to drag_translate. extend is added before flooring.

snap_point_to_unit

At drag end, computes a boundary box snapped to the Unit grid from the move-drag result of a boundary box without area (a point). drag_offset must be the value passed to drag_translate.

Type Aliases

DefaultSteps

Pointer type used when a grid does not name one.

Parameter

Unbounded local coordinate system for a single boundary box, where each side length is 1 and sign follows the unit coordinate.

Point

A point in unit coordinates, one Unit per axis.

Px

Orthogonal, axis-independent unit system extending infinitely in the positive direction from the origin.

Unit

Arbitrary orthogonal unit system, finite or infinite per axis, whose value is an ordinal from its own origin in the positive direction.