Struct plexus::graph::ArcView

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

View of an arc.

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

Arcs provide the connectivity information within a MeshGraph and are the primary mechanism for traversing its topology. Moreover, most edge-like operations are exposed by arcs, because they are directed and therefore can emit deterministic results (unlike true edges).

Examples

Traversing a graph of a cube via its arcs to find an opposing face:

use plexus::graph::MeshGraph;
use plexus::prelude::*;
use plexus::primitive::cube::Cube;
use plexus::primitive::index::HashIndexer;

let mut graph = Cube::new()
    .polygons_with_position()
    .collect_with_indexer::<MeshGraph<Triplet<_>>, _>(HashIndexer::default())
    .unwrap();

let face = graph.faces().nth(0).unwrap();
let opposite = face
    .into_arc()
    .into_opposite_arc()
    .into_next_arc()
    .into_next_arc()
    .into_opposite_arc()
    .into_face()
    .unwrap();

Methods

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

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

Converts a mutable view into an orphan view.

pub fn into_ref(self) -> ArcView<&'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::Point2;
use plexus::graph::MeshGraph;
use plexus::prelude::*;

let mut graph = MeshGraph::<Point2<f32>>::from_raw_buffers_with_arity(
    vec![0u32, 1, 2, 3],
    vec![(0.0, 0.0), (1.0, 0.0), (1.0, 1.0), (0.0, 1.0)],
    4,
)
.unwrap();
let key = graph
    .arcs()
    .find(|arc| arc.is_boundary_arc())
    .unwrap()
    .key();
let arc = graph.arc_mut(key).unwrap().extrude(1.0).unwrap().into_ref();

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

pub fn with_ref<T, K, F>(self, f: F) -> Either<Result<T, GraphError>, Self> where
    T: FromKeyedSource<(K, &'a mut M)>,
    F: FnOnce(ArcView<&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> ArcView<M, G> where
    M: Reborrow,
    M::Target: AsStorage<ArcPayload<G>>,
    G: Geometry, 

pub fn key(&self) -> ArcKey

Gets the key for the arc.

pub fn is_boundary_arc(&self) -> bool

Returns true if this is a boundary arc.

A boundary arc has no associated face.

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

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

Converts the arc into its interior path.

pub fn into_boundary_arc(self) -> Option<Self>

Returns the arc if it is a boundary arc, otherwise None.

pub fn into_opposite_arc(self) -> Self

Converts the arc into its opposite arc.

pub fn into_next_arc(self) -> Self

Converts the arc into its next arc.

pub fn into_previous_arc(self) -> Self

Converts the arc into its previous arc.

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

Gets the interior path of the arc.

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

Returns the same arc if it is a boundary arc, otherwise None.

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

Gets the opposite arc.

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

Gets the next arc.

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

Gets the previous arc.

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

pub fn neighborhood(&self) -> ArcNeighborhood

Gets the nieghborhood of the arc.

pub fn into_source_vertex(self) -> VertexView<M, G>

Converts the arc into its source vertex.

pub fn into_destination_vertex(self) -> VertexView<M, G>

Converts the arc into its destination vertex.

pub fn source_vertex(&self) -> VertexView<&M::Target, G>

Gets the source vertex of the arc.

pub fn destination_vertex(&self) -> VertexView<&M::Target, G>

Gets the destination vertex of the arc.

impl<M, G> ArcView<M, G> where
    M: Reborrow,
    M::Target: AsStorage<ArcPayload<G>> + AsStorage<EdgePayload<G>> + Consistent,
    G: Geometry, 

pub fn into_edge(self) -> EdgeView<M, G>

Converts the arc into its edge.

pub fn edge(&self) -> EdgeView<&M::Target, G>

Gets the edge of the arc.

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

pub fn into_face(self) -> Option<FaceView<M, G>>

Converts the arc into its face.

If this is a boundary arc, then None is returned.

pub fn face(&self) -> Option<FaceView<&M::Target, G>>

Gets the face of this arc.

If this is a boundary arc, then None is returned.

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

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

Gets an iterator of views over the vertices connected by the arc.

impl<M, G> ArcView<M, G> where
    M: Reborrow + ReborrowMut,
    M::Target: AsStorage<ArcPayload<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 connected by the arc.

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

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

Gets an iterator of views over the faces connected to the arc.

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

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

Gets an iterator of orphan views over the faces connected to the arc.

impl<'a, M, G> ArcView<&'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_with<F>(self, f: F) -> VertexView<&'a mut M, G> where
    F: FnOnce() -> G::Vertex, 

Splits an edge (and its arcs) into two neighboring edges that share a vertex.

Splitting inserts a new vertex with the geometry provided by the given function. The leading arc of the inserted vertex will be one half of the arc that initiated the split and therefore will be part of the same interior path.

Returns the inserted vertex.

Examples

Split an edge in a graph with weighted vertices:

use plexus::geometry::Geometry;
use plexus::graph::MeshGraph;
use plexus::prelude::*;
use plexus::primitive::Triangle;

pub enum Weight {}

impl Geometry for Weight {
    type Vertex = f64;
    type Arc = ();
    type Edge = ();
    type Face = ();
}

let mut graph = MeshGraph::<Weight>::from_raw_buffers(
    vec![Triangle::new(0usize, 1, 2)],
    vec![1.0, 2.0, 0.5],
)
.unwrap();
let key = graph.arcs().nth(0).unwrap().key();
let vertex = graph.arc_mut(key).unwrap().split_with(|| 0.1);

pub fn split_at_midpoint(self) -> VertexView<&'a mut M, G> where
    G: EdgeMidpoint<Midpoint = VertexPosition<G>>,
    G::Vertex: AsPosition, 

Splits an edge (and its arcs) at the midpoint of the arc's vertices.

Splitting inserts a new vertex with the geometry of the arc's source vertex but modified such that the positional data of the vertex is the computed midpoint of both of the arc's vertices. The leading arc of the inserted vertex will be one half of the arc that initiated the split and therefore will be part of the same interior path.

This function is only available if a graph's geometry exposes positional data in its vertices and that data supports interpolation. See the geometry module.

Returns the inserted vertex.

Examples

Split an edge in a triangle at its midpoint:

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

let mut graph = MeshGraph::<Point2<f64>>::from_raw_buffers(
    vec![Triangle::new(0usize, 1, 2)],
    vec![(0.0, 0.0), (1.0, 0.0), (0.0, 1.0)],
)
.unwrap();
let key = graph.arcs().nth(0).unwrap().key();
let vertex = graph.arc_mut(key).unwrap().split_at_midpoint();

pub fn bridge(
    self,
    destination: Selector<ArcKey>
) -> Result<FaceView<&'a mut M, G>, GraphError>

Connects a boundary arc to another boundary arc with a face.

Bridging arcs inserts a new face and, as needed, new arcs and edges. The inserted face is always a quadrilateral. The bridged arcs must be boundary arcs with an orientation that allows them to form an interior path.

Arcs can be bridged within an interior path. The destination arc can be chosen by key or index, where an index selects the nth arc from the source arc within the interior path.

Returns the inserted face if successful.

Errors

Returns an error if the destination arc cannot be found, either arc is not a boundary arc, or the orientation of the destination arc is incompatible.

Examples

Bridging two disjoint quadrilaterals together:

use nalgebra::Point2;
use plexus::geometry::convert::IntoGeometry;
use plexus::geometry::Geometry;
use plexus::graph::{MeshGraph, VertexKey, VertexView};
use plexus::prelude::*;
use plexus::primitive::Quad;

fn find<'a, I, T, G>(input: I, geometry: T) -> Option<VertexKey>
where
    I: IntoIterator<Item = VertexView<&'a MeshGraph<G>, G>>,
    T: Copy + IntoGeometry<G::Vertex>,
    G: 'a + Geometry,
    G::Vertex: PartialEq,
{
    input
        .into_iter()
        .find(|vertex| vertex.geometry == geometry.into_geometry())
        .map(|vertex| vertex.key())
}

let mut graph = MeshGraph::<Point2<f64>>::from_raw_buffers(
    vec![Quad::new(0usize, 1, 2, 3), Quad::new(4, 5, 6, 7)],
    vec![
        (-2.0, 0.0),
        (-1.0, 0.0), // b
        (-1.0, 1.0), // a
        (-2.0, 1.0),
        (1.0, 0.0), // c
        (2.0, 0.0),
        (2.0, 1.0),
        (1.0, 1.0), // d
    ],
)
.unwrap();
let a = find(graph.vertices(), (-1.0, 1.0)).unwrap();
let b = find(graph.vertices(), (-1.0, 0.0)).unwrap();
let c = find(graph.vertices(), (1.0, 0.0)).unwrap();
let d = find(graph.vertices(), (1.0, 1.0)).unwrap();
let face = graph
    .arc_mut((a, b).into())
    .unwrap()
    .bridge(ByKey((c, d).into()))
    .unwrap();

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

Extrudes a boundary arc along its normal.

Extrusion inserts a new edge (and arcs) with the same geometry as the initiating arc, but modifies the positional geometry of the new edge's vertices such that they extend geometrically along the normal of the originating arc. The originating arc is then bridged with an arc in the opposing edge. This inserts a quadrilateral face. See bridge.

An arc's normal is perpendicular to the arc and also coplanar with the arc and one of its neighbors. This is computed via a projection.

Returns the opposing arc. This is the arc in the destination edge that is within the same interior path as the initiating arc.

Errors

Returns an error if the arc is not a boundary arc.

Examples

Extrude an exterior arc of a quadrilateral.

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

let mut graph = MeshGraph::<Point2<f64>>::from_raw_buffers_with_arity(
    vec![0usize, 1, 2, 3],
    vec![(0.0, 0.0), (1.0, 0.0), (1.0, 1.0), (0.0, 1.0)],
    4,
)
.unwrap();
let key = graph
    .arcs()
    .find(|arc| arc.is_boundary_arc())
    .map(|arc| arc.key())
    .unwrap();
graph.arc_mut(key).unwrap().extrude(1.0).unwrap();

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

Removes the arc, its opposite arc, and edge.

Any and all dependent topology is also removed, such as connected faces, vertices with no remaining leading arc, etc.

Returns the source vertex of the initiating arc.

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

pub fn normal(&self) -> Result<G::Normal, GraphError>

Trait Implementations

impl<M, G> Copy for ArcView<M, G> where
    M: Copy + Reborrow,
    M::Target: AsStorage<ArcPayload<G>>,
    G: Geometry, 

impl<M, G> From<ArcView<M, G>> for ArcNeighborhood where
    M: Reborrow,
    M::Target: AsStorage<ArcPayload<G>> + AsStorage<VertexPayload<G>> + Consistent,
    G: Geometry, 

fn from(arc: ArcView<M, G>) -> Self

Performs the conversion.

impl<M, G> Clone for ArcView<M, G> where
    M: Clone + Reborrow,
    M::Target: AsStorage<ArcPayload<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> DerefMut for ArcView<M, G> where
    M: Reborrow + ReborrowMut,
    M::Target: AsStorage<ArcPayload<G>> + AsStorageMut<ArcPayload<G>>,
    G: Geometry, 

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

Mutably dereferences the value.

impl<M, G> Deref for ArcView<M, G> where
    M: Reborrow,
    M::Target: AsStorage<ArcPayload<G>>,
    G: Geometry, 

type Target = ArcPayload<G>

The resulting type after dereferencing.

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

Dereferences the value.