Research agg-sharp

2026-01-28 13:12:13 -08:00 · 2026-01-28 13:12:13 -08:00 · edee50802f
commit edee50802f
parent 58b74dcc50
2 changed files with 950 additions and 0 deletions
--- a/research/agg-sharp.md
+++ b/research/agg-sharp.md
@ -0,0 +1,944 @@
+# agg-sharp Submodule Documentation
+
+This directory contains comprehensive documentation of the agg-sharp submodule, the custom graphics and UI framework powering MatterControl.
+
+## Overview
+
+**agg-sharp** (Anti-Grain Geometry for C#) is a comprehensive graphics library providing:
+- 2D software rasterization and vector graphics
+- Custom widget-based UI framework
+- 3D mesh data structures and operations
+- OpenGL rendering integration
+- Font/typography support
+- Mathematical primitives and geometry algorithms
+
+**Technology Stack:**
+- .NET 6.0 (C#)
+- OpenGL (via abstraction layer)
+- Software rasterization (AGG port)
+- Multiple font format support (TTF, OTF, WOFF)
+
+## Documentation Index
+
+| # | Feature | Description |
+|---|---------|-------------|
+| 1 | [Core Graphics (agg)](#1-core-graphics-agg) | 2D vector rendering, image buffers, colors, transforms |
+| 2 | [GUI Widget System](#2-gui-widget-system) | Widget hierarchy, layout, input, theming |
+| 3 | [PolygonMesh](#3-polygonmesh) | 3D mesh structures, CSG, file formats |
+| 4 | [VectorMath](#4-vectormath) | Vectors, matrices, geometric primitives |
+| 5 | [RenderOpenGL](#5-renderopengl) | OpenGL integration, mesh rendering |
+| 6 | [DataConverters](#6-dataconverters) | 2D/3D format conversion, Object3D hierarchy |
+| 7 | [Typography](#7-typography) | Font loading, text shaping, glyph layout |
+| 8 | [CSG Module](#8-csg-module) | Declarative solid geometry |
+| 9 | [Supporting Libraries](#9-supporting-libraries) | Clipper, Triangle, geometry3Sharp, etc. |
+
+## Project Structure
+
+```
+Submodules/agg-sharp/
+├── agg/                    # Core 2D graphics (Anti-Grain Geometry)
+├── Gui/                    # Widget system and UI framework
+├── PolygonMesh/            # 3D mesh data structures
+├── VectorMath/             # Linear algebra primitives
+├── RenderOpenGl/           # OpenGL rendering integration
+├── DataConverters2D/       # 2D data conversion utilities
+├── DataConverters3D/       # 3D scene graph and file formats
+├── Typography/             # Font loading and text rendering
+├── Csg/                    # Constructive Solid Geometry
+├── clipper_library/        # 2D polygon clipping
+├── Tesselate/              # Polygon tessellation
+├── Triangle/               # Delaunay triangulation
+├── geometry3Sharp/         # 3D geometry algorithms
+├── ImageProcessing/        # Image manipulation
+├── Localizations/          # Translation support
+├── QuadTree/               # Spatial indexing
+└── examples/               # Sample applications
+```
+
+---
+
+# 1. Core Graphics (agg)
+
+## Quick Summary
+
+The `agg` module is a C# port of Anti-Grain Geometry providing high-quality 2D software rasterization with anti-aliasing, vector path rendering, image compositing, and color management.
+
+## Technical In-Depth Review
+
+### Architecture
+
+The rendering pipeline follows the classic AGG model:
+
+```
+IVertexSource (paths)
+    → ScanlineRasterizer
+    → IScanlineCache
+    → ScanlineRenderer
+    → ImageBuffer (with blenders)
+```
+
+### Core Components
+
+**Graphics2D** - Main rendering API (`agg/Graphics2D.cs`)
+- Abstract base class for all 2D rendering operations
+- Provides drawing primitives: `Line()`, `Circle()`, `Rectangle()`, `FillRectangle()`
+- Text rendering: `DrawString()` with font support
+- Transform stack: `PushTransform()`, `PopTransform()`, `SetTransform()`
+- Extensible via `ImageGraphics2D` concrete implementation
+
+**ImageBuffer** - Pixel storage (`agg/Image/ImageBuffer.cs`)
+- BGRA pixel format (32-bit and 24-bit support)
+- Configurable stride for memory alignment
+- Events: `ImageChanged` for reactive updates
+- Float variant: `ImageBufferFloat` for high-precision
+
+**ScanlineRasterizer** - Anti-aliased rasterization (`agg/ScanlineRasterizer.cs`)
+- 24.8 fixed-point subpixel precision
+- Filling rules: Non-zero and Even-odd
+- Gamma correction support
+- Cell-based anti-aliasing via `RasterizerCellsAa`
+
+**Vertex Sources** (`agg/VertexSource/`)
+- `VertexStorage` - Path container with MoveTo/LineTo/Curve commands
+- `Ellipse`, `Arc`, `RoundedRect` - Geometric primitives
+- `Stroke` - Converts paths to stroked outlines (configurable joins/caps)
+- `FlattenCurves` - Bezier to line segment conversion
+- `VertexSourceApplyTransform` - Applies affine transforms
+
+**Transforms** (`agg/Transform/`)
+- `Affine` - 2x3 affine transformation matrix
+- `Bilinear`, `Perspective` - Advanced transformations
+- Factory methods: `NewTranslation()`, `NewRotation()`, `NewScaling()`
+
+**Color System** (`agg/Primitives/Color.cs`)
+- `Color` struct - BGRA 8-bit per channel
+- `ColorF` - Floating-point precision variant
+- Both 0-255 and 0.0-1.0 property accessors
+- Predefined constants: Black, White, Red, etc.
+
+**Blenders** (`agg/Image/Blenders/`)
+- `BlenderBGRA` - Standard alpha blending
+- `BlenderPreMultBGRA` - Pre-multiplied alpha
+- `BlenderGammaBGRA` - Gamma-corrected blending
+- Interface: `IRecieveBlenderByte`, `IRecieveBlenderFloat`
+
+### Design Choices
+
+- **Software rendering**: Provides pixel-perfect cross-platform consistency
+- **Scanline-based**: Cache-friendly horizontal processing
+- **Subpixel precision**: 8 fractional bits for smooth anti-aliasing
+- **Composable transforms**: Matrix multiplication via operator overloading
+
+## API Reference
+
+### Core Classes
+
+| Class | Location | Description |
+|-------|----------|-------------|
+| `Graphics2D` | agg/Graphics2D.cs | Abstract rendering API |
+| `ImageGraphics2D` | agg/Image/ImageGraphics2D.cs | ImageBuffer renderer |
+| `ImageBuffer` | agg/Image/ImageBuffer.cs | Pixel buffer |
+| `ScanlineRasterizer` | agg/ScanlineRasterizer.cs | AA rasterization |
+| `ScanlineRenderer` | agg/ScanlineRenderer.cs | Scanline to pixels |
+| `Color` | agg/Primitives/Color.cs | BGRA color |
+| `Affine` | agg/Transform/Affine.cs | 2D transformation |
+| `VertexStorage` | agg/VertexSource/VertexStorage.cs | Path container |
+
+### Key Interfaces
+
+| Interface | Purpose |
+|-----------|---------|
+| `IVertexSource` | Path/shape data provider |
+| `IColorType` | Color abstraction |
+| `IScanlineCache` | Scanline coverage data |
+| `IRecieveBlenderByte` | Pixel blending strategy |
+
+---
+
+# 2. GUI Widget System
+
+## Quick Summary
+
+The `Gui` module provides a complete widget-based UI framework with hierarchical layouts, input handling, theming, and platform abstraction. All UI elements inherit from `GuiWidget`.
+
+## Technical In-Depth Review
+
+### Widget Hierarchy
+
+```
+GuiWidget (base)
+├── Properties: BackgroundColor, Border, Padding, Margin
+├── Layout: HAnchor, VAnchor, LayoutEngine
+├── Children: AscendableSafeList<GuiWidget>
+├── Input: Mouse/Keyboard events, Focus management
+└── Rendering: Invalidation, double-buffering
+```
+
+### Layout System
+
+**Anchoring** (`GuiWidget.cs`)
+- `HAnchor`: Left, Center, Right, Fit, Stretch, MaxFitOrStretch
+- `VAnchor`: Bottom, Center, Top, Fit, Stretch, MaxFitOrStretch
+- Controls automatic sizing and positioning relative to parent
+
+**Layout Engines** (`Gui/LayoutEngines/`)
+- `LayoutEngineSimpleAlign` - Basic anchor-based alignment
+- `LayoutEngineFlow` - Sequential flow layout (horizontal/vertical)
+- `FlowLayoutWidget` - Convenience container using flow layout
+
+**FlowDirection Enum:**
+- `LeftToRight`, `RightToLeft`, `TopToBottom`, `BottomToTop`
+
+### Input Handling
+
+**Mouse Events:**
+- `MouseDown`, `MouseUp`, `Click` - Button interactions
+- `MouseMove`, `MouseEnter`, `MouseLeave` - Position tracking
+- `MouseWheel` - Scroll support
+- `GestureFling` - Touch gestures
+
+**Keyboard Events:**
+- `KeyDown`, `KeyUp` - Key state changes
+- `KeyPressed` - Character input
+
+**Focus Management:**
+- `Focus()`, `Unfocus()` - Manual control
+- `Focused`, `ContainsFocus` - State queries
+- `TabStop`, `TabIndex` - Tab navigation
+
+### Platform Abstraction
+
+**SystemWindow** (`Gui/SystemWindow/SystemWindow.cs`)
+- Top-level window container
+- Properties: `Title`, `IsModal`, `UseOpenGL`
+- Manages tooltip display via `ToolTipManager`
+
+**IPlatformWindow** Interface:
+- `Caption`, `DesktopPosition`, `MinimumSize`
+- `BringToFront()`, `Activate()`, `Close()`
+- `SetCursor()`, `NewGraphics2D()`
+
+**ISystemWindowProvider** Interface:
+- Abstracts window creation across platforms
+- Implementations: `SingleWindowProvider`, platform-specific providers
+
+### Theming
+
+**ThemeConfig** (`Gui/Theme/ThemeConfig.cs`)
+- Color palette: `BackgroundColor`, `TextColor`, `PrimaryAccentColor`
+- Typography: `DefaultFontSize`, `FontSize7-14`
+- Button styling: `ButtonHeight`, `ButtonRadius`, `ButtonBackgroundColor`
+- State colors: `ThreeStateColor` (Focused, Hovered, Inactive)
+
+**ThemeConfig Methods:**
+- `MakeRoundedButton()` - Apply rounded style
+- `ApplyBottomBorder()` - Add border decoration
+- `CreateHeading()`, `CreateDialogButton()` - Themed widget factories
+
+### Animation & Threading
+
+**Animation** (`Gui/Animation.cs`)
+- `DrawTarget`, `FramesPerSecond`, `SecondsPerUpdate`
+- `Start()`, `Stop()` - Animation lifecycle
+- `Animation.Run()` - Static helper for timed animations
+
+**UiThread** (`Gui/UiThread.cs`)
+- `RunOnUiThread()`, `RunOnIdle()` - Deferred execution
+- `SetInterval()`, `ClearInterval()` - Repeated actions
+- `ExecuteWhen()` - Condition-based execution
+
+### Key Widgets
+
+| Widget | Location | Purpose |
+|--------|----------|---------|
+| `Button` | Gui/Button/ | Clickable button |
+| `CheckBox` | Gui/CheckBox/ | Toggle checkbox |
+| `TextEditWidget` | Gui/TextWidgets/ | Text input |
+| `TextWidget` | Gui/TextWidgets/ | Static text display |
+| `Slider` | Gui/Slider/ | Value slider |
+| `Menu`, `MenuItem` | Gui/Menu/ | Dropdown menus |
+| `ScrollableWidget` | Gui/ScrollableWidget/ | Scrolling container |
+| `DropDownList` | Gui/Menu/ | Selection dropdown |
+
+## API Reference
+
+### Core Classes
+
+| Class | Location | Description |
+|-------|----------|-------------|
+| `GuiWidget` | Gui/GUIWidget.cs | Base widget class |
+| `SystemWindow` | Gui/SystemWindow/SystemWindow.cs | Top-level window |
+| `FlowLayoutWidget` | Gui/FlowLayoutWidget.cs | Flow layout container |
+| `ThemeConfig` | Gui/Theme/ThemeConfig.cs | Theme configuration |
+| `Animation` | Gui/Animation.cs | Animation timing |
+| `UiThread` | Gui/UiThread.cs | UI thread utilities |
+
+### Key Events
+
+| Event | Source | Description |
+|-------|--------|-------------|
+| `Click` | GuiWidget | Mouse click completed |
+| `MouseDown/Up` | GuiWidget | Button press/release |
+| `KeyDown/Up` | GuiWidget | Key press/release |
+| `FocusChanged` | GuiWidget | Focus state changed |
+| `BoundsChanged` | GuiWidget | Size/position changed |
+| `TextChanged` | GuiWidget | Text property changed |
+
+---
+
+# 3. PolygonMesh
+
+## Quick Summary
+
+The `PolygonMesh` module provides 3D mesh data structures, CSG (boolean) operations, spatial acceleration structures, file format support, and ray tracing capabilities.
+
+## Technical In-Depth Review
+
+### Mesh Data Structure
+
+**Mesh** (`PolygonMesh/Mesh.cs`)
+- `Vertices`: List<Vector3Float> - Vertex positions
+- `Faces`: FaceList - Triangles (3 vertex indices each)
+- `FaceTextures`: Dictionary<int, FaceTextureData> - Per-face textures
+- `FaceBspTree`: BspNode - Spatial acceleration
+- `PropertyBag`: Dictionary<string, object> - Extensible metadata
+
+**Key Operations:**
+- `Transform(Matrix4X4)` - Apply transformation
+- `MergeVertices()` - Weld coincident vertices
+- `ReverseFaces()` - Flip normals
+- `Split(Plane)` - Split mesh on plane
+- `GetAxisAlignedBoundingBox()` - Bounds calculation
+- `CalculateNormals()` - Recompute face normals
+
+### CSG Operations
+
+**CsgOperations** (`PolygonMesh/Csg/CsgOperations.cs`)
+- `Union(meshA, meshB)` - Boolean union
+- `Subtract(meshA, meshB)` - Boolean difference
+- `Intersect()` - Boolean intersection
+
+**CsgBySlicing** (`PolygonMesh/Csg/CsgBySlicing.cs`)
+- Polygon-based CSG implementation
+- Uses Clipper library for 2D polygon operations
+- BVH acceleration for spatial queries
+- `SimilarPlaneFinder` for coplanar face grouping
+
+**Processing Modes:**
+- `Polygons` - Standard polygon-based CSG
+- `Marching_Cubes` - Experimental implicit surface
+- `Dual_Contouring` - Feature-preserving implicit
+
+### Spatial Acceleration
+
+**FaceBspTree** (`PolygonMesh/Processors/FaceBspTree.cs`)
+- Binary Space Partition for faces
+- `Create()` - Build from mesh
+- `GetFacesInVisibilityOrder()` - Depth-sorted rendering
+- Used for transparent object rendering
+
+**BoundingVolumeHierarchy** (`PolygonMesh/RayTracer/Bvh/`)
+- `BvhBuilderAac` - Axis-aligned clustering
+- `BvhBuilderBottomUp` - Bottom-up construction
+- `BvhBuilderLocallyOrderedClustering` - Morton code ordering
+- O(log n) ray intersection queries
+
+### File Format Support
+
+| Format | Class | Features |
+|--------|-------|----------|
+| STL | `StlProcessing` | Binary/ASCII, streaming |
+| OBJ | `ObjSupport`, `Obj` | Materials, textures |
+| AMF | `AmfDocument` | Multi-material, compressed |
+| 3MF | `IxMilia.ThreeMf` | Full 3MF spec support |
+
+### Ray Tracing
+
+**RayTracer** (`PolygonMesh/RayTracer/RayTracer.cs`)
+- Anti-aliasing: None, Low(4), Medium(8), High(16), VeryHigh(32)
+- Buffers: Color, Depth, Normal
+- Features: Diffuse, Highlights, Reflection, Refraction, Shadows
+
+**Primitives** (`PolygonMesh/RayTracer/Primitive/Shapes/`)
+- `TriangleShape`, `BoxShape`, `SphereShape`, `CylinderShape`, `PlaneShape`
+- Materials: Solid, Chessboard, Texture
+
+## API Reference
+
+### Core Classes
+
+| Class | Location | Description |
+|-------|----------|-------------|
+| `Mesh` | PolygonMesh/Mesh.cs | Mesh data structure |
+| `Face` | PolygonMesh/Face.cs | Triangle face |
+| `CsgOperations` | PolygonMesh/Csg/CsgOperations.cs | Boolean ops |
+| `FaceBspTree` | PolygonMesh/Processors/FaceBspTree.cs | BSP tree |
+| `StlProcessing` | PolygonMesh/Processors/StlProcessing.cs | STL I/O |
+
+### Mesh Extensions
+
+| Method | Purpose |
+|--------|---------|
+| `Copy()` | Deep copy mesh |
+| `GetCoplanarFaces()` | Find faces on same plane |
+| `GetMeshEdges()` | Extract edge topology |
+| `GetNonManifoldEdges()` | Detect topology errors |
+| `IsManifold()` | Validate mesh topology |
+| `RepairTJunctions()` | Fix T-junction artifacts |
+
+---
+
+# 4. VectorMath
+
+## Quick Summary
+
+The `VectorMath` module provides double-precision vector types, matrices, geometric primitives (rays, planes, AABBs), quaternions, and mathematical utilities for 3D graphics.
+
+## Technical In-Depth Review
+
+### Vector Types
+
+**Vector2** (`VectorMath/Vector2.cs`)
+- Components: X, Y (double)
+- Constants: Zero, One, UnitX, UnitY
+- Operations: Dot, Cross (2D scalar), Lerp, Rotate
+- Extensions: Polygon utilities, path analysis
+
+**Vector3** (`VectorMath/Vector3.cs`)
+- Components: X, Y, Z (double)
+- Operations: Dot, Cross, Normalize, Lerp
+- Transforms: Position, Normal, Vector transforms with Matrix4X4
+- Float variant: `Vector3Float` for GPU compatibility
+
+**Vector4** (`VectorMath/Vector4.cs`)
+- Components: X, Y, Z, W (double)
+- Homogeneous coordinates support
+- Matrix transformation with perspective division
+- Swizzle: `.Xy`, `.Xyz` properties
+
+### Matrix Types
+
+**Matrix4X4** (`VectorMath/Matrix4x4.cs`)
+- 4x4 double-precision matrix (row-major)
+- Position in Row3 (graphics convention)
+- Factory methods:
+  - `CreateTranslation()`, `CreateRotation()`, `CreateScale()`
+  - `CreatePerspectiveFieldOfView()`, `CreateOrthographic()`
+  - `LookAt()` - Camera view matrix
+- Operations: Mult, Invert, Transpose, GetRotation
+
+**Quaternion** (`VectorMath/Quaternion.cs`)
+- Unit quaternion rotation representation
+- Construction: Component, from matrix, from two directions
+- Properties: X, Y, Z, W, Xyz
+
+### Geometric Primitives
+
+**Ray** (`VectorMath/Ray.cs`)
+- Origin + Direction (normalized)
+- Precomputed: `oneOverDirection`, `sign` array
+- Range: `minDistanceToConsider`, `maxDistanceToConsider`
+- Fast AABB intersection (slab method)
+
+**Plane** (`VectorMath/Plane.cs`)
+- Normal + DistanceFromOrigin
+- Construction: From normal+distance, normal+point, three points
+- Methods: `GetDistanceFromPlane()`, `LineHitPlane()`, `RayHitPlane()`
+
+**AxisAlignedBoundingBox** (`VectorMath/AxisAlignedBoundingBox.cs`)
+- MinXYZ, MaxXYZ corners
+- Methods: `ExpandToInclude()`, `Intersects()`, `Contains()`
+- Properties: Center, Size, Volume, SurfaceArea
+
+**Frustum** (`VectorMath/Frustum.cs`)
+- 6 planes: Left, Right, Top, Bottom, Near, Far
+- View frustum culling support
+
+### Math Utilities
+
+**MathHelper** (`VectorMath/MathHelper.cs`)
+- Constants: Pi, Tau, E, various Pi fractions
+- Trigonometric helpers
+
+**Easing** (`VectorMath/Easing.cs`)
+- Animation curves from Tween.js
+- Types: Linear, Quadratic, Cubic, Elastic, Bounce, etc.
+- Modes: EaseIn, EaseOut, EaseInOut
+
+## API Reference
+
+### Core Classes
+
+| Class | Location | Description |
+|-------|----------|-------------|
+| `Vector2` | VectorMath/Vector2.cs | 2D vector |
+| `Vector3` | VectorMath/Vector3.cs | 3D vector |
+| `Vector4` | VectorMath/Vector4.cs | 4D/homogeneous |
+| `Matrix4X4` | VectorMath/Matrix4x4.cs | 4x4 transform |
+| `Quaternion` | VectorMath/Quaternion.cs | Rotation quaternion |
+| `Ray` | VectorMath/Ray.cs | Ray primitive |
+| `Plane` | VectorMath/Plane.cs | Plane primitive |
+| `AxisAlignedBoundingBox` | VectorMath/AxisAlignedBoundingBox.cs | AABB |
+
+### Coordinate Conventions
+
+- Right-handed coordinate system
+- Row-major matrix layout
+- Position in Row3 of Matrix4X4
+- Unit quaternions for rotation
+
+---
+
+# 5. RenderOpenGL
+
+## Quick Summary
+
+The `RenderOpenGL` module integrates OpenGL rendering with agg-sharp, providing hardware-accelerated mesh rendering, shader management, and texture handling.
+
+## Technical In-Depth Review
+
+### Core Graphics
+
+**Graphics2DOpenGL** (`RenderOpenGl/Renderer/Graphics2DOpenGL.cs`)
+- Extends `Graphics2D` for OpenGL context
+- Orthographic projection management
+- Anti-aliased 2D rendering via texture-based alpha
+- Scissor test for clipping
+
+### Mesh Rendering Plugins
+
+Plugins cache rendering data in mesh `PropertyBag`:
+
+**GLMeshTrianglePlugin** (`RenderOpenGl/GLMeshTrianglePlugin.cs`)
+- Groups faces by texture into `SubTriangleMesh` objects
+- Data: positions, normals, UVs, per-vertex colors
+- Invalidation tracking via `mesh.ChangedCount`
+
+**GLMeshVertexArrayObjectPlugin** (`RenderOpenGl/GLMeshVertexArrayObjectPlugin.cs`)
+- Modern VAO-based rendering
+- VBO for positions, EBO for indices
+- Uses `GL.DrawElements()`
+
+**GLMeshWirePlugin** (`RenderOpenGl/GLMeshWirePlugin.cs`)
+- Wireframe edge rendering
+- Optional angle-based edge filtering
+- Background processing for complex meshes
+
+**GLMeshNonManifoldPlugin** (`RenderOpenGl/GLMeshNonManifoldPlugin.cs`)
+- Highlights non-manifold edges
+- Background edge analysis
+
+### Texture Management
+
+**ImageGlPlugin** (`RenderOpenGl/ImageGlPlugin.cs`)
+- Weak-reference caching by image buffer
+- Power-of-2 texture handling
+- Mipmap generation support
+- Format: RGBA (converted from BGRA)
+
+### Rendering Pipeline
+
+**GLHelper** (`RenderOpenGl/RenderMeshToGl.cs`)
+- High-level mesh rendering orchestration
+- RenderTypes: Shaded, Wireframe, Outlines, NonManifold, Overhang
+
+**SetGlContext():**
+- Viewport, face culling, depth function
+- Lighting setup (2 directional lights)
+- Projection/modelview matrices
+
+**Render Types:**
+| Type | Description |
+|------|-------------|
+| Shaded | Textured/lit solid mesh |
+| Wireframe | Edges only |
+| Outlines | Solid + wireframe overlay |
+| NonManifold | Highlight topology errors |
+| Overhang | Overhang analysis coloring |
+
+### Lighting
+
+**LightingData** (`RenderOpenGl/LightingData.cs`)
+- Two directional lights
+- Ambient, Diffuse, Specular components
+- Per-vertex color material support
+
+### 3D Line Rendering
+
+**WorldViewExtensions** (`RenderOpenGl/WorldViewExtensions.cs`)
+- `Render3DLine()` - Screen-space width lines
+- `RenderCylinderOutline()`, `RenderRing()`, `RenderAabb()`
+- Frustum clipping before rendering
+
+## API Reference
+
+### Core Classes
+
+| Class | Location | Description |
+|-------|----------|-------------|
+| `Graphics2DOpenGL` | RenderOpenGl/Renderer/Graphics2DOpenGL.cs | 2D GL rendering |
+| `GLMeshTrianglePlugin` | RenderOpenGl/GLMeshTrianglePlugin.cs | Triangle cache |
+| `ImageGlPlugin` | RenderOpenGl/ImageGlPlugin.cs | Texture management |
+| `GLHelper` | RenderOpenGl/RenderMeshToGl.cs | Render pipeline |
+| `LightingData` | RenderOpenGl/LightingData.cs | Light config |
+
+### GL Abstraction
+
+| Interface/Class | Purpose |
+|-----------------|---------|
+| `IOpenGL` | OpenGL operation abstraction |
+| `GL` | Thread-safe GL facade |
+| `GL/Enums/` | OpenGL constant definitions |
+
+---
+
+# 6. DataConverters
+
+## Quick Summary
+
+The `DataConverters2D` and `DataConverters3D` modules handle format conversion between 2D/3D data types, scene graph management, and file format import/export.
+
+## Technical In-Depth Review
+
+### DataConverters2D
+
+**Tessellation** (`DataConverters2D/`)
+- `CachedTesselator` - Caches vertices/indices during tessellation
+- `VertexSourceToTesselator` - Converts IVertexSource to tessellator input
+- Processes vertex commands: MoveTo, LineTo, Close
+
+**Polygon Operations** (`DataConverters2D/VertexSourceToClipperPolygons.cs`)
+- `CreatePolygons()` - IVertexSource to Clipper polygons
+- `Offset()` - Polygon expansion/contraction
+- `GetCorrectedWinding()` - Fix winding direction
+
+**Image I/O** (`DataConverters2D/ImageIO.cs`)
+- Load/Save: PNG, JPG, GIF (with animation)
+- Uses SixLabors.ImageSharp
+- `ConvertImageToImageBuffer()` - Format conversion
+
+### DataConverters3D
+
+**Object3D Hierarchy** (`DataConverters3D/Object3D/`)
+
+**IObject3D Interface:**
+- `Children` - Hierarchical scene graph
+- `Mesh` - Associated geometry
+- `Matrix` - Local transformation
+- `Color`, `MaterialIndex`, `OutputType`
+- Methods: `Clone()`, `GetAxisAlignedBoundingBox()`, `ToJson()`
+
+**Object3D Class:**
+- Concrete IObject3D implementation
+- GUID-based identification
+- Thread-safe rebuild locking
+- JSON serialization support
+
+**InteractiveScene:**
+- Selection management
+- `SelectedItem`, `SelectedItemRoot`
+- Scene-level operations
+
+**File Format Support:**
+
+| Format | Class | Features |
+|--------|-------|----------|
+| AMF | `AmfDocument` | ZIP compression, streaming |
+| OBJ/MTL | `ObjSupport` | Materials, vertices, faces |
+| 3MF | `IxMilia.ThreeMf` | Full 3MF specification |
+
+**Conversion Utilities:**
+- `MeshToBVH` - Convert Object3D to ray-traceable BVH
+- `CenterAndHeightMaintainer` - Position preservation during operations
+- `CsgToRayTraceable` - CSG to ray tracer primitives
+
+## API Reference
+
+### Core Classes
+
+| Class | Location | Description |
+|-------|----------|-------------|
+| `CachedTesselator` | DataConverters2D/ | Tessellation cache |
+| `VertexSourceToClipperPolygons` | DataConverters2D/ | Polygon conversion |
+| `ImageIO` | DataConverters2D/ | Image I/O |
+| `IObject3D` | DataConverters3D/Object3D/ | Scene interface |
+| `Object3D` | DataConverters3D/Object3D/ | Scene implementation |
+| `InteractiveScene` | DataConverters3D/Object3D/ | Selection management |
+| `AmfDocument` | DataConverters3D/ | AMF loader |
+| `ObjSupport` | DataConverters3D/ | OBJ loader |
+
+---
+
+# 7. Typography
+
+## Quick Summary
+
+The `Typography` module provides comprehensive font loading, glyph management, and text shaping using OpenType features.
+
+## Technical In-Depth Review
+
+### Font Loading
+
+**Typeface** (`Typography.OpenFont/Typeface.cs`)
+- Core font representation
+- Properties: Name, UnitsPerEm, Ascender, Descender, LineGap
+- Manages glyph array and all font tables
+
+**OpenFontReader** (`Typography.OpenFont/OpenFontReader.cs`)
+- Reads: TTF, OTF, WOFF, WOFF2, TTC
+- `ReadPreview()` - Lightweight metadata
+- `Read()` - Full font parsing
+
+### Font Tables
+
+**Core Tables:**
+- `Head` - Font header, metrics
+- `HorizontalMetrics` - Advance widths
+- `Cmap` - Character to glyph mapping
+- `OS2` - Font classification
+
+**TrueType:**
+- `Glyf` - TrueType outlines
+- `GlyphLocations` - Glyph offsets
+
+**CFF (PostScript):**
+- `CFFTable` - Compact Font Format
+- `Type2CharStringParser` - Charstring evaluation
+
+**OpenType Layout:**
+- `GSUB` - Glyph Substitution (ligatures, alternates)
+- `GPOS` - Glyph Positioning (kerning, marks)
+- `GDEF` - Glyph Definition
+
+### Text Shaping
+
+**GlyphLayout** (`Typography.GlyphLayout/GlyphLayout.cs`)
+- Text shaping engine
+- Process: chars → codepoints → glyphs → GSUB → GPOS
+- Output: `UnscaledGlyphPlan` list
+
+**GlyphSubstitution** (`Typography.GlyphLayout/GlyphSubstitution.cs`)
+- GSUB feature application
+- Ligatures, composition, alternates
+
+**GlyphSetPosition** (`Typography.GlyphLayout/GlyphPosition.cs`)
+- GPOS feature application
+- Kerning, mark positioning
+
+### Glyph Representation
+
+**Glyph** (`Typography.OpenFont/Glyph.cs`)
+- Index, Bounds, GlyphPoints, AdvanceWidth
+- TTF: Point arrays
+- CFF: Cff1GlyphData
+
+## API Reference
+
+### Core Classes
+
+| Class | Location | Description |
+|-------|----------|-------------|
+| `Typeface` | Typography.OpenFont/ | Font representation |
+| `OpenFontReader` | Typography.OpenFont/ | Font file parser |
+| `GlyphLayout` | Typography.GlyphLayout/ | Text shaping |
+| `Glyph` | Typography.OpenFont/ | Single glyph |
+
+### Font Tables
+
+| Table | Purpose |
+|-------|---------|
+| `Head` | Font header |
+| `Cmap` | Character mapping |
+| `GSUB` | Glyph substitution |
+| `GPOS` | Glyph positioning |
+| `Glyf` | TrueType outlines |
+
+---
+
+# 8. CSG Module
+
+## Quick Summary
+
+The standalone `Csg` module provides declarative Constructive Solid Geometry with primitives, transformations, and boolean operations that can be converted to polygon meshes.
+
+## Technical In-Depth Review
+
+### Primitive Classes
+
+**Box** (`Csg/Solids/Box.cs`)
+- Rectangular prisms
+- Methods: `BevelEdge()`, `ChamferEdge()`, `BevelAll()`
+
+**Sphere** (`Csg/Solids/Sphere.cs`)
+- Defined by radius
+
+**Cylinder** (`Csg/Solids/Cylinder.cs`)
+- Dual-radius cones
+- Configurable polygon sides
+
+**LinearExtrude** (`Csg/Solids/LinearExtrude.cs`)
+- 2D polygon → 3D solid
+- Optional twist
+
+**RotateExtrude** (`Csg/Solids/RotateExtrude.cs`)
+- Revolution of 2D profile
+
+### Transformations
+
+| Class | Operation |
+|-------|-----------|
+| `Translate` | Vector3 translation |
+| `Rotate` | Euler angle rotation |
+| `Scale` | Per-axis scaling |
+| `Align` | Align face to position |
+| `SetCenter` | Recenter object |
+
+### Boolean Operations
+
+| Class | Operator | Operation |
+|-------|----------|-----------|
+| `Union` | `+` | Combine objects |
+| `Difference` | `-` | Subtract objects |
+| `Intersection` | - | Common volume |
+
+### Conversion
+
+**CsgToMesh** (`Csg/Processors/CsgToMesh.cs`)
+- Visitor pattern converter
+- `Convert(CsgObject) → Mesh`
+
+**OpenSCadOutput** (`Csg/Processors/OpenSCadOutput.cs`)
+- Generate OpenSCAD scripts
+- `GetScadString(CsgObject) → string`
+
+## API Reference
+
+### Core Classes
+
+| Class | Location | Description |
+|-------|----------|-------------|
+| `CsgObject` | Csg/CsgObject.cs | Base class |
+| `Box` | Csg/Solids/Box.cs | Box primitive |
+| `Cylinder` | Csg/Solids/Cylinder.cs | Cylinder primitive |
+| `Union` | Csg/Operations/Union.cs | Boolean union |
+| `Difference` | Csg/Operations/Difference.cs | Boolean difference |
+| `CsgToMesh` | Csg/Processors/CsgToMesh.cs | Mesh conversion |
+
+---
+
+# 9. Supporting Libraries
+
+## Quick Summary
+
+Several supporting libraries provide specialized functionality for polygon operations, triangulation, and computational geometry.
+
+## Module Overview
+
+### clipper_library
+
+**Purpose:** Robust 2D polygon clipping using the Vatti algorithm.
+
+**Key Classes:**
+- `Clipper` - Main clipping engine
+- `ClipperOffset` - Polygon offsetting
+- `PolyTree` - Hierarchical result structure
+
+**Operations:** Union, Intersection, Difference, XOR
+
+### Tesselate
+
+**Purpose:** GLU-style polygon tessellation.
+
+**Key Classes:**
+- `Tesselator` - Main tessellation engine
+- Callback interface for triangle output
+
+**Features:** Handles complex polygons with holes
+
+### Triangle
+
+**Purpose:** Constrained Delaunay triangulation via Triangle.NET.
+
+**Key Classes:**
+- `Mesh` - Triangulation result
+- `ConstraintMesher` - Constrained triangulation
+- `QualityMesher` - Mesh refinement
+
+### geometry3Sharp
+
+**Purpose:** Comprehensive 3D geometry library (ported from WildMagic5).
+
+**Modules:**
+- `math/` - Vectors, boxes, transforms
+- `mesh/` - DMesh3, mesh operators
+- `curve/` - Bezier, NURBS, polygons
+- `distance/` - Point-to-geometry queries
+- `comp_geom/` - Convex hull, arrangements
+
+### ImageProcessing
+
+**Purpose:** Image manipulation filters.
+
+**Key Classes:**
+- `Blur`, `Dilate`, `Erode`, `Threshold`
+- `InvertLightness`, `Subtract`
+
+### Localizations
+
+**Purpose:** Multi-language translation support.
+
+**Key Classes:**
+- `TranslationMap` - Translation dictionary
+- Extension: `"text".Localize()`
+
+### QuadTree
+
+**Purpose:** 2D spatial indexing.
+
+**Key Classes:**
+- `QuadTree<T>` - Generic quad tree
+- `Branch<T>`, `Leaf<T>` - Tree nodes
+- Object pooling for efficiency
+
+## Dependencies
+
+```
+PolygonMesh ──┬── VectorMath
+              ├── clipper_library
+              ├── geometry3Sharp
+              └── Triangle
+
+DataConverters3D ──┬── PolygonMesh
+                   ├── DataConverters2D
+                   └── Csg
+
+RenderOpenGl ──┬── Agg
+               └── PolygonMesh
+
+Gui ──┬── Agg
+      ├── DataConverters2D
+      └── Localizations
+
+Agg ──┬── VectorMath
+      └── Typography
+```
+
+---
+
+## Key Namespaces
+
+| Namespace | Purpose |
+|-----------|---------|
+| `MatterHackers.Agg` | Core 2D graphics |
+| `MatterHackers.Agg.UI` | Widget system |
+| `MatterHackers.PolygonMesh` | 3D mesh operations |
+| `MatterHackers.VectorMath` | Linear algebra |
+| `MatterHackers.RenderOpenGl` | OpenGL integration |
+| `MatterHackers.DataConverters2D` | 2D conversion |
+| `MatterHackers.DataConverters3D` | 3D scene graph |
+| `Typography.OpenFont` | Font loading |
+| `Typography.GlyphLayout` | Text shaping |
+| `MatterHackers.Csg` | Solid geometry |
+| `ClipperLib` | Polygon clipping |
+| `TriangleNet` | Mesh triangulation |
+| `g3` | geometry3Sharp |
--- a/research/index.md
+++ b/research/index.md
@ -38,6 +38,12 @@ MatterControl is a comprehensive 3D printing workflow application built by Matte
 | 13 | [Mesh Operations](13-mesh-operations.md) | Import/export, processing, CSG |
 | 14 | [Utilities & Helpers](14-utilities.md) | Caching, localization, threading, math |

+## Submodule Documentation
+
+| Submodule | Document | Description |
+|-----------|----------|-------------|
+| agg-sharp | [agg-sharp.md](agg-sharp.md) | Graphics library: 2D rendering, GUI widgets, 3D mesh, VectorMath, OpenGL, Typography |
+
 ## Key Entry Points

 | File | Purpose |