beffroi-tools/docs/midra-layout.md

624 lines
38 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

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

# Midra Layout
A native Rust/egui workspace for positioning rectangular layers, with offline editing
and an explicit Eikos 4K device link.
Select layers, paste draw.io or import SVG geometry, move them visually or enter exact corner
positions and dimensions. Configure source/input formats and content framing;
visible-box coordinates and provisional crop calculations update together.
Connection reads and reviewed device sends happen only on request.
```sh
cargo run --locked -p midra-layout
```
## Paste layer values and import SVG
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 → SVG file…** opens an SVG file in the
same review window; raw SVG XML 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 **Apply 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.
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 1 MiB, 256 rectangles, and
64 levels of nesting. SVG imports retain the same outline and position-only
choices as draw.io imports.
### draw.io clipboard
The first adapter accepts raw or once-percent-encoded `mxGraphModel` 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 1 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.
## Move and edit layers
- Click a layer or its list entry to select it alone. **Shift-click** toggles that
layer in the selection. Selected layers appear in the foreground. 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** 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**.
- Choose one of the four corner markers. Switching corner changes the displayed
offsets without moving the layer. Enter offsets, width and height, then click
**Apply position / size** or press Enter in a field. Resizing preserves that
corner's offsets. Invalid values leave the document unchanged.
- **Escape** cancels a drag or restores uncommitted numeric fields. In the paste
dialog it closes the preview without applying it. 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
**Fit selected** frames the entire selection. 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**,
**Adjust layer crop**, alignment, copying values, and lock/hide actions. 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.
- **Escape** cancels an active drag and exits the mode. Choose **Resize: individual
layer** to return to normal handles; reducing the selection below two also
leaves group resize. 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.
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.
## Current limits
The document currently has two local rectangles and two source identities.
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 initial backdrop is illustrative; importing a reference picture replaces it.
Live video and verified hardware container/crop conversion remain future work.
Project JSON save/load and SVG geometry export are implemented (see below).
[Layer management and export scope](midra-layout-plan.md#11-later-stretch-goal-layer-management-and-export-scope)
are also later stretch goals: **Add layer**, Midra layer
mapping in **Options**, and device-targeted export of a **specific layer** or
**visible layers only**. SVG already supports all or visible layers. Optional folders would organize local layers. Visibility and organization
will not send commands or change the live device.
Applying layer format through the WebRCS REST API is a
[later stretch goal](midra-layout-plan.md#10-later-stretch-goal-apply-layer-format-through-the-webrcs-rest-api).
The currently connected Eikos is live: this work must remain offline, with no
device probing or commands. A future integration must preview changes and require
an explicit send action; local editing must never update the device automatically.
The displayed WebRCS values use the planned center-from-top-left convention.
Actual firmware coordinate limits, crop behavior and decimal acceptance are not
verified yet. Fractional values remain visible rather than silently rounded.
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](midra-layout-plan.md) and
[resolution/cropping specification](midra-layout-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 **Import** dropdown groups layer-value imports and screen references.
Layer imports require selected destinations. After importing a reference picture,
**Import → Reference settings…** opens its visibility, opacity and scaling controls.
Drop one PNG, JPEG or BMP into the window, or choose **Import → Reference image…**. 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 hide it, adjust opacity, replace it 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.
Files are limited to 64 MiB and dimensions to 8192 pixels per side or the GPU's
texture limit, whichever is smaller. Invalid imports keep the previous image.
Reference settings are session-only and independent of layer undo/redo.
### 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.
## 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.
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. Choose a local **Source identity** and its original **Source format** and native
dimensions. Input 1/2 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. 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. Apply source/input/layer changes
together; the selected screen-corner anchor stays fixed.
4. Use **Layer crop / zoom & position** for zoom (100–10000%) and X/Y offsets in output pixels.
These controls operate on the applied formats. **Apply crop** is one edit;
**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; 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.
**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](midra-layout-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, source/input/layer formats, crop framing, and mapped imports. Each
section tracks its own values; reverting an edit clears its pending state.
Layer properties has three tabs: **Source** for native/input resolution and input
crop, **Layer** for the final visible box, and **Crop** for content zoom and offset.
The three right-click properties entries open their matching tab directly.
Switching tabs retains pending edits. Source and Layer changes still apply together
with their shared Apply button; Crop has its own Apply button.
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.
## 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 the embedded reference image. Apply pending edits
before saving. Opening asks before replacing current work and starts a fresh
undo history. Existing files require confirmation before replacement.
**Project → Export → Export SVG** offers **All layers** and **Visible layers only**.
These exports contain whole-pixel layer boxes. Import them with **Import → SVG
file** and map the detected rectangles to the same number of selected layers.
SVG exchanges geometry; JSON preserves the complete project, including crops
and the reference image.
The [save/export interface specification](interfaces/midra-layout.md) documents
both formats, their limitations, validation, and compatibility policy, with a
[complete JSON example](interfaces/midra-layout-v1.example.json).
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-coordinate test pattern in viewport**. 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.
## 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 SVG 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 directly above
**Apply position / size** 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.
## Preferences window
Open **Menu → Preferences…**, **Options → Preferences…**, the toolbar cog's
**Preferences…** 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
Enable **Preferences → 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 bypass snapping. 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.
## Midra connection and sending
Open **Midra connection…** in the main menu (also in **Preferences → Midra integration**), enter the device IP, then **Connect**. The address saves automatically in the application config and survives project loads and restarts; startup does not connect automatically.
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 → Configure Midra export…**. 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 when the snapshot already matches or a send is in progress.
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](midra-layout-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.
## Layer management
Use **Layers → Manage layers & folders…** or **Manage…** above the inspector list.
Add layers, select one or more to remove, and apply names/folder labels. 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.
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 now version 4, with tested migration from versions 1–3.
**Project → Export → Export SVG → Selected layers…** exports just the current selection,
including a single layer. All/visible export remains available.
## 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.
Embedded reference decoding during project load remains synchronous.
Resize snapping now uses the same preference and Alt bypass 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.
SVG export 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.
## 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.
## 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
clipboard/SVG review, select the destinations. Paste and SVG 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 an SVG background. Map to any subset of them; other layers stay
unchanged. Duplicate mappings and empty imports remain invalid.
- **Project → Export → Export SVG → 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.
**Apply to Midra**, beside ONLINE/OFFLINE and in **Export**, sends the selected layers using the current destination mappings, screen, Preview/Program target and sizing strategy. If mapping is incomplete, it opens the send window first. Configure these choices in **Export → Configure Midra export…**. The action is disabled offline, during transfers, or when values already match the last snapshot. Sending writes directly and verifies readback; results appear in the send window. 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.