Struct plexus::graph::MeshGraph

pub struct MeshGraph<G = (R64, R64, R64)> where
    G: GraphData,  { /* private fields */ }

Half-edge graph representation of a polygonal mesh.

MeshGraphs form a polygonal mesh from four interconnected entities: vertices, arcs, edges, and faces. These entities are exposed by view and orphan types as well as types that represent rings and paths in a graph. Entities can be associated with arbitrary data, including no data at all. See the GraphData trait.

This flexible representation supports fast traversals and searches and can be used to manipulate both the data and topology of a mesh.

See the graph module documentation and user guide for more details.

Implementations

impl<G> MeshGraph<G> where
    G: GraphData, 

pub fn new() -> Self

Creates an empty MeshGraph.

Examples

use plexus::graph::MeshGraph;

let mut graph = MeshGraph::<()>::new();

pub fn vertex_count(&self) -> usize

Gets the number of vertices in the graph.

pub fn vertex(&self, key: VertexKey) -> Option<VertexView<&Self>>

Gets an immutable view of the vertex with the given key.

pub fn vertex_mut(&mut self, key: VertexKey) -> Option<VertexView<&mut Self>>

Gets a mutable view of the vertex with the given key.

pub fn vertices(&self) -> impl Iterator<Item = VertexView<&Self>>

Gets an iterator of immutable views over the vertices in the graph.

pub fn vertex_orphans(&mut self) -> impl Iterator<Item = VertexOrphan<'_, G>>

Gets an iterator of orphan views over the vertices in the graph.

pub fn arc_count(&self) -> usize

Gets the number of arcs in the graph.

pub fn arc(&self, key: ArcKey) -> Option<ArcView<&Self>>

Gets an immutable view of the arc with the given key.

pub fn arc_mut(&mut self, key: ArcKey) -> Option<ArcView<&mut Self>>

Gets a mutable view of the arc with the given key.

pub fn arcs(&self) -> impl Iterator<Item = ArcView<&Self>>

Gets an iterator of immutable views over the arcs in the graph.

pub fn arc_orphans(&mut self) -> impl Iterator<Item = ArcOrphan<'_, G>>

Gets an iterator of orphan views over the arcs in the graph.

pub fn edge_count(&self) -> usize

Gets the number of edges in the graph.

pub fn edge(&self, key: EdgeKey) -> Option<EdgeView<&Self>>

Gets an immutable view of the edge with the given key.

pub fn edge_mut(&mut self, key: EdgeKey) -> Option<EdgeView<&mut Self>>

Gets a mutable view of the edge with the given key.

pub fn edges(&self) -> impl Iterator<Item = EdgeView<&Self>>

Gets an iterator of immutable views over the edges in the graph.

pub fn edge_orphans(&mut self) -> impl Iterator<Item = EdgeOrphan<'_, G>>

Gets an iterator of orphan views over the edges in the graph.

pub fn face_count(&self) -> usize

Gets the number of faces in the graph.

pub fn face(&self, key: FaceKey) -> Option<FaceView<&Self>>

Gets an immutable view of the face with the given key.

pub fn face_mut(&mut self, key: FaceKey) -> Option<FaceView<&mut Self>>

Gets a mutable view of the face with the given key.

pub fn faces(&self) -> impl Iterator<Item = FaceView<&Self>>

Gets an iterator of immutable views over the faces in the graph.

pub fn face_orphans(&mut self) -> impl Iterator<Item = FaceOrphan<'_, G>>

Gets an iterator of orphan views over the faces in the graph.

pub fn path<I>(&self, keys: I) -> Result<Path<'static, &Self>, GraphError> where
    I: IntoIterator,
    I::Item: Borrow<VertexKey>, 

Gets an immutable path over the given sequence of vertex keys.

Errors

Returns an error if a vertex is not found or the path is malformed.

pub fn path_mut<I>(
    &mut self,
    keys: I
) -> Result<Path<'static, &mut Self>, GraphError> where
    I: IntoIterator,
    I::Item: Borrow<VertexKey>, 

Gets a mutable path over the given sequence of vertex keys.

Errors

Returns an error if a vertex is not found or the path is malformed.

pub fn aabb(&self) -> Aabb<VertexPosition<G>> where
    G::Vertex: AsPosition,
    VertexPosition<G>: EuclideanSpace,
    Scalar<VertexPosition<G>>: IntrinsicOrd, 

Gets an axis-aligned bounding box that encloses the graph.

pub fn triangulate(&mut self)

Triangulates the graph, tessellating all faces into triangles.

pub fn smooth<T>(&mut self, factor: T) where
    T: Into<Scalar<VertexPosition<G>>>,
    G: VertexCentroid,
    G::Vertex: AsPositionMut,
    VertexPosition<G>: EuclideanSpace, 

Smooths the positions of vertices in the graph.

Each position is translated by its offset from its centroid scaled by the given factor. The centroid of a vertex position is the mean of the positions of its adjacent vertices. That is, given a factor $k$ and a vertex with position $P$ and centroid $Q$, its position becomes $P+k(Q-P)$.

pub fn split_at_path(path: Path<'_, &mut Self>) -> Result<(), GraphError>

Splits the graph along a path.

Splitting a graph creates boundaries along the given path and copies any necessary vertex, arc, and edge data.

If the path bisects the graph, then splitting will result in disjointed sub-graphs.

Examples

use nalgebra::Point2;
use plexus::graph::MeshGraph;
use plexus::prelude::*;
use plexus::primitive::Trigon;

type E2 = Point2<f64>;

// Create a graph from two triangles.
let mut graph = MeshGraph::<E2>::from_raw_buffers(
    vec![Trigon::new(0usize, 1, 2), Trigon::new(2, 1, 3)],
    vec![(-1.0, 0.0), (0.0, -1.0), (0.0, 1.0), (1.0, 0.0)],
)
.unwrap();

// Find the shared edge that bisects the triangles and then construct a path
// along the edge and split the graph.
let key = graph
    .edges()
    .find(|edge| !edge.is_boundary_edge())
    .map(|edge| edge.into_arc().key())
    .unwrap();
let mut path = graph.arc_mut(key).unwrap().into_path();
MeshGraph::split_at_path(path).unwrap();

pub fn disjoint_subgraph_vertices(
    &self
) -> impl ExactSizeIterator<Item = VertexView<&Self>>

Gets an iterator over a vertex within each disjoint sub-graph.

Traverses the graph and returns an arbitrary vertex within each disjoint sub-graph. A sub-graph is disjoint if it cannot be reached from all other topology in the graph.

Examples

use nalgebra::Point2;
use plexus::graph::MeshGraph;
use plexus::prelude::*;
use plexus::primitive::Trigon;

type E2 = Point2<f64>;

// Create a graph from two disjoint triangles.
let graph = MeshGraph::<E2>::from_raw_buffers(
    vec![Trigon::new(0u32, 1, 2), Trigon::new(3, 4, 5)],
    vec![
        (-2.0, 0.0),
        (-1.0, 0.0),
        (-1.0, 1.0),
        (1.0, 0.0),
        (2.0, 0.0),
        (1.0, 1.0),
    ],
)
.unwrap();

// A vertex from each disjoint triangle is returned.
for vertex in graph.disjoint_subgraph_vertices() {
    // ...
}

pub fn into_disjoint_subgraphs(self) -> Vec<Self>

Moves disjoint sub-graphs into separate graphs.

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the graph’s underlying storage as much as possible.

pub fn to_mesh_by_vertex<B>(&self) -> Result<B, B::Error> where
    B: Buildable<Facet = ()>,
    B::Vertex: FromGeometry<G::Vertex>, 

Creates a Buildable mesh data structure from the graph.

The output is created from each unique vertex in the graph. No face data is used, and the Facet type is always the unit type ().

Examples

Creating a MeshBuffer from a MeshGraph used to modify a cube:

use decorum::N64;
use nalgebra::Point3;
use plexus::buffer::MeshBufferN;
use plexus::graph::MeshGraph;
use plexus::prelude::*;
use plexus::primitive::cube::Cube;
use plexus::primitive::generate::Position;

type E3 = Point3<N64>;

let mut graph: MeshGraph<E3> = Cube::new().polygons::<Position<E3>>().collect();
let key = graph.faces().nth(0).unwrap().key();
graph
    .face_mut(key)
    .unwrap()
    .extrude_with_offset(1.0)
    .unwrap();

let buffer: MeshBufferN<usize, E3> = graph.to_mesh_by_vertex().unwrap();

Errors

Returns an error if the graph does not have constant arity that is compatible with the index buffer. Typically, a graph is triangulated before being converted to a buffer.

pub fn to_mesh_by_vertex_with<B, F>(&self, f: F) -> Result<B, B::Error> where
    B: Buildable<Facet = ()>,
    F: FnMut(VertexView<&Self>) -> B::Vertex, 

Creates a Buildable mesh data structure from the graph.

The output is created from each unique vertex in the graph, which is converted by the given function. No face data is used, and the Facet type is always the unit type ().

Errors

Returns an error if the vertex data cannot be inserted into the output, there are arity conflicts, or the output does not support topology found in the graph.

pub fn to_mesh_by_face<B>(&self) -> Result<B, B::Error> where
    B: Buildable,
    B::Vertex: FromGeometry<G::Vertex>,
    B::Facet: FromGeometry<G::Face>, 

Creates a Buildable mesh data structure from the graph.

The output is created from each face in the graph. For each face, the face data and data for each of its vertices is inserted into the mesh via FromGeometry. This means that a vertex is inserted for each of its adjacent faces.

Errors

Returns an error if the vertex data cannot be inserted into the output, there are arity conflicts, or the output does not support topology found in the graph.

pub fn to_mesh_by_face_with<B, F>(&self, f: F) -> Result<B, B::Error> where
    B: Buildable,
    B::Facet: FromGeometry<G::Face>,
    F: FnMut(FaceView<&Self>, VertexView<&Self>) -> B::Vertex, 

Creates a Buildable mesh data structure from the graph.

The output is created from each face in the graph. For each face, the face data and data for each of its vertices is converted into the output vertex data by the given function. This means that a vertex is inserted for each of its adjacent faces. The data of each face is is inserted into the output via FromGeometry.

Examples

Creating a MeshBuffer from a MeshGraph used to compute normals:

use decorum::R64;
use nalgebra::Point3;
use plexus::buffer::MeshBuffer;
use plexus::geometry::Vector;
use plexus::graph::MeshGraph;
use plexus::prelude::*;
use plexus::primitive::cube::Cube;
use plexus::primitive::generate::Position;
use plexus::primitive::BoundedPolygon;

type E3 = Point3<R64>;

pub struct Vertex {
    pub position: E3,
    pub normal: Vector<E3>,
}

let graph: MeshGraph<E3> = Cube::new().polygons::<Position<E3>>().collect();

let buffer: MeshBuffer<BoundedPolygon<usize>, _> = graph
    .to_mesh_by_face_with(|face, vertex| Vertex {
        position: *vertex.position(),
        normal: face.normal().unwrap(),
    })
    .unwrap();

Errors

Returns an error if the vertex data cannot be inserted into the output, there are arity conflicts, or the output does not support topology found in the graph.

Trait Implementations

impl<G> Buildable for MeshGraph<G> where
    G: GraphData, 

Exposes a MeshBuilder that can be used to construct a MeshGraph incrementally from surfaces and facets.

See the builder module documentation for more.

Examples

Creating a MeshGraph from a triangle:

use nalgebra::Point2;
use plexus::builder::Buildable;
use plexus::graph::MeshGraph;
use plexus::prelude::*;

let mut builder = MeshGraph::<Point2<f64>>::builder();
let graph = builder
    .surface_with(|builder| {
        let a = builder.insert_vertex((0.0, 0.0))?;
        let b = builder.insert_vertex((1.0, 0.0))?;
        let c = builder.insert_vertex((0.0, 1.0))?;
        builder.facets_with(|builder| builder.insert_facet(&[a, b, c], ()))
    })
    .and_then(|_| builder.build())
    .unwrap();

type Builder = GraphBuilder<G>

type Error = GraphError

type Vertex = <G as GraphData>::Vertex

Vertex data.

type Facet = <G as GraphData>::Face

Facet data.

fn builder() -> Self::Builder

impl<G> Default for MeshGraph<G> where
    G: GraphData, 

fn default() -> Self

Returns the “default value” for a type.

impl<G> DynamicArity for MeshGraph<G> where
    G: GraphData, 

type Dynamic = MeshArity

fn arity(&self) -> Self::Dynamic

impl<P, G> From<P> for MeshGraph<G> where
    P: Polygonal,
    G: GraphData,
    G::Vertex: FromGeometry<P::Vertex>, 

fn from(polygon: P) -> Self

Converts to this type from the input type.

impl<E, G> FromEncoding<E> for MeshGraph<G> where
    E: FaceDecoder + VertexDecoder,
    G: GraphData,
    G::Face: FromGeometry<E::Face>,
    G::Vertex: FromGeometry<E::Vertex>, 

type Error = GraphError

fn from_encoding(
    vertices: <E as VertexDecoder>::Output,
    faces: <E as FaceDecoder>::Output
) -> Result<Self, Self::Error>

impl<G, P> FromIndexer<P, P> for MeshGraph<G> where
    G: GraphData,
    G::Vertex: FromGeometry<P::Vertex>,
    P: Map<usize> + Polygonal,
    P::Output: Grouping<Group = P::Output> + IntoVertices + Polygonal<Vertex = usize>,
    Vec<P::Output>: IndexBuffer<P::Output, Index = usize>, 

type Error = GraphError

fn from_indexer<I, N>(input: I, indexer: N) -> Result<Self, Self::Error> where
    I: IntoIterator<Item = P>,
    N: Indexer<P, P::Vertex>, 

impl<G, P> FromIterator<P> for MeshGraph<G> where
    G: GraphData,
    G::Vertex: FromGeometry<P::Vertex>,
    P: Polygonal,
    P::Vertex: Clone + Eq + Hash,
    Self: FromIndexer<P, P>, 

fn from_iter<I>(input: I) -> Self where
    I: IntoIterator<Item = P>, 

Creates a value from an iterator.

impl<P, G, H> FromRawBuffers<P, H> for MeshGraph<G> where
    P: IntoVertices + Polygonal,
    P::Vertex: Integer + ToPrimitive + Unsigned,
    G: GraphData,
    G::Vertex: FromGeometry<H>, 

type Error = GraphError

fn from_raw_buffers<I, J>(indices: I, vertices: J) -> Result<Self, Self::Error> where
    I: IntoIterator<Item = P>,
    J: IntoIterator<Item = H>, 

Creates a type from raw buffers.

impl<N, G, H> FromRawBuffersWithArity<N, H> for MeshGraph<G> where
    N: Integer + ToPrimitive + Unsigned,
    G: GraphData,
    G::Vertex: FromGeometry<H>, 

fn from_raw_buffers_with_arity<I, J>(
    indices: I,
    vertices: J,
    arity: usize
) -> Result<Self, Self::Error> where
    I: IntoIterator<Item = N>,
    J: IntoIterator<Item = H>, 

Creates a MeshGraph from raw buffers. The arity of the polygons in the index buffer must be given and constant.

Errors

Returns an error if the arity of the index buffer is not constant, any index is out of bounds, or there is an error inserting topology into the graph.

Examples

use nalgebra::Point3;
use plexus::graph::MeshGraph;
use plexus::index::{Flat3, LruIndexer};
use plexus::prelude::*;
use plexus::primitive::generate::Position;
use plexus::primitive::sphere::UvSphere;

type E3 = Point3<f64>;

let (indices, positions) = UvSphere::new(16, 16)
    .polygons::<Position<E3>>()
    .triangulate()
    .index_vertices::<Flat3, _>(LruIndexer::with_capacity(256));
let mut graph = MeshGraph::<E3>::from_raw_buffers_with_arity(indices, positions, 3).unwrap();

type Error = GraphError

impl<G> IntoPolygons for MeshGraph<G> where
    G: GraphData, 

type Output = IntoIter<<MeshGraph<G> as IntoPolygons>::Polygon, Global>

type Polygon = UnboundedPolygon<<G as GraphData>::Vertex>

fn into_polygons(self) -> Self::Output

impl<G> StaticArity for MeshGraph<G> where
    G: GraphData, 

type Static = (usize, Option<usize>)

const ARITY: Self::Static = (3, None)

impl<T, H, G, const A: usize> TryFrom<MeshBuffer<Flat<T, A>, H>> for MeshGraph<G> where
    Constant<A>: ToType,
    TypeOf<A>: NonZero,
    T: Copy + Integer + NumCast + Unsigned,
    H: Clone,
    G: GraphData,
    G::Vertex: FromGeometry<H>, 

fn try_from(buffer: MeshBuffer<Flat<T, A>, H>) -> Result<Self, Self::Error>

Creates a MeshGraph from a flat MeshBuffer. The arity of the polygons in the index buffer must be known and constant.

Errors

Returns an error if a MeshGraph cannot represent the topology in the MeshBuffer.

Examples

use nalgebra::Point2;
use plexus::buffer::MeshBuffer;
use plexus::graph::MeshGraph;
use plexus::index::Flat4;
use plexus::prelude::*;
use std::convert::TryFrom;

type E2 = Point2<f64>;

let buffer = MeshBuffer::<Flat4, E2>::from_raw_buffers(
    vec![0u64, 1, 2, 3],
    vec![(0.0f64, 0.0), (1.0, 0.0), (1.0, 1.0), (0.0, 1.0)],
)
.unwrap();
let mut graph = MeshGraph::<E2>::try_from(buffer).unwrap();

type Error = GraphError

The type returned in the event of a conversion error.

impl<P, H, G> TryFrom<MeshBuffer<P, H>> for MeshGraph<G> where
    P: Grouping<Group = P> + IntoVertices + Polygonal,
    P::Vertex: Copy + Integer + NumCast + Unsigned,
    H: Clone,
    G: GraphData,
    G::Vertex: FromGeometry<H>, 

fn try_from(buffer: MeshBuffer<P, H>) -> Result<Self, Self::Error>

Creates a MeshGraph from a structured MeshBuffer.

Errors

Returns an error if a MeshGraph cannot represent the topology in the MeshBuffer.

Examples

use nalgebra::Point2;
use plexus::buffer::MeshBuffer;
use plexus::graph::MeshGraph;
use plexus::prelude::*;
use plexus::primitive::Tetragon;
use std::convert::TryFrom;

type E2 = Point2<f64>;

let buffer = MeshBuffer::<Tetragon<u64>, E2>::from_raw_buffers(
    vec![Tetragon::new(0u64, 1, 2, 3)],
    vec![(0.0f64, 0.0), (1.0, 0.0), (1.0, 1.0), (0.0, 1.0)],
)
.unwrap();
let mut graph = MeshGraph::<E2>::try_from(buffer).unwrap();

type Error = GraphError

The type returned in the event of a conversion error.