mattercontrol/research/07-library-system.md

# Library & Content Management

## Summary

The Library system provides a hierarchical content browser for managing 3D models, designs, and print files. It uses a container-based architecture supporting multiple backends including file system, SQLite database, cloud storage, and bundled assets.

## Technical Description

### Architecture

```
LibraryConfig (ILibraryContext)
├── RootLibraryContainer
│   ├── Computer (FileSystemContainer)
│   ├── Local Library (SqliteLibraryContainer)
│   ├── Queue (FileSystemContainer)
│   ├── Bundled Parts (BundledPartsCollectionContainer)
│   ├── History (RootHistoryContainer)
│   └── Custom Library Folders...
├── ContentProviders (file type handlers)
└── MenuExtensions (context menu actions)
```

### Core Interfaces

**ILibraryContext:**
```csharp
public interface ILibraryContext
{
    event EventHandler<ContainerChangedEventArgs> ContainerChanged;
    event EventHandler<ContainerChangedEventArgs> ContentChanged;
    ILibraryContainer ActiveContainer { get; set; }
}
```

**ILibraryContainer:**
| Property/Method | Description |
|-----------------|-------------|
| `Items` | Child items (files) |
| `ChildContainers` | Sub-containers (folders) |
| `Parent` | Parent container |
| `Load()` | Load container contents |
| `Activate()/Deactivate()` | Lifecycle hooks |
| `GetThumbnail()` | Generate item thumbnail |

**ILibraryItem:**
| Property | Description |
|----------|-------------|
| `ID` | Unique identifier |
| `Name` | Display name |
| `DateCreated` | Creation timestamp |
| `DateModified` | Last modified timestamp |

### Container Types

| Container | Purpose | Location |
|-----------|---------|----------|
| `RootLibraryContainer` | Top-level root | Providers/ |
| `FileSystemContainer` | File/folder access | Providers/FileSystem/ |
| `SqliteLibraryContainer` | Database-backed library | Providers/Sqlite/ |
| `BundledPartsCollectionContainer` | Built-in parts | Providers/MatterControl/ |
| `PlatingHistoryContainer` | Print history | Providers/MatterControl/ |
| `PrinterContainer` | Printer-specific storage | Providers/Printer/ |
| `ZipContainer` | ZIP archive browsing | Providers/Zip/ |
| `GitHubContainer` | GitHub repo browsing | Providers/GitHub/ |

### Content Providers

Content providers handle loading and saving specific file types:

| Provider | Extensions |
|----------|------------|
| `MeshContentProvider` | stl, obj, 3mf, amf, mcx |
| `GCodeContentProvider` | gcode |
| `ImageContentProvider` | png, gif, jpg, jpeg |
| `OpenScadContentProvider` | scad |

Registration:
```csharp
Library.ContentProviders.Add("stl", new MeshContentProvider());
Library.ContentProviders.Add("gcode", new GCodeContentProvider());
```

### Item Types

**ILibraryAsset:** File-based items with content
```csharp
public interface ILibraryAsset : ILibraryItem
{
    string FileName { get; }
    string ContentType { get; }
    long FileSize { get; }
}
```

**ILibraryObject3D:** 3D model items
```csharp
public interface ILibraryObject3D : ILibraryItem
{
    Task<IObject3D> GetObject3D(Action<double, string> progress);
}
```

**ILibraryContainerLink:** Lazy-loaded container reference
```csharp
public interface ILibraryContainerLink : ILibraryItem
{
    ILibraryContainer GetContainer();
    bool IsReadOnly { get; }
}
```

### Container Actions

| Action | Description |
|--------|-------------|
| `AddItems` | Add new files |
| `AddContainers` | Create sub-folders |
| `RenameItems` | Rename items |
| `RemoveItems` | Delete items |

### Writable Containers

`ILibraryWritableContainer` extends containers with write operations:

```csharp
public interface ILibraryWritableContainer
{
    void Add(IEnumerable<ILibraryItem> items);
    void Remove(IEnumerable<ILibraryItem> items);
    void Rename(ILibraryItem item, string revisedName);
    void Move(IEnumerable<ILibraryItem> items, ILibraryWritableContainer dest);
    void SetThumbnail(ILibraryItem item, int width, int height, ImageBuffer thumbnail);
}
```

### Navigation

Container navigation uses parent references:

```csharp
// Navigate up
ActiveContainer = ActiveContainer.Parent;

// Get breadcrumb path
var ancestors = activeContainer.Ancestors();
```

### Thumbnails

`ThumbnailsConfig` manages thumbnail generation:

```csharp
// Request thumbnail
var thumbnail = await Library.EnsureCorrectThumbnailSizing(
    originalThumbnail,
    thumbWidth,
    thumbHeight,
    resizedCallback);
```

Thumbnail sources:
1. Cached thumbnail in database
2. Generated from 3D model render
3. Extracted from file (3MF, AMF)
4. Default icon fallback

### Library UI Widgets

| Widget | Location | Purpose |
|--------|----------|---------|
| `LibraryListView` | Library/Widgets/ | List/grid item display |
| `LibraryBrowserPage` | PartPreviewWindow/ | Full library browser |
| `LibrarySelector` | CustomWidgets/LibrarySelector/ | Folder picker |
| `SaveAsPage` | PartPreviewWindow/ | Save dialog |

### Design Rationale

**Container Pattern**: Using a container abstraction allows:
- Uniform navigation across different storage backends
- Easy addition of new storage types (cloud, network, etc.)
- Consistent UI regardless of data source

**Lazy Loading**: `ILibraryContainerLink` enables:
- Fast initial display
- Load content only when expanded
- Memory-efficient browsing

**Content Providers**: Separating file handling from containers:
- Same file types work in any container
- Easy to add new format support
- Clear responsibility separation

## Reference

### Core Classes

| Class | Location | Description |
|-------|----------|-------------|
| `LibraryConfig` | [Library/Providers/LibraryConfig.cs](MatterControlLib/Library/Providers/LibraryConfig.cs) | Library manager |
| `RootLibraryContainer` | [Library/Providers/RootLibraryContainer.cs](MatterControlLib/Library/Providers/RootLibraryContainer.cs) | Root container |
| `FileSystemContainer` | [Library/Providers/FileSystem/](MatterControlLib/Library/Providers/FileSystem/) | File system access |
| `LibraryContainer` | [Library/Providers/LibraryContainer.cs](MatterControlLib/Library/Providers/LibraryContainer.cs) | Base container |

### Interfaces

| Interface | Location | Description |
|-----------|----------|-------------|
| `ILibraryContext` | [Library/Providers/LibraryConfig.cs](MatterControlLib/Library/Providers/LibraryConfig.cs) | Context interface |
| `ILibraryContainer` | [Library/Interfaces/ILibraryContainer.cs](MatterControlLib/Library/Interfaces/ILibraryContainer.cs) | Container interface |
| `ILibraryItem` | [Library/Interfaces/ILibraryItem.cs](MatterControlLib/Library/Interfaces/ILibraryItem.cs) | Item interface |
| `ILibraryAsset` | [Library/Interfaces/ILibraryAsset.cs](MatterControlLib/Library/Interfaces/ILibraryAsset.cs) | Asset interface |
| `IContentProvider` | [Library/ContentProviders/](MatterControlLib/Library/ContentProviders/) | Content provider |

### Content Providers

| Class | Location | Extensions |
|-------|----------|------------|
| `MeshContentProvider` | [Library/ContentProviders/](MatterControlLib/Library/ContentProviders/) | stl, obj, 3mf, amf |
| `GCodeContentProvider` | [Library/ContentProviders/](MatterControlLib/Library/ContentProviders/) | gcode |
| `ImageContentProvider` | [Library/ContentProviders/](MatterControlLib/Library/ContentProviders/) | png, jpg, gif |

### Events

| Event | Source | Description |
|-------|--------|-------------|
| `ContainerChanged` | `ILibraryContext` | Active container changed |
| `ContentChanged` | `ILibraryContainer` | Container contents modified |