# [−][src]Struct plexus::graph::FaceView

pub struct FaceView<M, G> where    M: Reborrow,    M::Target: AsStorage<Face<G>>,    G: GraphGeometry,  { /* fields omitted */ }

View of a face in a graph.

Provides traversals, queries, and mutations related to faces in a graph. See the module documentation for more information about topological views.

Faces are notated by the path of their associated ring. A triangular face with a perimeter formed by vertices $A$, $B$, and $C$ is notated $\overrightarrow{\{A,B,C\}}$. While the precise ordering of vertices is determined by a face's leading arc, the same face may be notated using rotations of this set, such as $\overrightarrow{\{B,C,A\}}$.

## Methods

### impl<M, G> FaceView<M, G> where    M: Reborrow,    M::Target: AsStorage<Face<G>>,    G: GraphGeometry, [src]

#### pub fn key(&self) -> FaceKey[src]

Gets the key for the face.

### impl<'a, M, G> FaceView<&'a mut M, G> where    M: 'a + AsStorageMut<Face<G>>,    G: 'a + GraphGeometry, [src]

#### pub fn into_orphan(self) -> FaceOrphan<'a, G>[src]

Converts a mutable view into an orphan view.

#### pub fn into_ref(self) -> FaceView<&'a M, G>[src]

Converts a mutable view into an immutable view.

This is useful when mutations are not (or no longer) needed and mutual access is desired.

# Examples

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

let mut graph = Cube::new()
.polygons::<Position<Point3<N64>>>()
.collect::<MeshGraph<Point3<f64>>>();
let key = graph.faces().nth(0).unwrap().key();
let face = graph
.face_mut(key)
.unwrap()
.extrude(1.0)
.unwrap()
.into_ref();

// This would not be possible without conversion into an immutable view.
let _ = face.into_arc();
let _ = face.into_arc().into_next_arc();

### impl<M, G> FaceView<M, G> where    M: Reborrow,    M::Target: AsStorage<Arc<G>> + AsStorage<Face<G>> + Consistent,    G: GraphGeometry, [src]

#### pub fn into_ring(self) -> RingView<M, G>[src]

Converts the face into its ring.

#### pub fn into_arc(self) -> ArcView<M, G>[src]

Converts the face into its leading arc.

#### pub fn ring(&self) -> RingView<&M::Target, G>[src]

Gets the ring of the face.

#### pub fn arc(&self) -> ArcView<&M::Target, G>[src]

Gets the leading arc of the face.

#### pub fn traverse_by_breadth(    &self) -> impl Clone + Iterator<Item = FaceView<&M::Target, G>>[src]

Gets an iterator that traverses the faces of the graph in breadth-first order beginning with the face on which this function is called.

The traversal moves from the face to its neighboring faces and so on. If there are disjoint faces in the graph, then a traversal will not reach all faces in the graph.

#### pub fn traverse_by_depth(    &self) -> impl Clone + Iterator<Item = FaceView<&M::Target, G>>[src]

Gets an iterator that traverses the faces of the graph in depth-first order beginning with the face on which this function is called.

The traversal moves from the face to its neighboring faces and so on. If there are disjoint faces in the graph, then a traversal will not reach all faces in the graph.

#### pub fn interior_arcs(    &self) -> impl Clone + Iterator<Item = ArcView<&M::Target, G>>[src]

Gets an iterator of views over the arcs in the face's ring.

#### pub fn neighboring_faces(    &self) -> impl Clone + Iterator<Item = FaceView<&M::Target, G>>[src]

Gets an iterator of views over neighboring faces.

### impl<M, G> FaceView<M, G> where    M: Reborrow,    M::Target: AsStorage<Arc<G>> + AsStorage<Face<G>> + AsStorage<Vertex<G>> + Consistent,    G: GraphGeometry, [src]

#### pub fn distance(    &self,     source: Selector<VertexKey>,     destination: Selector<VertexKey>) -> Result<usize, GraphError>[src]

Gets the distance (number of arcs) between two vertices within the face.

#### pub fn vertices(    &self) -> impl Clone + Iterator<Item = VertexView<&M::Target, G>>[src]

Gets an iterator of views over the vertices that form the face.

### impl<M, G> FaceView<M, G> where    M: ReborrowMut,    M::Target: AsStorageMut<Arc<G>> + AsStorage<Face<G>> + Consistent,    G: GraphGeometry, [src]

#### pub fn interior_arc_orphans(&mut self) -> impl Iterator<Item = ArcOrphan<G>>[src]

Gets an iterator of orphan views over the arcs in the face's ring.

### impl<M, G> FaceView<M, G> where    M: ReborrowMut,    M::Target: AsStorage<Arc<G>> + AsStorageMut<Face<G>> + Consistent,    G: GraphGeometry, [src]

#### pub fn neighboring_face_orphans(    &mut self) -> impl Iterator<Item = FaceOrphan<G>>[src]

Gets an iterator of orphan views over neighboring faces.

### impl<M, G> FaceView<M, G> where    M: ReborrowMut,    M::Target: AsStorage<Arc<G>> + AsStorage<Face<G>> + AsStorageMut<Vertex<G>> + Consistent,    G: GraphGeometry, [src]

#### pub fn vertex_orphans(&mut self) -> impl Iterator<Item = VertexOrphan<G>>[src]

Gets an iterator of orphan views over the vertices that form the face.

#### pub fn flatten(&mut self) -> Result<(), GraphError> where    G: FacePlane,    G::Vertex: AsPosition,    VertexPosition<G>: EuclideanSpace + FiniteDimensional<N = U3>, [src]

Flattens the face by translating the positions of all vertices into a best-fit plane.

Returns an error if a best-fit plane could not be computed or positions could not be translated into the plane.

### impl<'a, M, G> FaceView<&'a mut M, G> where    M: AsStorage<Arc<G>> + AsStorage<Edge<G>> + AsStorage<Face<G>> + AsStorage<Vertex<G>> + Default + Mutable<G>,    G: 'a + GraphGeometry, [src]

#### pub fn split(    self,     source: Selector<VertexKey>,     destination: Selector<VertexKey>) -> Result<ArcView<&'a mut M, G>, GraphError>[src]

Splits the face by bisecting it with a composite edge inserted between two non-neighboring vertices within the face's perimeter.

The vertices can be chosen by key or index, where index selects the $n^\text{th}$ vertex within the face's ring.

This can be thought of as the opposite of merge.

Returns the inserted arc that spans from the source vertex to the destination vertex if successful. If a face $\overrightarrow{\{A,B, C,D\}}$ is split from $A$ to $C$, then it will be decomposed into faces in the rings $\overrightarrow{\{A,B,C\}}$ and $\overrightarrow{\{C,D,A\}}$ and the arc $\overrightarrow{AC}$ will be returned.

# Errors

Returns an error if either of the given vertices cannot be found, are not within the face's perimeter, or the distance between the vertices along the ring is less than two.

# Examples

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

let mut graph = MeshGraph::<Point2<f64>>::from_raw_buffers(
vec![Tetragon::new(0usize, 1, 2, 3)],
vec![(0.0, 0.0), (1.0, 0.0), (1.0, 1.0), (0.0, 1.0)],
)
.unwrap();
let key = graph.faces().nth(0).unwrap().key();
let arc = graph
.face_mut(key)
.unwrap()
.split(ByIndex(0), ByIndex(2))
.unwrap()
.into_ref();

#### pub fn merge(self, destination: Selector<FaceKey>) -> Result<Self, GraphError>[src]

Merges the face into a neighboring face over their shared composite edge.

The neighboring face can be chosen by key or index, where index selects the $n^\text{th}$ neighbor of the face.

This can be thought of as the opposite of split.

Returns the merged face if successful.

# Errors

Returns an error if the destination face cannot be found or is not a neighbor of the initiating face.

# Examples

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

let mut graph = MeshGraph::<Point2<f64>>::from_raw_buffers(
vec![Tetragon::new(0usize, 1, 2, 3), Tetragon::new(0, 3, 4, 5)],
vec![
(0.0, 0.0),  // 0
(1.0, 0.0),  // 1
(1.0, 1.0),  // 2
(0.0, 1.0),  // 3
(-1.0, 1.0), // 4
(-1.0, 0.0), // 5
],
)
.unwrap();

let key = graph.faces().nth(0).unwrap().key();
let face = graph
.face_mut(key)
.unwrap()
.merge(ByIndex(0))
.unwrap()
.into_ref();

#### pub fn bridge(self, destination: FaceKey) -> Result<(), GraphError>[src]

Connects faces with equal arity with faces inserted along their perimeters.

The inserted faces are always quadrilateral. Both the initiating face and destination face are removed.

# Errors

Returns an error if the destination face cannot be found or the arity of the face and its destination are not the same.

#### pub fn triangulate(self) -> Self[src]

Decomposes the face into triangles. Does nothing if the face is triangular.

Returns the terminating face of the decomposition.

#### pub fn poke_with<F>(self, f: F) -> VertexView<&'a mut M, G> where    F: FnOnce() -> G::Vertex, [src]

Subdivides the face about a vertex. A triangle fan is formed from each arc in the face's perimeter and the vertex.

Poking inserts a new vertex with geometry provided by the given function.

Returns the inserted vertex.

# Examples

Forming a pyramid from a triangular face:

use nalgebra::Point3;
use plexus::graph::MeshGraph;
use plexus::prelude::*;
use plexus::primitive::Trigon;
use plexus::AsPosition;

let mut graph = MeshGraph::<Point3<f64>>::from_raw_buffers(
vec![Trigon::new(0usize, 1, 2)],
vec![(-1.0, 0.0, 0.0), (1.0, 0.0, 0.0), (0.0, 2.0, 0.0)],
)
.unwrap();
let key = graph.faces().nth(0).unwrap().key();
let mut face = graph.face_mut(key).unwrap();

// See poke_with_offset, which provides this functionality.
let mut geometry = face.centroid();
let position = geometry.as_position().clone() + face.normal().unwrap();
face.poke_with(move || {
*geometry.as_position_mut() = position;
geometry
});

#### pub fn poke_at_centroid(self) -> VertexView<&'a mut M, G> where    G: FaceCentroid,    G::Vertex: AsPosition, [src]

Subdivides the face about its centroid. A triangle fan is formed from each arc in the face's perimeter and a vertex inserted at the centroid.

Returns the inserted vertex.

#### pub fn poke_with_offset<T>(    self,     offset: T) -> Result<VertexView<&'a mut M, G>, GraphError> where    T: Into<Scalar<VertexPosition<G>>>,    G: FaceCentroid + FaceNormal,    G::Vertex: AsPosition,    VertexPosition<G>: EuclideanSpace, [src]

Subdivides the face about its centroid. A triangle fan is formed from each arc in the face's perimeter and a vertex inserted at the centroid. The inserted vertex is then translated along the initiating face's normal by the given offset.

Returns the inserted vertex if successful.

# Errors

Returns an error if the geometry could not be computed.

# Examples

Constructing a "spikey" sphere:

use decorum::N64;
use nalgebra::Point3;
use plexus::graph::MeshGraph;
use plexus::prelude::*;
use plexus::primitive::generate::Position;
use plexus::primitive::sphere::UvSphere;

let mut graph = UvSphere::new(16, 8)
.polygons::<Position<Point3<N64>>>()
.collect::<MeshGraph<Point3<f64>>>();
let keys = graph.faces().map(|face| face.key()).collect::<Vec<_>>();
for key in keys {
graph.face_mut(key).unwrap().poke_with_offset(0.5).unwrap();
}

#### pub fn extrude<T>(self, offset: T) -> Result<FaceView<&'a mut M, G>, GraphError> where    T: Into<Scalar<VertexPosition<G>>>,    G: FaceNormal,    G::Vertex: AsPosition,    VertexPosition<G>: EuclideanSpace, [src]

Extrudes the face.

Returns the extruded face if successful.

# Errors

Returns an error if the geometry could not be computed.

#### pub fn remove(self) -> Option<RingView<&'a mut M, G>>[src]

Removes the face.

Returns the remaining ring of the face if it is not entirely disjoint.

## Trait Implementations

### impl<M, G> Deref for FaceView<M, G> where    M: Reborrow,    M::Target: AsStorage<Face<G>>,    G: GraphGeometry, [src]

#### type Target = Face<G>

The resulting type after dereferencing.

### impl<M, G> DynamicArity for FaceView<M, G> where    M: Reborrow,    M::Target: AsStorage<Arc<G>> + AsStorage<Face<G>> + Consistent,    G: GraphGeometry, [src]

#### fn arity(&self) -> Self::Dynamic[src]

Gets the arity of the face. This is the number of arcs that form the face's ring.

## Blanket Implementations

### impl<T> Same<T> for T

#### type Output = T

Should always be Self

### impl<T> ToOwned for T where    T: Clone, [src]

#### type Owned = T

The resulting type after obtaining ownership.

### impl<T, U> TryFrom<U> for T where    U: Into<T>, [src]

#### type Error = Infallible

The type returned in the event of a conversion error.

### impl<T, U> TryInto<U> for T where    U: TryFrom<T>, [src]

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.