mattercontrol/research/13-mesh-operations.md

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):

// 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:

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:

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

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/	Mesh repair
DecimateObject3D	DesignTools/Operations/	Decimation
MeshContentProvider	Library/ContentProviders/	Mesh loading