255 lines
18 KiB
Markdown
255 lines
18 KiB
Markdown
# Midra Layout file interfaces
|
||
|
||
These are offline editor formats, not Analog Way REST payloads. Implementation:
|
||
[`project.rs`](../../crates/midra-layout/src/project.rs). Regression tests:
|
||
[`project.rs`](../../crates/midra-layout/tests/project.rs). Update this contract,
|
||
examples and tests in the same change as any save/export schema change.
|
||
|
||
## Project JSON, version 10
|
||
|
||
Suggested filename: `layout.midra.json`. Encoding: UTF-8, pretty-printed JSON,
|
||
with a trailing newline. A project preserves applied document values at their
|
||
stored floating-point precision. No display rounding is applied. The loader
|
||
requires every field below, rejects unknown fields, and rejects unsupported
|
||
versions. Version 1 files first gain
|
||
`editor.show_toolbar_icon_names: false`. Versions 1 and 2 then migrate to version 3
|
||
with their original two layer IDs, names `Presenter` and `Slides`, empty folders,
|
||
and `next_layer_id: 3`; other values are preserved.
|
||
The [version 1 example](midra-layout-v1.example.json) remains a migration fixture.
|
||
Version 4 adds `editor.outline_layers: false`, and reference `native_size: false`
|
||
and `offset: [0, 0]` when migrating versions 1–3. Old fitting behavior is preserved.
|
||
Version 5 adds required `midra_link` to every layer. Versions 1–4 migrate with null links; links cannot be supplied under an older version. Version 6 renames `editor.position_corner` to `editor.position_point` and adds `center`. Versions 1–5 retain their original corner; center and the new field are rejected in those older schemas. Version 7 adds `editor.backdrop_title`; versions 1–6 gain `"Example Conference Name"` and cannot supply this field under the old schema. Version 8 adds required `editor.position_layer_point`: null keeps matched points; a point enables independent measurement. Versions 1–7 migrate to null and cannot supply this field. Version 9 adds required `layers[].pivot`; versions 1–8 migrate to `[0.5, 0.5]` and cannot supply this field. Version 10 replaces `reference` with the required ordered `references` array. Versions 1–9 migrate null to `[]` and a single image to a one-element array, preserving all image settings. Saving always writes version 10; older applications reject it.
|
||
Incompatible files are never partially applied.
|
||
|
||
[Complete example](midra-layout-v10.example.json) is a valid default project,
|
||
without a reference image. New projects label the lower layer `02 / Slides` and
|
||
the upper layer `01 / Presenter`; existing projects retain their saved IDs/names.
|
||
It is loaded by the regression tests.
|
||
|
||
| Root field | Representation / meaning |
|
||
| --- | --- |
|
||
| `format` | Exactly `"beffroi.midra-layout"` |
|
||
| `version` | Integer `10` |
|
||
| `next_layer_id` | Positive integer strictly greater than every layer ID; not rewound by undo |
|
||
| `output_resolution` | `{ "width": integer, "height": integer }`, screen pixels |
|
||
| `inputs` | 1–1024 input objects, consecutive IDs starting at 1 |
|
||
| `layers` | 1–256 layer objects, unique positive stable IDs, in back-to-front stacking order (last is topmost) |
|
||
| `references` | Required array of 0–32 embedded reference-image objects, back-to-front compositing order |
|
||
| `editor` | Selection, positioning and viewport preferences |
|
||
|
||
Input objects:
|
||
|
||
| Field | Representation / meaning |
|
||
| --- | --- |
|
||
| `id` | Consecutive input slot ID; not an external device identifier |
|
||
| `source_format` | `"four_three"`, `"sixteen_nine"`, `"sixteen_ten"`, `"square"`, or `"custom"` |
|
||
| `native_resolution` | `{ "width": integer, "height": integer }`, native input pixels |
|
||
| `input_crop` | `{ "left": number, "right": number, "top": number, "bottom": number }`, pixels removed from the native input |
|
||
|
||
The user-facing input resolution is derived by subtracting opposite input crop
|
||
edges from native dimensions. The source format remains explicit even with
|
||
custom input cropping. Non-custom source formats must match the native resolution
|
||
within the existing half-pixel rounding tolerance.
|
||
|
||
Layer objects:
|
||
|
||
| Field | Representation / meaning |
|
||
| --- | --- |
|
||
| `id` | Unique positive stable editor layer ID; independent of list position and Midra mapping |
|
||
| `name` | Nonblank display name, at most 128 characters |
|
||
| `midra_link` | Required: null (unlinked) or `{ "screen": "2", "layer": "1" }`. Positive decimal device IDs as strings, at most 16 ASCII digits; unknown fields rejected. No host, bank or credentials. |
|
||
| `pivot` | Required `[x, y]` gravity point relative to the layer top-left, in fractions of width/height. Center is `[0.5, 0.5]`; outside points are allowed. Finite doubles within ±1,000,000, preserved without rounding. Placement/reset is undoable; follows layer movement/reordering. Omitted from SVG and device writes. |
|
||
| `folder` | Local folder name, at most 128 characters; empty means ungrouped |
|
||
| `source_id` | Existing input slot ID; multiple layers may share an input |
|
||
| `bounds` | `{ "x": number, "y": number, "width": number, "height": number }`, final visible box in screen pixels; x/y are its top-left position |
|
||
| `advanced_crop` | Four nonnegative edges in usable input pixels, after input cropping |
|
||
| `visible` | Boolean editor visibility |
|
||
| `locked` | Boolean editor selection/movement protection |
|
||
|
||
The visible box is the user's layer resolution. Its content zoom and offset are
|
||
**derived** from `advanced_crop`, usable input size and visible box size; they are
|
||
not duplicated in the save file. Retained source pixels must have the same ratio
|
||
as the box. Crop zoom must be 1–100 (100–10000%). Shared input assignments and
|
||
both crop stages survive round trips without rewriting the crop values.
|
||
|
||
Each reference object:
|
||
|
||
| Field | Representation / meaning |
|
||
| --- | --- |
|
||
| `name` | Display filename, not a path to read |
|
||
| `image_base64` | Standard padded RFC 4648 base64 of the original PNG/JPEG/BMP file bytes; no data-URL prefix |
|
||
| `visible` | Boolean |
|
||
| `opacity` | Number from 0 to 1 |
|
||
| `preserve_ratio` | Boolean: fit proportionally if true, stretch to screen if false; applies when native sizing is off |
|
||
| `native_size` | Boolean: image pixels map 1:1 to screen pixels; anchored at screen top-left before offset |
|
||
| `offset` | `[x, y]` finite screen-pixel translation, each within ±1,000,000; applies after fitting/native placement |
|
||
|
||
Images are embedded, so moving the project does not break the references. Each
|
||
image retains independent visibility, opacity and fitting settings. Later entries
|
||
paint over earlier ones; hidden entries do not erase earlier images. The editor
|
||
lists them topmost first with distinct reference coloring, eye/remove controls
|
||
and Show only this reference. They have no layer IDs, geometry handles, device
|
||
links or selection/alignment participation. The currently focused reference row
|
||
is session-only; saved visibility determines the reopened composite.
|
||
|
||
At most 32 images and 64 MiB of combined original image bytes are accepted.
|
||
The existing 96 MiB project JSON limit still applies. No
|
||
external files, URLs or device endpoints are accessed on load. Image dimensions
|
||
are decoded from the bytes. The existing image loader enforces a 64 MiB encoded
|
||
file limit, maximum 8192 pixels per side (or the GPU texture limit if smaller),
|
||
and a 256 MiB decoder allocation limit. Bad image data aborts opening and leaves
|
||
the current editor unchanged. Project file reading/parsing, validation and reference
|
||
decoding run in a background worker. The editor is replaced only after every
|
||
image succeeds; Cancel loading ignores late worker results. Recovery checkpoints
|
||
pause during loading. Texture upload/presentation still depends on the GUI/GPU.
|
||
Captured Midra stills use the same reference object and embedded PNG bytes, with
|
||
no device request on reload; no schema/version change is required.
|
||
|
||
Editor object:
|
||
|
||
| Field | Representation / meaning |
|
||
| --- | --- |
|
||
| `selected_layer_ids` | Array of unique IDs of visible, unlocked layers; may be empty |
|
||
| `backdrop_title` | Required string, 0–128 Unicode characters, no control characters. Example backdrop title; empty hides the text. Preserved exactly, including spaces; omitted from SVG/device output. |
|
||
| `position_point` | Screen measurement origin: `"top_left"`, `"top_right"`, `"bottom_left"`, `"bottom_right"`, `"center"` |
|
||
| `position_layer_point` | Required: null for the matching layer point (advanced toggle off), or one of the same five point strings for an independent layer endpoint (toggle on) |
|
||
| `keep_aspect_ratio` | Boolean for layer resizing |
|
||
| `viewport_zoom` | Positive fit-relative scale, 0.0001–256 |
|
||
| `viewport_pan` | `[x, y]`, viewport pan in screen-coordinate pixels; finite, absolute value at most 1e9 |
|
||
| `show_source_pattern` | Boolean: show source patterns on other layers during crop editing; normal editing always hides patterns |
|
||
| `show_toolbar_icon_names` | Boolean: show names beneath toolbar icons; false by default |
|
||
| `outline_layers` | Boolean: transparent layer fill for reference alignment; selection/handles remain visible |
|
||
|
||
Position offsets measure from `position_point` on the screen to the chosen layer point (matching when `position_layer_point` is null). Screen corners retain inward signs: right origins reverse X, bottom origins reverse Y. Screen center uses positive right/down. For screen top-left → layer center, offsets are the layer’s absolute center coordinates. Numeric resizing and manual ratio edits preserve the chosen layer endpoint’s offsets. Switching either point or toggling independent measurement never moves a layer. Stored bounds remain top-left coordinates; viewport guides use the same endpoints.
|
||
|
||
Resolution dimensions must be whole pixels from 1 to 16384. Layer x/y must be finite and within ±1,000,000 pixels; layer widths/heights
|
||
and retained input dimensions must be positive, finite, and at most 1,000,000
|
||
pixels. Crop edges must be finite and nonnegative, with a positive retained
|
||
region. Off-screen x/y are allowed. Invalid source references, duplicate layer IDs or out-of-order input IDs, invalid crops,
|
||
missing fields and non-finite values are rejected before replacing the document.
|
||
Projects larger than 96 MiB are rejected.
|
||
|
||
Save includes **applied values only**. Pending text/format/import drafts, prepared aspect-ratio targets, open
|
||
dialogs, undo/redo history, crop-edit mode, resize mode, grid/pivot/navigation tool selections, and provisional device
|
||
export calculations are not persisted. The current resize mode stays selected
|
||
when opening another project in the same session; a fresh launch starts with
|
||
Individual mode. Names and folder labels are stored. Removing layers does not renumber surviving
|
||
IDs; adding a layer consumes `next_layer_id`. Unused input slots are retained
|
||
to preserve shared-source references. Loading starts a fresh history. Loading requires a
|
||
replacement confirmation; failed loading leaves current work intact. Writes use
|
||
a same-directory temporary file and atomic publication. Existing destination
|
||
files require explicit replacement confirmation for Save/exports. Measurement-point
|
||
clicks and the independent-point toggle are an exception: they reread the current
|
||
project and atomically update only `editor.position_point` and
|
||
`editor.position_layer_point`, preserving its other stored values (including external edits).
|
||
Older schemas migrate to v10 on this write. No project path is stored in settings;
|
||
new documents require a first Save. Geometry exports never change the active project path.
|
||
Missing/invalid/unwritable projects are left untouched and an error is shown;
|
||
active in-memory choices remain available for a manual Save. A failed no-overwrite write
|
||
leaves the existing file intact.
|
||
|
||
## Layer history and export scopes
|
||
|
||
Add/remove/rename, reordering and folder edits are undoable. Device mappings are not implied
|
||
by editor IDs. Selection stores stable layer IDs, not zero-based indices. At
|
||
least one layer must remain. Visibility and locks remain local protection flags and are undoable.
|
||
Geometry export supports all, visible-only, explicit specific-layer (including hidden)
|
||
or selected layers (including a single
|
||
layer); rectangles retain stable IDs and document stacking order. Names appear as titles/labels in current geometry exchanges; folders are omitted.
|
||
|
||
Reordering changes only the order of the existing `layers` array, not IDs or
|
||
per-layer values. Reordering uses the existing array order for every exchange version. Moving layer 1 above
|
||
layer 2 in the list saves IDs in `[2, 1]` order and emits `layer-2` before `layer-1` in SVG.
|
||
Loading preserves that order; selected-layer exports still follow document order,
|
||
not selection order. Source slots, `next_layer_id`, names, folders, crop geometry,
|
||
visibility/locks and Midra links remain attached to their original layer IDs.
|
||
The layer manager displays reverse document order (top row is topmost). The inspector
|
||
collects same-name folder members into one collapsible group, ordered by each group's
|
||
frontmost member; children retain reverse stacking order. Legacy interleaved groups
|
||
are displayed together without silently rewriting the saved stack. Selection does not
|
||
raise a layer; canvas drawing and hit testing follow the saved stack.
|
||
|
||
Folders remain single-level names on layer records; no schema change is required.
|
||
There are no empty-folder records or implicit path separators. Creating/renaming a
|
||
folder updates all member `folder` strings in one history step; renaming to another
|
||
existing folder name is rejected (use membership moves to combine groups).
|
||
Moving a folder reorders its members as one contiguous block, preserving member order,
|
||
IDs, source references, crops and Midra links. A layer row drop changes membership and
|
||
stacking together in one history step. Folder eye/lock actions update each member's
|
||
`visible`/`locked` flags atomically; Undo restores mixed prior states. Folder selection
|
||
respects each member's visibility/lock. Collapse state is session-only and is omitted
|
||
from save/export formats; an empty group disappears when its last member leaves.
|
||
Geometry exports continue to omit folders.
|
||
|
||
## Legacy SVG geometry exchange, version 1
|
||
|
||
The Export menu now produces SVG v2 and draw.io v1 with optional artwork; see
|
||
[geometry exchange](midra-layout-exchange.md) for their current contracts and
|
||
examples. The v1 API below remains readable and available for compatibility.
|
||
|
||
Suggested filename: `layout.svg`. UTF-8 SVG with SVG namespace, `width`, `height`
|
||
and `viewBox="0 0 W H"` equal to the output screen. The root carries
|
||
`data-midra-layout-geometry="1"`. A title and one `<rect>` per exported layer follow.
|
||
|
||
```xml
|
||
<svg xmlns="http://www.w3.org/2000/svg" data-midra-layout-geometry="1"
|
||
width="1920" height="1080" viewBox="0 0 1920 1080">
|
||
<title>Midra Layout geometry</title>
|
||
<rect id="layer-1" x="120" y="180" width="640" height="360" fill="#173b50"/>
|
||
<rect id="layer-2" x="1160" y="180" width="640" height="360" fill="#173b50"/>
|
||
</svg>
|
||
```
|
||
|
||
- IDs are stable layer names `layer-1`, `layer-2`; rectangle order is document
|
||
order, independent of viewport selection.
|
||
- Coordinates are the visible box top-left and size, rounded independently to
|
||
nearest whole pixels; half values round away from zero. Negative coordinates
|
||
are retained. Dimensions that would round to zero reject export.
|
||
- There are no strokes, transforms or groups, so stroke expansion is unnecessary.
|
||
- **All layers** includes hidden and locked layers as ordinary visible rectangles.
|
||
**Visible layers only** omits hidden layers but includes locked visible ones.
|
||
An empty visible selection rejects export instead of producing an unimportable file.
|
||
- The file is a geometry interchange, not a project backup. It deliberately omits
|
||
source assignments, crops, content zoom, reference image, lock/visibility flags,
|
||
selection and camera. Use project JSON to preserve those.
|
||
- Select the same number of destination layers, then use **Import → SVG file**
|
||
and review the mappings. A full-screen rectangle bearing this export marker
|
||
is treated as a layer, not an automatically ignored background. Other SVGs keep
|
||
the existing full-page background detection rule.
|
||
- Reimporting restores rounded box geometry through the regular import options;
|
||
it does not set the screen resolution or restore omitted project state. External
|
||
SVG editors may remove the marker; then review the background checkbox on import.
|
||
|
||
## Compatibility changes
|
||
|
||
Project version 10 and the versioned geometry exchanges are strict contracts. A breaking project field/meaning change must bump
|
||
`version` and either implement a tested migration or clearly reject older/newer
|
||
files. Changing rectangle/marker semantics requires a corresponding documented
|
||
exchange-interface revision and importer tests. Update this document and its example
|
||
with every schema or semantic change, including additive fields under the strict
|
||
unknown-field policy. Never silently interpret a future version as a supported version.
|
||
|
||
Midra links belong to layer identity and survive selection changes, refresh, rename, reorder and project round trips. Link edits support Undo/Redo. New layers and older projects start unlinked. Links refer to the currently connected device; Preview/Program and sizing remain session choices, and Program permission remains an application preference. Duplicate destinations can be stored, but a send containing duplicates is rejected before any writes. Unavailable screens/layers are reported without deleting the saved links. Geometry exports omit links.
|
||
|
||
Midra destinations are identified by the pair **screen ID + layer ID**: Screen 1
|
||
Layer 1 and Screen 2 Layer 1 are distinct links. Both IDs are already persisted
|
||
in project version 5; no schema change is needed. Opening **Midra mapping & transfer…** or
|
||
**Configure Midra export…** restores the first selected layer's available linked
|
||
screen. Destination choices display both IDs. Browsing another screen does not
|
||
retarget existing links; choosing a destination there explicitly replaces that
|
||
layer's saved link. Direct send/load actions use each layer's saved screen,
|
||
independently of the screen currently displayed in the configuration window.
|
||
|
||
Automatic session recovery wraps this project representation in a separate [recovery file](midra-layout-recovery.md); named project JSON is version 10.
|
||
|
||
## Folder-scoped Midra transfers
|
||
|
||
The shared Midra transfer scope is session-only and is not saved. Defaults use all
|
||
layers; Selected/Folder modes filter by the existing selection or `folder` fields.
|
||
Folders may store alternative layouts whose `midra_link` values reuse the same screen
|
||
and layer; each individual send requires unique destinations within its scope.
|
||
Manual device import now saves the reviewed `midra_link` with imported geometry/crops
|
||
in one Undo step. New layers inherit the chosen folder; existing folder names remain.
|
||
All these values use the existing layer fields (unchanged in version 10). See
|
||
[device transfer scopes](midra-device-send.md#shared-transfer-scopes-and-folder-layouts).
|