8.3 KiB
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 2
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 are migrated to version 2 by setting
editor.show_toolbar_icon_names to false; all other values are preserved.
The version 1 example remains a migration fixture.
Saving always writes version 2. Older applications reject version 2 files.
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 2 |
output_resolution |
{ "width": integer, "height": integer }, screen pixels |
inputs |
Exactly two input objects, IDs 1 and 2, in that order |
layers |
Exactly two layer objects, IDs 1 and 2, in that order |
reference |
null or an embedded reference-image object |
editor |
Selection, positioning and viewport preferences |
Input objects:
| Field | Representation / meaning |
|---|---|
id |
Input slot 1 or 2; 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 |
Editor layer slot 1 or 2; independent of future Midra mapping |
source_id |
Input ID 1 or 2; both 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 |
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 |
position_corner |
"top_left", "top_right", "bottom_left", "bottom_right" |
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 |
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/out-of-order 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, open dialogs, undo/redo history, crop-edit mode, resize mode, and provisional device export calculations are not persisted. Current layer names are fixed by editor slot and are not stored. 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.
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 editor-slot names
layer-1,layer-2; rectangle order is slot order, independent of viewport selection/foreground drawing. - 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 2 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.