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:

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	Main 3D viewport
Object3DControlsLayer	View3D/Object3DControlsLayer.cs	Interaction layer
TrackballTumbleWidgetExtended	View3D/TrackballTumbleWidgetExtended.cs	Camera controls
TumbleCubeControl	View3D/TumbleCubeControl.cs	View cube widget
SelectedObjectPanel	PartPreviewWindow/SelectedObjectPanel.cs	Property panel

Scene Classes

Class	Location	Description
ISceneContext	ApplicationView/ISceneContext.cs	Scene context interface
InteractiveScene	Submodules/agg-sharp/DataConverters3D	Scene root
IObject3D	Submodules/agg-sharp/DataConverters3D	Object interface
EditContext	ApplicationView/EditContext.cs	Edit state

Interaction Classes

Class	Location	Description
IObject3DControl	View3D/Interaction/IObject3DControl.cs	Control handle interface
Object3DControl	View3D/Interaction/Object3DControl.cs	Base control
SceneActions	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	Bed geometry
WorldView	Submodules/agg-sharp/VectorMath	Camera/projection