# 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 |