Complete research project

research/13-mesh-operations.md

@@ -0,0 +1,200 @@
+# Mesh Operations
+
+## Summary
+
+MatterControl provides comprehensive mesh processing capabilities through the agg-sharp/PolygonMesh libraries, supporting import/export of various formats, mesh manipulation, boolean operations, repair, and optimization.
+
+## Technical Description
+
+### Mesh Architecture
+
+```
+Mesh (PolygonMesh)
+├── Vertices (Vector3 positions)
+├── Faces (triangles)
+├── FaceBsp (spatial acceleration)
+└── Properties
+    ├── BoundingBox
+    └── Volume
+```
+
+### Supported Formats
+
+**Import:**
+| Format | Extension | Handler |
+|--------|-----------|---------|
+| STL | .stl | `StlProcessing` |
+| OBJ | .obj | `ObjSupport` |
+| AMF | .amf | `AmfDocument` |
+| 3MF | .3mf | `Object3D.Load()` |
+| MCX | .mcx | Native format |
+
+**Export:**
+| Format | Extension | Handler |
+|--------|-----------|---------|
+| STL (binary) | .stl | `MeshFileIo.Save()` |
+| STL (ASCII) | .stl | `MeshFileIo.Save()` |
+| AMF | .amf | `AmfDocument.Save()` |
+| 3MF | .3mf | `Object3D.Save()` |
+
+### Mesh Processing
+
+Located in `Submodules/agg-sharp/PolygonMesh/Processors/`:
+
+| Processor | Purpose |
+|-----------|---------|
+| `MeshHelper` | Common mesh operations |
+| `StlProcessing` | STL import/export |
+| `CsgOperations` | Boolean operations |
+
+### Boolean Operations
+
+CSG (Constructive Solid Geometry):
+
+```csharp
+// Union
+Mesh result = CsgOperations.Union(meshA, meshB);
+
+// Subtraction
+Mesh result = CsgOperations.Subtract(meshA, meshB);
+
+// Intersection
+Mesh result = CsgOperations.Intersect(meshA, meshB);
+```
+
+**Implementation:**
+- Uses BSP trees for spatial partitioning
+- Handles coplanar faces
+- Produces manifold output
+
+### Mesh Repair
+
+`RepairObject3D` fixes common mesh issues:
+
+| Fix | Description |
+|-----|-------------|
+| Hole filling | Close open boundaries |
+| Duplicate removal | Remove coincident vertices |
+| Normal repair | Fix inverted normals |
+| Non-manifold | Repair non-manifold edges |
+
+### Mesh Decimation
+
+`DecimateObject3D` reduces polygon count:
+
+```csharp
+public class DecimateObject3D : MeshWrapperObject3D
+{
+    public double ReductionPercent { get; set; } = 50;
+}
+```
+
+Uses edge collapse algorithm preserving shape.
+
+### Mesh Transforms
+
+| Operation | Method |
+|-----------|--------|
+| Translate | `mesh.Translate(offset)` |
+| Rotate | `mesh.Transform(rotationMatrix)` |
+| Scale | `mesh.Transform(scaleMatrix)` |
+| Mirror | Transform with negative scale |
+
+### Spatial Acceleration
+
+`FaceBspTree` provides fast ray intersection:
+
+```csharp
+var bspTree = FaceBspTree.Create(mesh);
+var hit = bspTree.GetClosestIntersection(ray);
+```
+
+Uses for:
+- Object selection (picking)
+- Collision detection
+- Boolean operations
+
+### MCX Format
+
+Native scene format (JSON-based):
+
+```
+MCX file (ZIP archive)
+├── manifest.json (metadata)
+├── scene.json (scene graph)
+└── Assets/
+    └── {guid}.stl (mesh files)
+```
+
+**Benefits:**
+- Preserves scene hierarchy
+- Stores parametric data
+- Includes thumbnails
+
+### Mesh Helpers
+
+Utility methods in `MeshHelper`:
+
+| Method | Purpose |
+|--------|---------|
+| `CreateCylinder()` | Generate cylinder mesh |
+| `CreateCube()` | Generate box mesh |
+| `CreateSphere()` | Generate sphere mesh |
+| `CopyFaces()` | Duplicate face subset |
+| `Split()` | Split mesh by plane |
+
+### Volume Calculation
+
+```csharp
+double volume = mesh.GetVolume();
+AxisAlignedBoundingBox bounds = mesh.GetAxisAlignedBoundingBox();
+```
+
+Used for:
+- Material estimation
+- Scale validation
+- Build volume checking
+
+### Design Rationale
+
+**Custom Mesh Library**: Using PolygonMesh provides:
+- Full control over algorithms
+- Optimized for 3D printing use cases
+- No external dependencies
+
+**BSP Acceleration**: Spatial indexing enables:
+- Fast ray casting for selection
+- Efficient boolean operations
+- Real-time collision checks
+
+**MCX Format**: Custom format allows:
+- Full scene preservation
+- Parametric object storage
+- Efficient streaming
+
+## Reference
+
+### Core Classes
+
+| Class | Location | Description |
+|-------|----------|-------------|
+| `Mesh` | Submodules/agg-sharp/PolygonMesh | Mesh data structure |
+| `Face` | Submodules/agg-sharp/PolygonMesh | Triangle face |
+| `Vertex` | Submodules/agg-sharp/PolygonMesh | Vertex data |
+
+### Processing
+
+| Class | Location | Description |
+|-------|----------|-------------|
+| `StlProcessing` | Submodules/agg-sharp | STL I/O |
+| `CsgOperations` | Submodules/agg-sharp | Boolean ops |
+| `MeshHelper` | Submodules/agg-sharp | Utilities |
+| `FaceBspTree` | Submodules/agg-sharp | Spatial index |
+
+### MatterControl Classes
+
+| Class | Location | Description |
+|-------|----------|-------------|
+| `RepairObject3D` | [DesignTools/Operations/](MatterControlLib/DesignTools/Operations/) | Mesh repair |
+| `DecimateObject3D` | [DesignTools/Operations/](MatterControlLib/DesignTools/Operations/) | Decimation |
+| `MeshContentProvider` | [Library/ContentProviders/](MatterControlLib/Library/ContentProviders/) | Mesh loading |