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

14 KiB
Raw Blame History

Midra Layout file interfaces

These are offline editor formats, not Analog Way REST payloads. Implementation: project.rs. Regression tests: project.rs. Update this contract, examples and tests in the same change as any save/export schema change.

Project JSON, version 9

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 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. Saving always writes version 9; older applications reject it. Incompatible files are never partially applied.

Complete example is a valid default project, without a reference image. It is loaded by the regression tests.

Root field Representation / meaning
format Exactly "beffroi.midra-layout"
version Integer 9
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)
reference null or an embedded reference-image object
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.

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

The image is embedded, so moving the project does not break the reference. 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.

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 source-coordinate preview setting
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. 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. SVG 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/folders are not added to the geometry SVG format.

Reordering changes only the order of the existing layers array, not IDs or per-layer values. Reordering uses the existing array order; SVG remains v1. 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 inspector and layer manager display the reverse of document order: top row is topmost. Selection does not raise a layer; canvas drawing and hit testing follow the saved stack.

SVG geometry exchange, version 1

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.

<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 9 and SVG version 1 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 SVG 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. SVG exports geometry only and omits 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 Apply changes… 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.