geometry-central

A BarycentricVector is a vector that lies along a surface, representing a displacement between two points. It is currently only supported on triangle meshes.

Unlike a ray, a BarycentricVector represents a constant vector field within a face. It can exist in three states, indicated by the BarycentricVector::type enum:

• Face: The vector lies within a specific face. It is identified by BarycentricVector::face and its coordinates are stored in BarycentricVector::faceCoords (expressed in barycentric coordinates of the face).
• Edge: The vector lies along a specific edge. It is identified by BarycentricVector::edge and its coordinates are stored in BarycentricVector::edgeCoords (ordered according to the edge's vertices).
• Vertex: The vector is at a single vertex. It is identified by BarycentricVector::vertex and is always a zero-length vector.

Barycentric vectors are useful for intrinsic geometry computations, such as inner products, because they allow for vector arithmetic that depends only on the surface's intrinsic properties.

enum class BarycentricVectorType { Face = 0, Edge, Vertex };

The SignpostIntrinsicTriangulation is a data structure that encodes an intrinsic triangulation by storing "signposts" at mesh vertices. For every intrinsic edge, it stores the edge's length and its direction at the two incident vertices. This information allows the triangulation to be positioned above the input mesh.

Tradeoffs

Compared to the IntegerCoordinates representation, signposts have the following characteristics:

• Pros:
  • Performance: Generally faster runtime than integer coordinates.
  • Tangent vector data: Naturally provides tangent space coordinate systems consistent with the input mesh, facilitating work with tangent-valued data.
• Cons:
  • Robustness: Relies on tracing intrinsic edge paths across the input surface, which can be sensitive to floating-point errors. Reconstructing a common subdivision may fail if the input mesh contains degenerate triangles.

When computing $n$-direction fields where $n > 1$ (such as line fields where $n=2$ or cross fields where $n=4$), geometry-central uses a "power" representation for efficiency. Instead of storing a single tangent vector, it stores a vector raised to the $n$-th power (using complex number exponentiation). This ensures that all $n$ symmetric directions map to the same representative vector.

To recover the actual $n$ tangent direction vectors from a representative vector, you must take the $n$-th root and then rotate the resulting vector to find the other directions.

// Compute a cross field
int n = 4; 
VertexData<Vector2> crossValues = computeSmoothestVertexDirectionField(*geometry, n);

for(Vertex v : mesh->vertices()) {
  
  Vector2 representative = crossValues[v];
  // take the n'th root to get a base direction
  Vector2 crossDir = crossDir.pow(representative, 1. / n); 

  // loop over the n directions
  for(int rot = 0; rot < 4; rot++) {
    // crossDir is one of the four cross directions, as a tangent vector
    crossDir = crossDir.rot90();
  }
}

Block decomposition allows you to decompose a square matrix into interleaved submatrix blocks (AA, AB, BA, BB). This is commonly used to extract boundary components of a finite element matrix to apply boundary conditions.

1. Define Membership: Create a Vector<bool> where true indicates entries belonging to set 'A' (e.g., boundary nodes) and false indicates set 'B' (interior nodes).
2. Decompose: Use blockDecomposeSquare to generate a BlockDecompositionResult.
3. Partition Vectors: Use decomposeVector to split a global vector (like a RHS vector) into components for A and B.
4. Solve and Reassemble: Solve the reduced system using the sub-blocks and reassembleVector to combine the interior solution and boundary values into a full vector.

// Hypothetical input data
SparseMatrix<double> mat = /* your square matrix */;
size_t N = mat.rows();
size_t NBoundary = /* ... */;
Vector<double> rhsVals = Vector<double>::Zero(N);        // rhs for the system
Vector<double> bcVals = Vector<double>::Ones(NBoundary); // boundary values at
                                                         // some nodes

// Build the membership vector, which indicates which entries should be separated
// in to set "A" (others are in "B")
Vector<bool> setAMembership(N);
for(size_t i = 0; i < N; i++) {
  if(/* element i is boundary */) {
    setAMembership(i) = true;
  } else {
    setAMembership(i) = false;
  }
}

// Construct the decomposition 
BlockDecompositionResult<double> decomp = 
  blockDecomposeSquare(mat, setAMembership, true);

// The four sub-blocks of the matrix are now in
// decomp.AA, decomp.AB, decomp.BA, decomp.BB

// Split up the rhs vector
Vector<double> rhsValsA, rhsValsB;
decomposeVector(decomp, rhsVals, rhsValsA, rhsValsB);

// Solve problem
Vector<double> combinedRHS = rhsValsA - decomp.AB * bcVals;
Vector<double> Aresult = solve(decomp.AA, combinedRHS);

// Combine the two boundary conditions and interior solution to a full vector
Vector<double> result = reassembleVector(decomp, Aresult, bcVals);

Geometry Central provides two primary mesh types for representing surfaces:

1. SurfaceMesh: A general-purpose polygonal mesh structure. It can represent non-manifold meshes (e.g., three faces meeting at a single edge). Use this when your geometry does not satisfy manifold constraints.
2. ManifoldSurfaceMesh: A specialized, more efficient version of SurfaceMesh that strictly enforces manifoldness and orientation. It inherits from SurfaceMesh, so it can be used anywhere a SurfaceMesh is required.

Key Differences:

• Manifoldness: ManifoldSurfaceMesh requires that the surface locally looks like a plane (no hourglass vertices or multiple faces per edge).
• Orientation: ManifoldSurfaceMesh requires a consistent combinatorial orientation (clockwise ordering of halfedges around faces). It cannot represent non-orientable surfaces like a Klein bottles.
• Operations: Some mutations that would make a mesh non-manifold should only be called on a SurfaceMesh. ManifoldSurfaceMesh guarantees its invariants are preserved during all operations.

#include "geometrycentral/surface/surface_mesh.h"
#include "geometrycentral/surface/manifold_surface_mesh.h"

In Geometry Central, element types like Vertex, Halfedge, Edge, Face, BoundaryLoop, and Corner are not the actual mesh data themselves, but rather lightweight "handles" (temporary references) to the underlying elements.

Key behaviors:

• Lifecycle: Creating a Vertex variable does not create a new vertex in the mesh; it just refers to one. Allowing a handle to go out of scope does not delete the element from the mesh.
• Identity: Multiple handle variables can refer to the same underlying element.
• Construction: You should not call constructors directly. Instead, obtain handles by:
  • Iterating through the mesh (e.g., for(Vertex v : mesh.vertices()))
  • Traversing from a neighbor (e.g., Face f = halfedge.face())
  • Iterating around an element (e.g., for(Halfedge he : vertex.outgoingHalfedges()))
• Comparison & Hashing: All handles support equality checks (==, !=), comparisons (<, >, <=, >=) based on iteration order, and hashing (allowing them to be used as keys in std::unordered_map).