mattercontrol/research/14-utilities.md

# Utilities & Helpers

## Summary

MatterControl includes various utility classes and helper systems supporting caching, localization, networking, thumbnail generation, and common operations used throughout the application.

## Technical Description

### Web Cache

`WebCache` provides cached HTTP requests:

```csharp
public static class WebCache
{
    public static Task<string> RetrieveText(string url);
    public static Task<ImageSequence> RetrieveImageSquenceAsync(string url);
    public static void ClearCache();
}
```

**Features:**
- Local file caching
- Configurable expiration
- Network error handling

### Localization

The `Localizations` library handles internationalization:

```csharp
string localized = "Text to translate".Localize();
```

**Components:**
- `.po` file format
- Runtime language switching
- Fallback to English

### Thumbnail Generation

`ThumbnailsConfig` manages thumbnail creation:

```csharp
public class ThumbnailsConfig
{
    public ImageBuffer LoadCachedThumbnail(ILibraryItem item, int width, int height);
    public Task<ImageBuffer> GetThumbnail(ILibraryItem item, int width, int height);
    public void Shutdown();
}
```

**Sources:**
1. Cached in database
2. Embedded in file (3MF, AMF)
3. Rendered from mesh
4. Default icon

### Threading Utilities

`UiThread` ensures UI thread execution:

```csharp
UiThread.RunOnIdle(() => {
    // UI operations
});

UiThread.CurrentTimerMs; // High-resolution timer
```

### Safe Collections

Thread-safe collection wrappers:

```csharp
public class SafeList<T> : IEnumerable<T>
{
    public void Add(T item);
    public bool Remove(T item);
    public void Clear();
}
```

### Running Tasks

`RunningTasksConfig` manages background operations:

```csharp
Tasks.Execute(
    "Task Name",
    owner,
    async (reporter, cancellationToken) => {
        reporter?.Invoke(0.5, "Progress message");
    },
    taskActions: new RunningTaskOptions()
    {
        PauseAction = () => { /* pause */ },
        StopAction = (abort) => { /* stop */ }
    });
```

### Help System

`HelpIndex` provides searchable help:

```csharp
public static class HelpIndex
{
    public static bool IndexExists { get; }
    public static Task RebuildIndex();
    public static IEnumerable<SearchResult> Search(string query);
}
```

Uses Lucene.Net for full-text search.

### Markdown Support

`MarkdownWidget` renders markdown content:

```csharp
var markdown = new MarkdownWidget(theme, scrollable: true)
{
    Markdown = "# Title\nContent here"
};
```

Uses Markdig parser with custom Agg renderer.

### Vector Math

`VectorMath` library provides:

| Type | Description |
|------|-------------|
| `Vector2` | 2D vector |
| `Vector3` | 3D vector |
| `Matrix4X4` | 4x4 transformation matrix |
| `Quaternion` | Rotation representation |
| `AxisAlignedBoundingBox` | AABB bounds |
| `Ray` | Ray for intersections |

### Color Utilities

Color manipulation helpers:

```csharp
Color.SetPreMultiply();
Color.GrayToColor(targetColor);
Color.AdjustLightness(factor);
```

### File Utilities

Common file operations:

| Class | Purpose |
|-------|---------|
| `AggContext.FileDialogs` | File open/save dialogs |
| `StaticData` | Resource file access |
| `ApplicationDataStorage` | App data paths |

### Extension Methods

Various extension helpers:

| Extension | Purpose |
|-----------|---------|
| `string.Localize()` | Translation |
| `GuiWidget.AnchorAll()` | Layout shortcut |
| `IEnumerable.IndexOf()` | Index finding |
| `Color.WithAlpha()` | Alpha adjustment |

### Clipboard Integration

System clipboard access:

```csharp
Clipboard.Instance.SetText(text);
string text = Clipboard.Instance.GetText();
bool hasImage = Clipboard.Instance.ContainsImage;
```

### Platform Abstraction

`INativePlatformFeatures` interface:

| Feature | Description |
|---------|-------------|
| `OpenUrlInBrowser()` | Launch browser |
| `IsNetworkConnected()` | Network check |
| `GetSystemFonts()` | Font enumeration |
| `GetSerialPorts()` | Serial port list |

### Design Rationale

**Static Utility Classes**: Common operations as static helpers:
- Easy access throughout codebase
- No instantiation overhead
- Clear naming conventions

**Thread-Safe Collections**: SafeList/SafeDictionary:
- Prevent race conditions
- Simple API
- Consistent behavior

**Caching**: WebCache and thumbnails:
- Improved performance
- Offline capability
- Reduced bandwidth

## Reference

### Core Utilities

| Class | Location | Description |
|-------|----------|-------------|
| `WebCache` | [Utilities/WebCache.cs](MatterControlLib/Utilities/WebCache.cs) | HTTP caching |
| `UiThread` | Submodules/agg-sharp | UI thread helper |
| `SafeList<T>` | Submodules/agg-sharp | Thread-safe list |

### Thumbnails

| Class | Location | Description |
|-------|----------|-------------|
| `ThumbnailsConfig` | [Library/ThumbnailsConfig.cs](MatterControlLib/Library/ThumbnailsConfig.cs) | Thumbnail manager |
| `MeshThumbnails` | Submodules/agg-sharp | Mesh rendering |

### Tasks

| Class | Location | Description |
|-------|----------|-------------|
| `RunningTasksConfig` | [PartPreviewWindow/RunningTasksConfig.cs](MatterControlLib/PartPreviewWindow/RunningTasksConfig.cs) | Task manager |
| `RunningTaskOptions` | [PartPreviewWindow/RunningTaskOptions.cs](MatterControlLib/PartPreviewWindow/RunningTaskOptions.cs) | Task options |

### Help

| Class | Location | Description |
|-------|----------|-------------|
| `HelpIndex` | [Library/HelpIndex.cs](MatterControlLib/Library/HelpIndex.cs) | Help search |
| `MarkdownWidget` | Submodules/agg-sharp/MarkdigAgg | Markdown display |

### Math

| Class | Location | Description |
|-------|----------|-------------|
| `Vector3` | Submodules/agg-sharp/VectorMath | 3D vector |
| `Matrix4X4` | Submodules/agg-sharp/VectorMath | Transform matrix |
| `AxisAlignedBoundingBox` | Submodules/agg-sharp/VectorMath | AABB |