Create visual Midra quick start and topic guides
Beffroi/beffroi-tools/pipeline/head This commit looks good Details

This commit is contained in:
Dandaedre 2026-11-14 20:32:30 +01:00
parent ba67f21c83
commit 6ba5b06e90
19 changed files with 1320 additions and 1075 deletions

View File

@ -108,21 +108,11 @@ See [development setup](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/
## Midra Layout templates
Ready-made canvases with two named 16:9 layers. Choose a size, then a format.
[Browse all starter files →](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/templates/midra-layout/README.md)
<details>
<summary><strong>Browse Full HD and UHD 4K templates</strong> — SVG, draw.io, PPTX, FIG, AI, JSON, CSV, DXF and HTML</summary>
These starter files contain two named 16:9 layers on an exact pixel canvas.
- **Full HD — 1920 × 1080:** [SVG](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/templates/midra-layout/midra-layout-1080p-2-layers.svg) · [draw.io](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/templates/midra-layout/midra-layout-1080p-2-layers.drawio) · [JSON](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/templates/midra-layout/midra-layout-1080p-2-layers.json) · [CSV](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/templates/midra-layout/midra-layout-1080p-2-layers.csv) · [DXF](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/templates/midra-layout/midra-layout-1080p-2-layers.dxf) · [HTML](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/templates/midra-layout/midra-layout-1080p-2-layers.html) · [PPTX](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/templates/midra-layout/midra-layout-1080p-2-layers.pptx) · [Figma FIG](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/templates/midra-layout/midra-layout-1080p-2-layers.fig) · [Illustrator AI](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/templates/midra-layout/midra-layout-1080p-2-layers.ai)
- **UHD 4K — 3840 × 2160:** [SVG](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/templates/midra-layout/midra-layout-4k-2-layers.svg) · [draw.io](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/templates/midra-layout/midra-layout-4k-2-layers.drawio) · [JSON](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/templates/midra-layout/midra-layout-4k-2-layers.json) · [CSV](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/templates/midra-layout/midra-layout-4k-2-layers.csv) · [DXF](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/templates/midra-layout/midra-layout-4k-2-layers.dxf) · [HTML](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/templates/midra-layout/midra-layout-4k-2-layers.html) · [PPTX](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/templates/midra-layout/midra-layout-4k-2-layers.pptx) · [Figma FIG](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/templates/midra-layout/midra-layout-4k-2-layers.fig) · [Illustrator AI](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/templates/midra-layout/midra-layout-4k-2-layers.ai)
PPTX and FIG samples contain an editable slide/frame; AI samples were generated with
VectorCraft 0.24.1. Midra imports/exports Illustrator AI using an optional
local VectorCraft CLI. See [formats, dependencies and licensing builds](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/interfaces/midra-layout-exchange.md#optional-native-document-codecs-and-licensing-builds).
</details>
Matching Full HD and UHD 4K layouts are available in SVG, draw.io, geometry JSON,
CSV, DXF, HTML, PPTX, Figma FIG and Illustrator AI. The catalog contains every
base file, import guidance and format dependencies.
## Explore further

View File

@ -8,7 +8,7 @@
| --- | --- | --- |
| PPTX Reporter | [Guide](pptx-reporter/README.md) · [Visual walkthrough](pptx-reporter/visual-guide.md) | [Report formats](pptx-reporter/report-formats.md) · [Windows quick start](pptx-reporter/windows-quickstart.txt) · [Portable quick start](pptx-reporter/portable-quickstart.txt) |
| Rundown Converter | [Guide](rundown-converter/README.md) · [Portable quick start](rundown-converter/portable-quickstart.txt) | [Corpus findings](rundown-converter/corpus.md) · [Plan](rundown-converter/plan.md) |
| Midra Layout | [Guide](midra-layout/README.md) | [Resolutions and cropping](midra-layout/resolutions.md) · [Device checks](midra-layout/device-check.md) · [Plan](midra-layout/plan.md) |
| Midra Layout | [Introduction](midra-layout/README.md) · [User guide](midra-layout/guide/README.md) | [Resolutions and cropping](midra-layout/resolutions.md) · [Device checks](midra-layout/device-check.md) · [Plan](midra-layout/plan.md) |
| ASCII Names | [Guide](ascii-names/README.md) | [Changelog](ascii-names/changelog.md) |
| Document Exporter | [Guide](exporter/README.md) | [Changelog](exporter/changelog.md) |
| MPC-HC Companion | [Setup and development](../companion-modules/media-player-classic/README.md) | [Changelog](media-player-classic/changelog.md) |
@ -17,7 +17,7 @@
- **Development:** [setup and checks](development/README.md), [CI and coverage](development/ci.md), [builds and portable releases](development/releases.md), [application artwork](development/releases.md#application-artwork).
- **File and device contracts:** [interface index](interfaces/README.md), including versioned examples and compatibility rules.
- **Starter files:** [Midra Layout templates](../README.md#midra-layout-templates) in [templates/midra-layout](templates/midra-layout/).
- **Starter files:** [Midra Layout catalog](templates/midra-layout/README.md), with Full HD and 4K base files in all nine exchange formats.
- **Release history:** [v0.6.0 notes](releases/v0.6.0.md), [v0.3.0 notes](releases/v0.3.0.md) and [per-tool changelogs](changelogs.md).
- **Future work:** [ideas](../Ideas.md), [program task list](planning/program-task-list.md), [Flipper Link feasibility](planning/flipper-link.md).

View File

@ -8,8 +8,8 @@ preserve layer **visible-box geometry**, not sources, crop settings, zoom, pivot
Midra links, locks, visibility, camera or selection. Pictures illustrate current
cropping; importing a picture does not reconstruct its crop or source settings.
Ready-to-open two-layer templates are published under
`docs/templates/midra-layout/` for Full HD (1920 × 1080) and UHD 4K
The [starter-file catalog](../templates/midra-layout/README.md) centralizes ready-to-open
two-layer templates under `docs/templates/midra-layout/` for Full HD (1920 × 1080) and UHD 4K
(3840 × 2160), in all nine exchange formats (including PPTX, FIG and AI). The 4K geometry is an exact
2× scale of the Full HD layout. Regenerate them with:

File diff suppressed because it is too large Load Diff

View File

@ -4,6 +4,8 @@
## Unreleased
- Replace the long overview with a visual quick start, move detailed workflows into topic guides, and centralize all nine starter-file formats in one catalog. Add real application screenshots with reproducible capture notes; retain the existing template files and validation contracts.
- Clarify shared Midra links: warn with other linked layer/folder names while allowing link edits; disable conflicting scoped sends and list all overlapping destinations. Preserve conflict-free folder/selection sends and remapping. Remove nested-folder/additional-codec backlog items and replace the extra-links proposal with this shared-destination workflow. Regression tests cover warning text, send blocking and scope isolation.
- Remove duplicate overlay-grid controls from snapping menus; keep them in the adjacent Grid toolbar menu and a separate section in Editing preferences.

View File

@ -0,0 +1,26 @@
# Midra Layout user guide
[Introduction and quick start](../README.md) · [Starter files](../../templates/midra-layout/README.md) · [Changelog](../changelog.md)
Detailed controls, workflows and limitations are grouped below. Start with layers
and the canvas, then use the chapters relevant to your workflow.
| Chapter | What it covers |
| --- | --- |
| [Layers and editing](editing.md) | Select, move, resize, align, name, order and group layers |
| [Canvas and reference images](canvas.md) | Workspace defaults, view tools, guides, grid, reference pictures and positioning points |
| [Formats, crop and precision](formats-and-crop.md) | Input/output sizes, content framing, visual crop controls and numeric precision |
| [Import, export and project files](files.md) | Clipboard mapping, geometry files, export scopes, saving and recovery |
| [Menus and preferences](preferences.md) | Application menus, themes, saved settings and snapping |
| [Midra connection and transfers](device.md) | Connection, reviewed device writes, folder layouts and input snapshots |
| [Viewport performance](performance.md) | Reproducing the headless capacity check and interpreting its results |
## Technical reference
- [Resolution and cropping model](../resolutions.md): equations and worked examples.
- [File and device contracts](../../interfaces/README.md): schemas, migration, supported formats and device behavior.
- [Hardware verification](../device-check.md): tested device behavior and limitations.
- [Implementation plan](../plan.md): remaining acceptance work and design background.
These are ordinary Markdown chapters with relative links; no documentation build
is required to browse them.

View File

@ -0,0 +1,255 @@
# Canvas and reference images
[Midra Layout](../README.md) · [Guide contents](README.md) · [Starter files](../../templates/midra-layout/README.md)
## Workspace defaults and limits
New projects start with two local rectangles and two source identities;
you can add more layers and editor inputs.
Output resolution defaults to **1920 × 1080 (16:9)** and can be changed.
The output dialog identifies standard aspect ratios from the current resolution;
nonstandard ratios display as Custom.
The example backdrop is titled **Example Conference Name** by default. Edit it
under **Options → Example backdrop** or **Settings → Reference images**. Changes
appear immediately and save with the project; leave it blank to hide the text,
or use **Reset example title**. Up to 128 single-line characters are allowed.
The title is clipped to the banner and appears only without an imported reference
image, at any output resolution. It is not exported to SVG or sent to Midra.
The initial backdrop is illustrative and adapts to every output resolution/aspect ratio; importing a reference picture replaces it.
Project save/load, nine-format geometry exchange, arbitrary layer collections,
single-level folders and persistent Midra screen/layer links are implemented.
File export offers current/specific/selected/all/visible scopes; device transfers
use All/Selected/Folder. Organization never sends commands by itself.
The Midra connection and mapping/transfer UI supports explicit sends and loads,
with both sizing strategies and Centered crop conversion readback-tested on
Eikos 3.3.10. Program sending is enabled by a manual preference. Ordinary local
editing does not send; linked send is a direct user action. Physical-output
comparison, broader firmware coverage and non-Centered/masked conversion remain
[acceptance/backlog work](../plan.md#remaining-acceptance-and-release-checks).
Visible-box center readouts are distinct from crop-corrected device containers.
Internal precision is retained; views show one decimal and exports whole pixels.
The window can be resized; the screen keeps its aspect ratio, and the right
inspector scrolls on shorter windows. Minimum size is 1000 × 720 logical points.
A graphical desktop session is required to launch.
The Cargo workspace includes this crate in lint, tests, docs and coverage.
Regression tests cover the supplied clipboard, malformed/unsupported input,
corner conversion, group drag/undo, selection boxes, alignment targets, and GUI
paste/focus behavior. Layer-list scrolling uses the wheel or scrollbar so dragging
across list entries cannot accidentally scroll while selecting.
See the [project plan](../plan.md) and
[resolution/cropping specification](../resolutions.md) for the implemented
geometry model and remaining hardware-verification work.
Each layer row has **Lock / Locked** and **Hide / Show** buttons. Locked layers
remain visible but cannot be selected, dragged, nudged, aligned or edited. Hidden
layers keep their geometry and stay in the list, but are excluded from drawing
and selection. Locking or hiding clears that layer's selection; showing it does
not unlock it. These are local session controls, separate from geometry undo/redo
(which can still restore earlier geometry), and never send device commands.
Selected layers use gold outlines, labels, handles and position guides; unselected
layers use muted outlines and labels. Gold in the layer list follows the same
selection state, including when several layers are selected.
### Reference pictures
The screen name and output resolution remain visible above the output when reference
images are loaded; Fit screen includes room for both labels.
Imported images accumulate in a purple **Reference images** section below the
layer list, newest/topmost first. **Add image…** and **+ Add…** accept multiple
files. Use each eye icon to show/hide a guide, the remove icon to delete it,
or right-click **Show only this reference** to switch guides quickly. Double-click
opens that image's settings. Reference rows cannot be dragged, resized, aligned
or sent to Midra; selecting one clears the editable-layer selection.
Removal is also available in **Import → Remove reference image** and the viewport
context menu's **Reference images** submenu, with a picker for the target image.
Images remain fixed behind the layers; their existing explicit fit/opacity settings
remain available. Visible images composite back-to-front. Saves and recovery retain
all images and settings, while background-enabled exports flatten visible guides.
Older single-image projects migrate automatically to the new v10 collection.
The **Import** dropdown groups layer-value imports and screen references.
Layer imports offer destination mapping. After importing a reference picture,
**Import → Reference settings…** opens its visibility, opacity and scaling controls.
Drop one or more PNG, JPEG or BMP images into the window, or choose **Import → Add reference images…**. The image is fixed behind the layers in screen coordinates; zooming
and panning keep it aligned. Layer fills become translucent to reveal the image.
Use the reference window to pick an imported image, hide it, adjust opacity or remove it.
**Fill screen** maps the entire image to the current output resolution. An exact
pixel match needs no warning. Scaling up or down with matching proportions shows
an amber warning; a different aspect ratio (such as 16:10) shows a red **SEVERE
WARNING** because the image is distorted. Neither warning blocks importing or
moving layers. **Fit inside** preserves proportions and centers the image with
empty margins where needed; scaling still produces an amber warning.
Up to 32 images with a combined 64 MiB of file bytes can be stored; dimensions
are limited to 8192 pixels per side or the GPU's texture limit, whichever is
smaller. Invalid imports keep all existing images. Reference images and settings
are saved with the project; their edits are independent of layer undo/redo.
### Optional independent positioning points
**Measure position from** normally uses matching screen/layer points, keeping the
inspector compact. Enable **Use a different measure point** to reveal **To layer
point**. The first selector is the screen origin; the second is the layer endpoint.
For absolute center coordinates, choose screen **Top left** and layer **Center**.
Changing points or turning the toggle off only updates the displayed offsets.
Numeric size and ratio edits keep the selected layer endpoint fixed. Screen-right
and screen-bottom origins keep their existing inward-positive signs; screen
center uses positive right/down. Both points and the toggle autosave immediately to the opened or last-saved project.
Only these choices are written; other edits still need Save. For a new project,
save it once to establish its file. Write failures keep the selection active and show an error.
Older projects open with matched points. Canvas guides show the chosen endpoints.
### Displaying and entering aspect ratios
Layer dimensions and resolution controls show their current width:height ratio
(e.g. **16:9**). A ratio field beside **Keep aspect ratio when resizing** accepts
`16:9`, `4/3`, or a positive decimal such as `1.85`. Press Enter or leave the field
to commit. With the lock checked, width stays fixed and height changes, preserving
the selected position reference (including center). Undo restores the geometry
and crop together. Zero, negative, non-finite and out-of-range results are rejected.
With the lock unchecked, entering a ratio does not resize: it stays ready until
the lock is enabled. The displayed current ratio still describes the actual
sizes. Selecting another layer discards that prepared value. In Layer properties,
manual ratios and presets resize immediately when locked, as do width/height edits.
The Layer tab needs no Apply; pending Source edits still require their own Apply. Unapplied ratio text/targets are temporary UI state, not saved settings
or a separate project constraint. Source content remains proportionally scaled.
### Select, Move, Pan and Zoom tools
The toolbar's **Select**, **Move**, **Pan** and **Zoom** icons are mutually exclusive and
remain selected until another is chosen. **V**, **M**, **H** and **Z** select them when
not typing in a field; hover the icons for help. Grid/Pivot toggle choices are
retained independently.
- **Select (V):** select, move, resize and marquee-select layers using the existing
controls; crop editing remains available.
- **Move (M):** drag anywhere to move the current selection without changing it
or resizing. In crop mode, moves the selected layer’s content.
- **Pan (H):** drag anywhere in the viewport to move the camera without editing
layers or changing selection.
- **Zoom (Z):** click to zoom in around the pointer, Alt-click to zoom out. Drag
right to zoom in or left to zoom out, anchored at the gesture's starting point.
- **Space-drag / middle-drag:** temporarily pan from any tool. Scroll zoom works
from every tool. Escape restores the camera if a pan/zoom drag is in progress.
Navigation tool choice survives selection changes and project loads in the current
session; a new launch starts with Select. Pan/Zoom do not alter geometry, crop values
or document history. Existing project saves still preserve zoom/pan values.
### Persistent editing tools
The toolbar’s **Snap ▾** dropdown groups the **10 px grid** and **100 px grid**
icon toggles with the snapping options. Its label shows the effective grid,
including modifier overrides. **Pivot** stays beside it as an independent toggle.
Click again to turn a tool off. Only one grid can stay selected; Pivot can combine
with either. A cyan outline marks the selected toggle; the fill shows its current
effect, including temporary modifier changes. Tooltips explain the shortcuts.
Icons wrap onto another row when the window is narrow.
| Held modifier | Temporary effect |
| --- | --- |
| Shift | 10 px grid; disables it if that grid is already selected |
| Ctrl+Shift | 100 px grid; disables it if that grid is already selected |
| Ctrl without Shift | Inverts Pivot on/off |
| Alt | Overrides either grid and inverts ordinary snapping |
A different grid shortcut temporarily replaces the selected grid. Ctrl+Shift does
not invert Pivot, so a selected Pivot tool can combine with the 100 px grid.
Releasing modifiers restores the selected tools, including during a drag. Tools
stay selected across selection changes and project loads in this session; they
are not saved to projects/settings and start off on launch. They affect layer
movement/resize, not numeric edits or crop-content handles.
### Overlay grid
The **Grid** toolbar icon opens **Show overlay grid**, **Snap to overlay grid**,
and **Columns / Rows** controls (1–64 each, default 8 × 6). The grid is drawn
above reference images and the sample artwork, below layers, across the full output.
Subdivisions scale with the output resolution and can fall on fractional pixels.
Enable snapping in the magnet menu and **Snap to overlay grid** in the Grid menu to snap layer edges,
centers, resize handles and pivots to these lines. Showing and snapping are
independent; the 10/100 px modifier grids still take precedence. These options
are saved in application preferences. The guide is not included in exports.
### Ctrl resize pivot
With Pivot off, hold **Ctrl** (or select **Pivot**) to show a draggable crosshair on selected layers (center by
default). Drag the marker to place it, including outside the layer; this changes only its saved pivot, not its geometry. Double-click the visible pivot to reset to center.
**Ctrl-drag a layer resize handle** to resize around the fixed pivot. Ctrl can be
pressed/released during the gesture; the result is recalculated from the starting
geometry. With Pivot selected, Ctrl temporarily restores the normal opposite-edge anchor. Escape cancels a
resize or restores the previous pivot placement.
| Resize mode | Pivot behavior |
| --- | --- |
| Individual | Only the dragged layer resizes around its pivot |
| Same handles | Placing a marker sets the same relative pivot on selected layers |
| Mirror horizontally | Placing a marker reflects the partner’s pivot left/right |
| Opposite handles | Placing a marker reflects the partner’s pivot on both axes |
Dragging a pivot snaps within six logical display pixels of the layer's four corners,
four side midpoints and center, even with snapping disabled. Nearby local anchors
win over a grid; elsewhere the active 10/100 px grid or enabled pixel/screen-edge/
visible-layer-edge options apply. Guides show reached anchors/edges/grid lines.
Alt bypasses the nine built-in anchors and grids while retaining its usual
inversion of configured snapping. Release uses the current modifiers.
Moving any marker updates the related markers as above. Changing selection or resize mode preserves stored points. Each layer's own pivot stays fixed
while resizing; unequal sizes retain proportional scaling. Aspect-ratio lock,
snapping (including edge contact), Alt inversion and Undo still apply. A handle
on the pivot's axis cannot resize that axis; move the pivot or use another handle.
Layers do not flip when dragged through the pivot; minimum sizes still apply.
**Ctrl+Shift remains the 100 px grid** (or temporarily disables a selected 100 px grid); it uses pivot anchoring if Pivot is selected. Pivot positions are saved per layer in the project, survive selection changes and reopening, and follow layers when moved. Placement and reset support Undo/Redo. They do not affect numeric sizing. In **Adjust layer crop** mode, Ctrl/Pivot scales the image with its source pixel under the gravity point fixed; the visible layer box stays unchanged. Crop limits stop scaling before revealing empty space, including with outside pivots.
### Resizing with corner handles
Drag a selected layer's gold corner handles to resize it; the opposite corner
stays fixed. **Keep aspect ratio when resizing**, above the viewport, is enabled
by default. Clear it to adjust width and height independently against the reference
picture. The same toggle links numeric width/height edits. Pasted dimensions
remain exactly as supplied by the source.
Dragging a handle in a multiple selection selects and resizes only that layer.
Sizes cannot flip or shrink below one pixel during dragging. Escape cancels;
one Undo restores the complete resize. Locked or hidden layers cannot be resized.
## Reference placement and loading
Reference settings now offer **Native pixels**, mapping each image pixel to one
screen pixel at the screen's top-left, plus X/Y offsets in screen pixels. Offsets
also work with Fit/Stretch. The image is clipped to the output screen. Native
mode does not scale or distort the image, so stretch warnings do not apply.
**Outline-only layers** keeps the reference unobscured while retaining selection
and resize handles; it is also available in viewport options. Crop editing still
shows its source guide. Placement and outline mode are saved in project v4.
Picture import/drop reads and decodes off the UI thread, retaining the current
reference until successful completion. Canceling/removing discards late results;
failed replacements keep the current image. Decoder work is serialized to bound
peak memory. Minification uses linear filtering, magnification nearest-neighbor.
Project/recovery reads and embedded reference decoding also run in a worker;
the editor is installed atomically after all images validate.
Resize snapping now uses the same preference and Alt inversion as movement snapping.
It preserves opposite anchors, aspect ratio and group-resize proportions. Guides
appear only when the resulting handle reaches the target; crop-content gestures
remain unsnapped. At 2 logical pixels per screen pixel, adaptive coordinate rulers
appear; at 8, a pixel grid appears. Guide drawing is limited to the visible region.
Every exchange format also offers **Specific layer…**, listing every local layer, including
hidden/locked layers. Choosing one explicitly exports its geometry without
changing visibility or selection. No device mapping or send is implied.

View File

@ -0,0 +1,128 @@
# Midra connection and transfers
[Midra Layout](../README.md) · [Guide contents](README.md) · [Starter files](../../templates/midra-layout/README.md)
## Use folders as local Midra layouts
The Midra **Apply to** selector is shared by the status bar, Export menu, and
send/import windows. It starts at **All layers**, regardless of canvas selection.
Choose **Only selected layers** for an explicit selection filter, or **Folder: …**
for a complete folder. The choice lasts for the session; it is not a project setting.
It affects Midra transfers, not clipboard/file import or geometry export scopes.
To prepare several layouts that reuse the same device layers:
1. Put each layout in a folder and configure its saved screen/layer links through
**Midra mapping & transfer…**. Every row can still be remapped or unlinked.
2. Choose **Folder: …** in the status selector, or right-click a folder and choose
**Use folder for Midra transfers**.
3. Click **Send folder links**. Then click another folder name and send again:
Folder mode follows the clicked folder. Clicking a folder never sends by itself.
4. **Load folder links** reads fresh Preview geometry/cropping into that folder.
Loading requires visible, unlocked destinations and supports Undo.
Multiple editor layers may link to the same device destination, within or across
folders. Mapping shows a warning listing the other linked layers and their folders.
Sending is disabled when the chosen scope contains overlapping **screen + layer**
destinations, with a list of the conflicts. Choose a conflict-free folder or selection,
or remap/skip rows; links outside that send scope do not block it.
Linked send/load skip unlinked layers. An empty selection or missing folder never
falls back to All. Transfers already started retain the links captured at click time.
These are local geometry layouts, not device preset recalls or source-routing memories.
**Import layers from Midra** proposes unambiguous saved links within the scope.
Each row offers Skip or a scoped existing layer; All/Folder scopes also allow New layer. **Use saved links**
restores those suggestions; **Import unmapped as new layers** fills unused rows.
New layers join the chosen folder, and importing saves their reviewed screen/layer
links with the geometry as one Undo step. Existing layers keep their folder. Multiple
local copies of the same device layer can be updated together with linked Load;
the manual import dialog requires one unambiguous destination per device row.
## Midra connection and sending
Open **Midra connection…** in the main menu (also in **Settings → Midra integration**), enter the device IP, then **Connect**. The address saves automatically in the application config and survives project loads and restarts; startup connects automatically only if **Try autoconnecting at startup** is enabled in Settings → Midra integration.
Open **Import → Midra layers…** for the separate layer import window. **Refresh layers** reads a fresh snapshot; **Connection settings…** opens the connection window.
Choose a destination beside each device layer: existing layer, new layer, or skip.
Centered crops import visible bounds and framing; unsupported aspect/mask cases
are explained in the review. Imports are one undoable edit.
After connecting, open **Export → Midra mapping & transfer…**. Choose editor layers,
map each to a Midra layer, select **Preview** or **Program**, and select a container
strategy: **Output-sized** or **Source aspect**. Expand **Exact device changes** to
review sizes, centers, crop values and aspect, then click **Send mapped layers**.
The button is disabled while a send is in progress. Matching stored values can still be sent to apply staged geometry to hardware.
The source's native dimensions must match the destination's current content.
The target bank is fixed when configured. Sending starts immediately without a stale-state check. Writes are sequential;
partial failures require refreshing, not automatic retries or rollback. Success
means all changed fields matched device readback. There are no automatic sends
from edits, imports or undo. Closing the connection window does not cancel a send
already started; wait for its result before loading another project.
See [hardware checks and limitations](../device-check.md) and the
[device exchange contract](../../interfaces/midra-device-send.md). The footer's ONLINE
status reflects the last successful read, not continuous polling.
## Capture an input still from Midra
For a layer, open **Layer properties → Preview** (or right-click → **Input preview
& crop guides**):
1. Check **Enable input preview**.
2. Choose the physical input to preview. Inputs without signal are hidden by
default; **Show inputs without signal** inside the dropdown reveals them with
a **No signal** label. The same filter applies to the snapshot-import picker.
Signal indicators reflect the last connection refresh. This only chooses an image source; it
does not change Midra input routing or the editor's source-format identity.
3. Selecting an input captures a first still automatically and loads it straight
into this layer. It waits only for the shared five-second request throttle, not
the auto-refresh interval. Click **Capture still**, directly below the input
selector, to replace the still. Selecting a different input queues its first
capture too; rapid changes keep only the latest choice. The snapshot-import
picker also captures on selection, but still requires an explicit import.
4. Alternatively, enable **Auto-refresh this preview** below Capture. It fetches
the first image automatically and then updates it on the timer.
Auto-refresh is per layer. **Request interval** is shared across automatic
previews, defaults to 10 seconds and accepts 5–300 seconds. Visible automatic
previews refresh one input at a time; automatic previews sharing an input share
one fetched image. First captures queued for that same input also share the
result, even when selected while a request is running. One fetch serves all
waiting layers; existing stills with auto-refresh off remain unchanged.
Requests are serialized with a minimum five-second gap, including manual captures.
A failed refresh retains the last image; changing the input clears the previous
input's image. Disabling the preview hides it and pauses its refreshes.
**Crop guide opacity** defaults to 35% with an image; without an enabled image,
guides remain fully opaque and the slider is disabled. Selection handles stay
fully visible. Layer previews and timer settings are session-only. The timer
pauses offline and while the separate capture/import dialog is open. Reduced
snapshot resolution and freshness are controlled by the device. If snapshots
are disabled for an input, enable them in WebRCS and refresh the connection.
**Import → Import input snapshot…** opens a capture/import window (also available
from the reference-images context menu). Choose the physical input and a
**Destination**: any editor layer, or **Reference image**. No layer selection is
required. Capture and inspect the still, then click **Import into layer** or
**Add as reference**. Layer destinations offer **Keep refreshing this layer**
and the shared refresh interval. This starts timed updates after import; leaving
it off imports a fixed layer still. Selection and layer geometry are unchanged.
Reference images never offer auto-refresh: they are fixed screen guides embedded
in the project, with the usual size/aspect warnings. Cancel/close discards a pending
dialog capture; another request waits for completion or the 20-second timeout.
No capture action changes device settings or routing. See the
[input preview contract](../../interfaces/midra-input-preview.md).
Opening a project or restoring recovery now reads, validates and decodes embedded
references in a worker. The current editor stays intact until the whole project
is ready. Manual loading has a Cancel button; errors keep the old project.
Recovery autosave pauses while loading, including on exit.
In the opt-in **Layer properties → Source** section, **Editor input** offers Inputs 1–8 separately
from Midra screen/layer destinations. Use **New editor input** for additional
local identities, then **Apply source changes**. Layers sharing an editor input
share its source format and input crop. Assignments are saved in projects and
undoable; they do not change physical input routing.

View File

@ -0,0 +1,153 @@
# Layers and editing
[Midra Layout](../README.md) · [Guide contents](README.md) · [Starter files](../../templates/midra-layout/README.md)
## Layer folders
The Layers sidebar groups folder members under collapsible folder rows.
Click the chevron to expand/collapse; click the folder name to select its visible,
unlocked layers. Shift-click adds/removes its contents from the selection.
Double-click a folder or layer name to rename it. Folder eye and lock icons apply
to every member; Undo restores each member's previous state, including mixed states.
Select layers and choose **+ Folder…** to group them. Drag a layer onto a folder
name to move it inside, or onto **LAYERS** to return it to the root. Dropping on
another layer also changes stacking order and adopts that layer's folder.
Drag folder names above/below another folder to reorder all their layers as one
block. Right-click offers rename, selection, visibility, locking, moving up/down,
and **Ungroup folder** (keeps the layers). A layer's right-click **Move to folder**
menu also offers existing folders, the root, and a new folder.
Folders are local, single-level groups stored with their layers. Empty folders
are removed automatically; collapse state lasts for this session. The existing
**Manage…** window remains available for bulk name/folder editing. Grouping does
not affect device links or source assignments. All document edits support Undo.
## Move and edit layers
- Click a layer or its list entry to select it alone. **Shift-click** toggles that
layer in the selection. Selection does not change stacking. The top row of the layer list is the frontmost layer. In overlaps, the frontmost selectable
layer wins; the list lets you
reach the lower layer. Clicking empty canvas clears selection; Shift-clicking
empty canvas preserves it.
- **Left-drag on empty canvas** draws a selection box, selecting every rectangle
it intersects, in either drag direction. **Shift-drag on empty canvas** draws an additive box,
including when starting over a layer. Escape cancels the box and restores the
previous selection.
- Drag a selected layer to move the whole selection together; dragging an
unselected layer selects and moves it alone. Movement uses whole-screen-pixel
deltas and preserves fractional starting positions, sizes and relative spacing.
Drag a corner handle to resize that layer, or use the single-layer numeric fields.
- Arrow keys move the selection by **1 px**; Shift-arrow moves it by **10 px**.
- Under **Measure position from**, choose a corner or the center marker. Center offsets measure layer center from screen center (positive right/down); zero centers the layer. Switching reference changes the displayed
offsets without moving the layer. Position and size edits apply when you leave
a field or press Enter. Resizing preserves that
reference point's offsets. Invalid values leave the document unchanged.
- **Escape** cancels a drag or restores uncommitted numeric fields. In the paste
dialog it asks whether to Apply or Discard detected values. Group drags cancel atomically.
- The history toolbar icons (**Undo/Redo**) or Ctrl/Cmd-Z, Ctrl/Cmd-Shift-Z (also Ctrl/Cmd-Y) reverse
edits. Each drag, alignment, applied paste or numeric edit is one step; retain 100 undo
records. View changes and selection are not document edits.
- Scroll over the viewport to zoom around the pointer. Space-drag or middle-drag
pans. In the compact toolbar’s view group, **Fit screen** resets the view and
**Zoom to selection** frames the entire selection. A view warning appears only when a visible layer is completely out of view; select it in the layer list to frame it. The inspector separately flags layers partly or entirely beyond the output screen and suggests alignment or position edits. A divider separates view tools from Undo/Redo. Hover an icon for its label.
Camera changes do not modify coordinates. Off-screen layers retain their exact
coordinates, display a warning and remain selectable through the layer list.
- **Copy position values** (or **Copy selected positions** for multiple layers)
copies labeled plain text with each selected layer's center position and
dimensions. **Ctrl/Cmd-C** does the same when the viewport has focus. These
values can be pasted back using **Ctrl/Cmd-V** or **Paste layer(s) values**, with
the usual destination mapping and exact layer-count requirement. Center values
are converted back to top-left bounds; whole-pixel export rounding still applies
(an odd width/height can produce a half-pixel top-left). Source formats and crop
offsets are not copied. Crop zoom is included separately as a percentage and
can be toggled on paste. This is not a native WebRCS clipboard payload.
Right-click a layer for **Source properties**, **Layer properties**, **Crop properties**, **Preview properties**,
**Adjust layer crop**, alignment, **Copy layer values**, **Paste layer values**, and lock/hide actions.
Paste reads the clipboard and opens the existing value/mapping review before applying changes. Right-clicking a layer
already in a selection keeps the whole selection and offers **Resize together**.
Right-clicking an unselected layer selects it first. Locked/hidden layers remain
protected; use the layer list to unlock/show them. Right-click empty canvas for
**Output format**.
## Resize selected layers together
Select multiple layers, then choose **Same handles**, **Mirror horizontally**, or **Opposite handles** in the
right-hand inspector’s resize dropdown. Drag a corner or side handle on any
selected layer to scale the selection together. All three modes use **equal
proportional scaling**, not equal pixel additions: a 10% width increase applies
to every selected layer’s own width.
- **Same handles** uses the matching handle on every layer.
- **Mirror horizontally** requires exactly two layers. Left/right handles are
mirrored: bottom-right matches bottom-left, and top-right matches top-left.
Top and bottom midpoint handles remain top and bottom respectively.
- **Opposite handles** requires exactly two layers. The other layer uses the
opposite handle: right/left, top/bottom, and diagonally opposite corners
(bottom-right matches top-left). This was previously called Mirror resize.
- Each layer keeps the opposite edge or corner fixed. With aspect ratio locked,
both dimensions use the same scale; otherwise width and height scale
independently. Side handles affect only their axis when the ratio is unlocked.
- Minimum sizes constrain the shared scale. Invalid geometry rejects the whole
update. Crops adjust with sizing, and one Undo restores all layers and crops.
- The last resize mode stays selected for the session, including after selection
changes, Escape, Undo/Redo and project loads. A single selected layer resizes
individually; reselecting multiple layers reuses the chosen mode. Mirror and
Opposite still require exactly two layers. Choose **Resize: individual layer**
to change back explicitly. **Escape** cancels an active drag without resetting
the choice. Locking/hiding during a drag cancels the entire gesture.
## Align selected layers
Open the **Align selected layers** icon menu beside the view/history toolbar.
The **Align to** dropdown automatically uses **Screen (one selected layer)**
for a single layer and **Selected layers** (their combined bounds) for multiple
layers. Screen alignment uses the current output resolution.
It also lists **Layer 1: Presenter**, **Layer 2: Slides**, and any future layers.
An explicitly chosen reference layer takes precedence, stays fixed and does not
need to be selected. There is no separate Screen option for multi-selection.
In **Adjust layer crop** mode, alignment positions the zoomed content inside the
selected layer's visible box. Left/top/right/bottom align the corresponding
content edge to the box edge; center resets that axis's offset. Corners align both
axes in one Undo step. Zoom, source proportions and layer geometry stay fixed;
leaving crop mode restores normal layer alignment and its previous target.
The compact icon grid offers four corners, top/bottom/left/right edges, center
on both axes, and separate horizontal/vertical centering. The top-right button
centers horizontally (X); the bottom-right button centers vertically (Y). Edge buttons change
only their axis; corner buttons change both axes. Hover an icon for its label.
Every action preserves layer sizes and is one undo step, including corner moves.
The menu also works with one selected layer and a different reference layer.
The inspector lists each selected layer's resulting center coordinates; select
one layer for numeric size editing, or use a shared resize mode for the selection.
Paste/import accepts the full selection.
Text inputs receive normal text paste and arrow navigation while focused; they
never interpret these actions as geometry import or layer movement. Paste preview
identifies every destination explicitly and applies the mapped selection together.
## Layer management
Use **Layers → Manage layers & folders…** or **Manage…** above the inspector list.
Add layers, select one or more to remove, and edit names/folder labels. Names and folders commit on Enter or focus loss. These
changes support Undo/Redo; at least one layer must remain. Folder filtering helps
manage the list without changing stacking order. Lock/Show remain local, undoable flags.
Use each row’s **↑ / ↓** buttons in **Layers & folders** to reorder immediately,
or drag a layer name in the right-hand list and drop above/below another row.
A cyan line marks the drop position; Escape or releasing outside the list cancels.
Choose **All folders** to enable the manager’s reorder buttons. Hidden/locked
layers can be reordered without changing their flags. Each move is one Undo step;
pending names/folders follow their layer. The list reads front-to-back (top row on
top); saved arrays and SVG read back-to-front. Moving a row up brings it forward;
moving down sends it backward. Selection does not change stacking. Reordering never changes geometry, source assignments or Midra links,
and never sends to the device.
Stable IDs survive removal and are independent of Midra layer numbers. Group
movement, alignment and Same-handles resizing work across the selection;
Mirror/Opposite resizing still require exactly two layers.
Project JSON is version 10, with tested migration from older supported versions.
Every format’s **Selected layers…** action exports just the current selection,
including a single layer. All/visible export remains available.

View File

@ -0,0 +1,271 @@
# Import, export and project files
[Midra Layout](../README.md) · [Guide contents](README.md) · [Starter files](../../templates/midra-layout/README.md)
## Paste layer values and import geometry
1. Choose destinations using **Choose destination layers…** in the Import menu
or review window. Selecting them on the canvas or right-hand list also works
(Shift-click for multiple layers).
2. Copy layer values in Midra Layout or rectangles in draw.io, then press **Ctrl/Cmd-V** with the viewport
focused. Alternatively, click **Paste layer(s) values**, paste into the text
area and click **Read geometry**. **Import → Geometry file…** opens SVG, draw.io,
geometry JSON/CSV, DXF or HTML in the same review window; supported text can
also be pasted. **Import → Clipboard values**
reads the clipboard directly and opens the mapping review.
3. Review each detected rectangle and choose its destination layer. With nothing
selected, each rectangle's dropdown lists all editor layers (hidden/locked
destinations are disabled). Map the rectangles individually; no selection
step is required, and applying leaves the viewport selection unchanged. Initial
mapping follows document order and the selected layer list. Each rectangle must map to a different
destination (restricted to the selection when one exists). Fewer rectangles than selected layers are allowed;
unmapped layers stay unchanged. Too many rectangles or duplicate mappings
block Apply and explain what needs changing. Nothing changes yet.
4. Choose independently what to paste: **Format (width / height)**, **Position**,
and **Crop zoom**. Zoom is enabled only when present in the data (new Midra
clipboard values include it; older copies, draw.io and SVG do not). All
available values are initially enabled. Unchecked values retain destination
settings; format-only paste keeps its top-left position. Choose **Include
outline in bounds** if the layer should cover the rectangle's outline too.
Zoom applies to the resulting layer size; existing crop offsets clamp if
necessary. Mixed batches keep destination zoom where the source lacks it.
At least one available value must be enabled.
5. Click **Import mapped values** to update the entire selection in one undo step.
Cancel leaves all layers unchanged. Invalid geometry
blocks the whole batch, without partial changes.
The workspace supports 1–256 layers; the import review handles all selected
layers rather than choosing one rectangle from a larger clipboard selection.
### SVG bounds
SVG import accepts square-corner rectangles and simple closed rectangular
paths/polygons, including translated/scaled groups and inline styles. It applies
page dimensions and `viewBox` transforms, using CSS units at 96 px/in. Coordinates
are relative to the SVG page; exporting only a selection may lose its original
document position. The SVG is used for bounds, not rendered as a reference image.
A first full-page rectangle or image is marked as a possible background. Check
**Ignore full-page background** to exclude it from the count and mapping. This
is explicit: a full-page rectangle can also be a real layer. Image backgrounds
must be excluded; their contents and external links are never loaded.
Midra SVG v2 placeholder images import as one layer box each; their image content
is not decoded. Other visible artwork, rotation/skew, rounded rectangles, clipping, masks,
filters, stylesheets, and unsupported SVG features are refused with an error.
Hidden objects and definitions are ignored. Export simple rectangles with inline
styles for predictable results. Files are limited to 16 MiB, 256 rectangles plus an optional background, and
64 levels of nesting. SVG imports retain the same outline and position-only
choices as draw.io imports.
### draw.io clipboard
The draw.io adapter accepts single-page `.drawio`/`.xml` files (including native
compression) and raw or once-percent-encoded `mxGraphModel` clipboard XML, like
[the supplied clipboard fixture](../../../crates/midra-layout/tests/fixtures/drawio-rectangle.txt).
Draw.io coordinates map **1:1 to screen pixels**, with a top-left origin. This is
an explicit import convention; no page-scale, physical-unit or viewport-size
conversion is inferred. Missing X/Y means zero. Decimal dimensions are preserved.
The supplied example imports **X 12, Y 271, width 945, height 531.58**. The center
is **484.5, 536.79**. The visible box has its exact imported ratio; it is not rounded
or coerced into a 16:9 preset. “Format” here means the visible rectangle's width,
height and aspect, not native source format or advanced cropping.
**Include outline in bounds** is off by default on each paste. For an outline of
width `s`, enabling it subtracts `s/2` from X and Y and adds `s` to width and
height, preserving the center. This follows the half-stroke expansion in
[mxGraph's bounding-box calculation](https://github.com/jgraph/mxgraph/blob/master/javascript/src/js/shape/mxShape.js).
Your sample's 5 px outline gives **950 × 536.58 at (9.5, 268.5)**. Only the bounds
are imported; no border is drawn or configured on the device.
The option is disabled for position-only paste: that mode uses the original
geometry's top-left and keeps the target layer's dimensions. Zero-width,
`strokeColor=none`/`transparent`, zero stroke opacity and zero overall opacity
produce no outline expansion. A missing width uses the standard 1 px default;
the detected width is shown in the preview. Each rectangle in a multi-object
paste uses its own width. Shadows, sketch effects and raster antialiasing fringes
are not included. Invalid thickness/opacity values or bounds beyond the
application limits are rejected without changing the document.
The adapter otherwise ignores colors, text, style aspect locks and other
appearance settings. It currently rejects grouped/nested geometry, connections,
nonrectangular shapes, relative coordinates, alternate bounds, rotated/flipped
objects, named/inherited styles, wrapped objects and compressed `.drawio` files.
Mixed selections containing unsupported objects are rejected as a whole. Invalid
input makes no document changes. Text is limited to 16 MiB; geometry must have
finite coordinates within ±1,000,000 px and positive sizes up to 1,000,000 px.
These are application limits, not verified Eikos limits.
Draw.io also exposes raw page XML through **Extras → Edit Diagram**, as described
in its [source-editing documentation](https://www.drawio.com/docs/manual/advanced/diagram-source-edit/).
Support is based on the supplied clipboard data and regression fixtures; live
clipboard testing against a running draw.io instance remains to be done.
## Save, open and export
Use the **Project** toolbar menu to **Save project…** or **Open project…**.
Projects use readable, versioned `.midra.json` files and preserve applied output,
inputs, layer bounds/crops, source assignments, locks, visibility, selection,
viewport preferences, and all embedded reference images. Apply pending edits
before saving. Opening asks before replacing current work and starts a fresh
undo history. Existing files require confirmation before replacement.
The [starter-file catalog](../../templates/midra-layout/README.md) contains all nine
exchange formats, with two layers for 1920 × 1080 and 3840 × 2160 canvases.
**Project → Export → Export layers…** opens one shared window. Choose SVG,
draw.io, JSON, CSV, DXF, HTML, PPTX, Figma FIG or Illustrator AI, then
**Current layer…**,
**Selected layers…**, **Specific layer…**, **All layers…** and **Visible layers
only…**. A current-layer export keeps its original screen position and full-screen
canvas. The window offers **Include background layer**. SVG, draw.io, geometry
JSON, HTML, PPTX, FIG and AI also offer **Include placeholder pictures** with embedded source-grid
imagery; CSV and DXF explicitly disable pictures and carry rectangle geometry.
Import a supported format with **Import → Geometry file…** or paste its text, then
choose a slide/page/frame where applicable, then map detected layers to destinations.
PPTX uses 96 pixels per inch; FIG uses native pixels. AI requires a separately
installed `vectorcraft-cli`; its artboards appear in the same canvas selector.
Import/export runs in the background and reports conversion failures without
modifying the project. Backgrounds are automatically ignored;
placeholder images each count as one layer. draw.io files saved with compression
are supported. SVG rendered by draw.io Desktop is recognized through its retained
cell IDs; generated HTML labels and raster text fallbacks are ignored. Draw.io
may crop and rebase that SVG unless the exported diagram includes the background
layer. These exports round-trip whole-pixel visible-box geometry, not
source/crop settings; the separate `.midra.json` project format preserves the full project. See the
[geometry exchange contract and native draw.io checks](../../interfaces/midra-layout-exchange.md)
and [project save contract](../../interfaces/midra-layout.md).
Visual crop mode also provides **Reset crop** beside **Done adjusting crop** in
layer properties. It restores 100% content zoom and centered offsets, keeps the
visible box and source/input crop unchanged, and leaves visual editing active.
The reset is undoable.
The toolbar’s **Viewport options** cog contains **Keep aspect ratio when resizing**
and **Show source patterns on other layers while cropping**. Both apply immediately
and are preserved in saved projects. Crop editing always previews source content
and keeps its proportions, independently of these layer/view preferences.
The toolbar’s **Import** button uses a downward arrow into a tray. Hover for its
label; its dropdown contains SVG, clipboard values, and reference-image actions.
## Choose layers inside import and export menus
You can choose layers without returning to the viewport:
- **Import → Choose destination layers…**, and the same picker inside the
geometry review, select the destinations. Paste and file import can open
with nothing selected: map each detected rectangle directly to an available
layer using its destination dropdown. When using a selection, there must be at least as many chosen destinations as imported rectangles
after ignoring a background. Map to any subset of them; other layers stay
unchanged. Duplicate mappings and empty imports remain invalid.
- A format’s **Choose layers to export…** selects the group for
**Selected layers…**. **Specific layer…** remains available for individual layers,
including hidden layers.
- Midra send preparation has **Choose editor layers to send…**, followed by a
device-destination dropdown for each chosen layer. It can open online with
nothing selected. Sending requires explicit review and clicking **Send mapped layers**.
- Midra import retains its independent per-device-layer destinations, including
**New layer** and **Do not import**.
The shared pickers update the viewport selection. Hidden/locked layers are labeled
and disabled in these pickers; choosing layers changes no geometry. Full project
save/load and screen reference images are document-wide operations, so they have
no layer mapping.
**Midra mapping & transfer…**, beside ONLINE/OFFLINE and in **Export**, opens the Midra export configuration without sending, even when layers already have saved links. Choose layers, destination mappings, Preview/Program and sizing, then click **Send mapped layers** to send. The action is disabled offline or during transfers. Sending writes geometry, pulses the WebRCS preset-update command, and verifies geometry readback. Only applied editor values are sent.
Layer rows use padlock and eye icon buttons for locking and visibility, with tooltips and highlighted locked/hidden states. Double-click a layer name in the right-hand list to rename it. Enter saves, Escape or Cancel discards the edit; names must contain 1–128 characters. Renaming preserves the layer ID and folder and supports Undo.
Hold **Shift** while moving or resizing layers to snap to a **10 px grid**;
**Ctrl+Shift** uses a **100 px grid**. A matching selected grid tool is temporarily disabled instead; a different shortcut temporarily switches grid size. These grids override ordinary
pixel/edge snapping, even when snapping is disabled in Settings. **Alt**
overrides both grids and temporarily inverts ordinary snapping. The modifier state on release determines the final position.
Grid coordinates are screen pixels measured from the screen's top-left, independent
of viewport zoom. Group movement snaps the selection's bounding top-left and keeps
relative spacing. Resize snapping keeps opposite anchors and group proportions;
free corners snap both axes, while ratio-locked corners snap one driving axis.
Cyan guides mark reached grid lines. Numeric entry, crop-content gestures and camera
panning are unaffected. Shift-click still toggles selection; Shift-drag on a layer
moves it on the grid, and Shift-drag on empty canvas adds a selection box.
This replaces the previous Shift-to-invert-resize-snapping shortcut.
With snapping and layer-edge snapping enabled, resizing in **Mirror** mode snaps
the two moving inner edges into exact contact, including unequal-sized layers.
**Opposite** mode also supports vertical contact. A guide marks the meeting edge;
anchors and aspect-ratio settings are preserved. Move beyond the snap radius to
continue resizing, or hold Alt to temporarily invert snapping. Shift/Ctrl+Shift grid overrides remain.
Midra layer lists omit unassigned source slots (`NONE` or empty). Assigned inputs remain listed even if the layer is off. The exporter defaults to Preview and hides Program until **Settings → Midra integration → Allow sending to Program** is checked. This preference is saved automatically; turning it off returns the exporter and quick Apply action to Preview.
Destination choices in **Midra mapping & transfer…** now save immediately on the editor layer and support Undo. Save the project JSON to keep links across sessions. Links include screen and layer IDs and survive refreshes and selection changes. Choose the empty destination on the linked screen to unlink. The direct send button is available beside Midra mapping & transfer and in Export; in **All layers** scope it includes unselected, hidden and locked linked layers, grouped by screen. Its label changes to **Send selected links** or **Send folder links** in those scopes. Midra mapping & transfer… opens mapping configuration for the current scope. Preview/Program and sizing still use the current export options.
Every explicit send now includes WebRCS’s preset apply pulse (`xUpdate` false → true). This applies staged geometry when automatic updates are disabled, including a repeat send where WebRCS already shows the desired values.
**Send all linked layers** sends immediately using saved links and the current target and sizing settings, without opening the export window. The button shows progress and its tooltip reports completion. Invalid links or send failures open the export window with the error.
**Load linked layers**, beside the connection status and in Export, reads fresh
Midra Preview geometry and crop framing into linked editor layers in the shared
transfer scope. The default **All layers** ignores canvas selection; **Only selected
layers** and **Folder: …** explicitly restrict the operation. The load button inside
**Midra mapping & transfer…** uses that same scope and the saved links. Both actions are read-only
on the device and always load Preview (independent of the send target). They do
not recall device memories or presets. Loading is one atomic Undo step; links
remain saved. Missing screens/layers, mismatched output resolutions, unsupported
geometry, and hidden or locked editor destinations reject the complete import
without changing the document. Unlock/show destinations before loading. Results
appear in the transfer window or the load button's status tooltip. No project or
settings schema changes are involved.
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
**Midra mapping & transfer…** restores the first scoped 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.
### Recovery autosave and New project
Applied edits and reference images are checkpointed to `last_project.json`
beside the application settings, at most every two seconds between gestures and
again on normal exit. The last session resumes automatically on launch without
an Open dialog. Unchanged snapshots are not rewritten. Named project files remain
explicit saves (measurement-point autosave still updates its two fields).
**Project → New project…** starts the default layout after confirmation. The warning
shows the last recorded manual-save age; autosave does not count. Choose **Save and
create new…**, **Discard and create new**, or **Cancel**. Cancelling a save or a
failed save keeps the current project. Opening another project also replaces the
recovery copy, so save a named copy when you want to keep multiple projects.
Recovery contains applied project values, not undo history or unfinished text,
Source/import drafts. A crash can lose edits since the last checkpoint; normal
exit cancels unfinished canvas gestures. Project-menu status shows the recovery
path and failures. A corrupt/unsupported recovery file is preserved with autosave
paused; Retry recovery attempts to load it again. For a write failure, Retry
attempts to save again. New project explicitly replaces the recovery copy.
See the [recovery file contract](../../interfaces/midra-layout-recovery.md).
Right-click a layer in the viewport for **Rename layer…** / **Delete layer** alongside
the existing tools. Layer-list rows have a compact menu with just those two actions.
Actions target the clicked layer; deletion supports Undo and requires a visible,
unlocked layer with at least one other layer remaining.
In **Layer properties → Crop**, X/Y offsets are constrained to the valid range
for the current zoom, input dimensions and visible box. Typing or dragging beyond
an edge stops at that edge; reducing zoom clamps existing offsets to the new
bounds. An axis with no spare content stays at zero. These adjustments apply
immediately and support Undo without an offset-range error.
The tiled source pattern is hidden during normal layout editing, including when
loading saved projects/settings with source-pattern display enabled. Double-click
a layer or open its Crop properties to show its pattern and faded cropped overflow;
leaving crop editing hides them again. **Show source patterns on other layers
while cropping** optionally displays patterns on the other layers during that
mode only (except outline-only layers).

View File

@ -0,0 +1,161 @@
# Formats, crop and precision
[Midra Layout](../README.md) · [Guide contents](README.md) · [Starter files](../../templates/midra-layout/README.md)
## Formats and content framing
Open the **Output format** icon (screen with sliders), first in the toolbar, for HD (1280 × 720), Full HD (1920 × 1080), UHD 4K
(3840 × 2160), aspect presets or a custom whole-pixel resolution. Output/native
sizes support 1–16384 pixels per side as an implementation limit, not a promise
of hardware support. Layer positions/sizes remain unchanged; screen-corner
coordinates, alignment, reference-image mapping and warnings use the new output.
Valid output presets and numeric resolution edits apply immediately; invalid drafts
leave the output unchanged and are retained for correction.
The same window offers numeric camera zoom relative to fit-to-screen and a
**1:1 display pixels** action; camera changes never modify crop geometry.
Select one layer and click its **Layer resolution** card to open **Layer properties**:
1. Enable advanced editing in **Source**, choose a local **Editor input**, then its original **Source format** and native
dimensions. Editor inputs are planning identities, not device routing commands.
2. Set **Input resolution** to the usable size. Typing a custom size centers the
input crop; edit L/R/T/B for asymmetric placement. Crop edges stop at zero
when dragging; negative or non-finite typed/pasted values are not accepted. Native-size changes reset
the draft crop to the full source before review. A custom input retains the
original Source format, e.g. 16:9 native 1920 × 1080 cropped to 1920 × 1000.
3. Set **Layer resolution** to the final visible box. Use the aspect toggle to
enter an independent custom width and height. Layer changes apply immediately;
the selected measurement anchor stays fixed. Source/input changes require Apply.
4. Use **Layer crop / zoom & position** for zoom (100–10000%) and X/Y offsets in output pixels.
Zoom is bounded to 100–10000%; negative or non-finite entries are rejected.
X/Y offsets remain signed for left/up positioning; they are not crop amounts.
These controls operate on the applied formats and update immediately as edited.
A continuous zoom/offset drag is one Undo step;
**Recenter** preserves zoom; **Reset crop** returns to the minimum centered
cover crop. Invalid typed offsets show the permitted range and do not apply.
5. Click **Adjust layer crop** in the selected layer’s parameters, below its format
summary, or **double-click a layer on the canvas**, to drag or arrow-nudge
content inside the fixed box. The button
highlights while active; double-click again or click **Done adjusting crop** to leave the mode.
Drags clamp at valid crop boundaries; Escape cancels a drag and leaves this
mode. Wheel zoom still controls the camera. A source-coordinate test pattern
illustrates framing; it is deliberately separate from the screen reference.
While editing, cropped-out content appears at 50% opacity outside the box,
behind other layers. This preview stops at the usable input boundary; input
cropping remains excluded. The content inside the box stays fully opaque.
Grab the faded area to reframe content too; other visible layers covering it
take precedence. Empty space beyond the usable input is not draggable content.
Sources shared by both layers share the input crop. The dialog names affected
layers; each keeps its independent layer crop. Shared changes undo atomically,
and edits affecting a locked layer require it to be unlocked first.
Moving/alignment preserves crops. Resizing keeps content zoom and the retained
center where possible, automatically shifting the crop when needed to fit the
new size. Source/input changes do the same when applied in Layer properties.
No recentering or extra acceptance is needed. Undo restores both size and crop.
**Layer properties → Crop** activates visual crop editing while the tab is open.
Switching to Source/Layer or closing the window turns it off; no extra button is needed.
The standalone inspector and context-menu crop controls remain available.
**Adjust layer crop** changes the crop values inside the layer while keeping its
visible box fixed; **Reset crop** returns to the minimum centered crop.
**Calculated crops / provisional WebRCS mapping** shows input crops in native
pixels, advanced crops in usable-input pixels, combined retained native bounds,
visible size/center, and projected full-input geometry. These values are not a
verified device recipe: Centered-mode container behavior, crop units/limits and
quantization still require offline firmware verification. No hardware commands
are generated or sent. See [the resolution model](../resolutions.md)
for equations and worked examples.
## Display/export precision and midpoint handles
Geometry in the viewport, inspector and calculation view is shown to the nearest
0.1 pixel. Copied positions and provisional calculation exports use whole pixels
(round-half-away-from-zero). Internal geometry and crops retain full precision;
viewing/copying or applying unchanged rounded fields does not quantize the document.
This presentation rule does not validate the hardware's crop/container mapping.
Each selected box also has a handle at the middle of every side. Dragging top or
bottom resizes height with the opposite edge fixed; left or right does the same
for width. With the aspect lock enabled, the other dimension scales around its
center, keeping the opposite edge’s midpoint fixed. Disable it to change just
one axis. Corner handles still keep the
opposite corner fixed. Crop preservation, lock protection, Escape and Undo apply
to both kinds of resize handles.
Apply buttons are muted and disabled when their values already match the layout.
Pending changes make Apply solid purple. This applies to position/size, output
resolution drafts, source/input formats, names/folders, and mapped imports. Each
section tracks its own values; reverting an edit clears its pending state.
**Source is an advanced section**, disabled until **Edit advanced input settings
and include my edits when sending** is checked. Its device controls mirror the
linked Preview layer's current input and active plug in WebRCS Advanced Input:
content ratio, transform ratio, custom ratio, layer fill, input crop preset and
four pixel crop edges. Usually keep these settings on the Midra. Input crop
runs before dynamic layer crop/zoom without resizing the layer bounding box;
this is device processing, not an editor-only effect. Inputs are shared, so an
input edit can also affect other layers and Program.
Opening Source, checking the box, or changing a value does not send. Only fields
actually edited are staged for the next explicit Send, and only when that send
includes a destination routed to the same input/plug. Untouched aspect/crop
settings stay as they are on the machine. Unchecking discards staged edits.
The opt-in and device edits are session-only: disconnecting, changing the device
address or loading a project clears them. Source routing is never changed.
Refresh/load after sending to inspect the resulting device content dimensions.
The separately labeled **Editor source model (local geometry)** retains the
existing offline format/input-resolution calculations, also gated by the checkbox.
Its native dimensions are metadata, not device timing commands. Its local input
correction still folds into exported *layer* crop; it does not configure the
shared hardware input. Apply source changes commits this local model, whereas
the device controls above wait for Send.
Layer properties has five tabs: **Source** for native/input resolution and input
crop, **Layer** for the final visible box, **Crop** for content zoom and offset,
**Mapping** for the saved Midra screen/layer link, and **Preview** for capture, timed refresh, preview visibility, guide opacity and the cropped image preview. Editor input identity belongs to the opt-in **Source** tab.
The right-click properties entries open their matching tab directly.
Mapping offers device screen/layer selectors when connected, or numeric IDs offline.
Link edits apply locally immediately and support Undo. **Unmap** removes the link,
excluding the layer from linked sends and loads; it does not change the device.
Editor input identity remains a separate source setting requiring Apply.
Switching tabs retains pending Source edits, which require Apply. Layer size and
Crop changes apply immediately; each continuous drag is one Undo step.
Position/size edits commit on Enter or focus loss, output resolution changes
apply as edited, and names/folders commit on Enter or focus loss (also before
closing or changing the layer list). These controls have no Apply button.
Invalid geometry stays unchanged and errors appear inline. Closing output
settings discards invalid uncommitted values without a confirmation dialog.
Source edits remain staged; **Apply source changes** commits them. Closing with
pending Source edits, a rename, invalid batch names/folders, or mapped Midra
imports asks **Would you like to apply changes?**, with **Apply** and **Discard**.
Invalid Apply keeps the draft and error. Clipboard/SVG review uses **Import mapped
values**; Escape or clicking outside asks Apply/Discard, while Cancel discards.
Pending property/name edits temporarily disable the main workspace to preserve
the edited layer. Switching property tabs keeps pending Source edits.
Reference display, camera, theme and preference controls already apply immediately.
Device destination links also save to the local document immediately. Device
sends remain explicit: closing export configuration never sends, and local
Apply/Discard prompts never write to Midra. This does not change project save or
application-exit behavior. Applied edits recover automatically on launch; use Save project for a separate named copy.
While adjusting a layer crop, click empty canvas or another layer to leave crop
mode and select normally. Clicking or dragging the visible image or its faded
outside preview keeps crop mode active. Property controls remain usable while
editing the crop.
In visual crop mode, an accent-colored bounding box surrounds the full usable input image,
including the faded preview. Drag any corner or side midpoint to zoom the content
through cropping; the gold visible layer box stays fixed. Content always keeps
its proportions, independently of the layer resize ratio toggle. The opposite
content corner or edge stays anchored where possible; offsets clamp to keep the visible
box filled when zooming out. Zoom is limited to 100–10000%. Drag the image to pan
its content. Each zoom gesture is one undo step; Escape cancels an active gesture.
Use viewport zoom/pan to reach content handles beyond the current view.

View File

@ -0,0 +1,16 @@
# Viewport performance
[Midra Layout](../README.md) · [Guide contents](README.md) · [Starter files](../../templates/midra-layout/README.md)
## Viewport capacity check
Run the explicit headless timing check with:
```sh
cargo test --locked --release -p midra-layout --bin midra-layout viewport_capacity_timing -- --ignored --nocapture
```
On the development Linux host (2026-11-13), 256 visible layers at 1440×940
measured p50 **0.73 ms**, p95 **0.78 ms** across 100 frames after 20 warm-up frames.
This measures egui CPU frame construction, not GPU presentation, image decoding,
OS/DPI behavior or performance on an operator laptop. It is not a release gate.

View File

@ -0,0 +1,104 @@
# Menus and preferences
[Midra Layout](../README.md) · [Guide contents](README.md) · [Starter files](../../templates/midra-layout/README.md)
## Application menu
The header’s **Menu** brings the application’s commands together:
- **Project**: open/save JSON and export SVG.
- **Import**: SVG, clipboard layer values, and reference images.
- **Edit**: undo/redo, copy values, select all editable layers, or deselect.
- **View**: fit screen/selection, 1:1 pixels, output format, and reference settings.
- **Layers**: selected-layer properties, crop/reset, alignment, shared resizing,
lock/hide, and per-layer selection/visibility/lock controls.
- **Options**: resize aspect ratio and the source-coordinate preview.
The toolbar, cog and right-click shortcuts use the same commands and preferences.
Detailed numeric controls remain in their existing properties dialogs.
Enable **Options → Show toolbar icon names** (also available from the toolbar cog)
to display captions beneath the icons. It is off by default and saved with the
project; older projects open with captions off.
### Application themes
**Menu → Options → Theme** (also in the toolbar cog) shows up to three recently
used themes, newest first. **More themes…** opens the complete picker with color
swatches: Midra Dark plus all 18 themes from the SOTV song-database theme folder.
A fresh installation lists only Midra Dark until other themes are selected.
Selecting a theme updates the UI and viewport immediately and saves the recent
history across restarts. Reusing a theme moves it to the top without duplicates.
Closing the picker without choosing leaves the theme and history unchanged.
The viewport, grid, layer boxes and source test patterns use the selected palette;
selected layers remain gold (darker gold for contrast in light themes). Imported
reference images retain their colors. Theme and history survive opening projects
and are not included in project JSON or geometry exports.
The SOTV palettes are bundled with the app from
`sotv/song_database/styles/themes/` in the sibling `SOTV_Websites` repository;
Corporate Light uses `styles/base/variables.css`. No sibling repository is needed
to build or run Midra Layout. See the [theme catalog and settings contract](../../interfaces/midra-layout-settings.md)
for names, source files, stable IDs and palette adaptations.
### Saved application options
Options save automatically when changed: theme, toolbar icon names, aspect-ratio
lock and source-coordinate preview. No separate Apply or Save is needed.
The `directories` crate selects the OS configuration directory:
- Linux: `$XDG_CONFIG_HOME/midra-layout/settings.json`, or
`~/.config/midra-layout/settings.json` when XDG_CONFIG_HOME is unset.
- Windows: `%APPDATA%\beffroi\midra-layout\config\settings.json`.
- macOS: `~/Library/Application Support/org.beffroi.midra-layout/settings.json`.
Hover **Options save automatically** in Options to see the actual path. These are
startup defaults. Existing project files still restore their saved aspect-ratio,
caption and source-preview settings for the open document, without rewriting the
application defaults. A subsequent explicit Options change saves the current set
of options as the new defaults. Theme always remains an application preference.
Missing settings use defaults; the file is created on the first option change.
Unreadable, malformed or unsupported settings use defaults and show an Options
error; the original file is preserved and saving is disabled until the file is
repaired or moved and the application restarted. Write failures keep options
active in memory and offer **Retry saving options**. No project data, images or
clipboard contents are stored here. The [settings interface](../../interfaces/midra-layout-settings.md)
documents the file and compatibility rules.
**Keep aspect ratio when resizing** is also available below the position/size
fields in the selected layer's right panel and in the layer
right-click menu (including multiple selections). These controls share the
Options setting and save changes automatically. They do not apply or discard
pending size/position edits. Crop zoom remains proportional.
## Settings window
Open **Menu → Open all settings…**, **Options → Open all settings…**, the toolbar cog's
**Open all settings…** entry, or **Ctrl/Cmd+,**. The window groups the available controls:
- **Appearance:** themes, recent choices, icon captions and source-coordinate preview.
- **Editing:** aspect-ratio lock, movement snapping and a keyboard/mouse reference.
- **Reference images:** import and access to the current project's image settings.
- **Files & settings:** the settings-file path, copy-path action and restore defaults.
- **Midra integration:** current offline status and compatibility limitations.
Changes apply and save immediately, sharing state with quick menus and inspector
shortcuts. Close simply dismisses the window. Restore defaults resets preferences
without altering geometry or pending position/size edits. Device controls are not
presented as implemented until their mapping and transport are available.
### Movement snapping
The viewport right-click menu and quick Options menu both include **Snapping**:
enable movement/resizing snapping and choose pixel, screen or visible-layer edges.
These are the same automatically saved controls as Settings → Editing.
Enable **Settings → Editing → Snap movement & resizing** and choose pixel,
screen-edge and/or other-visible-layer-edge targets. Nearby edges show a guide;
the proximity radius stays six logical pixels at any zoom. A selection moves as
a rigid group. Hidden layers are ignored; visible locked layers can be targets.
Hold **Alt** to temporarily invert snapping: off when enabled, on when disabled. Turning snapping on/off alone never moves layers.
Exact numeric entry and nudges bypass proximity snapping; resize handles snap while preserving their anchors/ratios, and crop-content
handles retain their existing behavior. One drag remains one undo step, with Escape to cancel.

Binary file not shown.

After

Width:  |  Height:  |  Size: 124 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 151 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 169 KiB

View File

@ -0,0 +1,95 @@
# Updating the Midra Layout screenshots
[Midra Layout introduction](../README.md) · [Detailed user guide](../guide/README.md)
The introduction uses real application captures, not the design mockups in
`../design/`. Each image has an adjacent HTML comment in the introduction that
points to its recipe below.
## Capture provenance
Captured on **2026-11-14** from the default-feature debug build at source commit
`ba67f21`, on Linux/X11 (XFCE). The app's client area was **1440 × 940 pixels**,
at 100% display scaling, with the default dark theme. Screenshots are unedited
PNG captures of the app client area, without desktop decorations or the mouse
pointer. The original captures used ImageMagick `import -window <window-id>`;
a temporary Python `ctypes` helper located the isolated process's X11 window and
used XTest clicks to select the controls. The helper is not required to reproduce
the images: the same steps can be performed manually.
All images use the built-in example backdrop and the default **1920 × 1080**
project. No external artwork, saved user project or device connection was used.
The footer should read **OFFLINE**. No hardware reads or writes are needed.
## Prepare a clean session
From the repository root, build the current app and start it with temporary user
settings and recovery storage. Use a new temporary directory for each capture
session so that earlier recovery data does not replace the default layout.
```sh
cargo build --locked -p midra-layout
MIDRA_DOC_SESSION=$(mktemp -d /tmp/midra-layout-docs.XXXXXX)
XDG_CONFIG_HOME="$MIDRA_DOC_SESSION/config" \
XDG_DATA_HOME="$MIDRA_DOC_SESSION/data" \
target/debug/midra-layout
```
These isolation variables apply on Linux. On another platform, use an isolated
user profile or restore the same default project and theme before capturing.
Keep the default window size and 100% display scaling. The output canvas is
1920 × 1080; the two layers are **01 / Presenter** and **02 / Slides**, each
640 × 360. Select **01 / Presenter** in the Layers list. Do not move or resize it.
After each action, move the pointer into empty space below the canvas, without
clicking, and wait for the UI to settle. Clicking empty space clears selection.
Dismiss any notification or tooltip before capturing.
With ImageMagick, run the following in a second terminal and click the Midra
window to select it. Alternatively, use your desktop's “capture window” action
with the pointer and window border excluded.
```sh
import docs/midra-layout/images/01-workspace.png
```
For a known X11 client-window ID, the equivalent command is:
```sh
# Set MIDRA_DOC_WINDOW to the ID of this temporary Midra Layout window.
import -window "$MIDRA_DOC_WINDOW" docs/midra-layout/images/01-workspace.png
```
Capture each state below to its corresponding filename. Keep the full client
area; do not crop, add annotations, or substitute a mockup. Close the temporary
app after the last capture.
## 01-workspace.png
Start from the clean session with **01 / Presenter** selected and no menus or
dialogs open. Both layer boxes should be visible. The right inspector shows
640 × 360 dimensions and measurements from the top-right corner: 120 pixels
from the right and 180 pixels from the top. Capture the workspace.
## 02-layer-properties.png
From the workspace state, click the **640.0 × 360.0 px / 16:9** resolution field
in the right inspector. Keep the **Layer** tab selected in the Layer properties
window, with **Keep aspect when resizing** checked and the original width and
height unchanged. Do not move or resize the properties window. Capture it over
the canvas.
## 03-crop.png
From the Layer properties state, click the **Crop** tab. This activates visual
crop mode and displays the source pattern on the canvas. Leave the default
100% zoom and centered content unchanged. Capture the crop controls and preview.
Do not connect a device or import an input snapshot to reproduce this picture.
## Check the update
- Open all three PNGs and confirm the intended controls and layer labels are readable.
- Check that there are no tooltips, transient notifications, unrelated windows or private data.
- Preview the [introduction](../README.md) and keep its captions and image alt text consistent with the UI.
- Update the capture date, source commit and any changed steps in this file; keep the adjacent screenshot comments current.
- Commit the three PNGs and documentation changes together. Temporary settings and captures do not belong in Git.

View File

@ -6,7 +6,7 @@ original draft checklist: unchecked items below are actual remaining work,
not already implemented features awaiting a historical milestone.
The original visual proposals are retained below for design context.
The [user guide](README.md) describes current controls; the
The [user guide](guide/README.md) describes current controls; the
[device-send contract](../interfaces/midra-device-send.md) and
[hardware findings](device-check.md) distinguish automated tests,
device readback and physical-screen acceptance.

46
docs/templates/midra-layout/README.md vendored Normal file
View File

@ -0,0 +1,46 @@
# Midra Layout starter files
[Midra Layout](../../midra-layout/README.md) · [User guide](../../midra-layout/guide/README.md) · [Geometry format contract](../../interfaces/midra-layout-exchange.md)
This folder is the single source for the base files in every supported geometry
exchange format. Each file contains the same two named 16:9 layer boxes on an
exact pixel canvas, without backgrounds or placeholder pictures. The UHD layout
is an exact 2× scale of the Full HD layout.
Choose your canvas and format, download the file, then edit it in the matching
application or import it through **Import → Geometry file…** in Midra Layout.
Review the detected rectangles and their destination layers before applying.
| Format | Full HD · 1920 × 1080 | UHD 4K · 3840 × 2160 | Use with |
| --- | --- | --- | --- |
| SVG | [Download .svg](midra-layout-1080p-2-layers.svg) | [Download .svg](midra-layout-4k-2-layers.svg) | Vector editors and browsers |
| draw.io | [Download .drawio](midra-layout-1080p-2-layers.drawio) | [Download .drawio](midra-layout-4k-2-layers.drawio) | diagrams.net / draw.io |
| Geometry JSON | [Download .json](midra-layout-1080p-2-layers.json) | [Download .json](midra-layout-4k-2-layers.json) | Scripts and geometry exchange |
| Geometry CSV | [Download .csv](midra-layout-1080p-2-layers.csv) | [Download .csv](midra-layout-4k-2-layers.csv) | Spreadsheets and data tools |
| DXF | [Download .dxf](midra-layout-1080p-2-layers.dxf) | [Download .dxf](midra-layout-4k-2-layers.dxf) | CAD tools |
| HTML | [Download .html](midra-layout-1080p-2-layers.html) | [Download .html](midra-layout-4k-2-layers.html) | Browsers and web layouts |
| PowerPoint | [Download .pptx](midra-layout-1080p-2-layers.pptx) | [Download .pptx](midra-layout-4k-2-layers.pptx) | PowerPoint, LibreOffice Impress or DeckCraft |
| Figma FIG | [Download .fig](midra-layout-1080p-2-layers.fig) | [Download .fig](midra-layout-4k-2-layers.fig) | Figma or FigCraft |
| Illustrator AI | [Download .ai](midra-layout-1080p-2-layers.ai) | [Download .ai](midra-layout-4k-2-layers.ai) | Illustrator or VectorCraft |
## Geometry files and saved projects
These files exchange visible layer boxes. They do not store the complete editor
state, source assignments, crop settings or device links. In particular, the
`.json` starter is **geometry JSON**, not a saved Midra project. Use **Project →
Save project…** for a full `.midra.json` project; see the
[project format](../../interfaces/midra-layout.md). Versioned schema and migration
examples stay beside their [interface contracts](../../interfaces/README.md).
PPTX and FIG support uses the optional native codecs included in the default
build. Illustrator AI import/export requires a separately installed VectorCraft
CLI. See [dependencies and licensing builds](../../interfaces/midra-layout-exchange.md#optional-native-document-codecs-and-licensing-builds).
## Maintaining the base files
Keep all formats here and link to this catalog instead of copying files or
maintaining separate download lists. The [generation and verification commands](../../interfaces/midra-layout-exchange.md)
rebuild both canvas sizes with the application exporter and verify their geometry.
Text and native PPTX/FIG fixtures are covered by regression tests; the AI check
requires VectorCraft and is opt-in. The AI samples were checked with VectorCraft
0.24.1, not Adobe Illustrator.