beffroi-tools/docs/midra-layout.md

58 KiB
Raw Blame History

Midra Layout

Application icon

A native Rust/egui workspace for positioning rectangular layers, with offline editing and an explicit Eikos 4K device link. Select layers, paste or import draw.io/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.

cargo run --locked -p midra-layout

Paste layer values and import SVG / draw.io

  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 / draw.io file… opens an SVG or draw.io file in the same review window; raw SVG/draw.io 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 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. 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. 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. 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. 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, 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.
  • 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.

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 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. 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 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. 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 and resolution/cropping specification 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.

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.

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.

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. 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. 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; 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 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.

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

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 / Export draw.io offers 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. Both menus offer Include background layer (visible reference or plain backdrop) and Include placeholder pictures (source-grid imagery reflecting cropping). Images are embedded and require no external files.

Import either format with Import → SVG / draw.io file… or paste its XML, then map detected layers to destinations. Backgrounds are automatically ignored; placeholder images each count as one layer. draw.io files saved with compression are supported. These exports round-trip whole-pixel visible-box geometry, not source/crop settings; JSON preserves the full project. See the geometry exchange contract and native draw.io checks and project save contract.

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.

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

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 → 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 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 and the device exchange contract. 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 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 9, with tested migration from older supported versions. 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 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.

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:

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 changes…, 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 Configure Midra export… 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. Send all linked layers is available beside Apply, in Export and in the send window; it includes unselected, hidden and locked linked layers, grouped by screen. Apply changes… opens configuration for the chosen layers. 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 all linked editor layers, regardless of selection. Apply changes… → Load mapped layers reads only the selected editor layers using the links chosen in that window. 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 Apply changes… or Configure Midra export… restores the first selected layer's available linked screen. Destination choices display both IDs. Browsing another screen does not retarget existing links; choosing a destination there explicitly replaces that layer's saved link. Direct send/load actions use each layer's saved screen, independently of the screen currently displayed in the configuration window.

Recovery autosave and New project

Applied edits and the reference image 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.

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