From 20aa5101bc97730e57fcdef542eac5d0d8bda11d Mon Sep 17 00:00:00 2001 From: Hanno Braun Date: Wed, 22 Feb 2023 12:47:39 +0100 Subject: [PATCH 1/3] Fix typo in doc comment --- crates/fj-kernel/src/objects/full/edge.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/fj-kernel/src/objects/full/edge.rs b/crates/fj-kernel/src/objects/full/edge.rs index 2c578bd06..96a9236a8 100644 --- a/crates/fj-kernel/src/objects/full/edge.rs +++ b/crates/fj-kernel/src/objects/full/edge.rs @@ -72,7 +72,7 @@ impl fmt::Display for HalfEdge { /// An edge, defined in global (3D) coordinates /// -/// In contract to [`HalfEdge`], `GlobalEdge` is undirected, meaning it has no +/// In contrast to [`HalfEdge`], `GlobalEdge` is undirected, meaning it has no /// defined direction, and its vertices have no defined order. This means it can /// be used to determine whether two [`HalfEdge`]s map to the same `GlobalEdge`, /// regardless of their direction. From fd641dcd818a485bdfbac4f5b5c3670c00457d7e Mon Sep 17 00:00:00 2001 From: Hanno Braun Date: Wed, 22 Feb 2023 13:20:17 +0100 Subject: [PATCH 2/3] Update documentation of `HalfEdge` --- crates/fj-kernel/src/objects/full/edge.rs | 37 ++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/crates/fj-kernel/src/objects/full/edge.rs b/crates/fj-kernel/src/objects/full/edge.rs index 96a9236a8..be36a9239 100644 --- a/crates/fj-kernel/src/objects/full/edge.rs +++ b/crates/fj-kernel/src/objects/full/edge.rs @@ -8,7 +8,42 @@ use crate::{ storage::{Handle, HandleWrapper}, }; -/// A half-edge +/// A directed edge, defined in a surface's 2D space +/// +/// The concept of an "edge" in Fornjot is represented by two structs, +/// `HalfEdge` and [`GlobalEdge`]. `HalfEdge` has two attributes that make it +/// distinct from [`GlobalEdge`]: +/// +/// - `HalfEdge` is directed, meaning it has a defined start and end vertex. +/// - `HalfEdge` is defined in the 2-dimensional space of a surface. +/// +/// When multiple faces, which are bound by edges, are combined to form a solid, +/// the `HalfEdge`s that bound the face on the surface are then coincident with +/// the `HalfEdge`s of other faces, where those faces touch. Those coincident +/// `HalfEdge`s are different representations of the same edge. This edge is +/// represented by an instance of [`GlobalEdge`]. +/// +/// There are some requirements that a `HalfEdge` needs to uphold to be valid: +/// +/// 1. Coincident `HalfEdge`s *must* refer to the same [`GlobalEdge`]. +/// 2. `HalfEdge`s that are coincident, i.e. located in the same space, must +/// always be congruent. This means they must coincide *exactly*. The overlap +/// must be complete. None of the coincident `HalfEdge`s must overlap with +/// just a section of another. +/// +/// That second requirement means that a `HalfEdge` might need to be split into +/// multiple smaller `HalfEdge`s that are each coincident with a `HalfEdge` in +/// another face. +/// +/// # Implementation Note +/// +/// There is no validation code that verifies whether coincident `HalfEdge`s +/// refer to the same [`GlobalEdge`] or not: +/// +/// +/// Conversely, there is no validation code to verify that coincident +/// `HalfEdge`s are congruent: +/// #[derive(Clone, Debug, Eq, PartialEq, Hash, Ord, PartialOrd)] pub struct HalfEdge { curve: Handle, From c00ac2eab8b1290977d72c004309137bd7834d89 Mon Sep 17 00:00:00 2001 From: Hanno Braun Date: Wed, 22 Feb 2023 13:23:03 +0100 Subject: [PATCH 3/3] Update documentation of `GlobalEdge` --- crates/fj-kernel/src/objects/full/edge.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/crates/fj-kernel/src/objects/full/edge.rs b/crates/fj-kernel/src/objects/full/edge.rs index be36a9239..c25653416 100644 --- a/crates/fj-kernel/src/objects/full/edge.rs +++ b/crates/fj-kernel/src/objects/full/edge.rs @@ -105,12 +105,15 @@ impl fmt::Display for HalfEdge { } } -/// An edge, defined in global (3D) coordinates +/// An undirected edge, defined in global (3D) coordinates /// /// In contrast to [`HalfEdge`], `GlobalEdge` is undirected, meaning it has no /// defined direction, and its vertices have no defined order. This means it can /// be used to determine whether two [`HalfEdge`]s map to the same `GlobalEdge`, /// regardless of their direction. +/// +/// See [`HalfEdge`]'s documentation for more information on the relationship +/// between [`HalfEdge`] and `GlobalEdge`. #[derive(Clone, Debug, Eq, PartialEq, Hash, Ord, PartialOrd)] pub struct GlobalEdge { curve: HandleWrapper,