update user guide

.gitignore

@@ -1,2 +1,4 @@
+/target
 
-/target
+serve_doc.sh
+kill_doc.sh

README.md

@@ -11,6 +11,33 @@ issues, thanks to the language's guarantees.
 
 ## Usage
 
+The [user guide][UG] provides an overview of everything available in the 
+project. It can be generated offline using **mdbook**: 
+
+```shell
+# Serve the doc on a local server
+mdbook serve --open -d ../target/doc/ honeycomb-guide/ &
+cargo doc --all --no-deps
+```
+
+```shell
+# Kill the local server
+kill $(pidof mdbook) 
+
+# Without pidof
+kill $(ps -e | awk '/mdbook/ {print $1}')
+```
+
+[UG]: https://lihpc-computational-geometry.github.io/honeycomb/
+
+### Rust
+
+Basic structure are provided in the **honeycomb-core** crate. Its content is listed
+in the [user guide][UGHC] and details about its usage can be found in its [Rust documentation][DOCHC]
+
+[UGHC]: https://lihpc-computational-geometry.github.io/honeycomb/project-structure/honeycomb-core.html
+[DOCHC]: https://lihpc-computational-geometry.github.io/honeycomb/honeycomb_core/
+
 ## Contributing
 
 ## License

honeycomb-core/src/twomap.rs

@@ -76,7 +76,7 @@ const TWO_MAP_BETA: usize = 3;
 /// The following example goes over multiple operations on the mesh in order
 /// to demonstrate general usage of the structure and its methods.
 ///
-/// ![TWOMAP_EXAMPLE](link_to_example_file.svg)
+/// ![TWOMAP_EXAMPLE](../../images/TwoMapExample.svg)
 ///
 /// Note that the map we operate on has no boundaries. In addition to the different
 /// operations realized at each step, we insert a few assertions to demonstrate the

honeycomb-guide/src/SUMMARY.md

@@ -6,6 +6,7 @@
 
 - [Workspace](./project-structure/workspace.md)
     - [honeycomb-core](./project-structure/honeycomb-core.md)
+    - [honeycomb-guide](./project-structure/honeycomb-guide.md)
 
 # Definitions
 
@@ -15,4 +16,17 @@
     - [Beta Functions](./definitions/betaf.md)
     - [Orbits](./definitions/orbits.md)
     - [Embedding](./definitions/embedding.md)
-- [Basic Operations](./definitions/basicops.md)
+- [Basic Operations](./definitions/basicops.md)
+    - [Add / Remove a dimension](./definitions/changeNdim.md)
+    - [Add / Remove a free dart](./definitions/changeNdart.md)
+    - [Sewing operation](./definitions/sew.md)
+    - [Unsewing operation](./definitions/unsew.md)
+- [Advanced Operations](./definitions/advancedops.md)
+    - [Generic orbit](./definitions/genorbit.md)
+    - [I-cells computation](./definitions/icells.md)
+    - [Orientation](./definitions/orientation.md)
+
+# Examples
+
+- [TwoMap](./examples/twomap.md)
+

honeycomb-guide/src/definitions/advancedops.md

@@ -0,0 +1 @@
+# Advanced Operations

honeycomb-guide/src/definitions/betaf.md

@@ -1 +1,25 @@
 # Beta Functions
+
+Each combinatorial map of dimension *N* defines *N* beta functions linking 
+the set of darts together (e.g. a 2-map contains *β<sub>1</sub>* and 
+*β<sub>2</sub>*). These functions model the topology of the map, giving 
+information about connections of the different cells of the map / mesh. In 
+our case, we mostly use:
+
+- *β<sub>1</sub>*, a (partial) permutation, 
+- *β<sub>2</sub>*, *β<sub>3</sub>*, two (partial) involutions
+
+
+<figure style="text-align:center">
+    <img src="../images/BetaFunc.svg" alt="Embed" />
+    <figcaption><i>Representation of β<sub>1</sub> (red, only on a single face) and β<sub>2</sub> (yellow) for a simple 2-map</i></figcaption>
+</figure>
+
+Additionally, we define *β<sub>0</sub>* as the inverse of *β<sub>1</sub>*, i.e. 
+*β<sub>0</sub>(β<sub>1</sub>(d)) = d*. This comes from a practical consideration
+for performances and efficiency of the implementation.
+
+The *β<sub>i</sub>* functions can be interpreted as navigation functions along the
+*i-th* dimensions: *β<sub>1</sub>* makes you navigate along the edges, *β<sub>2</sub>*
+along the faces, etc. This can be generalized to *N* dimensions, but we are only 
+interested in 2D and 3D at the moment.

honeycomb-guide/src/definitions/changeNdart.md

@@ -0,0 +1 @@
+# Add / Remove a free dart

honeycomb-guide/src/definitions/changeNdim.md

@@ -0,0 +1 @@
+# Add / Remove a dimension

honeycomb-guide/src/definitions/cmaps.md

@@ -1 +1,26 @@
 # Combinatorial Maps
+
+N-dimensional combinatorial maps, noted *N-map*, are objects made up of 
+two main elements:
+
+- A set of darts, darts being the smallest elements making up the map
+- N beta functions, linking the darts of the map
+
+Additionally, we can define *embedded data* as spatial anchoring of the 
+darts making up the map. While the first two elements hold topological
+information, embedded data gives information about the "shape" of the 
+map (e.g. vertices position in a spatial domain).
+
+With these elements, we can represent and operate on meshes. 
+
+## Example
+
+Operations on a combinatorial map can affect its topology, shape or both:
+
+<figure style="text-align:center">
+    <img src="../images/TwoMapMesh.svg" alt="MapMeshEquivalent" />
+    <figcaption><i>Mesh-Map equivalent of a four step transformation</i></figcaption>
+</figure>
+
+The specifics on how data is encoded is detailed in attribute-specific 
+sections.

honeycomb-guide/src/definitions/darts.md

@@ -1 +1,16 @@
 # Darts
+
+Darts are the finest grain composing combinatorial maps. The structure
+of the map is given by the relationship between darts, defined through 
+beta functions.
+
+<figure style="text-align:center">
+    <img src="../images/Darts.svg" alt="Darts" />
+    <figcaption><i>Boundless square modeling using four darts</i></figcaption>
+</figure>
+
+In our implementation, darts exist implictly through indexing and their
+associated data. There are no dart *objects* in a strict sense, there is
+only a given number of dart, their associated data ordered by an array-like
+logic, and a record of "unused" slots that can be used for dart insertion.
+Because of this, we assimilate dart and dart index.

honeycomb-guide/src/definitions/embedding.md

@@ -1 +1,31 @@
 # Embedding
+
+Embedding, or embedded data refers to the association of topological
+entities (darts, *i*-cells) to geometrical data (spatial positions,
+vertices, faces, volumes).
+
+We choose to encode the origin of darts as their associated vertex. In
+order to avoid duplicating coordinates, what is associated to each dart
+is an identifier, meaning that all darts starting from a given point in 
+space share the same associated vertex ID.
+
+<figure style="text-align:center">
+    <img src="../images/Embed.svg" alt="Embed" />
+    <figcaption><i>Geometric embedding of spatial data</i></figcaption>
+</figure>
+
+In the above example, the data would be organized in the following way:
+
+- *darts = { null, d1, d2, d3, d4 }*
+- *associated_vertex = { null, v1, v2, v3, v4 }*
+- *vertices = { (0.0, 0.0), (0.0, 1.0), (1.0, 1.0), (1.0, 0.0) }*
+
+In this case, *v1 = 0*; *v2 = 1*; *v3 = 2*; *v4 = 3*.
+
+Association of darts and vertices ID is done implictly through indexing;
+In practice, the *darts* vector does not even exist. This example is limited
+to vertices, but we also keep track of faces, and volumes eventually.
+
+The embedding of geometrical data also has implication for operations
+on the map. This is detailed along operation specificities in their 
+dedicated sections.

honeycomb-guide/src/definitions/genorbit.md

@@ -0,0 +1 @@
+# Generic orbit

honeycomb-guide/src/definitions/icells.md

@@ -0,0 +1 @@
+# I-cells

honeycomb-guide/src/definitions/introduction.md

@@ -1 +1,11 @@
 # Introduction
+
+## Scope
+
+Because our implementation has very practical goals, the definitions 
+presented here use a more intuitive approach rather than strict 
+mathematical concepts.
+
+Our main interest at the moment being 2D and 3D combinatorial maps,
+some operations are defined with consideration to these restricitions.
+This is especially useful for orbits and sewing operations.

honeycomb-guide/src/definitions/orbits.md

@@ -1 +1,26 @@
 # Orbits
+
+We define orbits as a set of darts that are accessible from a given dart, 
+using a certain set of beta functions. For example:
+
+- *⟨β<sub>1</sub>⟩(d)* refers to all darts accessible from *d* using 
+  *β<sub>1</sub>* recursively any number of times.
+- *⟨β<sub>1</sub>, β<sub>3</sub>⟩(d)* refers to all darts accessible 
+  from *d* using any combination of *β<sub>1</sub>* and *β<sub>3</sub>*.
+
+## *i*-cells
+
+A specific subset of orbits, refered to as *i*-cells are defined and often 
+used in algorithms. The general definition is the following: 
+
+- **if i = 0**:  *0-cell(d) = ⟨{ β<sub>j</sub> o β<sub>k</sub> with 1 ≤ j < k ≤ N }⟩(d)*
+- **else**: *i-cell(d) = ⟨β<sub>1</sub>, β<sub>2</sub>, ..., β<sub>i-1</sub>, β<sub>i+1</sub>, ..., β<sub>N</sub>⟩(d)*
+
+In our case, we can use specialized definitions for our dimensions:
+
+| *i* | Geometry | 2-map | 3-map |
+| --- | --- | --- | --- |
+| 0 | Vertex | *⟨β<sub>1</sub> o β<sub>2</sub>⟩(d)* <br> **or** <br> *⟨β<sub>2</sub> o β<sub>-1</sub>⟩(d)* | *⟨β<sub>3</sub> o β<sub>2</sub>, β<sub>1</sub> o β<sub>3</sub>⟩(d)* <br> **or** <br> *⟨β<sub>3</sub> o β<sub>2</sub>, β<sub>3</sub> o β<sub>-1</sub>⟩(d)* |
+| 1 | Edge | *⟨β<sub>2</sub>⟩(d)* | *⟨β<sub>2</sub>, β<sub>3</sub>⟩(d)* |
+| 2 | Face | *⟨β<sub>1</sub>⟩(d)* | *⟨β<sub>1</sub>, β<sub>3</sub>⟩(d)* |
+| 3 | Volume | - | *⟨β<sub>1</sub>, β<sub>2</sub>⟩(d)* |

honeycomb-guide/src/definitions/orientation.md

@@ -0,0 +1 @@
+# Orientation

honeycomb-guide/src/definitions/sew.md

@@ -0,0 +1 @@
+# Sewing operation

honeycomb-guide/src/definitions/unsew.md

@@ -0,0 +1 @@
+# Unsewing operation

honeycomb-guide/src/examples/twomap.md

@@ -0,0 +1,21 @@
+# TwoMap
+
+## Usage
+
+A general example is [provided](../honeycomb_core/twomap/struct.TwoMap.html#example) in 
+the Rust doc of the TwoMap structure. From a meshing perspective, it corresponds to the 
+following operations:
+
+<figure style="text-align:center">
+    <img src="../images/TwoMapExample.svg" alt="TwoMapExample" />
+    <figcaption><i>Sample operations transforming two triangles into a square</i></figcaption>
+</figure>
+
+After the creation of an initial map modeling a simple triangle, we:
+- (a) add & initialize new darts to the map to model a second triangle.
+- (b) 2-sew the two triangles using according to a  **StretchLeft** sewing policy.
+- (c) move the most upper right vertex to form a square using both triangles.
+- (d) 2-unsew the inner edge, free and remove its darts to form an actual square.
+
+Most of those steps require multiple method calls and assertions are used to highlight
+the modification done to the structure along the way.

honeycomb-guide/src/index.md

@@ -13,13 +13,30 @@ issues, thanks to the language's guarantees.
 
 ### Requirements
 
-- **Rust 1.75** - *The code may compile and work for earlier versions, but we do not test for those*
+- **Rust stable release** - *Development started on 1.75, but we might use 
+  newer features as the project progresses*
+
+### Quickstart
+
+#### Rust
+
+...
+
+#### Documentation
+
+You can generate this documentation locally using **mdbook** and **cargo doc**:
+
+```shell
+# Serve the doc on a local server
+mdbook serve --open -d ../target/doc/ honeycomb-guide/ &
+cargo doc --all --no-deps
+```
 
 ## Links
 
 ### Documentation
 
-- [honeycomb-core](honeycomb_core) *Core definitions and tools*
+- [honeycomb-core](honeycomb_core/) *Core definitions and tools*
 
 ### References
 

honeycomb-guide/src/project-structure/honeycomb-core.md

@@ -1 +1,46 @@
 # honeycomb-core
+
+[Documentation](../honeycomb_core/)
+
+--- 
+
+**honeycomb-core** is a Rust crate that provides basic structures and 
+operations for combinatorial map manipulation. This includes map structures, 
+methods implementation, type aliases and geometric modeling for mesh
+representation.
+
+## Usage
+
+A quickstart example encompassing most features is provided for the following 
+structures:
+
+- [TwoMap](../honeycomb_core/twomap/struct.TwoMap.html#example)
+
+## Content
+
+### Structures
+
+- **TwoMap**: 2D combinatorial map implementation
+
+### Aliases
+
+- **Vertex2**: 2-elements array
+- **DartIdentifier**: Integer identifier for darts
+- **VertexIdentifier**: Integer identifier for 0D cells
+- **FaceIdentifier**: Integer identifier for 2D cells
+- **VolumeIdentifier**: Integer identifier for 3D cells
+
+### Enums
+
+- **SewPolicy**: Logic to follow for the geometrical part of the sewing operation.
+- **UnsewPolicy**: Logic to follow for the geometrical part of the unsewing operation.
+
+## Future additions
+
+- [ ] Add a custom vector type for spatial representation (2D & 3D)
+- [ ] Replace returned `Vec` by an alternative structure or type
+  to prevent too many runtime allocations.
+- [ ] Write structure benchmarks (2D)
+- [ ] Add I/O support for mesh formats (2D)
+- [ ] Add orientation checks (2D)
+- [ ] Implement 3D maps

honeycomb-guide/src/project-structure/honeycomb-guide.md

@@ -0,0 +1,27 @@
+# honeycomb-guide
+
+---
+
+**honeycomb-guide** is the mdbook project used to generate the documentation you are
+currently reading. Its content mainly focuses on definition and feature-listing 
+rather than technical details on implementation. The latter can be found in the code 
+documentation.
+
+## Building
+
+You can generate this documentation locally using **mdbook** and **cargo doc**:
+
+```shell
+mdbook serve --open -d ../target/doc/ honeycomb-guide/ &
+cargo doc --all --no-deps
+```
+
+## Contributing
+
+A few observations on writing documentation using **mdbook**:
+
+- Note that if you edit the user guide's content, you will have to generate the rust doc 
+  again as mdbook remove all files of its target folder at each update.
+- When linking to a folder containing an `index.html` file, be sure to include the last 
+  `/` in the name of the folder if you don't name the index file directly. Not including 
+  that last character seems to break in-file linking of the local version.