Module plexus::primitive

Expand description

Primitive topological structures.

This module provides composable primitives that describe polygonal structures. This includes simple $n$-gons like triangles, polytope generators, and iterator expressions that compose and decompose iterators of primitives.

Types in this module generally describe cycle graphs and are not strictly geometric. For example, Polygonal types may be geometrically degenerate (e.g., collinear, converged, etc.) or used to approximate polygons from $\Reals^2$ embedded into higher-dimensional spaces. These types are also used for indexing, in which case their representation and data are both entirely topological.

Plexus uses the terms trigon and tetragon for its polygon types, which mean triangle and quadrilateral, respectively. This is done for consistency with higher arity polygon names (e.g., decagon). In some contexts, the term triangle is still used, such as in functions concerning triangulation.

Representations

Plexus provides various topological types with different capabilities summarized below:

Type	Morphism	Arity	Map	Zip	Tessellate
`NGon`	Monomorphic	$1,[3,32]$	Yes	Yes	Yes
`BoundedPolygon`	Polymorphic	$[3,4]$	Yes	No	Yes
`UnboundedPolygon`	Polymorphic	$[3,\infin)$	Yes	No	No

NGon is monomorphic and supports the broadest set of traits and features. However, its type-level arity is somewhat limited and its value-level arity is fixed. This means, for example, that it is not possible to have an iterator of NGons represent both trigons and tetragons, because these polygons must be distinct NGon types.

The polygon types BoundedPolygon and UnboundedPolygon are polymorphic and therefore support variable value-level arity. BoundedPolygon only expresses a limited set of polygons by enumerating NGons, but supports decomposition and other traits. UnboundedPolygon is most flexible and can represent any arbitrary polygon, but does not support any tessellation features.

Edges are always represented as NGon<_, 2>.

Examples

Generating raw buffers with positional data of a cube using an Indexer:

use decorum::N64;
use nalgebra::Point3;
use plexus::index::{Flat3, HashIndexer};
use plexus::prelude::*;
use plexus::primitive::cube::Cube;
use plexus::primitive::generate::Position;

let (indices, positions) = Cube::new()
    .polygons::<Position<Point3<N64>>>()
    .triangulate()
    .index_vertices::<Flat3, _>(HashIndexer::default());