mattercontrol/research/04-part-preview.md

# 3D View & Part Preview

## Summary

The 3D View system provides interactive visualization and manipulation of 3D models and G-code. It combines OpenGL-accelerated rendering with a trackball camera system, object selection, transformation controls, and a hierarchical scene tree.

## Technical Description

### Core Components

The 3D preview system consists of several layered components:

```
View3DWidget
├── Object3DControlsLayer - Interaction handling, drawing coordination
│   ├── TrackballTumbleWidgetExtended - Camera rotation/pan/zoom
│   ├── FloorDrawable - Bed visualization
│   └── IObject3DControl instances - Transform handles
├── SelectedObjectPanel - Property editing
├── TreeView - Scene hierarchy browser
└── TumbleCubeControl - View orientation indicator
```

### Scene Context (ISceneContext)

The `ISceneContext` interface abstracts the 3D editing environment:

| Property | Type | Description |
|----------|------|-------------|
| `Scene` | `InteractiveScene` | Root scene graph |
| `World` | `WorldView` | Camera/projection state |
| `EditContext` | `EditContext` | Source file and content store |
| `ViewState` | `SceneContextViewState` | View configuration |
| `BedCenter` | `Vector2` | Print bed center point |
| `Printer` | `PrinterConfig` | Associated printer (optional) |
| `GCodeRenderer` | `GCodeRenderer` | G-code visualization |

**Key Methods:**
- `AddToPlate()` - Insert items into scene
- `ClearPlate()` - Remove all objects
- `LoadContent()` - Load from file/library
- `SaveChanges()` - Persist scene to disk
- `LoadGCode()` - Load G-code for preview

### View3DWidget

The main 3D viewport widget providing:

**Camera Control:**
- Trackball rotation (middle mouse / drag)
- Pan (Shift + drag)
- Zoom (scroll wheel / pinch)
- View cube for quick orientation

**Selection:**
- Click to select objects
- Ctrl+Click for multi-select
- Rectangular selection via drag
- Tree view synchronization

**Transform Modes:**
- Part Select - Object picking
- Translate - Move objects
- Rotate - Rotate around axes
- Zoom/Scale - Size adjustment

### Object3DControlsLayer

The interaction layer manages:

1. **3D Control Handles**: Transform gizmos for selected objects
2. **Drawable Registration**: Custom rendering callbacks
3. **Hit Testing**: Ray casting for object picking
4. **Floor Rendering**: Bed mesh and grid visualization

**Control Types (Flags):**
| Flag | Purpose |
|------|---------|
| `MoveInZ` | Vertical movement handle |
| `RotateXYZ` | 3-axis rotation gizmo |
| `RotateZ` | Z-axis only rotation |
| `ScaleMatrixXY` | XY scaling handles |
| `Shadow` | Object shadow rendering |
| `SnappingIndicators` | Snap guide display |

### Scene Graph (InteractiveScene)

The scene uses a hierarchical object model:

```
InteractiveScene
├── UndoBuffer - Change history
├── SelectedItem - Current selection
└── Children (IObject3D)
    ├── Meshes
    ├── Groups
    └── Operations (CSG, transforms, etc.)
```

**IObject3D Interface:**
| Property | Type | Description |
|----------|------|-------------|
| `ID` | `string` | Unique identifier |
| `Name` | `string` | Display name |
| `Matrix` | `Matrix4X4` | Local transform |
| `Color` | `Color` | Material color |
| `MaterialIndex` | `int` | Material assignment |
| `OutputType` | `PrintOutputTypes` | Print behavior |
| `Children` | `SafeList<IObject3D>` | Child objects |
| `Mesh` | `Mesh` | Geometry data |

### Camera System

The `WorldView` class manages:

- **Model Matrix**: Scene rotation/position
- **View Matrix**: Camera position/orientation
- **Projection Matrix**: Perspective or orthographic
- **Near/Far Planes**: Dynamic clipping adjustment

**TrackballTumbleWidgetExtended** extends basic trackball with:
- Smooth momentum rotation
- Double-click to fit view
- Keyboard navigation (arrow keys)
- Dynamic near/far plane calculation

### GCode Visualization

When viewing G-code:

```
GCodeRenderer
├── GCodeFile - Parsed G-code data
├── RenderInfo - Layer/speed coloring
└── Layer visualization
    ├── Travel moves (thin lines)
    ├── Extrusion (thick, colored)
    └── Retractions (markers)
```

**Layer Controls:**
- `ActiveLayerIndex` - Current layer
- `SliceLayerSelector` - Layer scrubber widget
- Speed/feature coloring modes

### Tree View Integration

The scene tree (`TreeView`) provides:

- Hierarchical object display
- Drag-and-drop reordering
- Right-click context menus
- Selection synchronization
- Expand/collapse groups

**Object3DTreeBuilder** creates tree nodes from scene:
```csharp
treeNodeContainer.AddChild(Object3DTreeBuilder.Build(scene, treeView));
```

### Selected Object Panel

Property editing for selected objects:

```
SelectedObjectPanel
├── Object name/color editors
├── Transform fields (X, Y, Z, rotation)
├── Material selection
└── Operation-specific editors
    ├── Primitive parameters
    ├── Boolean operation settings
    └── Custom object3D properties
```

### Design Rationale

**Layered Architecture**: Separating View3DWidget, Object3DControlsLayer, and TrackballTumbleWidget allows:
- Independent testing of each layer
- Flexible composition (e.g., GCode-only vs full editing)
- Clear responsibility boundaries

**ISceneContext Abstraction**: Decouples view from editing context, enabling:
- Same view for printer beds and standalone designs
- Consistent API across different content types
- Easy mocking for tests

**Dynamic Near/Far Planes**: Automatically adjusting clipping planes based on scene bounds prevents:
- Z-fighting on large objects
- Clipping on small detailed parts
- Visual artifacts at extreme zooms

## Reference

### Core Classes

| Class | Location | Description |
|-------|----------|-------------|
| `View3DWidget` | [View3D/View3DWidget.cs](MatterControlLib/PartPreviewWindow/View3D/View3DWidget.cs) | Main 3D viewport |
| `Object3DControlsLayer` | [View3D/Object3DControlsLayer.cs](MatterControlLib/PartPreviewWindow/View3D/Object3DControlsLayer.cs) | Interaction layer |
| `TrackballTumbleWidgetExtended` | [View3D/TrackballTumbleWidgetExtended.cs](MatterControlLib/PartPreviewWindow/View3D/TrackballTumbleWidgetExtended.cs) | Camera controls |
| `TumbleCubeControl` | [View3D/TumbleCubeControl.cs](MatterControlLib/PartPreviewWindow/View3D/TumbleCubeControl.cs) | View cube widget |
| `SelectedObjectPanel` | [PartPreviewWindow/SelectedObjectPanel.cs](MatterControlLib/PartPreviewWindow/SelectedObjectPanel.cs) | Property panel |

### Scene Classes

| Class | Location | Description |
|-------|----------|-------------|
| `ISceneContext` | [ApplicationView/ISceneContext.cs](MatterControlLib/ApplicationView/ISceneContext.cs) | Scene context interface |
| `InteractiveScene` | Submodules/agg-sharp/DataConverters3D | Scene root |
| `IObject3D` | Submodules/agg-sharp/DataConverters3D | Object interface |
| `EditContext` | [ApplicationView/EditContext.cs](MatterControlLib/ApplicationView/EditContext.cs) | Edit state |

### Interaction Classes

| Class | Location | Description |
|-------|----------|-------------|
| `IObject3DControl` | [View3D/Interaction/IObject3DControl.cs](MatterControlLib/PartPreviewWindow/View3D/Interaction/IObject3DControl.cs) | Control handle interface |
| `Object3DControl` | [View3D/Interaction/Object3DControl.cs](MatterControlLib/PartPreviewWindow/View3D/Interaction/Object3DControl.cs) | Base control |
| `SceneActions` | [View3D/SceneActions.cs](MatterControlLib/PartPreviewWindow/View3D/SceneActions.cs) | Scene operations |

### Rendering

| Class | Location | Description |
|-------|----------|-------------|
| `GCodeRenderer` | Submodules/agg-sharp | G-code visualization |
| `FloorDrawable` | Internal | Bed/grid rendering |
| `BedMeshGenerator` | [View3D/BedMeshGenerator.cs](MatterControlLib/PartPreviewWindow/View3D/BedMeshGenerator.cs) | Bed geometry |
| `WorldView` | Submodules/agg-sharp/VectorMath | Camera/projection |