Layers & Frames

How OpenGPEX organizes visual content into Frames (artboards) containing Layers (visual elements).

Frames

A Frame is a top-level canvas container with:

Canvas dimensions (width × height in pixels)
Camera state (pan position + zoom level)
Layer stack (ordered collection of layers)
Active layer reference

You can have multiple frames in a single project for multi-view workflows.

Layer Types

Type	Description	Use Case
Image	Raster pixel data from imported files	Photos, bitmaps
Text	Editable text with styling	Titles, captions
Vector	Marker Tool shapes (rect, arrow, ellipse)	Annotations, callouts
Color	Full-canvas solid fill	Backgrounds
Paint	Freehand raster drawing	Pixel painting
Group	Container grouping child layers	Organization

Layer Properties

Every layer has:

Identity: unique ID, user-visible name
Visibility/Lock: toggle display and edit protection
Opacity & Blend Mode: 16 compositing modes available
Geometry: center position, rotation, flip, bounding dimensions
Masks: vector masks (shape-based) and bitmap masks (painted)
Adjustments: non-destructive brightness, contrast, saturation, hue, blur
Fragment metadata (optional): sourceLayerId (parent layer), assocMaskId (corresponding hole mask on parent) — see Cut-Link section below

Z-Order

Layers render bottom-to-top based on their position in an order array. Reordering only changes the array — layer objects stay referentially stable, making undo patches minimal.

Non-Destructive Editing

OpenGPEX preserves original pixel data at all times:

Original asset stored immutably in CAS (Content-Addressable Storage)
Layer metadata (position, masks, adjustments) stored as lightweight properties
Rendering combines asset + metadata on-the-fly
Undo simply reverts metadata — no need to restore pixel data

Cut-Link Fragment System

When a user performs Layer via Cut (Peel), OpenGPEX establishes a bidirectional link between the source layer and the resulting fragment:

Fragment → Source: metadata.sourceLayerId + metadata.assocMaskId identify the parent and its hole mask
Source → Fragment: an inverted VectorMask with assocLayerId pointing to the fragment

This enables:

Merge Back: recursively return fragments to their source (zero rasterization)
Union Merge: combine multiple fragments via polygon union (vector precision)
Auto-cleanup: deleting a fragment automatically removes its hole mask from the source

`sourceLayerId`	`assocMaskId`	Meaning
set	set	Cut fragment — bidirectional link, supports Merge Back
set	empty	Copy derivative — lineage only, no complementary constraint
empty	—	Independent layer

Sub-Layer System (Triplets)

Complex layers can contain child sub-layers:

Host: the main user-visible layer
Exchange: temporary drawing buffer
Frag: drawing fragment buffer

Geometry changes on a host layer automatically cascade to its children.

Last updated: 2026-08-30