beffroi-tools/docs/interfaces/midra-layout.md

255 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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).