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:

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:

Library.ContentProviders.Add("stl", new MeshContentProvider());
Library.ContentProviders.Add("gcode", new GCodeContentProvider());

Item Types

ILibraryAsset: File-based items with content

public interface ILibraryAsset : ILibraryItem
{
    string FileName { get; }
    string ContentType { get; }
    long FileSize { get; }
}

ILibraryObject3D: 3D model items

public interface ILibraryObject3D : ILibraryItem
{
    Task<IObject3D> GetObject3D(Action<double, string> progress);
}

ILibraryContainerLink: Lazy-loaded container reference

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:

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:

// Navigate up
ActiveContainer = ActiveContainer.Parent;

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

Thumbnails

ThumbnailsConfig manages thumbnail generation:

// 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	Library manager
RootLibraryContainer	Library/Providers/RootLibraryContainer.cs	Root container
FileSystemContainer	Library/Providers/FileSystem/	File system access
LibraryContainer	Library/Providers/LibraryContainer.cs	Base container

Interfaces

Interface	Location	Description
ILibraryContext	Library/Providers/LibraryConfig.cs	Context interface
ILibraryContainer	Library/Interfaces/ILibraryContainer.cs	Container interface
ILibraryItem	Library/Interfaces/ILibraryItem.cs	Item interface
ILibraryAsset	Library/Interfaces/ILibraryAsset.cs	Asset interface
IContentProvider	Library/ContentProviders/	Content provider

Content Providers

Class	Location	Extensions
MeshContentProvider	Library/ContentProviders/	stl, obj, 3mf, amf
GCodeContentProvider	Library/ContentProviders/	gcode
ImageContentProvider	Library/ContentProviders/	png, jpg, gif

Events

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