Struct plexus::graph::FaceView

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

View of a face.

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

Methods

impl<'a, M, G> FaceView<&'a mut M, G> where
    M: 'a + AsStorage<FacePayload<G>> + AsStorageMut<FacePayload<G>>,
    G: 'a + Geometry, 

pub fn into_orphan(self) -> OrphanFaceView<'a, G>

Converts a mutable view into an orphan view.

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

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 nalgebra::Point3;
use plexus::graph::MeshGraph;
use plexus::prelude::*;
use plexus::primitive::cube::Cube;

let mut graph = Cube::new()
    .polygons_with_position()
    .collect::<MeshGraph<Point3<f32>>>();
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();

pub fn with_ref<T, K, F>(self, f: F) -> Either<Result<T, GraphError>, Self> where
    T: FromKeyedSource<(K, &'a mut M)>,
    F: FnOnce(FaceView<&M, G>) -> Option<K>, 

Reborrows the view and constructs another mutable view from a given key.

This allows for fallible traversals from a mutable view without the need for direct access to the source MeshGraph. If the given function emits a key, then that key will be used to convert this view into another. If no key is emitted, then the original mutable view is returned.

impl<M, G> FaceView<M, G> where
    M: Reborrow,
    M::Target: AsStorage<FacePayload<G>>,
    G: Geometry, 

pub fn key(&self) -> FaceKey

Gets the key for the face.

impl<M, G> FaceView<M, G> where
    M: Reborrow,
    M::Target: AsStorage<ArcPayload<G>> + AsStorage<FacePayload<G>> + Consistent,
    G: Geometry, 

pub fn into_interior_path(self) -> InteriorPathView<M, G>

Converts the face into its interior path.

pub fn into_arc(self) -> ArcView<M, G>

Converts the face into its leading arc.

pub fn interior_path(&self) -> InteriorPathView<&M::Target, G>

Gets the interior path of the face.

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

Gets the leading arc of the face.

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

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

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

Gets an iterator of views over neighboring faces.

pub fn arity(&self) -> usize

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

impl<M, G> FaceView<M, G> where
    M: Reborrow,
    M::Target: AsStorage<ArcPayload<G>> + AsStorage<FacePayload<G>> + AsStorage<VertexPayload<G>> + Consistent,
    G: Geometry, 

pub fn neighborhood(&self) -> FaceNeighborhood

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

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

impl<M, G> FaceView<M, G> where
    M: Reborrow + ReborrowMut,
    M::Target: AsStorage<ArcPayload<G>> + AsStorageMut<ArcPayload<G>> + AsStorage<FacePayload<G>> + Consistent,
    G: Geometry, 

pub fn interior_orphan_arcs(&mut self) -> impl Iterator<Item = OrphanArcView<G>>

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

impl<M, G> FaceView<M, G> where
    M: Reborrow + ReborrowMut,
    M::Target: AsStorage<ArcPayload<G>> + AsStorage<FacePayload<G>> + AsStorageMut<FacePayload<G>> + Consistent,
    G: Geometry, 

pub fn neighboring_orphan_faces(
    &mut self
) -> impl Iterator<Item = OrphanFaceView<G>>

Gets an iterator of orphan views over neighboring faces.

impl<M, G> FaceView<M, G> where
    M: Reborrow + ReborrowMut,
    M::Target: AsStorage<ArcPayload<G>> + AsStorage<FacePayload<G>> + AsStorage<VertexPayload<G>> + AsStorageMut<VertexPayload<G>> + Consistent,
    G: Geometry, 

pub fn orphan_vertices(&mut self) -> impl Iterator<Item = OrphanVertexView<G>>

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

impl<'a, M, G> FaceView<&'a mut M, G> where
    M: AsStorage<ArcPayload<G>> + AsStorage<EdgePayload<G>> + AsStorage<FacePayload<G>> + AsStorage<VertexPayload<G>> + Default + Mutable<G>,
    G: 'a + Geometry, 

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

Splits the face by bisecting it with an edge (and arcs) inserted between two non-neighboring vertices within the face's perimeter.

The vertices can be chosen by key or index, where index selects the nth vertex within the face's interior path.

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.

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 interior path is less than two.

Examples

Splitting a quadrilateral face:

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

let mut graph = MeshGraph::<Point2<f64>>::from_raw_buffers(
    vec![Quad::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>

Merges the face into a neighboring face over their shared edge (and arcs).

The neighboring face can be chosen by key or index, where index selects the nth 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

Merging two neighboring quadrilateral faces:

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

let mut graph = MeshGraph::<Point2<f32>>::from_raw_buffers(
    vec![Quad::new(0usize, 1, 2, 3), Quad::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>

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

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, 

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.

pub fn poke_at_centroid(self) -> VertexView<&'a mut M, G> where
    G: FaceCentroid<Centroid = <G as Geometry>::Vertex>, 

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.

Examples

Forming a baseless triangular pyramid from a face:

use nalgebra::Point3;
use plexus::geometry::convert::AsPosition;
use plexus::graph::MeshGraph;
use plexus::prelude::*;
use plexus::primitive::Triangle;

let mut graph = MeshGraph::<Point3<f64>>::from_raw_buffers(
    vec![Triangle::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();

// Use the face's normal to translate the vertex from the centroid.
let normal = face.normal();
let mut vertex = face.poke_at_centroid();
let position = vertex.geometry.as_position() + (normal * 2.0);
*vertex.geometry.as_position_mut() = position;

pub fn extrude<T>(
    self,
    distance: T
) -> Result<FaceView<&'a mut M, G>, GraphError> where
    G: FaceNormal,
    G::Normal: Mul<T>,
    G::Vertex: AsPosition,
    ScaledFaceNormal<G, T>: Clone,
    VertexPosition<G>: Add<ScaledFaceNormal<G, T>, Output = VertexPosition<G>> + Clone, 

pub fn remove(self) -> InteriorPathView<&'a mut M, G>

Removes the face.

Returns the interior path of the face.

impl<M, G> FaceView<M, G> where
    M: Reborrow,
    M::Target: AsStorage<ArcPayload<G>> + AsStorage<FacePayload<G>> + AsStorage<VertexPayload<G>> + Consistent,
    G: FaceCentroid + Geometry, 

pub fn centroid(&self) -> G::Centroid

impl<M, G> FaceView<M, G> where
    M: Reborrow,
    M::Target: AsStorage<ArcPayload<G>> + AsStorage<FacePayload<G>> + AsStorage<VertexPayload<G>> + Consistent,
    G: FaceNormal + Geometry, 

pub fn normal(&self) -> G::Normal

Trait Implementations

impl<M, G> Clone for FaceView<M, G> where
    M: Clone + Reborrow,
    M::Target: AsStorage<FacePayload<G>>,
    G: Geometry, 

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<M, G> Copy for FaceView<M, G> where
    M: Copy + Reborrow,
    M::Target: AsStorage<FacePayload<G>>,
    G: Geometry, 

impl<M, G> From<FaceView<M, G>> for FaceNeighborhood where
    M: Reborrow,
    M::Target: AsStorage<ArcPayload<G>> + AsStorage<FacePayload<G>> + AsStorage<VertexPayload<G>> + Consistent,
    G: Geometry, 

fn from(face: FaceView<M, G>) -> Self

Performs the conversion.

impl<M, G> Deref for FaceView<M, G> where
    M: Reborrow,
    M::Target: AsStorage<FacePayload<G>>,
    G: Geometry, 

type Target = FacePayload<G>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<M, G> DerefMut for FaceView<M, G> where
    M: Reborrow + ReborrowMut,
    M::Target: AsStorage<FacePayload<G>> + AsStorageMut<FacePayload<G>>,
    G: Geometry, 

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.