Epic: Phase 4 — Edit Mode: Topology Tools

[fernandotonon]

Overview

Build on the Phase 3 vertex editing foundation to add topology modification tools — operations that change the mesh structure (add/remove vertices, edges, faces), not just move existing ones.

Prerequisites

• Phase 3 (Edit Mode with vertex/edge/face selection and transform)

Scope

1. Upgrade to Half-Edge Data Structure

• Replace the Phase 3 indexed mesh with a half-edge structure for topology queries
• Support: vertex split, edge collapse, face subdivision, boundary detection
• Efficient adjacency queries: faces around vertex, edges around face, vertices around edge
• Maintain UV seams, hard edges, and material boundaries during topology changes

2. Extrude

• Extrude Faces (E key with face selection): duplicate selected faces and connect to originals, then enter grab mode
• Extrude Edges (E key with edge selection): create new faces connecting selected edges to new positions
• Extrude Along Normals: extrude each face along its own normal (Alt+E)
• Extrude Region: extrude connected face selection as a single group
• Undo support

3. Bevel

• Bevel Edges (Ctrl+B): replace sharp edge with chamfer, mouse wheel adjusts segment count
• Bevel Vertices: create faceted corner at selected vertices
• Width control during operation (mouse movement)
• Profile control: flat, convex, concave (mouse wheel or input field)

4. Loop Cut

• Loop Cut (Ctrl+R): hover over edge to preview a loop cut location
• Mouse wheel to add parallel cuts
• Confirm with click, cancel with Escape
• Slide: adjust cut position along the edge after placement

5. Knife Tool

• Knife (K key): click vertices/edges to define a cut path
• Snaps to existing vertices and edge midpoints
• Enter to confirm cut, Escape to cancel
• Creates new edges and splits faces along the cut path

6. Merge Vertices

• Merge (M → Merge At Center): merge selected vertices to their centroid
• Reports: "Merged N vertices"

7. Delete / Dissolve

• Delete Vertices (X → Vertices): remove selected vertices and all connected faces
• Delete Edges (X → Edges): remove edges and adjacent faces
• Delete Faces (X → Faces): remove faces, keep edges and vertices
• Dissolve Vertices: remove vertices, merge surrounding faces
• Dissolve Edges: remove edges, merge adjacent faces
• All operations maintain mesh integrity (no dangling edges/vertices)

8. Subdivide

• Subdivide (right-click → Subdivide): split each selected face into 4 (quad) or 3 (tri) sub-faces
• Smooth option: Catmull-Clark subdivision (quads) or Loop subdivision (triangles)
• Fractal displacement option for organic surfaces

9. Fill / Grid Fill

• Fill (F key): create a face from 3-4 selected vertices or fill a closed edge loop
• Grid Fill: fill a closed edge loop with a grid of quads (useful for capping holes)

Technical Notes

• Half-edge implementation: consider using OpenMesh or a lightweight custom implementation
• Each topology operation needs its own QUndoCommand subclass storing full mesh state delta (or using command pattern with inverse operations)
• Performance: topology operations on meshes >10K faces should use spatial acceleration
• UV preservation: when splitting edges, interpolate UV coordinates linearly
• Bone weight preservation: when adding new vertices, interpolate weights from neighbors

Acceptance Criteria

• Extrude faces/edges with real-time preview
• Bevel edges with adjustable width and segments
• Loop cut with preview and slide
• Knife tool for freeform cuts
• Merge vertices by distance and at center
• Delete/dissolve operations maintain mesh integrity
• Subdivide with smooth option
• Fill faces from selected vertices/edge loops
• All operations are undoable
• UV coordinates and bone weights preserved through topology changes
• Exported mesh reflects all topology modifications