honeycomb_core/cmap/dim2/
structure.rs

1//! Main definitions
2//!
3//! This module contains the main structure definition ([`CMap2`]) as well as its constructor
4//! implementation.
5
6use crate::attributes::{AttrSparseVec, AttrStorageManager, UnknownAttributeStorage};
7use crate::cmap::components::{betas::BetaFunctions, unused::UnusedDarts};
8use crate::geometry::{CoordsFloat, Vertex2};
9
10use super::CMAP2_BETA;
11
12/// # 2D combinatorial map implementation
13///
14/// Information regarding maps can be found in the [user guide][UG].
15/// This documentation focuses on the implementation and its API.
16///
17/// [UG]: https://lihpc-computational-geometry.github.io/honeycomb/user-guide/definitions/cmaps
18///
19/// Notes on implementation:
20/// - We encode *β<sub>0</sub>* as the inverse function of *β<sub>1</sub>*. This is extremely
21///   useful (read *required*) to implement correct and efficient i-cell computation. Additionally,
22///   while *β<sub>0</sub>* can be accessed using the [`beta`][Self::beta] method, we do not define
23///   the 0-sew / 0-unsew operations.
24/// - We chose a boundary-less representation of meshes (i.e. darts on the boundary are 2-free).
25/// - The null dart will always be encoded as `0`.
26///
27/// ## Generics
28///
29/// - `T: CoordsFloat` -- Generic FP type for coordinates representation
30///
31/// ## Example
32///
33/// The following code corresponds to this flow of operations:
34///
35/// ![`CMAP2_EXAMPLE`](https://lihpc-computational-geometry.github.io/honeycomb/user-guide/images/bg_hcmap_example.svg)
36///
37/// Note that:
38/// - we create the map using its builder structure: [`CMapBuilder`][crate::prelude::CMapBuilder]
39/// - we insert a few assertions to demonstrate the progressive changes applied to the structure
40/// - even though the faces are represented in the figure, they are not stored in the structure
41/// - we use a lot of methods with the `force_` prefix; these are convenience methods when
42///   synchronization isn't needed
43///
44/// ```
45/// # fn main() {
46/// use honeycomb_core::{
47///     cmap::{CMap2, CMapBuilder, OrbitPolicy},
48///     geometry::Vertex2
49/// };
50///
51/// // build a triangle (A)
52/// let mut map: CMap2<f64> = CMapBuilder::<2, _>::from_n_darts(3).build().unwrap(); // three darts
53/// map.force_link::<1>(1, 2); // beta1(1) = 2 & beta0(2) = 1
54/// map.force_link::<1>(2, 3); // beta1(2) = 3 & beta0(3) = 2
55/// map.force_link::<1>(3, 1); // beta1(3) = 1 & beta0(1) = 3
56/// map.force_write_vertex(1, (0.0, 0.0));
57/// map.force_write_vertex(2, (1.0, 0.0));
58/// map.force_write_vertex(3, (0.0, 1.0));
59///
60/// // we can go through the face using an orbit
61/// {
62///     let mut face = map.orbit(OrbitPolicy::Face, 1);
63///     assert_eq!(face.next(), Some(1));
64///     assert_eq!(face.next(), Some(2));
65///     assert_eq!(face.next(), Some(3));
66///     assert_eq!(face.next(), None);
67/// }
68///
69/// // build a second triangle (B)
70/// let first_added_dart_id = map.add_free_darts(3);
71/// assert_eq!(first_added_dart_id, 4);
72/// map.force_link::<1>(4, 5);
73/// map.force_link::<1>(5, 6);
74/// map.force_link::<1>(6, 4);
75/// map.force_write_vertex(4, (0.0, 2.0));
76/// map.force_write_vertex(5, (2.0, 0.0));
77/// map.force_write_vertex(6, (1.0, 1.0));
78///
79/// // there should be two faces now
80/// let faces: Vec<_> = map.iter_faces().collect();
81/// assert_eq!(&faces, &[1, 4]);
82///
83/// // sew both triangles (C)
84/// map.force_sew::<2>(2, 4);
85///
86/// // there are 5 edges now, making up a square & its diagonal
87/// let edges: Vec<_> = map.iter_edges().collect();
88/// assert_eq!(&edges, &[1, 2, 3, 5, 6]);
89///
90/// // adjust bottom-right & top-left vertex position (D)
91/// assert_eq!(
92///     map.force_write_vertex(2, Vertex2::from((1.0, 0.0))),
93///     Some(Vertex2(1.5, 0.0)) // `write` act as a `replace`
94/// );
95/// assert_eq!(
96///     map.force_write_vertex(3, Vertex2::from((0.0, 1.0))),
97///     Some(Vertex2(0.0, 1.5)) // these values were the average of sewn vertices
98/// );
99///
100/// // separate the diagonal from the rest (E)
101/// map.force_unsew::<1>(1);
102/// map.force_unsew::<1>(2);
103/// map.force_unsew::<1>(6);
104/// map.force_unsew::<1>(4);
105/// // break up & remove the diagonal
106/// map.force_unsew::<2>(2); // this makes dart 2 and 4 free
107/// map.remove_free_dart(2);
108/// map.remove_free_dart(4);
109/// // sew the square back up
110/// map.force_sew::<1>(1, 5);
111/// map.force_sew::<1>(6, 3);
112///
113/// // there's only the square face left
114/// let faces: Vec<_> = map.iter_faces().collect();
115/// assert_eq!(&faces, &[1]);
116/// // we can check the vertices
117/// let vertices = map.iter_vertices();
118/// let mut value_iterator = vertices.map(|vertex_id| map.force_read_vertex(vertex_id).unwrap());
119/// assert_eq!(value_iterator.next(), Some(Vertex2::from((0.0, 0.0)))); // vertex ID 1
120/// assert_eq!(value_iterator.next(), Some(Vertex2::from((0.0, 1.0)))); // vertex ID 3
121/// assert_eq!(value_iterator.next(), Some(Vertex2::from((1.0, 0.0)))); // vertex ID 5
122/// assert_eq!(value_iterator.next(), Some(Vertex2::from((1.0, 1.0)))); // vertex ID 6
123/// # }
124/// ```
125pub struct CMap2<T: CoordsFloat> {
126    /// List of vertices making up the represented mesh
127    pub(super) attributes: AttrStorageManager,
128    /// List of vertices making up the represented mesh
129    pub(super) vertices: AttrSparseVec<Vertex2<T>>,
130    /// List of free darts identifiers, i.e. empty spots
131    /// in the current dart list
132    pub(super) unused_darts: UnusedDarts,
133    /// Array representation of the beta functions
134    pub(super) betas: BetaFunctions<CMAP2_BETA>,
135    /// Current number of darts
136    pub(super) n_darts: usize,
137}
138
139unsafe impl<T: CoordsFloat> Send for CMap2<T> {}
140unsafe impl<T: CoordsFloat> Sync for CMap2<T> {}
141
142#[doc(hidden)]
143/// **Constructor convenience implementations**
144impl<T: CoordsFloat> CMap2<T> {
145    /// Creates a new 2D combinatorial map.
146    #[allow(unused)]
147    #[must_use = "unused return value"]
148    pub(crate) fn new(n_darts: usize) -> Self {
149        Self {
150            attributes: AttrStorageManager::default(),
151            vertices: AttrSparseVec::new(n_darts + 1),
152            unused_darts: UnusedDarts::new(n_darts + 1),
153            betas: BetaFunctions::new(n_darts + 1),
154            n_darts: n_darts + 1,
155        }
156    }
157
158    /// Creates a new 2D combinatorial map with user-defined attributes
159    ///
160    /// We expect the passed storages to be defined but empty, i.e. attributes are known,
161    /// but no space has been used/  allocated yet.
162    #[must_use = "unused return value"]
163    pub(crate) fn new_with_undefined_attributes(
164        n_darts: usize,
165        mut attr_storage_manager: AttrStorageManager,
166    ) -> Self {
167        // extend all storages to the expected length: n_darts + 1 (for the null dart)
168        attr_storage_manager.extend_storages(n_darts + 1);
169        Self {
170            attributes: attr_storage_manager,
171            vertices: AttrSparseVec::new(n_darts + 1),
172            unused_darts: UnusedDarts::new(n_darts + 1),
173            betas: BetaFunctions::new(n_darts + 1),
174            n_darts: n_darts + 1,
175        }
176    }
177}
honeycomb_core/cmap/dim2/structure.rs

honeycomb_core/cmap/dim2/
structure.rs
