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

pub struct FaceView<B> where    B: Reborrow,    B::Target: AsStorage<Face<<B as Geometric>::Geometry>> + Geometric,  { /* fields omitted */ }

View of a face entity.

Exposes references to a face entity and provides the primary face API. 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\}}$.

# 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_with_offset(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<B, M, G> FaceView<B> where    B: Reborrow<Target = M>,    M: AsStorage<Arc<G>> + AsStorage<Face<G>> + Consistent + Geometric<Geometry = G>,    G: GraphGeometry, [src]

#### pub fn into_ring(self) -> Ring<B>[src]

Converts the face into its ring.

#### pub fn into_arc(self) -> ArcView<B>[src]

Converts the face into its leading arc.

#### pub fn ring(&self) -> Ring<&M>[src]

Gets the ring of the face.

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

Gets the leading arc of the face.

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

#### 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<B, G> FaceView<B> where    B: Reborrow,    B::Target: AsStorage<Arc<G>> + AsStorage<Face<G>> + Consistent + Geometric<Geometry = G>,    G: GraphGeometry, [src]

#### pub fn adjacent_arcs(&self) -> impl Clone + Iterator<Item = ArcView<&B::Target>>[src]

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

#### pub fn adjacent_faces(    &self) -> impl Clone + Iterator<Item = FaceView<&B::Target>>[src]

Gets an iterator of views over adjacent faces.

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

#### pub fn adjacent_vertices(    &self) -> impl Clone + Iterator<Item = VertexView<&B::Target>>[src]

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

### impl<B> FaceView<B> where    B: ReborrowMut,    B::Target: AsStorageMut<Arc<<B as Geometric>::Geometry>> + AsStorage<Face<<B as Geometric>::Geometry>> + Consistent + Geometric, [src]

#### pub fn adjacent_arc_orphans(    &mut self) -> impl Iterator<Item = ArcOrphan<<B as Geometric>::Geometry>>[src]

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

### impl<B> FaceView<B> where    B: ReborrowMut,    B::Target: AsStorage<Arc<<B as Geometric>::Geometry>> + AsStorageMut<Face<<B as Geometric>::Geometry>> + Consistent + Geometric, [src]

#### pub fn adjacent_face_orphans(    &mut self) -> impl Iterator<Item = FaceOrphan<<B as Geometric>::Geometry>>[src]

Gets an iterator of orphan views over adjacent faces.

### impl<B> FaceView<B> where    B: ReborrowMut,    B::Target: AsStorage<Arc<<B as Geometric>::Geometry>> + AsStorage<Face<<B as Geometric>::Geometry>> + AsStorageMut<Vertex<<B as Geometric>::Geometry>> + Consistent + Geometric, [src]

#### pub fn adjacent_vertex_orphans(    &mut self) -> impl Iterator<Item = VertexOrphan<<B as Geometric>::Geometry>>[src]

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

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

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

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

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

Gets an iterator that traverses adjacent faces by depth.

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

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

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

Splits the face by bisecting it with a composite edge inserted between two non-adjacent 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 arc inserted 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 an adjacent face over their shared composite edge.

The adjacent face can be chosen by key or index, where index selects the $n^\text{th}$ adjacent 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 adjacent to 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> 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> 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>, 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_with_offset<T>(    self,     offset: T) -> Result<FaceView<&'a mut M>, GraphError> where    T: Into<Scalar<VertexPosition<G>>>,    G: FaceNormal,    G::Vertex: AsPosition,    VertexPosition<G>: EuclideanSpace, [src]

Extrudes the face along its normal.

Returns the extruded face.

# Errors

Returns an error if the geometry could not be computed.

#### pub fn extrude_with_translation(    self,     translation: Vector<VertexPosition<G>>) -> FaceView<&'a mut M> where    G::Vertex: AsPosition,    VertexPosition<G>: EuclideanSpace, [src]

Extrudes the face along a translation.

Returns the extruded face.

# Errors

Returns an error if the geometry could not be computed.

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

Extrudes a face using the given vertex geometry.

Returns the extruded face.

# Errors

Returns an error if the geometry could not be computed.

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

Removes the face.

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

## Trait Implementations

### impl<B, M, G> ClosedView for FaceView<B> where    B: Reborrow<Target = M>,    M: AsStorage<Face<G>> + Geometric<Geometry = G>,    G: GraphGeometry, [src]

#### fn key(&self) -> Self::Key[src]

Gets the key for the face.

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

#### type Target = Face<G>

The resulting type after dereferencing.

### impl<B, M, G> DynamicArity for FaceView<B> where    B: Reborrow<Target = M>,    M: AsStorage<Arc<G>> + AsStorage<Face<G>> + Consistent + Geometric<Geometry = G>,    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.