# 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:

TypeMorphismArityMapZipTessellate
NGonMonomorphic$1,[3,32]$YesYesYes
BoundedPolygonPolymorphic$[3,4]$YesNoYes
UnboundedPolygonPolymorphic$[3,\infin)$YesNoNo

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());

## Modules

Cube primitives.

Decomposition and tessellation.

Polytope generation.

Sphere primitives.

## Structs

Monomorphic $n$-gon.

Unbounded polymorphic $n$-gon.

## Enums

Bounded polymorphic $n$-gon.

Intersection of edges.

## Traits

Polygonal structure.

Topological structure.

## Functions

Zips the vertices of Topological types from multiple iterators into a single iterator.