File Formats & Import/Export
Relevant source files
The following files were used as context for generating this wiki page:
The Rocreate project provides a robust system for handling various image file formats, project persistence, and data portability. It supports standard raster formats like PNG, professional multi-layer formats via PSD (Adobe Photoshop), and internal project structures for browser-based storage and recovery. This system is designed to work in both standalone web applications and embedded widget contexts.
Supported File Formats
Rocreate handles several distinct types of data for different use cases, ranging from simple image exports to complex layered project files.
| Format | Usage | Description |
|---|---|---|
| PNG | Export | Standard flattened image export or individual layer export. |
| PSD | Import/Export | Adobe Photoshop format, preserving layer names, opacity, and visibility. |
| .kleki / .kl | Import | Internal project formats used for transferring full canvas states. |
| IndexedDB | Persistence | Internal browser storage for project metadata and layer blobs. |
Sources: src/app/script/klecks/ui/tool-tabs/file-ui.ts:133-140, examples/embed/example.html:34-45
Export Architecture
The export system is centered around the SaveToComputer class and the klCanvasToPsdBlob utility. The application can generate blobs for different formats by processing the KlCanvas state.
PSD Export Process
Rocreate utilizes the ag-psd library (referenced in project licenses and help files) to convert the internal KlCanvas representation into a Photoshop-compatible Blob. This process involves mapping internal layer properties (name, opacity, visibility, mix mode) to the PSD data structure.
Save to Computer Logic
The SaveToComputer class manages the user interface for downloads. It supports a "Show Save Dialog" option which, when enabled in compatible browsers, utilizes the showSaveFilePicker API to allow users to specify file locations and names.
Key properties of SaveToComputer:
exportType: Can be 'png', 'psd', or 'layers' (multi-PNG).save(): Orchestrates the conversion and download.setShowSaveDialog(b: boolean): Toggles the use of the native File System Access API.
Sources: src/app/script/klecks/ui/tool-tabs/file-ui.ts:107-129, src/app/script/klecks/storage/save-to-computer.ts
Import System
The import system handles local file selection, drag-and-drop operations, and clipboard data. It is managed by the KlAppImportHandler.
Import Workflow
- File Selection: Triggered via a hidden
HTMLInputElementor a drag-and-drop event. - Type Detection: Supports
image/*,.psd,.kleki, and.klextensions. - Project Reconstruction:
- For images: Imported as a new layer or a new project.
- For PSDs: Read into a
TKlProjectstructure. - For internal formats: Deserialized directly into the application state.
Browser Storage & Persistence
For long-term work without manual saving, Rocreate implements an IndexedDB-based storage system. This is exposed via the ProjectStore and KlRecoveryManager.
Project Store
The ProjectStore saves the current state of the canvas, including all layers and metadata. It uses a ProjectConverter to transform the live HTMLCanvasElement layers into Blob objects suitable for database storage.
Recovery Manager
The KlRecoveryManager tracks session data to prevent work loss during browser crashes or accidental tab closures.
- Autosave: Periodically stores the project to IndexedDB.
- Recovery UI: Displays a count of recoverable items in a "bubble" on the File UI tab.
- Thumbnails: Generates small previews of stored projects for the Gallery or Recovery panel.
Sources: src/app/script/klecks/storage/project-store.ts, src/app/script/klecks/storage/kl-recovery-manager.ts, src/app/script/klecks/storage/tests/project-converter.test.ts:40-55
Embedded Integration
In the embed version (used as a widget), the import/export flow can be controlled programmatically. The Klecks constructor allows developers to provide an onSubmit callback and use methods like readPSD or openProject to load data from external servers.
// Example from embed usage
const klecks = new Klecks({
onSubmit: async (onSuccess, onError) => {
const pngBlob = await klecks.getPNG();
// Send blob to server...
},
});
// Loading an external PSD
fetch(psdURL).then(r => r.arrayBuffer()).then(buffer => {
return klecks.readPSD(buffer);
}).then(project => {
klecks.openProject(project);
});
Sources: examples/embed/example.html:47-75, src/app/script/app/kl-app.ts:110-125
Conclusion
The Rocreate File Formats & Import/Export system provides a bridge between the browser-based canvas and the professional digital art ecosystem. By supporting PSD through ag-psd and implementing a robust IndexedDB recovery system, it ensures that user work is both portable and secure. The system's flexibility allows it to serve as a standalone painting tool or a deeply integrated component in creative communities.