Image Tools / Docs
Reference

The .img format

A versioned, ZIP-backed project format — the editor's canonical save. What's inside, how migration works, and how to produce one programmatically.

.img is the editor's first-party project format — the equivalent of Photoshop's .psd or Figma's .fig. It's designed to be open, versioned, and machine-friendly so future automation (and AI agents) can produce valid projects without ever opening the editor UI.

#Container

A .img file is a ZIP archive. Open it with any unzip tool to see:

my-project.img/
├── manifest.json          // version, format, feature flags, resource manifest
├── document.json          // the full document state — layers, groups, history
├── assets/                // user-imported raster sources
├── bitmaps/               // base bitmap layer + decoded bitmaps
├── masks/                 // erase / draw / asset-erase masks
├── preview/               // small thumbnail for file previews
└── ...                    // additional resource folders by kind

Resources are referenced by id from document.json — the document never inlines large binaries.

#Manifest

manifest.json is the front door. It carries:

  • format — always "img"
  • formatVersion — currently 1. Bumped only for container changes (folder layout, manifest shape).
  • schemaVersion — currently 2. Bumped for document model changes — new required fields, renames, removed fields, changed semantics.
  • legacySchemaVersions — [1]. Versions that the loader can read via migration.
  • features — opt-in feature flags (e.g. groups, text-on-path, frame-clip) so loaders can warn early on docs they don't fully understand.
  • resources — manifest of every asset / mask / bitmap, with id, kind, mediaType, dimensions, and byte size.

#Document

document.json is the layered project. Top-level shape (simplified):

interface EditorDocument {
  schemaVersion: 2
  canvas: { width: number; height: number; background: BackgroundLayerData }
  crop?: CropState
  cropEnabled?: boolean
  layers: LayerData[]                 // all layer kinds, flat list, z-ordered
  groups: GroupData[]                 // required since v2 — empty array if none
  history: { past: Snapshot[]; future: Snapshot[]; current: Snapshot }
}

Layer kinds (bitmap, shape, text, icon, asset, draw) all share a base shape (id, transform, opacity, blendMode, effects, optional groupId) plus their kind-specific fields.

#See also