Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

All manuals

Midra Layout

Read the full manual →

Midra Layout icon

Midra Layout helps you prepare screen layouts for presentations and live events. Place video and slide layers on a canvas, check their sizes and positions, and frame their content before working with the screen processor. You can design offline, exchange geometry with drawing and presentation tools, and connect to an Analog Way Eikos 4K when you are ready to review and transfer a layout.

Quick start · Advanced guide · Starter files for all formats · Changelog

Start a layout

Run the desktop app from the repository root:

cargo run --locked -p midra-layout

A graphical desktop and a Rust build environment are required; see development setup. No device connection is needed for local editing.

A new project starts with a 1920 × 1080 canvas and two layers, Slides and Presenter. Select a layer on the canvas or in the list, drag it into place, and use its handles to resize it. Shift-click to select several layers; use Undo if you want to try a different arrangement.

The canvas shows the layout; the inspector gives exact dimensions and positions.

Position and organize layers

Enter exact pixel positions and dimensions in the inspector, or open Layer properties by clicking the layer-resolution field. Keep the aspect ratio locked when resizing, align layers, and group related layers in folders. Add more layers through Manage… in the Layers panel.

Use numeric controls for precise sizing, or work directly on the canvas.

See layers and editing for selection, alignment, folders and group resizing.

Frame content and use visual references

Open Layer properties → Crop to frame the source inside a layer. Crop editing keeps the visible layer box fixed while you adjust the content within it. You can also add reference images to the canvas to match an existing screen design.

Preview how the source fits inside the layer before transferring a layout.

See formats and crop and canvas and reference images for the detailed controls.

Save, exchange or send a layout

  • Save your work: use Project → Save project… for a .midra.json file that retains the full editor project.
  • Work with another application: drop a supported geometry file into the window, use Import → Geometry file…, or Project → Export → Export layers…. The starter-file catalog has matching Full HD and 4K files in SVG, draw.io, geometry JSON, CSV, DXF/DWG, HTML, PPTX, Figma FIG and Illustrator AI. It also lists format dependencies.
  • Use an Eikos 4K: connect, review layer mappings, then explicitly load or send the chosen layers. Ordinary editing does not send commands to the device. Follow the connection and transfer guide and its linked hardware-verification notes before using device writes.

For advanced workflows, start at the advanced guide. File schemas and compatibility rules are in the interface reference.

Screenshot capture and update instructions

All manuals

Quick start: your first layout

Introduction · Advanced guide · Starter files

Make a simple Slides + Presenter layout, save an editable project, and export its geometry. This walkthrough uses the default Full HD canvas and works offline; no screen processor is needed.

1. Open a fresh layout

Launch Midra Layout. To run from source, use this command from the repository root:

cargo run --locked -p midra-layout

See development setup if you need the build tools. If a previous layout was restored, save any work you want to keep, then choose Project → New project… and confirm.

The default canvas is 1920 × 1080, with Slides and Presenter layers. Leave that resolution unchanged for this walkthrough.

2. Place and size the layers

  1. Click Presenter in the Layers list or on the canvas.
  2. Drag the layer to position it. Drag a corner handle to resize it; keep Keep aspect ratio when resizing checked to preserve its proportions.
  3. For exact placement, use the inspector’s position fields. Check the selected measurement corner first: “From right” measures from the right edge, not the left.
  4. Select Slides and position it beside the presenter. Use Undo if a move or resize is not what you wanted.

The layer-resolution field opens Layer properties, where you can enter exact width and height. Leave the default sizes if you only want to try positioning.

3. Try framing the content

With Presenter selected, open Layer properties → Crop. The source pattern shows how content fits inside the visible layer box. Drag the content to adjust its position or use the crop handles to change its zoom.

The visible layer box stays fixed while cropping. Use Reset crop to return to the default framing, then switch back to the Layer tab to finish crop editing. You can skip this step if you only need rectangle positions.

4. Save the editable project

Apply any pending property edits, then choose Project → Save project… and save as first-layout.midra.json. This is the file to reopen when you want to continue editing: it retains the project, including source/crop settings and reference images.

Use Project → Open project… to load it later.

5. Export the layer geometry

Choose Project → Export → Export layers…, select SVG and All layers…, and save the export. For plain layer boxes, leave the background and placeholder pictures disabled. The SVG can be opened in a vector editor.

Keep the .midra.json project as well: a geometry export does not retain all editor settings. The starter-file catalog has matching layouts in every supported format if you prefer to start in another app.

Continue with the advanced guide

You now have an editable project and a geometry export. Choose your next task:

The advanced guide also links to settings, compatibility contracts and hardware-verification details.

All manuals

Midra Layout starter files

Midra Layout · User guide · Geometry format contract

This folder is the single source for the base files in every supported geometry exchange format. Each file contains the same two named 16:9 layer boxes on an exact pixel canvas, without backgrounds or placeholder pictures. The UHD layout is an exact 2× scale of the Full HD layout.

Choose your canvas and format, download the file, then edit it in the matching application or import it through Import → Geometry file… in Midra Layout. Review the detected rectangles and their destination layers before applying.

FormatFull HD · 1920 × 1080UHD 4K · 3840 × 2160Use with
SVGDownload .svgDownload .svgVector editors and browsers
draw.ioDownload .drawioDownload .drawiodiagrams.net / draw.io
Geometry JSONDownload .jsonDownload .jsonScripts and geometry exchange
Geometry CSVDownload .csvDownload .csvSpreadsheets and data tools
DXFDownload .dxfDownload .dxfCAD tools
DWGDownload .dwgDownload .dwgCAD tools; Craft bridge
HTMLDownload .htmlDownload .htmlBrowsers and web layouts
PowerPointDownload .pptxDownload .pptxPowerPoint, LibreOffice Impress or DeckCraft
Figma FIGDownload .figDownload .figFigma or FigCraft
Illustrator AIDownload .aiDownload .aiIllustrator or VectorCraft

Illustrator downloads in Gitea

Download both Illustrator templates as ZIP, then extract the .ai files. This avoids the browser’s PDF viewer changing the download extension. These AI files contain PDF-compatible artwork: Gitea detects the %PDF header and serves them as application/pdf with an inline disposition. It does not convert them. If you already downloaded the original bytes under a .pdf name, rename the extension to .ai; do not print or re-export from the PDF viewer.

The ZIP contains exact copies of the two AI samples. After updating them, rebuild it with python3 -m zipfile -c midra-layout-ai-templates.zip midra-layout-1080p-2-layers.ai midra-layout-4k-2-layers.ai from this folder.

Geometry files and saved projects

These files exchange visible layer boxes. They do not store the complete editor state, source assignments, crop settings or device links. In particular, the .json starter is geometry JSON, not a saved Midra project. Use Project → Save project… for a full .midra.json project; see the project format. Versioned schema and migration examples stay beside their interface contracts.

PPTX and FIG support uses the optional native codecs included in the default build. Illustrator AI import/export requires a separately installed VectorCraft CLI. See dependencies and licensing builds.

Maintaining the base files

Keep all formats here and link to this catalog instead of copying files or maintaining separate download lists. The generation and verification commands rebuild both canvas sizes with the application exporter and verify their geometry. Text and native PPTX/FIG/DWG fixtures are covered by regression tests; the AI check requires VectorCraft and is opt-in. The AI samples were checked with VectorCraft 0.24.1, not Adobe Illustrator.

The DXF and DWG samples were opened and rendered with QCAD Professional 3.28.2. Both formats were also saved as R21 (2007) in QCAD and reimported with unchanged layer coordinates. DXF and DWG carry unitless pixel geometry and no pictures.

All manuals

Midra Layout advanced guide

Introduction · Quick start: your first layout · Starter files · Changelog

Use this guide after the first-layout walkthrough, or jump directly to the detailed controls, workflows and limitations you need.

ChapterWhat it covers
Layers and editingSelect, move, resize, align, name, order and group layers
Canvas and reference imagesWorkspace defaults, view tools, guides, grid, reference pictures and positioning points
Formats, crop and precisionInput/output sizes, content framing, visual crop controls and numeric precision
Import, export and project filesClipboard mapping, geometry files, export scopes, saving and recovery
Menus and preferencesApplication menus, themes, saved settings and snapping
Midra connection and transfersConnection, reviewed device writes, folder layouts and input snapshots
Viewport performanceReproducing the headless capacity check and interpreting its results

Technical reference

These are ordinary Markdown chapters with relative links; no documentation build is required to browse them.

All manuals

Layers and editing

Midra Layout · Guide contents · Starter files

Layer folders

The Layers sidebar groups folder members under collapsible folder rows. Click the chevron to expand/collapse; click the folder name to select its visible, unlocked layers. Shift-click adds/removes its contents from the selection. Double-click a folder or layer name to rename it. Folder eye and lock icons apply to every member; Undo restores each member’s previous state, including mixed states.

Select layers and choose the Create folder icon to group them. Drag a layer onto a folder name to move it inside, or onto LAYERS to return it to the root. Dropping on another layer also changes stacking order and adopts that layer’s folder. Drag folder names above/below another folder to reorder all their layers as one block. Right-click offers rename, selection, visibility, locking, moving up/down, and Ungroup folder (keeps the layers). A layer’s right-click Move to folder menu also offers existing folders, the root, and a new folder.

Folders are local, single-level groups stored with their layers. Empty folders are removed automatically; collapse state lasts for this session. The existing Manage layers and folders remains available for bulk name/folder editing. Grouping does not affect device links or source assignments. All document edits support Undo.

Move and edit layers

  • Click a layer or its list entry to select it alone. Shift-click toggles that layer in the selection. Selection does not change stacking. The top row of the layer list is the frontmost layer. In overlaps, the frontmost selectable layer wins; the list lets you reach the lower layer. Clicking empty canvas clears selection; Shift-clicking empty canvas preserves it.
  • Left-drag on empty canvas draws a selection box, selecting every rectangle it intersects, in either drag direction. Shift-drag on empty canvas draws an additive box, including when starting over a layer. Escape cancels the box and restores the previous selection.
  • Drag a selected layer to move the whole selection together; dragging an unselected layer selects and moves it alone. Movement uses whole-screen-pixel deltas and preserves fractional starting positions, sizes and relative spacing. Drag a corner handle to resize that layer, or use the single-layer numeric fields.
  • Arrow keys move the selection by 1 px; Shift-arrow moves it by 10 px.
  • Under Measure position from, choose a corner or the center marker. Center offsets measure layer center from screen center (positive right/down); zero centers the layer. Switching reference changes the displayed offsets without moving the layer. Position and size edits apply when you leave a field or press Enter. Resizing preserves that reference point’s offsets. Invalid values leave the document unchanged.
  • Escape cancels a drag or restores uncommitted numeric fields. In the paste dialog it asks whether to Apply or Discard detected values. Group drags cancel atomically.
  • The history toolbar icons (Undo/Redo) or Ctrl/Cmd-Z, Ctrl/Cmd-Shift-Z (also Ctrl/Cmd-Y) reverse edits. Each drag, alignment, applied paste or numeric edit is one step; retain 100 undo records. View changes and selection are not document edits.
  • Scroll over the viewport to zoom around the pointer. Space-drag or middle-drag pans. In the compact toolbar’s view group, Fit screen resets the view and Zoom to selection frames the entire selection. A view warning appears only when a visible layer is completely out of view; select it in the layer list to frame it. The inspector separately flags layers partly or entirely beyond the output screen and suggests alignment or position edits. A divider separates view tools from Undo/Redo. Hover an icon for its label. Camera changes do not modify coordinates. Off-screen layers retain their exact coordinates, display a warning and remain selectable through the layer list.
  • Copy position values (or Copy selected positions for multiple layers) copies labeled plain text with each selected layer’s center position and dimensions. Ctrl/Cmd-C does the same when the viewport has focus. These values can be pasted back using Ctrl/Cmd-V or Paste layer(s) values, with the usual destination mapping and exact layer-count requirement. Center values are converted back to top-left bounds; whole-pixel export rounding still applies (an odd width/height can produce a half-pixel top-left). Source formats and crop offsets are not copied. Crop zoom is included separately as a percentage and can be toggled on paste. This is not a native WebRCS clipboard payload.

Right-click a layer for Source properties, Layer properties, Crop properties, Configure capture, Adjust layer crop, alignment, Copy layer values, Paste layer values, and lock/hide actions. Paste reads the clipboard and opens the existing value/mapping review before applying changes. Right-clicking a layer already in a selection keeps the whole selection and offers Resize together. Right-clicking an unselected layer selects it first. Locked/hidden layers remain protected; use the layer list to unlock/show them. Right-click empty canvas for Output format.

Resize selected layers together

Select multiple layers, then choose Same handles, Mirror horizontally, or Opposite handles in the right-hand inspector’s resize dropdown. Drag a corner or side handle on any selected layer to scale the selection together. All three modes use equal proportional scaling, not equal pixel additions: a 10% width increase applies to every selected layer’s own width.

  • Same handles uses the matching handle on every layer.
  • Mirror horizontally requires exactly two layers. Left/right handles are mirrored: bottom-right matches bottom-left, and top-right matches top-left. Top and bottom midpoint handles remain top and bottom respectively.
  • Opposite handles requires exactly two layers. The other layer uses the opposite handle: right/left, top/bottom, and diagonally opposite corners (bottom-right matches top-left). This was previously called Mirror resize.
  • Each layer keeps the opposite edge or corner fixed. With aspect ratio locked, both dimensions use the same scale; otherwise width and height scale independently. Side handles affect only their axis when the ratio is unlocked.
  • Minimum sizes constrain the shared scale. Invalid geometry rejects the whole update. Crops adjust with sizing, and one Undo restores all layers and crops.
  • The resize mode survives selection changes, Escape and Undo/Redo, and is saved with the project. Opening a project restores its saved resize mode. A single selected layer resizes individually; reselecting multiple layers reuses the chosen mode. Mirror and Opposite still require exactly two layers. Choose Resize: individual layer to change back explicitly. Escape cancels an active drag without resetting the choice. Locking/hiding during a drag cancels the entire gesture.

Align selected layers

Open the Align selected layers icon menu beside the view/history toolbar. The Align to dropdown automatically uses Screen (one selected layer) for a single layer and Selected layers (their combined bounds) for multiple layers. Screen alignment uses the current output resolution. It also lists Layer 1: Presenter, Layer 2: Slides, and any future layers. An explicitly chosen reference layer takes precedence, stays fixed and does not need to be selected. There is no separate Screen option for multi-selection.

In Adjust layer crop mode, alignment positions the zoomed content inside the selected layer’s visible box. Left/top/right/bottom align the corresponding content edge to the box edge; center resets that axis’s offset. Corners align both axes in one Undo step. Zoom, source proportions and layer geometry stay fixed; leaving crop mode restores normal layer alignment and its previous target.

The compact icon grid offers four corners, top/bottom/left/right edges, center on both axes, and separate horizontal/vertical centering. The top-right button centers horizontally (X); the bottom-right button centers vertically (Y). Edge buttons change only their axis; corner buttons change both axes. Hover an icon for its label. Every action preserves layer sizes and is one undo step, including corner moves. The menu also works with one selected layer and a different reference layer. The inspector lists each selected layer’s resulting center coordinates; select one layer for numeric size editing, or use a shared resize mode for the selection. Paste/import accepts the full selection.

Text inputs receive normal text paste and arrow navigation while focused; they never interpret these actions as geometry import or layer movement. Paste preview identifies every destination explicitly and applies the mapped selection together.

Layer management

Use Layers → Manage layers & folders… or the Manage layers and folders icon 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 11, with tested migration from older supported versions. Every format’s Selected layers… action exports just the current selection, including a single layer. All/visible export remains available.

All manuals

Canvas and reference images

Midra Layout · Guide contents · Starter files

Workspace defaults and limits

New projects start with two local rectangles and two source identities; you can add more layers and editor inputs. Output resolution defaults to 1920 × 1080 (16:9) and can be changed. The output dialog identifies standard aspect ratios from the current resolution; nonstandard ratios display as Custom. The example backdrop is titled Example Conference Name by default. Edit it under Options → Example backdrop or Settings → Reference images. Changes appear immediately and save with the project; leave it blank to hide the text, or use Reset example title. Up to 128 single-line characters are allowed. The title is clipped to the banner and appears only without an imported reference image, at any output resolution. It is not exported to SVG or sent to Midra.

The initial backdrop is illustrative and adapts to every output resolution/aspect ratio; importing a reference picture replaces it. Project save/load, ten-format geometry exchange, arbitrary layer collections, single-level folders and persistent Midra screen/layer links are implemented. File export offers current/specific/selected/all/visible scopes; device transfers use All/Selected/Folder. Organization never sends commands by itself.

The Midra connection and mapping/transfer UI supports explicit sends and loads, with both sizing strategies and Centered crop conversion readback-tested on Eikos 3.3.10. Program sending is enabled by a manual preference. Ordinary local editing does not send; linked send is a direct user action. Physical-output comparison, broader firmware coverage and non-Centered/masked conversion remain acceptance/backlog work. Visible-box center readouts are distinct from crop-corrected device containers. Internal precision is retained; views show one decimal and exports whole pixels.

The window can be resized; the screen keeps its aspect ratio, and the right inspector scrolls on shorter windows. Minimum size is 1000 × 720 logical points. A graphical desktop session is required to launch.

The Cargo workspace includes this crate in lint, tests, docs and coverage. Regression tests cover the supplied clipboard, malformed/unsupported input, corner conversion, group drag/undo, selection boxes, alignment targets, and GUI paste/focus behavior. Layer-list scrolling uses the wheel or scrollbar so dragging across list entries cannot accidentally scroll while selecting.

See the project plan 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 screen name and output resolution remain visible above the output when reference images are loaded; Fit screen includes room for both labels.

Imported images accumulate in a purple Reference images section below the layer list, newest/topmost first. Add image… and + Add… accept multiple files. Use each eye icon to show/hide a guide, the remove icon to delete it, or right-click Show only this reference to switch guides quickly. Double-click opens that image’s settings. Reference rows cannot be dragged, resized, aligned or sent to Midra; selecting one clears the editable-layer selection.

Removal is also available in Import → Remove reference image and the viewport context menu’s Reference images submenu, with a picker for the target image. Images remain fixed behind the layers; their existing explicit fit/opacity settings remain available. Visible images composite back-to-front. Saves and recovery retain all images and settings, while background-enabled exports flatten visible guides. Older single-image projects migrate automatically to the new v10 collection.

The Import dropdown groups layer-value imports and screen references. Layer imports offer destination mapping. After importing a reference picture, Import → Reference settings… opens its visibility, opacity and scaling controls.

Drop one or more PNG, JPEG or BMP images into the window, or choose Import → Add reference images…. The image is fixed behind the layers in screen coordinates; zooming and panning keep it aligned. Layer fills become translucent to reveal the image. Use the reference window to pick an imported image, hide it, adjust opacity or remove it.

Fill screen maps the entire image to the current output resolution. An exact pixel match needs no warning. Scaling up or down with matching proportions shows an amber warning; a different aspect ratio (such as 16:10) shows a red SEVERE WARNING because the image is distorted. Neither warning blocks importing or moving layers. Fit inside preserves proportions and centers the image with empty margins where needed; scaling still produces an amber warning.

Up to 32 images with a combined 64 MiB of file bytes can be stored; dimensions are limited to 8192 pixels per side or the GPU’s texture limit, whichever is smaller. Invalid imports keep all existing images. Reference images and settings are saved with the project; their edits are independent of layer undo/redo.

Optional independent positioning points

Measure position from normally uses matching screen/layer points, keeping the inspector compact. Enable Use a different measure point to reveal To layer point. The first selector is the screen origin; the second is the layer endpoint. For absolute center coordinates, choose screen Top left and layer Center.

Changing points or turning the toggle off only updates the displayed offsets. Numeric size and ratio edits keep the selected layer endpoint fixed. Screen-right and screen-bottom origins keep their existing inward-positive signs; screen center uses positive right/down. Both points and the toggle autosave immediately to the opened or last-saved project. Only these choices are written; other edits still need Save. For a new project, save it once to establish its file. Write failures keep the selection active and show an error. Older projects open with matched points. Canvas guides show the chosen endpoints.

Displaying and entering aspect ratios

Layer dimensions and resolution controls show their current width:height ratio (e.g. 16:9). A ratio field beside Keep aspect ratio when resizing accepts 16:9, 4/3, or a positive decimal such as 1.85. Press Enter or leave the field to commit. With the lock checked, width stays fixed and height changes, preserving the selected position reference (including center). Undo restores the geometry and crop together. Zero, negative, non-finite and out-of-range results are rejected.

With the lock unchecked, entering a ratio does not resize: it stays ready until the lock is enabled. The displayed current ratio still describes the actual sizes. Selecting another layer discards that prepared value. In Layer properties, manual ratios and presets resize immediately when locked, as do width/height edits. The Layer tab needs no Apply; pending Source edits still require their own Apply. Unapplied ratio text/targets are temporary UI state, not saved settings or a separate project constraint. Source content remains proportionally scaled.

Select, Move, Pan and Zoom tools

The toolbar’s Select, Move, Pan and Zoom icons are mutually exclusive and remain selected until another is chosen. V, M, H and Z select them when not typing in a field; hover the icons for help. Grid/Pivot toggle choices are retained independently.

  • Select (V): select, move, resize and marquee-select layers using the existing controls; crop editing remains available.
  • Move (M): drag anywhere to move the current selection without changing it or resizing. In crop mode, moves the selected layer’s content.
  • Pan (H): drag anywhere in the viewport to move the camera without editing layers or changing selection.
  • Zoom (Z): click to zoom in around the pointer, Alt-click to zoom out. Drag right to zoom in or left to zoom out, anchored at the gesture’s starting point.
  • Space-drag / middle-drag: temporarily pan from any tool. Scroll zoom works from every tool. Escape restores the camera if a pan/zoom drag is in progress.

Navigation tool choice survives selection changes and project loads in the current session; a new launch starts with Select. Pan/Zoom do not alter geometry, crop values or document history. Existing project saves still preserve zoom/pan values.

Persistent editing tools

The toolbar’s Snap ▾ dropdown groups the 10 px grid and 100 px grid icon toggles with the snapping options. Its label shows the effective grid, including modifier overrides. Pivot stays beside it as an independent toggle. Click again to turn a tool off. Only one grid can stay selected; Pivot can combine with either. A cyan outline marks the selected toggle; the fill shows its current effect, including temporary modifier changes. Tooltips explain the shortcuts. Icons wrap onto another row when the window is narrow.

Held modifierTemporary effect
Shift10 px grid; disables it if that grid is already selected
Ctrl+Shift100 px grid; disables it if that grid is already selected
Ctrl without ShiftInverts Pivot on/off
AltOverrides either grid and inverts ordinary snapping

A different grid shortcut temporarily replaces the selected grid. Ctrl+Shift does not invert Pivot, so a selected Pivot tool can combine with the 100 px grid. Releasing modifiers restores the selected tools, including during a drag. Tools stay selected across selection changes and project loads in this session; they are not saved to projects/settings and start off on launch. They affect layer movement/resize, not numeric edits or crop-content handles.

Overlay grid

The Grid toolbar icon opens Show overlay grid, Snap to overlay grid, and Columns / Rows controls (1–64 each, default 8 × 6). The grid is drawn above reference images and the sample artwork, below layers, across the full output. Subdivisions scale with the output resolution and can fall on fractional pixels.

Enable snapping in the magnet menu and Snap to overlay grid in the Grid menu to snap layer edges, centers, resize handles and pivots to these lines. Showing and snapping are independent; the 10/100 px modifier grids still take precedence. These options are saved in application preferences. The guide is not included in exports.

Ctrl resize pivot

With Pivot off, hold Ctrl (or select Pivot) to show a draggable crosshair on selected layers (center by default). Drag the marker to place it, including outside the layer; this changes only its saved pivot, not its geometry. Double-click the visible pivot to reset to center. Ctrl-drag a layer resize handle to resize around the fixed pivot. Ctrl can be pressed/released during the gesture; the result is recalculated from the starting geometry. With Pivot selected, Ctrl temporarily restores the normal opposite-edge anchor. Escape cancels a resize or restores the previous pivot placement.

Resize modePivot behavior
IndividualOnly the dragged layer resizes around its pivot
Same handlesPlacing a marker sets the same relative pivot on selected layers
Mirror horizontallyPlacing a marker reflects the partner’s pivot left/right
Opposite handlesPlacing a marker reflects the partner’s pivot on both axes

Dragging a pivot snaps within six logical display pixels of the layer’s four corners, four side midpoints and center, even with snapping disabled. Nearby local anchors win over a grid; elsewhere the active 10/100 px grid or enabled pixel/screen-edge/ visible-layer-edge options apply. Guides show reached anchors/edges/grid lines. Alt bypasses the nine built-in anchors and grids while retaining its usual inversion of configured snapping. Release uses the current modifiers.

Moving any marker updates the related markers as above. Changing selection or resize mode preserves stored points. Each layer’s own pivot stays fixed while resizing; unequal sizes retain proportional scaling. Aspect-ratio lock, snapping (including edge contact), Alt inversion and Undo still apply. A handle on the pivot’s axis cannot resize that axis; move the pivot or use another handle. Layers do not flip when dragged through the pivot; minimum sizes still apply. Ctrl+Shift remains the 100 px grid (or temporarily disables a selected 100 px grid); it uses pivot anchoring if Pivot is selected. Pivot positions are saved per layer in the project, survive selection changes and reopening, and follow layers when moved. Placement and reset support Undo/Redo. They do not affect numeric sizing. In Adjust layer crop mode, Ctrl/Pivot scales the image with its source pixel under the gravity point fixed; the visible layer box stays unchanged. Crop limits stop scaling before revealing empty space, including with outside pivots.

Resizing with corner handles

Drag a selected layer’s gold corner handles to resize it; the opposite corner stays fixed. Keep aspect ratio when resizing, above the viewport, is enabled by default. Clear it to adjust width and height independently against the reference picture. The same toggle links numeric width/height edits. Pasted dimensions remain exactly as supplied by the source.

Dragging a handle in a multiple selection selects and resizes only that layer. Sizes cannot flip or shrink below one pixel during dragging. Escape cancels; one Undo restores the complete resize. Locked or hidden layers cannot be resized.

Reference placement and loading

Reference settings now offer Native pixels, mapping each image pixel to one screen pixel at the screen’s top-left, plus X/Y offsets in screen pixels. Offsets also work with Fit/Stretch. The image is clipped to the output screen. Native mode does not scale or distort the image, so stretch warnings do not apply. Outline-only layers keeps the reference unobscured while retaining selection and resize handles; it is also available in viewport options. Crop editing still shows its source guide. Placement and outline mode are saved in project v4.

Picture import/drop reads and decodes off the UI thread, retaining the current reference until successful completion. Canceling/removing discards late results; failed replacements keep the current image. Decoder work is serialized to bound peak memory. Minification uses linear filtering, magnification nearest-neighbor. Project/recovery reads and embedded reference decoding also run in a worker; the editor is installed atomically after all images validate.

Resize snapping now uses the same preference and Alt inversion as movement snapping. It preserves opposite anchors, aspect ratio and group-resize proportions. Guides appear only when the resulting handle reaches the target; crop-content gestures remain unsnapped. At 2 logical pixels per screen pixel, adaptive coordinate rulers appear; at 8, a pixel grid appears. Guide drawing is limited to the visible region.

Every exchange format also offers Specific layer…, listing every local layer, including hidden/locked layers. Choosing one explicitly exports its geometry without changing visibility or selection. No device mapping or send is implied.

All manuals

Formats, crop and precision

Midra Layout · Guide contents · Starter files

Formats and content framing

Open the Output format icon (screen with sliders), first in the toolbar, for HD (1280 × 720), Full HD (1920 × 1080), UHD 4K (3840 × 2160), aspect presets or a custom whole-pixel resolution. Output/native sizes support 1–16384 pixels per side as an implementation limit, not a promise of hardware support. Layer positions/sizes remain unchanged; screen-corner coordinates, alignment, reference-image mapping and warnings use the new output. Valid output presets and numeric resolution edits apply immediately; invalid drafts leave the output unchanged and are retained for correction. The same window offers numeric camera zoom relative to fit-to-screen and a 1:1 display pixels action; camera changes never modify crop geometry.

Select one layer and click its Layer resolution card to open Layer properties:

  1. Enable advanced editing in Source, choose a local Editor input, then its original Source format and native dimensions. Editor inputs are planning identities, not device routing commands.
  2. Set Input resolution to the usable size. Typing a custom size centers the input crop; edit L/R/T/B for asymmetric placement. Crop edges stop at zero when dragging; negative or non-finite typed/pasted values are not accepted. Native-size changes reset the draft crop to the full source before review. A custom input retains the original Source format, e.g. 16:9 native 1920 × 1080 cropped to 1920 × 1000.
  3. Set Layer resolution to the final visible box. Use the aspect toggle to enter an independent custom width and height. Layer changes apply immediately; the selected measurement anchor stays fixed. Source/input changes require Apply.
  4. Use Layer crop / zoom & position for zoom (100–10000%) and X/Y offsets in output pixels. Zoom is bounded to 100–10000%; negative or non-finite entries are rejected. X/Y offsets remain signed for left/up positioning; they are not crop amounts. These controls operate on the applied formats and update immediately as edited. A continuous zoom/offset drag is one Undo step; Recenter preserves zoom; Reset crop returns to the minimum centered cover crop. Invalid typed offsets show the permitted range and do not apply.
  5. Click Adjust layer crop in the selected layer’s parameters, below its format summary, or double-click a layer on the canvas, to drag or arrow-nudge content inside the fixed box. The button highlights while active; double-click again or click Done adjusting crop to leave the mode. Drags clamp at valid crop boundaries; Escape cancels a drag and leaves this mode. Wheel zoom still controls the camera. A source-coordinate test pattern illustrates framing; it is deliberately separate from the screen reference. While editing, cropped-out content appears at 50% opacity outside the box, behind other layers. This preview stops at the usable input boundary; input cropping remains excluded. The content inside the box stays fully opaque. Grab the faded area to reframe content too; other visible layers covering it take precedence. Empty space beyond the usable input is not draggable content.

Sources shared by both layers share the input crop. The dialog names affected layers; each keeps its independent layer crop. Shared changes undo atomically, and edits affecting a locked layer require it to be unlocked first.

Moving/alignment preserves crops. Resizing keeps content zoom and the retained center where possible, automatically shifting the crop when needed to fit the new size. Source/input changes do the same when applied in Layer properties. No recentering or extra acceptance is needed. Undo restores both size and crop. Layer properties → Crop activates visual crop editing while the tab is open. Switching to Source/Layer or closing the window turns it off; no extra button is needed. The standalone inspector and context-menu crop controls remain available.

Adjust layer crop changes the crop values inside the layer while keeping its visible box fixed; Reset crop returns to the minimum centered crop.

Calculated crops / provisional WebRCS mapping shows input crops in native pixels, advanced crops in usable-input pixels, combined retained native bounds, visible size/center, and projected full-input geometry. These values are not a verified device recipe: Centered-mode container behavior, crop units/limits and quantization still require offline firmware verification. No hardware commands are generated or sent. See the resolution model for equations and worked examples.

Display/export precision and midpoint handles

Geometry in the viewport, inspector and calculation view is shown to the nearest 0.1 pixel. Copied positions and provisional calculation exports use whole pixels (round-half-away-from-zero). Internal geometry and crops retain full precision; viewing/copying or applying unchanged rounded fields does not quantize the document. This presentation rule does not validate the hardware’s crop/container mapping.

Each selected box also has a handle at the middle of every side. Dragging top or bottom resizes height with the opposite edge fixed; left or right does the same for width. With the aspect lock enabled, the other dimension scales around its center, keeping the opposite edge’s midpoint fixed. Disable it to change just one axis. Corner handles still keep the opposite corner fixed. Crop preservation, lock protection, Escape and Undo apply to both kinds of resize handles.

Apply buttons are muted and disabled when their values already match the layout. Pending changes make Apply solid purple. This applies to position/size, output resolution drafts, source/input formats, names/folders, and mapped imports. Each section tracks its own values; reverting an edit clears its pending state.

Source is an advanced section, disabled until Edit advanced input settings and include my edits when sending is checked. Its device controls mirror the linked Preview layer’s current input and active plug in WebRCS Advanced Input: content ratio, transform ratio, custom ratio, layer fill, input crop preset and four pixel crop edges. Usually keep these settings on the Midra. Input crop runs before dynamic layer crop/zoom without resizing the layer bounding box; this is device processing, not an editor-only effect. Inputs are shared, so an input edit can also affect other layers and Program.

Opening Source, checking the box, or changing a value does not send. Only fields actually edited are staged for the next explicit Send, and only when that send includes a destination routed to the same input/plug. Untouched aspect/crop settings stay as they are on the machine. Unchecking discards staged edits. The opt-in and device edits are session-only: disconnecting, changing the device address or loading a project clears them. Source routing is never changed. Refresh/load after sending to inspect the resulting device content dimensions.

The separately labeled Editor source model (local geometry) retains the existing offline format/input-resolution calculations, also gated by the checkbox. Its native dimensions are metadata, not device timing commands. Its local input correction still folds into exported layer crop; it does not configure the shared hardware input. Apply source changes commits this local model, whereas the device controls above wait for Send.

Layer properties has five tabs: Source for native/input resolution and input crop, Layer for the final visible box, Crop for content zoom and offset, Mapping for the saved Midra screen/layer link, and Preview for capture, timed refresh, preview visibility, guide opacity and the cropped image preview. Editor input identity belongs to the opt-in Source tab. The right-click properties entries open their matching tab directly. Mapping offers device screen/layer selectors when connected, or numeric IDs offline. Link edits apply locally immediately and support Undo. Unmap removes the link, excluding the layer from linked sends and loads; it does not change the device. Editor input identity remains a separate source setting requiring Apply. Switching tabs retains pending Source edits, which require Apply. Layer size and Crop changes apply immediately; each continuous drag is one Undo step.

Position/size edits commit on Enter or focus loss, output resolution changes apply as edited, and names/folders commit on Enter or focus loss (also before closing or changing the layer list). These controls have no Apply button. Invalid geometry stays unchanged and errors appear inline. Closing output settings discards invalid uncommitted values without a confirmation dialog.

Source edits remain staged; Apply source changes commits them. Closing with pending Source edits, a rename, invalid batch names/folders, or mapped Midra imports asks Would you like to apply changes?, with Apply and Discard. Invalid Apply keeps the draft and error. Clipboard/SVG review uses Import mapped values; Escape or clicking outside asks Apply/Discard, while Cancel discards. Pending property/name edits temporarily disable the main workspace to preserve the edited layer. Switching property tabs keeps pending Source edits.

Reference display, camera, theme and preference controls already apply immediately. Device destination links also save to the local document immediately. Device sends remain explicit: closing export configuration never sends, and local Apply/Discard prompts never write to Midra. This does not change project save or application-exit behavior. Applied edits recover automatically on launch; use Save project for a separate named copy.

While adjusting a layer crop, click empty canvas or another layer to leave crop mode and select normally. Clicking or dragging the visible image or its faded outside preview keeps crop mode active. Property controls remain usable while editing the crop.

In visual crop mode, an accent-colored bounding box surrounds the full usable input image, including the faded preview. Drag any corner or side midpoint to zoom the content through cropping; the gold visible layer box stays fixed. Content always keeps its proportions, independently of the layer resize ratio toggle. The opposite content corner or edge stays anchored where possible; offsets clamp to keep the visible box filled when zooming out. Zoom is limited to 100–10000%. Drag the image to pan its content. Each zoom gesture is one undo step; Escape cancels an active gesture. Use viewport zoom/pan to reach content handles beyond the current view.

All manuals

Import, export and project files

Midra Layout · Guide contents · Starter files

Paste layer values and import geometry

Drop SVG, draw.io/XML, geometry JSON/CSV, DXF/DWG, HTML, PPTX, FIG or AI files into the window to open the same geometry review as Import → Geometry file…. Native codecs still require their normal build options/dependencies. Filename extensions are case-insensitive; PNG/JPEG/BMP drops remain reference images. Multiple geometry files appear in the File / page / frame / slide chooser; choose one document/page to map at a time. Reading runs in the background, and nothing changes in the layout until Apply. The entire geometry drop is limited to 16 MiB; a failed document leaves the batch unapplied and reports its filename.

  1. Copy layer values or geometry and use Import → Clipboard values or Ctrl/Cmd-V with the viewport focused. Alternatively use Import → Geometry file… or drop a supported file. These entry points share one mapping review. If entering text manually, paste it and click Review pasted values.
  2. Once geometry is detected, the review only shows the loaded data, mapping and import options. Clipboard data is a collapsed, read-only preview; there are no additional file/paste buttons inside the review. Multiple documents/pages retain their page chooser.
  3. Under Destination layers, choose All layers, Selected layers, or Folder: …. Existing selection initially scopes and pre-maps the import; with no selection, choose destinations individually from All layers. Changing the scope never changes canvas selection and preserves mappings still in scope. Hidden/locked layers are excluded. Each source item has a prominent destination dropdown and collapsed Geometry · before / after details. Uncheck Include item to skip an item. Each included item must map to a different destination; fewer source items than destinations are fine. Duplicate or missing mappings block import. Other layers stay unchanged.
  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 mapped layers 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. Uncheck Include 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.

Save, open and export

Use the Project toolbar menu to Save project… or Open project…. Projects use readable, versioned .midra.json files and preserve applied output, inputs, layer bounds/crops, source assignments, locks, visibility, selection, viewport preferences, and all embedded reference images. Apply pending edits before saving. Opening asks before replacing current work and starts a fresh undo history. Existing files require confirmation before replacement.

The starter-file catalog contains all ten exchange formats, with two layers for 1920 × 1080 and 3840 × 2160 canvases.

Project → Export → Export layers… opens one shared window. Choose SVG, draw.io, JSON, CSV, DXF/DWG, HTML, PPTX, Figma FIG or Illustrator AI, then Current layer…, Selected layers…, Specific layer…, All layers… and Visible layers only…. A current-layer export keeps its original screen position and full-screen canvas. The window offers Include background layer. SVG, draw.io, geometry JSON, HTML, PPTX, FIG and AI also offer Include placeholder pictures with embedded source-grid imagery; CSV and DXF explicitly disable pictures and carry rectangle geometry.

Import a supported format with Import → Geometry file… or paste its text, then choose a slide/page/frame where applicable, then map detected layers to destinations. PPTX uses 96 pixels per inch; FIG uses native pixels. AI requires a separately installed vectorcraft-cli; its artboards appear in the same canvas selector. Import/export runs in the background and reports conversion failures without modifying the project. Backgrounds are automatically ignored; placeholder images each count as one layer. draw.io files saved with compression are supported. SVG rendered by draw.io Desktop is recognized through its retained cell IDs; generated HTML labels and raster text fallbacks are ignored. Draw.io may crop and rebase that SVG unless the exported diagram includes the background layer. These exports round-trip whole-pixel visible-box geometry, not source/crop settings; the separate .midra.json project format preserves the full project. See the geometry exchange contract and native draw.io checks 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.

Choose layers inside import and export menus

You can choose layers without returning to the viewport:

  • Import → Choose destination layers…, and the same picker inside the geometry review, select the destinations. Paste and file import can open with nothing selected: map each detected rectangle directly to an available layer using its destination dropdown. When using a selection, there must be at least as many chosen destinations as imported rectangles after ignoring a background. Map to any subset of them; other layers stay unchanged. Duplicate mappings and empty imports remain invalid.
  • A format’s Choose layers to export… selects the group for Selected layers…. Specific layer… remains available for individual layers, including hidden layers.
  • Midra send preparation has Choose editor layers to send…, followed by a device-destination dropdown for each chosen layer. It can open online with nothing selected. Sending requires explicit review and clicking Send mapped layers.
  • Midra import retains its independent per-device-layer destinations, including New layer and Do not import.

The shared pickers update the viewport selection. Hidden/locked layers are labeled and disabled in these pickers; choosing layers changes no geometry. Full project save/load and screen reference images are document-wide operations, so they have no layer mapping.

Midra mapping & transfer…, beside ONLINE/OFFLINE and in Export, opens the Midra export configuration without sending, even when layers already have saved links. Choose layers, destination mappings, Preview/Program and sizing, then click Send mapped layers to send. The action is disabled offline or during transfers. Sending writes geometry, pulses the WebRCS preset-update command, and verifies geometry readback. Only applied editor values are sent.

Layer rows use padlock and eye icon buttons for locking and visibility, with tooltips and highlighted locked/hidden states. Double-click a layer name in the right-hand list to rename it. Enter saves, Escape or Cancel discards the edit; names must contain 1–128 characters. Renaming preserves the layer ID and folder and supports Undo.

Hold Shift while moving or resizing layers to snap to a 10 px grid; Ctrl+Shift uses a 100 px grid. A matching selected grid tool is temporarily disabled instead; a different shortcut temporarily switches grid size. These grids override ordinary pixel/edge snapping, even when snapping is disabled in Settings. Alt overrides both grids and temporarily inverts ordinary snapping. The modifier state on release determines the final position. Grid coordinates are screen pixels measured from the screen’s top-left, independent of viewport zoom. Group movement snaps the selection’s bounding top-left and keeps relative spacing. Resize snapping keeps opposite anchors and group proportions; free corners snap both axes, while ratio-locked corners snap one driving axis. Cyan guides mark reached grid lines. Numeric entry, crop-content gestures and camera panning are unaffected. Shift-click still toggles selection; Shift-drag on a layer moves it on the grid, and Shift-drag on empty canvas adds a selection box. This replaces the previous Shift-to-invert-resize-snapping shortcut.

With snapping and layer-edge snapping enabled, resizing in Mirror mode snaps the two moving inner edges into exact contact, including unequal-sized layers. Opposite mode also supports vertical contact. A guide marks the meeting edge; anchors and aspect-ratio settings are preserved. Move beyond the snap radius to continue resizing, or hold Alt to temporarily invert snapping. Shift/Ctrl+Shift grid overrides remain.

Midra layer lists omit unassigned source slots (NONE or empty). Assigned inputs remain listed even if the layer is off. The exporter defaults to Preview and hides Program until Settings → Midra integration → Allow sending to Program is checked. This preference is saved automatically; turning it off returns the exporter and quick Apply action to Preview.

Destination choices in Midra mapping & transfer… now save immediately on the editor layer and support Undo. Save the project JSON to keep links across sessions. Links include screen and layer IDs and survive refreshes and selection changes. Choose the empty destination on the linked screen to unlink. The direct send button is available beside Midra mapping & transfer and in Export; in All layers scope it includes unselected, hidden and locked linked layers, grouped by screen. Its label changes to Send selected links or Send folder links in those scopes. Midra mapping & transfer… opens mapping configuration for the current scope. Preview/Program and sizing still use the current export options.

Every explicit send now includes WebRCS’s preset apply pulse (xUpdate false → true). This applies staged geometry when automatic updates are disabled, including a repeat send where WebRCS already shows the desired values.

Send all linked layers sends immediately using saved links and the current target and sizing settings, without opening the export window. The button shows progress and its tooltip reports completion. Invalid links or send failures open the export window with the error.

Load linked layers, beside the connection status and in Export, reads fresh Midra Preview geometry and crop framing into linked editor layers in the shared transfer scope. The default All layers ignores canvas selection; Only selected layers and Folder: … explicitly restrict the operation. The load button inside Midra mapping & transfer… uses that same scope and the saved links. Both actions are read-only on the device and always load Preview (independent of the send target). They do not recall device memories or presets. Loading is one atomic Undo step; links remain saved. Missing screens/layers, mismatched output resolutions, unsupported geometry, and hidden or locked editor destinations reject the complete import without changing the document. Unlock/show destinations before loading. Results appear in the transfer window or the load button’s status tooltip. No project or settings schema changes are involved.

Midra destinations are identified by the pair screen ID + layer ID: Screen 1 Layer 1 and Screen 2 Layer 1 are distinct links. Both IDs are already persisted in project version 5; no schema change is needed. Opening Midra mapping & transfer… or Midra mapping & transfer… restores the first scoped layer’s available linked screen. Destination choices display both IDs. Browsing another screen does not retarget existing links; choosing a destination there explicitly replaces that layer’s saved link. Direct send/load actions use each layer’s saved screen, independently of the screen currently displayed in the configuration window.

Recovery autosave and New project

Applied edits and reference images are checkpointed to last_project.json beside the application settings, at most every two seconds between gestures and again on normal exit. The last session resumes automatically on launch without an Open dialog. Unchanged snapshots are not rewritten. Named project files remain explicit saves (measurement-point autosave still updates its two fields).

Project → New project… starts the default layout after confirmation. The warning shows the last recorded manual-save age; autosave does not count. Choose Save and create new…, Discard and create new, or Cancel. Cancelling a save or a failed save keeps the current project. Opening another project also replaces the recovery copy, so save a named copy when you want to keep multiple projects.

Recovery contains applied project values, not undo history or unfinished text, Source/import drafts. A crash can lose edits since the last checkpoint; normal exit cancels unfinished canvas gestures. Successful restoration is silent. Recovery failures still display an actionable message. 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).

What the project saves

Project JSON includes source formats, both crop stages, geometry, layer ordering, folders, visibility/locking, pivots, Midra links, reference images, selection, viewport and positioning settings. It also saves snapping/grid settings, group resize mode, collapsed folders, capture input assignments, the last captured stills, guide opacity and refresh settings. Saved stills work offline; automatic refresh reopens paused until you capture or resume it explicitly.

Connection history, startup connection, theme and Program permission remain in application preferences. Unsaved drafts, undo history, open menus, active editing gestures and pending device operations are temporary. Transfer scope, target bank, sizing strategy and opt-in advanced device input edits remain session choices. See the complete persistence audit and versioned project contract.

All manuals

Menus and preferences

Midra Layout · Guide contents · Starter files

Application menu

The header’s Menu brings the application’s commands together:

  • Project: open/save JSON and export SVG.
  • Import: SVG, clipboard layer values, and reference images.
  • Edit: undo/redo, copy values, select all editable layers, or deselect.
  • View: fit screen/selection, 1:1 pixels, output format, and reference settings.
  • Layers: selected-layer properties, crop/reset, alignment, shared resizing, lock/hide, and per-layer selection/visibility/lock controls.
  • Options: resize aspect ratio and the source-coordinate preview.

The toolbar, cog and right-click shortcuts use the same commands and preferences. Detailed numeric controls remain in their existing properties dialogs.

Enable Options → Show toolbar icon names (also available from the toolbar cog) to display captions beneath the icons. It is off by default and saved with the project; older projects open with captions off.

Application themes

Menu → Options → Theme (also in the toolbar cog) shows up to three recently used themes, newest first. More themes… opens the complete picker with color swatches: Midra Dark plus all 18 themes from the SOTV song-database theme folder. A fresh installation lists only Midra Dark until other themes are selected. Selecting a theme updates the UI and viewport immediately and saves the recent history across restarts. Reusing a theme moves it to the top without duplicates. Closing the picker without choosing leaves the theme and history unchanged.

The viewport, grid, layer boxes and source test patterns use the selected palette; selected layers remain gold (darker gold for contrast in light themes). Imported reference images retain their colors. Theme and history survive opening projects and are not included in project JSON or geometry exports.

The SOTV palettes are bundled with the app from sotv/song_database/styles/themes/ in the sibling SOTV_Websites repository; Corporate Light uses styles/base/variables.css. No sibling repository is needed to build or run Midra Layout. See the theme catalog and settings contract 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.

All manuals

Midra connection and transfers

Midra Layout · Guide contents · Starter files

Connect a device or emulator

Enter an IP address in Device IP / port, optionally followed by a TCP port: 192.168.10.146:3000. Without a port, the app uses port 80. IPv6 addresses with a port use brackets, for example [::1]:3000. Omit URL schemes and paths. The same address is saved in preferences and used for reads, input snapshots, automatic reconnect and WebSocket sends.

Use Recent machines… to switch to one of the last four successful connections. Choosing an entry connects immediately to read its state; it does not send layers. History survives restarts, retains custom ports and excludes failed attempts.

The adapter accepts Eikos 4K, Pulse 4K, QuickVu 4K and QuickMatrix 4K and reads screen sizes and allocated layer counts from the device instead of assuming Eikos’s configuration. This covers the Midra 4K family, not earlier Midra products or the separate LivePremier/Alta families. Required firmware fields are still validated. Eikos 4K hardware and a Pulse 4K 3.3.7 emulator have been read successfully; QuickVu/QuickMatrix have parser regression coverage but still need individual emulator/hardware acceptance.

Use folders as local Midra layouts

The Midra Apply to selector is shared by the status bar, Export menu, and send/import windows. It starts at All layers, regardless of canvas selection. Choose Only selected layers for an explicit selection filter, or Folder: … for a complete folder. The choice lasts for the session; it is not a project setting. It affects Midra transfers, not clipboard/file import or geometry export scopes.

To prepare several layouts that reuse the same device layers:

  1. Put each layout in a folder and configure its saved screen/layer links through Midra mapping & transfer…. Every row can still be remapped or unlinked.
  2. Choose Folder: … in the status selector, or right-click a folder and choose Use folder for Midra transfers.
  3. Click Send folder links. Then click another folder name and send again: Folder mode follows the clicked folder. Clicking a folder never sends by itself.
  4. Load folder links reads fresh Preview geometry/cropping into that folder. Loading requires visible, unlocked destinations and supports Undo.

Multiple editor layers may link to the same device destination, within or across folders. Mapping shows a warning listing the other linked layers and their folders. Sending is disabled when the chosen scope contains overlapping screen + layer destinations, with a list of the conflicts. Choose a conflict-free folder or selection, or remap/skip rows; links outside that send scope do not block it. Linked send/load skip unlinked layers. An empty selection or missing folder never falls back to All. Transfers already started retain the links captured at click time. These are local geometry layouts, not device preset recalls or source-routing memories.

Import layers from Midra proposes unambiguous saved links within the scope. Each row offers Skip or a scoped existing layer; All/Folder scopes also allow New layer. Use saved links restores those suggestions; Import unmapped as new layers fills unused rows. New layers join the chosen folder, and importing saves their reviewed screen/layer links with the geometry as one Undo step. Existing layers keep their folder. Multiple local copies of the same device layer can be updated together with linked Load; the manual import dialog requires one unambiguous destination per device row.

Midra connection and sending

Open Midra connection… in the main menu (also in Settings → Midra integration), enter the device IP, then Connect. The address saves automatically in the application config and survives project loads and restarts; startup connects automatically only if Try autoconnecting at startup is enabled in Settings → Midra integration.

Open Import → Midra layers… for the separate layer import window. Refresh layers reads a fresh snapshot; Connection settings… opens the connection window. Choose a destination beside each device layer: existing layer, new layer, or skip. Centered crops import visible bounds and framing; unsupported aspect/mask cases are explained in the review. Imports are one undoable edit.

After connecting, open Export → Midra mapping & transfer…. Choose editor layers, map each to a Midra layer, select Preview or Program, and select a container strategy: Output-sized or Source aspect. Expand Exact device changes to review sizes, centers, crop values and aspect, then click Send mapped layers. The final row groups Load linked layers (down arrow, device to editor) and Send mapped layers (up arrow, editor to device); the Load label follows the selected transfer scope. 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.

Capture an input still from Midra

For a layer, open Layer properties → Preview (or right-click → Configure capture…):

When a connection or layer load completes, linked layers preselect their assigned physical input if available. This does not enable previews or request an image, and existing capture choices are preserved. Click Capture still when ready, or explicitly enable auto-refresh. Inputs without signal can still be preselected.

  1. Check Enable input preview.
  2. Choose the physical input to preview. Inputs without signal are hidden by default; Show inputs without signal inside the dropdown reveals them with a No signal label. The same filter applies to the snapshot-import picker. Signal indicators reflect the last connection refresh. This only chooses an image source; it does not change Midra input routing or the editor’s source-format identity.
  3. Selecting an input captures a first still automatically and loads it straight into this layer. It waits only for the shared five-second request throttle, not the auto-refresh interval. Click Capture still, directly below the input selector, to replace the still. Selecting a different input queues its first capture too; rapid changes keep only the latest choice. The snapshot-import picker also captures on selection, but still requires an explicit import.
  4. Alternatively, enable Auto-refresh this preview below Capture. It fetches the first image automatically and then updates it on the timer.

Auto-refresh is per layer. Request interval is shared across automatic previews, defaults to 10 seconds and accepts 5–300 seconds. Visible automatic previews refresh one input at a time; automatic previews sharing an input share one fetched image. First captures queued for that same input also share the result, even when selected while a request is running. One fetch serves all waiting layers; existing stills with auto-refresh off remain unchanged. Requests are serialized with a minimum five-second gap, including manual captures. A failed refresh retains the last image; changing the input clears the previous input’s image. Disabling the preview hides it and pauses its refreshes.

Crop guide opacity defaults to 35% with an image; without an enabled image, guides remain fully opaque and the slider is disabled. Selection handles stay fully visible. Layer previews, captured stills and timer settings are saved in the project. Saved auto-refresh reopens paused: use Resume auto-refresh or Capture still to resume. Opening a project does not fetch images. The timer pauses offline and while the separate capture/import dialog is open. Reduced snapshot resolution and freshness are controlled by the device. If snapshots are disabled for an input, enable them in WebRCS and refresh the connection.

Import → Import input snapshot… opens a capture/import window (also available from the reference-images context menu). Choose the physical input and a Destination: any editor layer, or Reference image. No layer selection is required. Capture and inspect the still, then click Import into layer or Add as reference. Layer destinations offer Keep refreshing this layer and the shared refresh interval. This starts timed updates after import; leaving it off imports a fixed layer still. Selection and layer geometry are unchanged.

Reference images never offer auto-refresh: they are fixed screen guides embedded in the project, with the usual size/aspect warnings. Cancel/close discards a pending dialog capture; another request waits for completion or the 20-second timeout. No capture action changes device settings or routing. See the input preview contract.

Opening a project or restoring recovery now reads, validates and decodes embedded references in a worker. The current editor stays intact until the whole project is ready. Manual loading has a Cancel button; errors keep the old project. Recovery autosave pauses while loading, including on exit.

In the opt-in Layer properties → Source section, Editor input offers Inputs 1–8 separately from Midra screen/layer destinations. Use New editor input for additional local identities, then Apply source changes. Layers sharing an editor input share its source format and input crop. Assignments are saved in projects and undoable; they do not change physical input routing.

All manuals

Midra formats, resolutions and advanced cropping

Status: offline geometry and UI implemented. Source/native formats, shared input cropping, virtual layer resolution, content zoom/offset, content dragging, dynamic output resolution, reference remapping and atomic undo are available. Crops are authoritative; zoom/offset are derived controls. Hardware container behavior, firmware crop limits and quantization remain unverified and are never presented as a validated device recipe. No REST calls are made.

Implementation limits: integer native/output dimensions 1–16384 per side; positive finite layer/input dimensions up to 1,000,000 px; content zoom 100–10000%. These are planning limits, not claimed hardware capabilities. Invalid edits are rejected atomically. If framing must shift after a resize/source change, the crop offsets adjust automatically to fit the new dimensions. Undo restores size and crop together. Layer properties exposes crop adjustment and reset controls.

Names and coordinate spaces

User-facing nameMeaningInternal representation
Source formatOriginal aspect, e.g. 4:3, 16:9, 16:10, with explicit native pixel dimensionsSource identity, native width/height, selected aspect
Output formatAspect of the screen represented by the viewportDerived from output width/height; optional preset/ratio lock
Viewport resolutionOutput screen pixels, selected from a preset or entered manuallyPositive integer screen width/height
Input resolutionUsable source area after input-level cropping; Custom retains the original Source format selectionFour crop edges in native source pixels; remaining dimensions derived
Layer resolutionFinal visible box on the screen, e.g. 300 × 250Final width/height plus advanced cropping, stored as four crop edges relative to the usable input
Content zoomHow tightly that usable input is framed inside the final boxDerived from crop rectangle and final size; 100% means minimum crop needed to fill the box
Offset X / YMovement of content inside the final boxDerived from asymmetric crop; positive values move the picture right/down
Viewport zoomMagnification of the editor view onlyCamera state; never changes output pixels or cropping

Assume square pixels for the initial implementation. A source format such as 16:9 does not establish whether its native size is 1280 × 720 or 1920 × 1080. Require native dimensions before converting pixel crops. Non-square-pixel or aspect-corrected inputs need an explicit later mapping; never infer one.

Cropping a 1920 × 1080 source to 1920 × 1000 changes the usable aspect to 1.92:1. The Source format still reads 16:9 because it describes the original source. It must not force the cropped area back to 16:9 or distort its pixels. This is the implemented interpretation of Custom input resolution.

Output controls in the first draft

Provide HD 1280 × 720, Full HD 1920 × 1080 and UHD 4K 3840 × 2160 as explicit resolution labels. Do not use “4K” alone where it could mean 4096 × 2160. Offer format choices such as 4:3, 16:9 and 16:10, and always display the actual width and height. A locked ratio links dimension edits; an unlocked custom pair sets its own ratio. Changing a format with a ratio lock preserves width and proposes the corresponding height, showing any integer rounding before commit. Choosing a resolution preset sets both dimensions and its ratio in one action.

Custom width/height are first-class, not hidden behind a device-preset list. Reject zero, negative, noninteger and nonfinite viewport dimensions. Enforce documented implementation limits, but distinguish these from supported device output modes. An arbitrary planning resolution is not a promise that the device can be configured to produce it.

Changing viewport resolution preserves layer positions and sizes in screen pixels. Recompute displayed right/bottom offsets; do not silently reposition or scale layers to preserve margins. Revalidate image mapping and off-screen status. Changing the application window size only changes the camera/layout.

Input resolution: source-level crop

For native dimensions Nw × Nh and input crops Il, Ir, It, Ib:

Iw = Nw - Il - Ir
Ih = Nh - It - Ib

All crop amounts are nonnegative and the remaining area must be positive. Custom dimensions may reduce either axis but cannot manufacture additional source pixels. Initially center the retained area, dividing removed pixels equally; provide explicit crop placement so black bars or unwanted edges need not be symmetric. Preserve fractional results internally until device quantization.

Example: native 1920 × 1080, input 1920 × 1000 gives input crops left 0, right 0, top 40, bottom 40. Source format remains 16:9.

Input cropping belongs to the source identity. If both layers use the same physical input, they share its input-resolution correction, while each has its own advanced crop. Show which layers an input edit affects and apply it as one undoable transaction. Different proposed input crops cannot be exported as if they were independent settings for the same physical input.

Layer resolution: advanced cropping

The visible layer box Bw × Bh is fixed while its content is reframed, just like an avatar crop. Cropping followed by proportional fitting produces the apparent zoom. There is no independent image-zoom transform to export to WebRCS.

The baseline uses cover geometry: scale proportionally until both box dimensions are covered, then remove overflow. It is not sufficient to choose the numerically largest side; compare both scale ratios. This avoids blank bars for landscape, portrait and unusually wide boxes.

Let the usable input be Iw × Ih, content zoom be z ≥ 1, and offsets ox, oy be in final output pixels. At 100%, z = 1; viewport camera zoom is unrelated.

k0 = max(Bw / Iw, Bh / Ih)       # minimum proportional scale that covers box
k  = k0 * z                    # output pixels per usable-input pixel
Rw = Bw / k                    # retained source region width
Rh = Bh / k                    # retained source region height

L = (Iw - Rw) / 2 - ox / k
R = (Iw - Rw) / 2 + ox / k
T = (Ih - Rh) / 2 - oy / k
B = (Ih - Rh) / 2 + oy / k

These four advanced crop edges are in post-input-crop source pixels, not screen pixels or percentages. The retained region starts at (L, T). It has aspect Bw / Bh, so proportional fitting reproduces the final box exactly.

The source-to-box mapping makes the offset sign explicit:

box_x = k * (input_x - L)
box_y = k * (input_y - T)
screen_x = visible_box_left + box_x
screen_y = visible_box_top  + box_y

Valid content offsets keep every crop nonnegative:

abs(ox) <= (k * Iw - Bw) / 2
abs(oy) <= (k * Ih - Bh) / 2

At baseline, one axis usually has no panning range. Increased zoom creates more room to pan. Dragging stops at these explicit limits; invalid typed values show an error rather than silently changing. Never reveal pixels removed by the input crop. Actual firmware crop limits may impose stricter bounds or maximum zoom.

Authoritative state and inverse controls

Store native source metadata, input crops, layer advanced crops, final visible size and visible position. The crops are authoritative; do not persist a second, independent zoom/offset transform that can disagree with them. The UI derives:

Rw = Iw - L - R
Rh = Ih - T - B
k  = Bw / Rw                    # must also equal Bh / Rh
z  = k / max(Bw / Iw, Bh / Ih)
ox = k * (R - L) / 2
oy = k * (B - T) / 2

Reject imported crop tuples that do not satisfy positive remaining area, matching aspect and supported precision. Do not silently stretch mismatched crops. Preserve exact/rational values where practical; never round the intermediate 444.444… width to 445 before computing a crop.

Composing the two crop stages gives native-source retained bounds:

native_left   = Il + L
native_top    = It + T
native_right  = Nw - Ir - R
native_bottom = Nh - Ib - B

This is a geometric identity, not an instruction to send the same crop twice. Keep input and layer settings separate. The device adapter must establish whether layer pixel crops use native dimensions, corrected input dimensions or another reference and convert once. Percent crop denominators also need verification.

Worked examples and expected values

All examples center the crop unless an offset is specified. Native dimensions are 1920 × 1080 and the final layer box is 300 × 250.

CaseInput areaContent zoomProjected full usable inputAdvanced crops L / R / T / B, in usable-input pixels
Uncorrected 16:91920 × 1080100%444.444… × 250312 / 312 / 0 / 0
Custom input1920 × 1000100%480 × 250360 / 360 / 0 / 0
Custom input, tighter framing1920 × 1000200%960 × 500660 / 660 / 250 / 250
Same, content moved right 30 px1920 × 1000200%960 × 500600 / 720 / 250 / 250

The uncorrected example removes 144.444… output pixels in total horizontally, or 72.222… on either side. The custom-input example removes 180 output pixels, or 90 per side. These are equivalent projected crop amounts, not the stored source-pixel values in the table. Every resulting visible box is 300 × 250.

At 200% with Custom input, the native combined crops are left/right 660 and top/bottom 290: the original 40-pixel input correction plus the 250-pixel layer crop on each vertical side. The retained native region is 600 × 500, scaled by 0.5 to fill the 300 × 250 box. This checks that input correction is applied once.

Device mapping: keep the container separate

Implemented device adapter: supports both an output-sized Midra layer with internal cropping and a source-aspect layer container with derived sizing and cropping. These use distinct container sizing algorithms, described in the device exchange contract, with hardware write/readback checks on Eikos 3.3.10. Physical-screen comparison remains outstanding. See remaining acceptance checks.

The intended hardware aspect choice is Centered, as requested. The Analog Way Midra 4K V3.2 manual, pp. 66 and 87 describes input crops in pixels and layer cropping with resizing, with a separate layer aspect selection. It does not establish every processing-order or rounding detail needed here for the installed firmware.

The adapter must return input crop settings, layer crop settings and units, aspect mode, device layer width/height and device center position. Keep these derived values distinct from the visible layer box. Verify whether a crop with the exact target aspect allows the device container to equal that box in Centered mode. If the device uses a different container, derive its size and position from the measured mapping. An asymmetric crop may require a position correction.

The projected full-input sizes in the example table are explanatory geometry, not automatically the layer sizes to enter into WebRCS. Do not confuse the helper’s cover calculation with the device’s named Centered/Cropped settings. Until verified, show calculations as provisional and do not label them a validated device recipe. Unsupported results must not be approximated with masking.

Quantize only at the device boundary. Check the reconstructed visible rectangle and sampled source region after quantization. Show the requested and achievable values and residual error; block a supposedly exact recipe when its error exceeds the verified device precision. Never silently alter the user’s final box.

Interaction and changes to the inspector

Retain the A/B/C positioning layouts. Add sections in this order after the draft:

  1. Source: source identity, Source format and native dimensions; Input resolution preset/custom and its crop placement. Shared-input effects visible.
  2. Layer resolution: final width/height and optional ratio lock, followed by the existing corner positioning controls.
  3. Framing: Content zoom, Offset X/Y, Recenter and Reset framing. An explicit “Adjust layer crop” mode makes dragging reframe content inside the fixed box; ordinary dragging still moves the complete box. Escape leaves framing mode.
  4. WebRCS values: derived size/position, crop settings and aspect mode, with an expandable explanation of units and any representability error.

Recenter preserves zoom and clears offsets. Reset framing sets baseline zoom and centered crops; neither changes input correction or final visible bounds. Pointer-wheel zoom remains camera zoom; content zoom uses its own control to avoid accidental geometry edits. Each drag/edit is one undoable operation.

Cropping requires a content illustration: a source-coordinate test pattern can show framing without live video. A user-provided source still may optionally be added later and must remain distinct from the screen-wide reference image. Do not suggest the screen reference picture is the layer’s source content.

Moving or aligning a layer leaves crop settings untouched. Resizing the final box preserves its selected positioning anchor; preserve content zoom and the normalized center of the retained source region, then recompute the required crop aspect. If that center becomes infeasible, show the necessary adjustment before applying. Source/input-resolution changes use the same explicit adjustment policy and affect all layers sharing the source. Do not mutate the crop merely because the inspector’s units or selected screen corner change.

Acceptance matrix for implementation

  • Round-trip crop ↔ zoom/offset for all worked examples without accumulating drift.
  • Equal source/box aspect at baseline gives zero advanced crop; landscape-to- portrait and portrait-to-landscape use the correct constrained axis.
  • Increasing zoom preserves final size and crop aspect; content pan changes opposite crop edges equally and oppositely while preserving retained dimensions.
  • Moving the box changes only its screen position; changing camera zoom changes no source, input, layer or device geometry.
  • Test zero/negative dimensions, oversized input custom dimensions, zoom below baseline, nonfinite values, exhausted crop area and out-of-range offsets.
  • Test odd dimensions, fractional edges, extreme aspect ratios, device rounding and repeated zoom/reset cycles without drift or premature integer rounding.
  • Input-crop changes affect shared-source layers consistently; independent layer crops remain independent. Undo restores all affected geometry atomically.
  • Test resizing, source-format changes and reference-image mapping changes with off-screen layers and mixed selections; no implicit proportional repositioning.
  • Compare the final visible bounds and sampled source corners with manual WebRCS results for centered/asymmetric crops and nonzero input correction. Verify both crop stages, aspect mode and device container rather than checking numbers alone.
  • Keep these checks independent of UI rendering; add interaction verification for mode switching, focus, framing limits, preview and undo when the UI is built.

All manuals

File and device interfaces

Documentation · Midra Layout guide

These contracts describe persistent formats, compatibility, validation and device transfers. Versioned examples live beside the relevant contract and are exercised by regression tests.

ContractContents
Midra Layout projectJSON project versions, SVG geometry, validation and migration
Application settingsPer-user preferences and settings versions
Geometry exchangeImport/export formats, precision, omissions and round trips
Recovery filesRecovery storage and restore behavior
Device importRead-only device geometry import
Device sendReviewed writes, crop conversion and restore diagnostics
Input previewsDevice snapshot retrieval and caching
Desktop launchersGenerated shortcuts and launcher metadata

For report output semantics, see PPTX Reporter formats.

All manuals

Midra Layout file interfaces

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

Project JSON, version 11

Suggested filename: layout.midra.json. Encoding: UTF-8, pretty-printed JSON, with a trailing newline. A project preserves applied document values at their stored floating-point precision. No display rounding is applied. The loader requires every field below, rejects unknown fields, and rejects unsupported versions. Version 1 files first gain editor.show_toolbar_icon_names: false. Versions 1 and 2 then migrate to version 3 with their original two layer IDs, names Presenter and Slides, empty folders, and next_layer_id: 3; other values are preserved. The version 1 example remains a migration fixture. Version 4 adds editor.outline_layers: false, and reference native_size: false and offset: [0, 0] when migrating versions 1–3. Old fitting behavior is preserved. Version 5 adds required midra_link to every layer. Versions 1–4 migrate with null links; links cannot be supplied under an older version. Version 6 renames editor.position_corner to editor.position_point and adds center. Versions 1–5 retain their original corner; center and the new field are rejected in those older schemas. Version 7 adds editor.backdrop_title; versions 1–6 gain "Example Conference Name" and cannot supply this field under the old schema. Version 8 adds required editor.position_layer_point: null keeps matched points; a point enables independent measurement. Versions 1–7 migrate to null and cannot supply this field. Version 9 adds required layers[].pivot; versions 1–8 migrate to [0.5, 0.5] and cannot supply this field. Version 10 replaces reference with the required ordered references array. Versions 1–9 migrate null to [] and a single image to a one-element array, preserving all image settings. Version 11 adds required workspace settings and embedded layer previews. Versions 1–10 gain the documented workspace defaults, with no captures or collapsed folders; supplying workspace in an older schema is rejected. Saving always writes version 11; older applications reject it. Incompatible files are never partially applied.

Complete example is a valid default project, without a reference image. New projects label the lower layer 02 / Slides and the upper layer 01 / Presenter; existing projects retain their saved IDs/names. It is loaded by the regression tests.

Root fieldRepresentation / meaning
formatExactly "beffroi.midra-layout"
versionInteger 11
next_layer_idPositive integer strictly greater than every layer ID; not rewound by undo
output_resolution{ "width": integer, "height": integer }, screen pixels
inputs1–1024 input objects, consecutive IDs starting at 1
layers1–256 layer objects, unique positive stable IDs, in back-to-front stacking order (last is topmost)
referencesRequired array of 0–32 embedded reference-image objects, back-to-front compositing order
editorSelection, positioning and viewport preferences
workspaceRequired working setup and layer previews, described below

Input objects:

FieldRepresentation / meaning
idConsecutive input slot ID; not an external device identifier
source_format"four_three", "sixteen_nine", "sixteen_ten", "square", or "custom"
native_resolution{ "width": integer, "height": integer }, native input pixels
input_crop{ "left": number, "right": number, "top": number, "bottom": number }, pixels removed from the native input

The user-facing input resolution is derived by subtracting opposite input crop edges from native dimensions. The source format remains explicit even with custom input cropping. Non-custom source formats must match the native resolution within the existing half-pixel rounding tolerance.

Layer objects:

FieldRepresentation / meaning
idUnique positive stable editor layer ID; independent of list position and Midra mapping
nameNonblank display name, at most 128 characters
midra_linkRequired: null (unlinked) or { "screen": "2", "layer": "1" }. Positive decimal device IDs as strings, at most 16 ASCII digits; unknown fields rejected. No host, bank or credentials.
pivotRequired [x, y] gravity point relative to the layer top-left, in fractions of width/height. Center is [0.5, 0.5]; outside points are allowed. Finite doubles within ±1,000,000, preserved without rounding. Placement/reset is undoable; follows layer movement/reordering. Omitted from SVG and device writes.
folderLocal folder name, at most 128 characters; empty means ungrouped
source_idExisting input slot ID; multiple layers may share an input
bounds{ "x": number, "y": number, "width": number, "height": number }, final visible box in screen pixels; x/y are its top-left position
advanced_cropFour nonnegative edges in usable input pixels, after input cropping
visibleBoolean editor visibility
lockedBoolean editor selection/movement protection

The visible box is the user’s layer resolution. Its content zoom and offset are derived from advanced_crop, usable input size and visible box size; they are not duplicated in the save file. Retained source pixels must have the same ratio as the box. Crop zoom must be 1–100 (100–10000%). Shared input assignments and both crop stages survive round trips without rewriting the crop values.

Each reference object:

FieldRepresentation / meaning
nameDisplay filename, not a path to read
image_base64Standard padded RFC 4648 base64 of the original PNG/JPEG/BMP file bytes; no data-URL prefix
visibleBoolean
opacityNumber from 0 to 1
preserve_ratioBoolean: fit proportionally if true, stretch to screen if false; applies when native sizing is off
native_sizeBoolean: image pixels map 1:1 to screen pixels; anchored at screen top-left before offset
offset[x, y] finite screen-pixel translation, each within ±1,000,000; applies after fitting/native placement

Images are embedded, so moving the project does not break the references. Each image retains independent visibility, opacity and fitting settings. Later entries paint over earlier ones; hidden entries do not erase earlier images. The editor lists them topmost first with distinct reference coloring, eye/remove controls and Show only this reference. They have no layer IDs, geometry handles, device links or selection/alignment participation. The currently focused reference row is session-only; saved visibility determines the reopened composite.

At most 32 images and 64 MiB of combined original image bytes are accepted. The existing 96 MiB project JSON limit still applies. No external files, URLs or device endpoints are accessed on load. Image dimensions are decoded from the bytes. The existing image loader enforces a 64 MiB encoded file limit, maximum 8192 pixels per side (or the GPU texture limit if smaller), and a 256 MiB decoder allocation limit. Bad image data aborts opening and leaves the current editor unchanged. Project file reading/parsing, validation and reference decoding run in a background worker. The editor is replaced only after every image succeeds; Cancel loading ignores late worker results. Recovery checkpoints pause during loading. Texture upload/presentation still depends on the GUI/GPU. Captured Midra stills use the same reference object and embedded PNG bytes, with no device request on reload; no schema/version change is required.

Editor object:

FieldRepresentation / meaning
selected_layer_idsArray of unique IDs of visible, unlocked layers; may be empty
backdrop_titleRequired string, 0–128 Unicode characters, no control characters. Example backdrop title; empty hides the text. Preserved exactly, including spaces; omitted from SVG/device output.
position_pointScreen measurement origin: "top_left", "top_right", "bottom_left", "bottom_right", "center"
position_layer_pointRequired: null for the matching layer point (advanced toggle off), or one of the same five point strings for an independent layer endpoint (toggle on)
keep_aspect_ratioBoolean for layer resizing
viewport_zoomPositive fit-relative scale, 0.0001–256
viewport_pan[x, y], viewport pan in screen-coordinate pixels; finite, absolute value at most 1e9
show_source_patternBoolean: show source patterns on other layers during crop editing; normal editing always hides patterns
show_toolbar_icon_namesBoolean: show names beneath toolbar icons; false by default
outline_layersBoolean: transparent layer fill for reference alignment; selection/handles remain visible

Position offsets measure from position_point on the screen to the chosen layer point (matching when position_layer_point is null). Screen corners retain inward signs: right origins reverse X, bottom origins reverse Y. Screen center uses positive right/down. For screen top-left → layer center, offsets are the layer’s absolute center coordinates. Numeric resizing and manual ratio edits preserve the chosen layer endpoint’s offsets. Switching either point or toggling independent measurement never moves a layer. Stored bounds remain top-left coordinates; viewport guides use the same endpoints.

Resolution dimensions must be whole pixels from 1 to 16384. Layer x/y must be finite and within ±1,000,000 pixels; layer widths/heights and retained input dimensions must be positive, finite, and at most 1,000,000 pixels. Crop edges must be finite and nonnegative, with a positive retained region. Off-screen x/y are allowed. Invalid source references, duplicate layer IDs or out-of-order input IDs, invalid crops, missing fields and non-finite values are rejected before replacing the document. Projects larger than 96 MiB are rejected.

Save includes applied values only. Pending text/format/import drafts, prepared aspect-ratio targets, open dialogs, undo/redo history, crop-edit mode, pivot/navigation tools, alignment targets, and provisional device export calculations are not persisted. Resize mode and grid snapping setup are restored from the project. Names and folder labels are stored. Removing layers does not renumber surviving IDs; adding a layer consumes next_layer_id. Unused input slots are retained to preserve shared-source references. Loading starts a fresh history. Loading requires a replacement confirmation; failed loading leaves current work intact. Writes use a same-directory temporary file and atomic publication. Existing destination files require explicit replacement confirmation for Save/exports. Measurement-point clicks and the independent-point toggle are an exception: they reread the current project and atomically update only editor.position_point and editor.position_layer_point, preserving its other stored values (including external edits). Older schemas migrate to v11 on this write. No project path is stored in settings; new documents require a first Save. Geometry exports never change the active project path. Missing/invalid/unwritable projects are left untouched and an error is shown; active in-memory choices remain available for a manual Save. A failed no-overwrite write leaves the existing file intact.

Layer history and export scopes

Add/remove/rename, reordering and folder edits are undoable. Device mappings are not implied by editor IDs. Selection stores stable layer IDs, not zero-based indices. At least one layer must remain. Visibility and locks remain local protection flags and are undoable. Geometry export supports all, visible-only, explicit specific-layer (including hidden) or selected layers (including a single layer); rectangles retain stable IDs and document stacking order. Names appear as titles/labels in current geometry exchanges; folders are omitted.

Reordering changes only the order of the existing layers array, not IDs or per-layer values. Reordering uses the existing array order for every exchange version. Moving layer 1 above layer 2 in the list saves IDs in [2, 1] order and emits layer-2 before layer-1 in SVG. Loading preserves that order; selected-layer exports still follow document order, not selection order. Source slots, next_layer_id, names, folders, crop geometry, visibility/locks and Midra links remain attached to their original layer IDs. The layer manager displays reverse document order (top row is topmost). The inspector collects same-name folder members into one collapsible group, ordered by each group’s frontmost member; children retain reverse stacking order. Legacy interleaved groups are displayed together without silently rewriting the saved stack. Selection does not raise a layer; canvas drawing and hit testing follow the saved stack.

Folders remain single-level names on layer records; no schema change is required. There are no empty-folder records or implicit path separators. Creating/renaming a folder updates all member folder strings in one history step; renaming to another existing folder name is rejected (use membership moves to combine groups). Moving a folder reorders its members as one contiguous block, preserving member order, IDs, source references, crops and Midra links. A layer row drop changes membership and stacking together in one history step. Folder eye/lock actions update each member’s visible/locked flags atomically; Undo restores mixed prior states. Folder selection respects each member’s visibility/lock. Collapse state is saved in workspace.collapsed_folders, but omitted from geometry exports; an empty group disappears when its last member leaves. Geometry exports continue to omit folders.

Legacy SVG geometry exchange, version 1

The Export menu now produces SVG v2 and draw.io v1 with optional artwork; see geometry exchange for their current contracts and examples. The v1 API below remains readable and available for compatibility.

Suggested filename: layout.svg. UTF-8 SVG with SVG namespace, width, height and viewBox="0 0 W H" equal to the output screen. The root carries data-midra-layout-geometry="1". A title and one <rect> per exported layer follow.

<svg xmlns="http://www.w3.org/2000/svg" data-midra-layout-geometry="1"
     width="1920" height="1080" viewBox="0 0 1920 1080">
  <title>Midra Layout geometry</title>
  <rect id="layer-1" x="120" y="180" width="640" height="360" fill="#173b50"/>
  <rect id="layer-2" x="1160" y="180" width="640" height="360" fill="#173b50"/>
</svg>
  • IDs are stable layer names layer-1, layer-2; rectangle order is document order, independent of viewport selection.
  • Coordinates are the visible box top-left and size, rounded independently to nearest whole pixels; half values round away from zero. Negative coordinates are retained. Dimensions that would round to zero reject export.
  • There are no strokes, transforms or groups, so stroke expansion is unnecessary.
  • All layers includes hidden and locked layers as ordinary visible rectangles. Visible layers only omits hidden layers but includes locked visible ones. An empty visible selection rejects export instead of producing an unimportable file.
  • The file is a geometry interchange, not a project backup. It deliberately omits source assignments, crops, content zoom, reference image, lock/visibility flags, selection and camera. Use project JSON to preserve those.
  • Use Import → Geometry file… and review the mappings. Choose destinations from All / Selected / Folder scopes; each included item needs a distinct layer. A full-screen rectangle bearing this export marker is treated as a layer, not an automatically ignored background. Other SVGs keep the existing full-page background detection rule.
  • Reimporting restores rounded box geometry through the regular import options; it does not set the screen resolution or restore omitted project state. External SVG editors may remove the marker; then review the background checkbox on import.

Compatibility changes

Project version 11 and the versioned geometry exchanges are strict contracts. A breaking project field/meaning change must bump version and either implement a tested migration or clearly reject older/newer files. Changing rectangle/marker semantics requires a corresponding documented exchange-interface revision and importer tests. Update this document and its example with every schema or semantic change, including additive fields under the strict unknown-field policy. Never silently interpret a future version as a supported version.

Midra links belong to layer identity and survive selection changes, refresh, rename, reorder and project round trips. Link edits support Undo/Redo. New layers and older projects start unlinked. Links refer to the currently connected device; Preview/Program and sizing remain session choices, and Program permission remains an application preference. Duplicate destinations can be stored within or across folders. Mapping warnings list the other linked layers/folders; a send scope containing duplicates is rejected before any writes, while conflict-free folders/selections remain valid. Unavailable screens/layers are reported without deleting the saved links. Geometry exports omit links.

Midra destinations are identified by the pair screen ID + layer ID: Screen 1 Layer 1 and Screen 2 Layer 1 are distinct links. Both IDs are already persisted in project version 5; no schema change is needed. Opening Midra mapping & transfer… 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.

Automatic session recovery wraps this project representation in a separate recovery file; named project JSON is version 11.

Folder-scoped Midra transfers

The shared Midra transfer scope is session-only and is not saved. Defaults use all layers; Selected/Folder modes filter by the existing selection or folder fields. Folders may store alternative layouts whose midra_link values reuse the same screen and layer; each individual send requires unique destinations within its scope. Manual device import now saves the reviewed midra_link with imported geometry/crops in one Undo step. New layers inherit the chosen folder; existing folder names remain. All these values use the existing layer fields (unchanged in version 10). See device transfer scopes.

Editor input creation

The opt-in Advanced Source section offers Inputs 1–8 independently of editor/device layer counts. Mapping only edits Midra screen/layer links, not input identities. New editor input extends this local list up to the existing 1024-slot limit. Selecting an unused identity is staged; Apply source changes creates any missing consecutive slots with the default 1920 × 1080, 16:9 source and zero input crop, then assigns the selected layer. Creation and assignment form one undoable edit. Multiple layers may share the new identity. Existing smaller projects remain unchanged until Apply; saving writes the materialized slots in inputs and the one-based assignment in layers[].source_id. Version 10 and older-version migration rules are unchanged. These IDs do not select or route physical inputs.

Workspace settings (version 11)

FieldRepresentation / validation / migration default
snappingRequired booleans enabled (false), pixels (true), screen_edges (true), layer_edges (true), grid (false), show_grid (true), and grid_divisions (two integers 1–64, default [8,6]). These override application defaults for the opened project.
resize_modeindividual (default), same, mirror, or opposite
grid_spacingnull (default), 10 or 100, in output pixels
collapsed_foldersUnique existing nonempty folder names; default []. Deleted/renamed stale entries are omitted when saving.
capture_interval_secondsInteger 5–300, default 10
show_empty_inputsBoolean, default false
previewsArray with at most one entry per existing layer; default []

Each preview has required fields layer_id (stable existing editor layer ID), source_id (the layer’s current editor input slot ID, starting at 1), input (physical capture input number, 0 means unassigned; maximum 1024), host (empty or numeric IP with optional port, used only to match capture assignments), enabled, automatic (booleans), guide_opacity (finite 0–1), name (at most 1024 UTF-8 bytes), and image_base64 (standard padded base64 encoded original image bytes, empty if no still has been captured). Stale assignments for removed layers or changed editor input slots are omitted on save. Captures retain original bytes, without recompression or display rounding.

Reference and preview images together must fit within 64 MiB decoded base64 bytes, and the whole JSON within 96 MiB. Decoding uses the same bounded image loader as references, on the project-loading worker. Malformed images abort the entire open, preserving current work. A capture shared by several layers is embedded in each preview entry; the same combined size limit applies.

Restoring a project never starts a connection or a capture. Saved stills appear offline; saved automatic capture choices are paused until Capture still, Resume auto-refresh, changing the input, or explicitly toggling auto-refresh. Pending jobs, throttles and queued selection captures are not restored. Device host matching still applies to automatic requests. These settings/stills are not part of geometry export formats; fixed references retain their existing optional background export behavior.

For the complete persistence audit and the reasons for keeping other controls out of project files, see Project persistence audit.

All manuals

Midra Layout persistence audit

Audited against the editor, project loader, application settings, capture controls, layer tree, format properties, import/export controls and device transfer state. Implemented with project version 11. This is an ownership audit: not every control should become document data.

ParametersOwner and decision
Output resolution / aspectProject: exact width/height. The output aspect preset is derived from them, not stored twice.
Layer position, dimensions, stacking orderProject: full-precision bounds and array order; display/export rounding never changes the saved values.
Input format, native dimensions, custom input crop, shared input slotProject: inputs and layer source_id, already saved.
Layer format, dynamic crop, zoom and offsetProject: final bounds and advanced crop, already saved. Zoom/offset/aspect are derived from these authoritative values.
Names, stable IDs, next ID, folder membership, visibility, lock, pivotProject, already saved. Folder visibility/locking acts on members, so there is no separate state to save. Empty folders are not document objects.
Device screen/layer mappingProject, already saved per layer. Physical source routing is separate and is not silently changed by a geometry send.
Reference images, order, visibility, opacity, fit/native sizing, offsetProject, already embedded. Focused reference row is temporary.
Selected layers, viewport zoom/pan, positioning originsProject, already saved. Selection is validated against visible/unlocked IDs.
Backdrop title, source guide pattern, outline mode, aspect-ratio lock, icon captionsProject, already saved. Pattern/ratio lock/captions also have application defaults.
Magnet, pixel/edge snapping, overlay visibility/divisions, overlay snappingAdded to project. Application settings remain the defaults for a new workspace; opening a project restores its setup.
10/100-pixel tool grid, group resize modeAdded to project. They determine editing behavior and now follow the saved workspace rather than the previously opened document.
Collapsed folder rowsAdded to project. Keeps larger memory collections manageable; stale folder names are filtered out.
Preview input, device-address binding, editor-source binding, enable flagAdded to project per stable layer ID. Preselected-but-not-yet-captured inputs are saved too.
Last captured still, guide opacityAdded to project. Original image bytes are embedded for offline reuse, subject to the shared 64 MiB image budget.
Auto-refresh choice, refresh interval, show no-signal inputsAdded to project. Auto-refresh restores paused; no fetch or connection is initiated by loading. Resume/capture is explicit.
Theme/recent themes, connection address/history, startup connection, allow ProgramApplication settings only. These belong to the workstation/operator; opening a document must not switch connections or global permissions. Capture host strings are bindings, not connection instructions.
All/selected/folder transfer scope, target bank, export sizing strategySession choices. Links and folders are persistent; the current transfer action and destination bank are not document content. Existing behavior is retained.
Advanced shared-device input edit checkbox and staged editsSession-only by design. These are pending changes to external shared input settings; only explicit edits are sent. Local source/crop geometry is saved separately.
Import mapping, size/position/zoom toggles, ignored items/pagesTemporary import review. Applied results are saved; unfinished operations and their external payloads are not.
Geometry export codec, selection scope, background/placeholders optionsTemporary export choices. No destination files are reopened or overwritten by project loading.
Alignment reference, prepared numeric ratio, active navigation/pivot/grid gesture, crop-edit mode, open tab/menu/dialogTemporary editing context. No partial interaction is replayed; the resize mode and grid spacing themselves are saved as above.
Undo/redo, text drafts, drag snapshots, selection marquee, errors/progress, cached device capabilities, network jobs/timersTransient runtime state. Loading starts a fresh document history and discards late capture results.
Named project path and last manual-save timeRecovery envelope only, not the portable project. Recovery uses the same project representation and image validation.

The application settings contract is unchanged (v8). The recovery envelope is unchanged (v1); its nested project migrates to v11. Geometry export representations are unchanged and omit capture images/settings; optional fixed-reference backgrounds retain their existing behavior.

Regression coverage includes current-schema round trips, versions 1–10 migration, invalid assignments/settings and unknown/missing fields, embedded-still decoding, atomic failure on malformed images, cleared stale previews, restore-without-fetch, manual resumption eligibility and saved resize setup. The guide and example JSON are updated with the schema.

All manuals

Midra Layout geometry exchange

The Export menu writes SVG v2, draw.io v1, geometry JSON v1, geometry CSV v1, DXF/DWG, HTML/CSS v1, PPTX, Figma FIG and Illustrator AI (the latter via a local VectorCraft CLI). Project JSON is version 11 and is the full-fidelity save format. These exchanges preserve layer visible-box geometry, not sources, crop settings, zoom, pivots, Midra links, locks, visibility, camera or selection. Pictures illustrate current cropping; importing a picture does not reconstruct its crop or source settings.

The starter-file catalog centralizes ready-to-open two-layer templates under docs/templates/midra-layout/ for Full HD (1920 × 1080) and UHD 4K (3840 × 2160), in all ten exchange formats (including PPTX, FIG and AI). The 4K geometry is an exact 2× scale of the Full HD layout. Regenerate them with:

cargo run --locked -p midra-layout --example check_geometry_exchange -- templates docs/templates/midra-layout
# Optional native codecs (default build); AI requires VectorCraft CLI:
MIDRA_VECTORCRAFT_CLI=/path/to/vectorcraft-cli cargo run --locked -p midra-layout --example check_geometry_exchange -- templates docs/templates/midra-layout pptx fig ai

The generator verifies imported geometry before writing each template and replaces existing templates in the explicitly supplied directory. Samples contain only two editable layer boxes, with no background or placeholder images. PPTX uses one slide, FIG one frame, and AI one artboard. Their canvas sizes are pixels (PPTX uses the documented 96 pixels/inch conversion). These files are geometry examples, not full-fidelity project saves. AI samples were generated and round-trip checked with VectorCraft CLI 0.24.1; Adobe Illustrator itself was not used for validation. Native fixtures are checked semantically rather than byte-for-byte because encoder metadata can vary. The AI regression check is opt-in and requires the real CLI:

MIDRA_VECTORCRAFT_CLI=/path/to/vectorcraft-cli cargo test --locked -p midra-layout --test exchange illustrator_readme_templates -- --ignored

Application and format matrix

WorkflowExchange formatImport/exportBackgroundPlaceholder pictures
Inkscape, Illustrator, Affinity Designer, Figma, web vector toolsSVGYesEmbedded PNGEmbedded PNG
diagrams.net / draw.iodraw.io XMLYesEmbedded PNGEmbedded PNG
Scripts, automation and future adaptersGeometry JSONYesEmbedded PNGEmbedded PNG
Excel, LibreOffice Calc and data toolsGeometry CSVYesGeometry rowNo
AutoCAD, LibreCAD and QCADDXFYesRectangle entityNo
Browsers and web layout toolsHTML/CSSYesEmbedded PNGEmbedded PNG
PowerPoint, LibreOffice Impress, DeckCraftPPTXYes; slide picker on importEmbedded PNGEmbedded PNG
Figma, FigCraftNative FIGYes; page/frame picker on importEmbedded PNGEmbedded PNG
Illustrator, VectorCraftNative AI via VectorCraft CLIYes; artboard picker on importEmbedded PNGEmbedded PNG

PSD, VSDX and ODG remain future adapters rather than implied support. PDF is a useful final visual but does not retain a reliable editable-rectangle contract for import, so it is not presented as a round-trip format.

Scope, coordinates and artwork

All formats offer Current layer (exactly one selected), Selected layers, Specific layer (including hidden), All layers and Visible layers only. Stable IDs are layer-N; order is document stacking order, independent of selection order. All chosen layers are exported visibly, even if hidden in the editor. No layers, unknown/duplicate IDs, invalid project geometry or dimensions rounding below one pixel reject export. X/Y are top-left output pixels, relative to the whole output screen, including for single-layer exports. X, Y, width and height round independently to nearest integer; halves round away from zero. Negative positions are retained. No stroke expansion is necessary: exported boxes have no outline.

Export layers… is one window: choose a format, artwork options and layer scope. All codecs share project validation and shape preparation; the byte-oriented interchange registry supplies formats, extensions and capabilities to the UI. Importing files uses the same mapping review as pasted text. Multi-page files require a page/frame/slide choice; changing it resets mappings. File parsing and conversion run on workers so the viewport remains responsive. Files are written only after encoding succeeds; existing destinations require replacement approval.

Options are shared for the current session, default off; they do not modify the project/settings schema:

  • Include background layer adds a first, full-screen shape with ID midra-background, explicitly marked as background. SVG, draw.io, JSON, HTML, PPTX, FIG and AI embed all visible references composited in project order over a dark backdrop using each image’s fit/stretch/native-size, offset and opacity; otherwise they embed a plain dark backdrop. This is a baked visual reference, not an editable copy of reference settings. Image raster dimensions are proportional to the screen, capped at 1920 pixels on the longest side; the exported shape still has the exact screen dimensions. CSV and DXF carry only the background rectangle.
  • Include placeholder pictures uses embedded PNG source-grid patterns instead of flat layer fills. The pattern reflects native input cropping and advanced cropping, fitted into each visible box. Each raster is capped at 512 pixels on its longest side. No live source image is available/captured by this exporter. The images contain no external URLs and need no network access. Imported picture layers are still geometry-only. Without this option, the layers are rectangles. CSV and DXF disable this option because they cannot embed self-contained raster pictures in the supported profile.

The background is detected and ignored by default on import and cannot be mapped as a content layer. A legitimate full-screen layer is kept as a layer. Every placeholder is one importable layer, not an image plus duplicate rectangle.

Optional native document codecs and licensing builds

The default vendor_formats Cargo feature uses the published, pinned deckcraft-pptx 0.6.1 and figcraft-format 0.5.1 crates with their document/geometry types. Their licenses are MIT OR Apache-2.0; vendor file formats do not imply a proprietary implementation license. No upstream app UI, font bundle, media engine or online service is embedded. VectorCraft’s AI readers are unpublished and pull in rendering, font and PDF stacks, so AI uses a separate optional executable rather than embedding that stack. Upstream licenses still apply to separately distributed tools; Midra does not bundle VectorCraft.

# Normal build: native PPTX/FIG/DWG codecs and the optional AI converter interface.
cargo build --locked --release -p midra-layout
# Excludes vendor codecs, their optional dependency trees and the AI interface.
cargo build --locked --release -p midra-layout --no-default-features --features no_proprietary

no_proprietary takes precedence in code and UI if combined with other features. Cargo features are additive: the --no-default-features part is required to remove the dependencies themselves. An --all-features build disables the adapters but still compiles optional dependencies. CI tests both configurations; production coverage uses defaults so native-codec code remains included in the denominator. This is a format/dependency policy switch, not a legal certification.

PPTX

Standard OOXML ZIP, one slide matching the screen; 96 screen pixels per inch, or 0.75 points per pixel (9525 EMU/px). Native shapes/pictures preserve editable names and boxes. The background is named midra-background, a reserved marker excluded from mapping. PNGs are embedded as media; no source URLs are used. PPTX/FIG export asks to rename a content layer with that reserved name so it cannot silently become an ignored background on reimport. Stable Midra device/source IDs are not represented in the native file.

Import lists each readable slide independently. Shapes and pictures use their explicit transforms, recursively composing group coordinate transforms. Rotation and flips produce axis-aligned enclosing boxes. Hidden, zero-sized, unpositioned and unsupported opaque/connector objects are omitted with a count in the review. Masters, inherited placeholders, text content, animations, media playback and source/crop semantics are not imported. The note reports slide dimensions and the fixed unit convention; importing never silently resizes the Midra output.

Figma FIG

FigCraft writes a native .fig ZIP containing the Kiwi-encoded canvas and embedded image assets. Export creates a Midra Layout frame with screen dimensions and rectangle children (image fills when requested). Coordinates are Figma pixels. The background uses the same reserved midra-background name. The upstream codec is best effort; warnings on export are errors rather than silent losses.

Import offers top-level frames/components as separate canvases, relative to their own origin, and pages with loose objects. Visible leaf objects are mapped by their transformed enclosing boxes; nested containers are traversed without duplicating their bounding rectangle. Hidden children and zero-sized objects are omitted. Upstream approximation warnings appear in the mapping review. Constraints, components, auto-layout rules, text and styling do not become Midra parameters. Native round-trip tests verify geometry/artwork with the pinned upstream codec; they do not constitute validation against every Figma service version.

Illustrator AI

Uses VectorCraft CLI, discovered through MIDRA_VECTORCRAFT_CLI, beside the Midra executable, in its bin/ subdirectory, then on PATH. Conversion runs locally in safe mode in a temporary directory, with a 60-second timeout and 16 MiB result limit. Nothing is installed automatically. The CLI reads AI and converts to SVG for the shared geometry importer, or writes PDF-compatible AI from Midra SVG. Import enumerates up to 64 artboards and presents each separately in the same canvas selector. Converter import warnings are shown in the mapping review; export warnings reject the result instead of silently losing content. SVG’s rectangle/path/image restrictions still apply; this is layer-box exchange, not arbitrary illustration reconstruction.

Manual native-file generation and round-trip diagnostics (no device access):

cargo run --locked -p midra-layout --example check_geometry_exchange -- native /tmp/midra-native pptx fig
MIDRA_VECTORCRAFT_CLI=/path/to/vectorcraft-cli cargo run --locked -p midra-layout --example check_geometry_exchange -- native /tmp/midra-ai ai

These generate plain and illustrated documents, with backgrounds, and verify the imported layer boxes. Existing diagnostic files are not overwritten. VectorCraft 0.24.1 native AI round trips were checked for both variants. DeckCraft 0.8.0 rendered the exported PPTX independently of the pinned 0.6.1 codec; the resulting Full HD image was visually inspected.

SVG v2

Example: midra-layout-svg-v2.example.svg. UTF-8 SVG; SVG namespace and optional XLink namespace. Root attributes:

  • data-midra-layout-geometry="2"
  • width, height: output screen dimensions in pixels
  • viewBox="0 0 W H"

Each layer is a <rect> (plain) or <image> (placeholder), with id="layer-N", data-midra-role="layer", x, y, width, height. A <title> carries its name for external viewers; Midra import does not rename destinations. Images use xlink:href="data:image/png;base64,..." and preserveAspectRatio="none". The optional background is an <image> with data-midra-role="background" and full-page bounds. No visible text geometry, transforms, clipping or CSS is needed.

The importer supports v1 and v2 and explicitly rejects other marked versions. VectorCraft-derived SVG may omit the root version and retain data-midra-role on wrapping groups. The importer inherits these role markers and their stable IDs; marked image layers remain importable and backgrounds remain excluded. Explicit unsupported root versions are still refused. Legacy Project::to_svg/to_svg_ids continue producing v1 rectangle-only SVG; the GUI uses v2. Old applications cannot import v2 placeholder images; use JSON or a plain rectangle-only export where required. Editors should retain role markers. If they remove them, ordinary image import remains intentionally limited to a first full-page background. Midra never fetches image URLs during import.

draw.io v1

Example: midra-layout-drawio-v1.example.drawio. UTF-8 uncompressed <mxfile compressed="false"> with one <diagram> containing an <mxGraphModel data-midra-layout-geometry="1">. pageWidth, pageHeight, pageScale="1", and page="1" establish the output canvas; diagram units are pixels. Root cells 0 and 1 provide the required graph root and default layer.

Each exported shape is an <mxCell vertex="1" parent="1"> with stable id, escaped plain-text value (layer name), and data-midra-role="layer" or "background". Its single <mxGeometry as="geometry"> stores pixel X/Y/width/ height. Styles disable outlines and rounding. Pictures use shape=image, imageAspect=0, and draw.io’s image=data:image/png,BASE64 style syntax (without ;base64, which would split the style). Background label text is empty.

Import accepts raw/once-percent-encoded mxGraphModel clipboard XML, single-page mxfile XML, and native compressed diagram text: Base64 → raw DEFLATE → percent decode → mxGraphModel. Native re-saving may remove the model’s Midra version attribute; role attributes and stable IDs survive in the tested version. The reserved midra-background ID also identifies the exported background. Unknown marked draw.io exchange versions are rejected. Multiple pages are refused with an instruction to export one page, rather than silently importing the wrong page. Groups, edges, rotation, flips, relative/alternate bounds and nonrectangular shapes remain unsupported; ordinary unrotated image cells now import their box.

Geometry JSON v1

UTF-8 JSON with root fields format: "beffroi.midra-geometry", version: 1, units: "px", canvas: {width,height} and layers. Each layer has id, name, role, x, y, width and height; image_png_base64 is optional. Roles are layer or background. Unknown fields, versions and units are rejected. IDs must be unique and at most 255 characters; names are limited to 1024 characters without controls. This JSON is the preferred small machine interface. It is not the version-10 project save file and does not contain sources, crop or device links.

Geometry CSV v1

RFC 4180 CSV with CRLF records and this fixed header:

midra_geometry_version,canvas_width,canvas_height,id,name,role,x,y,width,height

Every row repeats version 1 and the same canvas so a selected row remains self-describing. Names use normal CSV quoting. Roles and geometry have the same meaning as JSON. Empty files, mismatched canvases, extra/missing fields and non-integer geometry are rejected. CSV carries background geometry but no image data or placeholder pictures.

CAD: DXF and DWG profiles

DXF uses the official shared craft-dxf document model and serializer, pinned to Craft libraries revision 79e97b6febcb62de406e5bcf5a724bd3f7333065 (MIT OR Apache-2.0). It writes UTF-8 ASCII DXF AC1021 (AutoCAD 2007), with complete symbol tables, model/paper-space block records, dictionaries, layouts, unique handles, owner references and subclass markers. Handles reserve the low 0x100 range to avoid QCAD stock-object collisions; Craft remaps definitions and pointers together. This replaces the incomplete hand-written DXF skeleton rejected by QCAD. The rectangle/coordinate contract remains unchanged; older Midra DXF files are still readable.

Drawings are unitless ($INSUNITS=0): one CAD unit equals one screen pixel. Whole-pixel $LIMMIN/$LIMMAX describe the canvas, with matching initial extents. Every stable ID has a layer-table entry; every box is one closed four-vertex LWPOLYLINE. CAD Y increases upward, so cad_y = canvas_height - screen_y. Import reverses this conversion and requires explicit canvas limits (falling back to extents), rather than guessing scale or page origin. The special midra-background layer is excluded from destination mapping. Human names are layer descriptions; imported IDs remain CAD layer names. Pictures are omitted. DXF import uses Craft’s bounded ASCII/binary tag reader and retains the existing axis-aligned rectangle restrictions.

DWG uses the optional craft-dwg byte bridge from the same pinned revision, backed by unmodified acadrust 0.6.6 (MPL-2.0). It converts the same DXF model to AutoCAD 2007 DWG and back; canvas limits, IDs, pixel rounding and background rules are identical. A writer report of omitted records rejects export. Reader notes appear in the import review. Both DWG input and expanded DXF are limited to 16 MiB. DWG is available with vendor_formats, excluded by no_proprietary; DXF remains available in all builds. The bridge reports unsupported platforms explicitly (WebAssembly and FreeBSD ARM64 at this pin).

Geometry exchange is not a general CAD editor: arbitrary drawing entities, blocks and drafting annotations are not a supported round-trip profile. Keep original CAD drawings; import/export the rectangular layer layout separately.

HTML/CSS v1

The XHTML-compatible document is a directly viewable page. Root data-midra-layout-geometry="1" marks the version; #midra-canvas stores data-width/data-height. Each <div> or <img> stores authoritative data-midra-role, data-name, data-x, data-y, data-width and data-height; inline CSS renders the same box. Images use self-contained PNG data URLs. Import reads the data attributes, not computed CSS, scripts or browser layout. The file contains no script or external resource.

Limits, import and round trips

Operator acceptance (2026-11-14): the user confirmed PPTX working flawlessly, and draw.io and SVG working. Their reported format issues are marked solved in the task list.

Import files and clipboard text, and generated exports, are capped at 16 MiB (to allow self-contained images). Decompression is bounded: at most 48 MiB of percent-encoded text and 16 MiB decoded XML. Up to 256 layer boxes plus one background are allowed. No imported image is decoded or downloaded by the geometry importer. Export reference decoding retains the existing 8192-pixel per-side/256 MiB decoder bounds. Oversized exports fail before writing a file.

Use Import → Geometry file…, drop supported files, or paste supported text, then review and map shapes to editor layers. Drops route case-insensitive registered extensions (including draw.io XML and vendor formats) through the same asynchronous byte importer as the picker; native-codec build restrictions still apply. Path-backed and in-memory file drops are supported. Raster images retain reference-image behavior. Several geometry files become named choices in the file/page/frame/slide selector, with a combined 16 MiB input limit. Parsing is atomic across the geometry batch; errors report the failed filename, and no geometry is applied before mapping confirmation. Destination count need not match current selection. The review offers All / Selected / Folder destination scopes without changing canvas selection; hidden and locked layers are unavailable. Every included item needs a distinct destination, while excluded items and unmapped editor layers remain unchanged. Existing mappings survive scope changes when still eligible. Clipboard text and per-item geometry details are collapsed, read-only previews. These review choices are session-only and do not change any file schema. Import with size and position enabled restores the rounded geometry in one Undo step. Output screen resolution is not imported. Mapped names, sources and Midra links stay with the destination layers. File replacement retains the existing explicit overwrite confirmation and atomic-write path.

SVG files rendered by draw.io Desktop are also accepted. The importer recognizes the data-cell-id wrapper groups retained by draw.io, reads the first rectangle, image or symbol use in each cell, and ignores generated HTML labels, raster text fallbacks, symbols and the draw.io help link. The standard SVG 1.1 public DOCTYPE emitted by draw.io is accepted without fetching external content; XML parsing is limited to 200,000 nodes. The reserved midra-background cell remains an ignored background.

Draw.io’s SVG export normally crops the canvas to the diagram content, adds one pixel to its bounds and rebases cell coordinates. Those rebased coordinates are the only positions present in that SVG. Include Midra Layout’s background layer before exporting through draw.io when the full output-screen origin must survive the round trip.

Tests cover each format/artwork combination, the twelve text templates and six native PPTX/FIG/DWG templates (plus two AI templates in the opt-in CLI check), full-screen layers vs backgrounds, negative/fractional coordinates, repeat round trips, compressed clipboard/files, embedded references, invalid IDs/versions and no-overwrite file handling. A manual native-editor check is available:

cargo run --locked -p midra-layout --example check_geometry_exchange -- generate /tmp/midra-exchange-check
drawio -x --size page -o /tmp/midra-exchange-check/render.png /tmp/midra-exchange-check/illustrated.drawio
drawio -x -o /tmp/midra-exchange-check/resaved.xml /tmp/midra-exchange-check/illustrated.drawio
drawio -x -f svg -o /tmp/midra-exchange-check/drawio-rendered.svg /tmp/midra-exchange-check/illustrated.drawio
cargo run --locked -p midra-layout --example check_geometry_exchange -- verify /tmp/midra-exchange-check/resaved.xml
cargo run --locked -p midra-layout --example check_geometry_exchange -- verify /tmp/midra-exchange-check/drawio-rendered.svg

On 2026-11-14, installed draw.io Desktop 31.7.0 (/usr/bin/drawio, not Flatpak) rendered the illustrated diagram correctly, and its re-saved XML returned both layer boxes unchanged. Its SVG export, including <symbol>/<use> image cells and HTML/raster label fallbacks, also returned both layer boxes unchanged when the background preserved the page. Generated plain/illustrated SVG and draw.io files passed geometry verification. Native output artifacts remain in /tmp, not Git.

Protocol references: draw.io diagram format and desktop CLI, SVG 2, CSV RFC 4180, and Autodesk’s DXF group-code reference.

Multiple references are flattened into the same single background image in artwork-capable exports; no format version changes. Reimport reconstructs that background as a geometry/artwork item, not the editable reference collection. Use project JSON v11 to preserve independent images and visibility.

QCAD interoperability check

Validated with QCAD Professional 3.28.2: both 1080p and 4K DXF/DWG templates render two correctly placed rectangles without import/handle warnings. Saving both Full HD samples through QCAD as R21 (2007) and reimporting preserves both layer boxes. Example manual check (temporary output only):

QT_QPA_PLATFORM=offscreen /path/to/qcad/dwg2dwg -r R21 -o /tmp/layout.dwg docs/templates/midra-layout/midra-layout-1080p-2-layers.dwg
cargo run --locked -p midra-layout --example check_geometry_exchange -- verify /tmp/layout.dwg

The verifier now uses the unified byte importer for text and binary formats. The .ai starter ZIP is only a download wrapper, not a new import format; its two entries must remain byte-identical to the .ai fixtures (Python regression).

All manuals

Midra Layout application settings, version 8

Implementation: crates/midra-layout/src/settings.rs. This per-user JSON file is independent of the project JSON and SVG contracts. Complete default example. Version 1 files migrate automatically: the saved theme becomes the only entry in recent_themes, with all other preferences preserved. The version 1 example remains a migration fixture. Version 2 files then migrate by adding disabled snapping with all target types enabled. The version 2 example remains a migration fixture too. Version 3 files migrate by adding an empty midra_host; the version 3 example remains a migration fixture. Version 4 files migrate by adding allow_sending_to_program: false; the version 4 example remains a migration fixture. Version 5 files migrate with autoconnect_at_startup: false; the version 5 example remains a migration fixture. Version 6 files migrate with the overlay grid visible, snapping to it disabled, and grid_divisions: [8, 6]; the version 6 example remains a migration fixture. Version 7 migrates with an empty recent_midra_hosts list; the version 7 example remains a migration fixture. Saving writes version 8; old applications reject it.

The directories 6 crate resolves ProjectDirs::from("org", "beffroi", "midra-layout"). The filename is settings.json beneath config_dir():

PlatformLocation
Linux$XDG_CONFIG_HOME/midra-layout/settings.json, otherwise ~/.config/midra-layout/settings.json
Windows%APPDATA%\beffroi\midra-layout\config\settings.json (Roaming AppData)
macOS~/Library/Application Support/org.beffroi.midra-layout/settings.json

UTF-8, pretty-printed JSON with a trailing newline; maximum input size 64 KiB. Every field is required, unknown fields are rejected, and unknown versions or unknown theme names are rejected. There are no numeric coordinates or units.

FieldValues / default
versionInteger 8
autoconnect_at_startupBoolean; default false. Try one background connection at application startup if the saved address is nonblank.
allow_sending_to_programBoolean; default false. Enables the Program destination in the exporter. Turning it off restores Preview; applies to quick Apply too.
midra_hostDevice IP address text with optional TCP port (e.g. 192.168.10.146:3000, [::1]:3000; default port 80); default "". Saved as typed, including incomplete drafts; validated when connecting.
themeTheme ID from the catalog below; default "midra"
recent_themes1–3 unique theme IDs, newest first; first must equal theme; default ["midra"]
show_toolbar_icon_namesBoolean; default false
keep_aspect_ratioBoolean; default true
show_source_patternBoolean; default false. Shows source patterns on other layers only during crop editing; normal editing always hides patterns.
snappingObject with required boolean fields enabled (false), pixels (true), screen_edges (true; screen edges plus 25%, 50% and 75% guides on both axes), layer_edges (true), grid (false), show_grid (true), and grid_divisions ([8, 6]); unknown fields rejected

Loaded once at startup before the editor appears. Explicit Options changes save the current preferences and theme history immediately. The directory is created lazily; missing files do not trigger a write until the user changes an option. Writes use a temporary file in the same directory, file sync and atomic replacement. Multiple application instances use last-successful-write wins; no merging or live reloading is performed. Selecting a theme moves it to the front, removes any previous occurrence, and trims the list to three. Starting the app does not reorder the restored history. Opening or dismissing the full picker changes nothing.

Project JSON v1/v2 remains unchanged. Opening a project can restore its embedded caption, aspect-ratio and source-preview preferences for that document; it never writes application settings. Theme remains global. Editing an option afterward saves all currently active preferences as the next startup defaults. Snapping remains an application preference and is not read from or written into project JSON.

Invalid/unreadable settings fall back to defaults, report the failure in Options, and disable writes for that run to preserve the original file. Repair/move the file and restart to recover. A write failure retains in-memory preferences and the previous destination where atomic publication failed; Options offers a retry. Failure to locate a configuration directory also disables persistence with an Options error. Tests use temporary directories and never touch user settings.

The device address is saved immediately when edited in Midra connection…. Startup attempts a read-only connection only when autoconnect_at_startup is enabled and the saved address is nonblank. It never sends layer settings. Opening a project preserves the current connection and address, clears import choices, and loads the project’s saved layer destination links. Connection status and snapshots are not persisted. Layer destination links are saved in project JSON, not application settings. Restore default settings disables autoconnect and leaves the connection address unchanged; edit it in the connection window.

No layer geometry, source crops, camera state, project paths, image bytes or clipboard contents are stored. No settings are exported to SVG. Breaking or additive schema changes under this strict contract require a version bump, updated documentation/examples/tests, and either an explicit migration or an actionable unsupported-version error.

Bundled theme catalog

All 18 CSS themes in SOTV_Websites/sotv/song_database/styles/themes/ are represented, alongside Midra Dark. Palettes are bundled in src/theme.rs: no sibling checkout or CSS interpreter is required at build or runtime. Corporate uses the website’s base defaults. The existing three palettes retain their hand-tuned viewport colors; other palettes map body/panel/sidebar/tab surfaces, main/subtle text, button accent and border tokens into the editor. Action fills blend accent and panel; light-theme text/accent colors are darkened for contrast. The picker includes both light and dark themes with color swatches.

ThemeSettings IDSource CSS
Midra DarkmidraOriginal editor palette
Corporate Lightcorporate_lighttheme-corporate.css and ../base/variables.css
Foxified Darkfoxified_darktheme-foxified-dark.css
Bluecorebluecoretheme-bluecore.css
Dupont Monsantodupont_monsantotheme-dupont-monsanto.css
Eden Greeneden_greentheme-eden-green.css
Foxified Lightfoxified_lighttheme-foxified-light.css
HCIhcitheme-hci.css
Iron Docksiron_dockstheme-iron-docks.css
Peaceframepeaceframetheme-peaceframe.css
Rebelrebeltheme-rebel.css
Sirius Mindsirius_mindtheme-sirius-mind.css
Solarizedsolarizedtheme-solarized.css
Sons Of Banardsons_of_banardtheme-sons-of-banard.css
Storm Pilotstorm_pilottheme-storm-pilot.css
Tessier Ashpoltessier_ashpoltheme-tessier-ashpol.css
USTFustftheme-ustf.css
Verdant Rebelverdant_rebeltheme-verdant-rebel.css
Weicat Industrialweicat_industrialtheme-weicat-industrial.css

The Settings window and quick menus share the same settings. Changes apply and save immediately; closing the window requires no Apply step. Restore default preferences resets appearance and editing values, including theme history and snapping, without changing layer geometry or pending position/size text fields. Snapping uses a fixed six-logical-pixel proximity radius converted by viewport scale. It affects layer movement, resize handles and pivot placement; numeric entry, nudges and crop-content gestures bypass it. Resize snapping preserves anchors and proportions and shows guides only when the resulting edge actually reaches its target. The session-only toolbar grid tools select 10 or 100 screen pixels (mutually exclusive). Shift temporarily selects the 10 px grid; Ctrl+Shift selects 100 px. If that same grid tool is selected, the matching shortcut temporarily disables it instead. Alt overrides both grids and temporarily inverts the saved snapping-enabled value (off becomes on; on becomes off), including on release. The chosen pixel/screen/layer-edge targets still apply. These modifiers do not change the saved options or settings version.

Settings → Midra integration → Allow sending to Program saves immediately. Restore default settings disables it. Projects do not override this application preference; the Preview/Program destination itself remains session-only.

Try autoconnecting at startup is in Settings → Midra integration. It saves immediately but applies on the next launch; toggling it does not initiate a connection. One background attempt uses the regular connection timeout and error handling, with no automatic retry loop. Failures leave the app offline and are reported in Midra connection. Project loading does not trigger an attempt.

The session-only Pivot tool can combine with either grid. Ctrl without Shift temporarily inverts Pivot; Ctrl+Shift does not affect it. Tool selections are not persisted in application settings or projects; they survive project loads and selection changes within a session and start off on launch. Pivot positions belong to each layer and are saved in project v9, not application settings.

Select/Move/Pan/Zoom navigation tool choice is also session-only and survives project loads. It starts at Select on launch; V/M/H/Z switch tools only outside text entry. Camera zoom/pan remain part of the project, not application settings.

Pivot placement also has nine built-in local anchors (corners, side midpoints, center), active independently of snapping.enabled within the same six-logical-pixel radius. Anchors take priority over active grids and configured edge/pixel snapping. Alt bypasses these anchors and grids while inverting configured snapping as usual. This adds no settings fields; pivot positions are saved per layer in projects.

Recovery autosave is a separate last_project.json beside settings, not a settings field. See recovery format.

Overlay grid

snapping.grid_divisions contains integer column and row counts, each 1–64. Grid lines are at output_width * i / columns and output_height * j / rows, including output boundaries. Calculations retain fractional screen pixels (no rounding); the same coordinates drive rendering, movement, resize and pivot snapping. show_grid controls visibility independently of grid, which adds these lines to the magnet targets when snapping.enabled is active. Movement snaps layer edges and centers; resizing uses the existing anchor/ratio rules. Existing six-logical-pixel proximity tolerance, release behavior and modifier priorities remain unchanged; explicit 10/100 px grids take precedence. Crop-content resizing is not snapped. Invalid subdivision counts are rejected on settings load.

The Grid toolbar icon opens visibility, snapping and subdivision controls; they also appear in Settings → Editing as a separate Overlay grid section. The overlay is drawn above example artwork and reference pictures, below editable layers, clipped to the output. It is an editor guide, omitted from all project/export artwork. Preferences save immediately and survive project changes; v1–v6 migration does not alter geometry.

Custom ports use the existing midra_host string without a schema change. The port is shared by HTTP reads/captures and WebSocket writes, including startup autoconnection. Hostnames, URL schemes, paths and port 0 are rejected on use.

Recent connections

recent_midra_hosts is an array of zero to four unique canonical IP:port strings, most recently connected first (for example ["192.168.10.146:3000", "192.168.10.143:80"]). IPv6 entries use brackets. Successful reads or verified sends promote an endpoint; failed or cancelled attempts and typed drafts do not enter the list. Default port 80 is explicit so equivalent addresses deduplicate. Invalid addresses, noncanonical strings, duplicates and more than four entries are rejected.

The connection window lists these under Recent machines…. Choosing one sets the saved address, clears old device state/staged input edits, and starts a read-only connection. The picker is disabled during a pending operation. History belongs to application settings, not project files; migration starts empty because older settings do not record whether their last address connected successfully.

All manuals

Midra Layout recovery, version 1

last_project.json lives beside the per-user settings.json (see settings paths). It is an internal UTF-8 JSON envelope, not a named project export. Headless/default editors never access this path.

FieldMeaning
versionInteger 1; other versions rejected
projectComplete project v11, including embedded reference bytes; its units, precision and validation apply without display rounding
project_pathLast opened/successfully saved named JSON path, or null; geometry exports do not change it
manual_saved_atUnix UTC seconds of the last successful explicit project save, or null when unknown; recovery and measurement-point autosaves do not update it

Unknown envelope fields and files over 100 MiB are rejected. Project validation and reference decoding must succeed before replacing the editor. No file at project_path is opened during recovery; it identifies the target for subsequent measurement-point autosaves. The startup device connection remains governed by application settings, not recovery.

Startup/Retry reads, validation and embedded-image decoding run on a background worker. No partial project is installed. Checkpoints (including normal-exit checkpoints) are suspended until loading completes, so an unfinished or failed restore cannot overwrite the previous recovery file. Failures retain the file and pause recovery as before. The envelope remains version 1.

Checkpoints run at most every two seconds, outside active pointer/resize gestures, and on normal exit. Identical snapshots are skipped. Writes use the existing same-directory temporary-file, file-sync and atomic replacement helper. A failed write leaves the previous file intact and pauses retries until requested. Invalid startup recovery is preserved; Retry reloads it, while explicitly starting New project permits replacement. Multiple app instances share this single slot; last successful writer wins.

Recovery retains applied values only: no undo history, pending text/format/import drafts, transient tools, or credentials. A normal exit cancels unfinished canvas gestures before the final checkpoint. The schema does not replace named project JSON: Save continues to emit a bare project v11 document. Opening/New replaces the single recovery slot; New warns with the manual-save age and Save/Discard/Cancel. A failed or cancelled manual save never completes Save-and-create-new.

Complete recovery example is exercised by the startup regression test.

Future breaking envelope changes require a version bump and explicit migration or rejection. Recovery is not an interchange format; use Save for portable files.

Recovery envelope version 1 is unchanged. Nested project versions 1–10 migrate through the normal project loader before typed decoding, including the former single reference field. All reference images and visibility settings are saved.

All manuals

Midra device snapshot and container SVG bridge

Implementation: tools/midra_probe.py. Tests: tests/test_midra_probe.py. Hardware evidence and usage: Eikos check.

Snapshot

--save-snapshot writes UTF-8 JSON containing the raw object from GET /api/stores/device; the root key is device. No editor project version or custom wrapper is added. This is vendor state, not a Midra Layout project. The firmware owns its schema. The Rust adapter accepts Eikos 4K, Pulse 4K, QuickVu 4K and QuickMatrix 4K identities and validates the shared state fields. Reads were checked on Eikos 4K 3.3.10 hardware and the Pulse 4K 3.3.7 emulator (one 1920 × 1080 screen with four allocated layers). QuickVu and QuickMatrix have synthetic parser coverage; physical acceptance remains outstanding. The Rust connection accepts an IP with optional port, shared across HTTP and WebSocket; see connection syntax. --snapshot reads it offline, at most 32 MiB, and rejects missing required fields when extracting geometry. Unknown vendor fields are preserved on capture. Snapshots can contain private configuration. They are never sent back to a unit.

Geometry extraction uses these paths below device:

  • transition/screenList/items/{screen}/status/pp/transition: only AT_DOWN (Preview UP) or AT_UP (Preview DOWN) is accepted. Transitional states fail.
  • screenList/items/{screen}/canvas/status/size/pp/{sizeH,sizeV}: canvas pixels.
  • screenList/items/{screen}/presetList/items/{bank}/liveLayerList/items/{layer}: position/pp/{posH,posV} is the center in canvas pixels; size/pp/{sizeH,sizeV} is the device container size in pixels.
  • crop/pp and mask/pp: all four edges must be zero for SVG extraction. Their nonzero units/semantics are intentionally not converted yet.

Container SVG

This uses the existing geometry SVG marker, data-midra-layout-geometry="1", so a full-screen container is not mistaken for an ignorable background. Root width, height, and viewBox come from the device canvas. One or two rectangles are emitted in explicit --layers order, with IDs screen-{screen}-layer-{layer}, opaque fill and no stroke. Duplicate selections are refused. Missing slots fail rather than being skipped.

Rectangle x/y = center minus half-size. Values are not rounded: this is an import bridge preserving device measurements, not the editor’s rounded export. SVG imports accept fractional pixels. Numeric values must be finite, non-boolean, within ±1,000,000; widths/heights must be positive. The editor performs its own validation again before applying. Existing destinations are refused.

Only container position/size round-trips. No source association, aspect fitting, input crop, zoom, visibility, borders, effects or device connection is encoded. The desktop SVG mapping dialog must be reviewed before applying; the image’s visible bounds are not guaranteed to equal the container. This format must not be presented as a full device/project backup or as validated crop conversion.

Fractional content resolution in the Rust adapter

Device-reported status/pp/contentWidth and contentHeight can be fractional. For centered crop reconstruction, the Rust adapter rounds them to the nearest whole pixel (positive half-pixels round upward), while keeping raw vendor state unchanged. Each original value must still be finite and within 1–16384; rounding does not rescue out-of-range values. The rounded dimensions become the editor’s native source resolution, and normalized crop edges use those same dimensions. Container positions/sizes and the existing SVG bridge retain fractional precision.

A nonblocking layer warning gives both original and rounded dimensions. It is shown in connection/import/mapping feedback and retained after linked loading. Whole-pixel reports produce no rounding warning. The existing no-content fallback for unrouted, uncropped layers is unchanged. Invalid crops and real resolution mismatches remain errors.

All manuals

Midra reviewed layer exchange

The Rust adapter uses the configured IP and optional port for this endpoint (default 80), including emulator addresses such as 192.168.10.146:3000.

This is a transient device protocol, not a project/save schema. Reference collections in project v10 do not change device layer mapping. Compatibility exercised: Eikos 4K firmware 3.3.10, installed WebRCS app.e42fce4879f318b28cde.js. Other firmware needs verification.

Addressing and fields

HTTP GET /api/tpp/v1/system and /api/stores/device supply identity and snapshots. A WebSocket at ws://DEVICE_IP/ accepts JSON text:

{"channel":"DEVICE","data":{"path":["device","screenList","items","2","presetList","items","UP","liveLayerList","items","1","position","pp","posH"],"value":162}}

Normal geometry fields under the mapped live layer are:

  • size.pp.sizeH, size.pp.sizeV: integer container pixels, 1–65535.
  • position.pp.posH, position.pp.posV: integer center coordinates, −67268–67268.
  • crop.pp.left, right, top, bottom: normalized integers, 0–65535.
  • crop.pp.aspectOverride: CENTERED.

At AT_DOWN, Preview is UP and Program DOWN; AT_UP reverses those roles. The selected configuration captures one physical bank. Send writes directly without a preflight read or stale-snapshot refusal. Commands do not retarget halfway through. No TAKE or source routing, mask, effect, opacity or output setting is sent. Shared input aspect/crop fields are omitted unless explicitly opted into and edited as described below.

Conversion

When the destination reports positive content dimensions, the editor native source dimensions must equal status.pp.contentWidth/contentHeight. Missing or zero dimensions (for example, an unassigned input) use the editor’s native dimensions for crop conversion and do not block sending. Reported dimensions describe the incoming content used for this layer, not an instruction to change input hardware configuration.

Combine each local input crop edge with its advanced layer crop edge, in native source pixels. Quantize each combined edge to round(edge / native_axis * 65535). Reject exhausted retained regions, invalid geometry, masked destinations and source-resolution mismatch. Input correction is folded into the layer crop, so it affects only the mapped destination.

For Output-sized, round the requested visible width/height to container pixels. For Source aspect, compute k = max(visible_width/native_width, visible_height/native_height) and round native * k as the container size. The post-crop retained source fits inside this container with Centered aspect. Both modes center the container at the rounded requested visible center.

Reconstruct the retained size from quantized crop fractions, then use min(container_width/retained_width, container_height/retained_height) to derive visible bounds. Reject size errors above one output pixel. Center rounding has at most half a pixel of error. Stored editor coordinates retain full precision; review values use one decimal and transmitted geometry uses whole pixels.

Import and round trip

Centered layers with zero masks and valid content dimensions reconstruct their visible geometry with the same fit calculation. Imported sources are independent local sources with the device content dimensions, zero input correction, and all combined cropping stored in advanced crop. Thus the visual framing survives; the original separation into input correction and layer crop cannot be recovered. Imports are atomic and undoable, including creation of new layers/sources.

Other aspect modes retain container-only import and reject nonzero crop/mask. The Python snapshot-to-SVG bridge remains container-only under its existing contract.

Execution and failure semantics

Only an explicit Send click creates a worker. Read/refresh, editing, project load, import, undo and redo never write. Requests run off the UI thread with bounded socket operations. After preflight, changed fields are written sequentially once. Crop decreases precede increases to avoid temporarily exhausting the retained area while moving a crop. Readback checks every changed field. Valid plans remain sendable even when stored geometry matches: sending still applies staged values. Failure reports partial/uncertain outcomes without blind retries or automatic rollback.

Program selection is explicit. The application defaults to Preview and hides Program unless the persisted allow_sending_to_program preference is enabled. Turning it off resets the exporter to Preview, including quick Apply. Layer screen/destination links are saved in project version 5. Plans and raw snapshots are not saved in projects or preferences. The device address is saved in application settings, never in projects. Refresh and screen changes preserve saved links. Physical display validation remains separate from the successful device-field and import round trips.

The status-bar and Export-menu Midra mapping & transfer… actions only open export configuration, even when current layers have valid saved links. They never start a write. The user chooses a transfer scope, mappings, target and sizing, then explicitly clicks Send mapped layers for the displayed screen. Empty/unlinked rows are skipped. The load button uses all saved links in the scope, including links to other screens. Busy/offline actions are disabled. Send all linked layers remains a separate direct-send action using saved links. No persistent schema changes are involved.

Snapshot layer lists include only allocated live-layer entries, independently of input assignment (NONE, empty or absent) and OFF state. The active allocation comes from device/preconfig/status/stateList/items/CURRENT/screenList/items/{screen}/pp/layerCount. Only numeric live-layer IDs 1 through that count are listed or accepted as send destinations, even though the firmware stores eight slots. The staged NEW configuration, physical input count, background and foreground planes do not determine this list. Missing/invalid allocation metadata produces a connection error rather than exposing all slots. Missing layer IDs are not synthesized. Input routing is informational and is never changed by geometry transfers. A Centered layer without usable content dimensions and with zero crop/ mask imports its container geometry without inferred source framing; nonzero crops still require valid dimensions for visible-bound reconstruction. This changes device discovery/transfer behavior only; project and export schemas are unchanged.

The direct send button uses the shared transfer scope. Its default All layers includes all linked document layers, even unselected, hidden or locked ones. Only selected layers uses exactly the current selection (an empty selection does not mean All); Folder: … uses all members of the named folder, independently of selection/visibility/locks. Unlinked layers are skipped. Plans are grouped by saved screen ID and all groups are validated before starting. Screen groups send sequentially with readback; on failure later groups are not sent, and the result reports the failed screen and completed-group count. Links never auto-send and are not tied to an IP address.

Preset apply pulse

After the geometry writes, send two DEVICE WebSocket messages at device/preset/control/pp/xUpdate: false, then true, matching WebRCS’s DEVICE_PRESET_CONTROL_SET_ONE action sequence. This commits staged preset edits when enableAutoUpdate is false. Do not change enableAutoUpdate or issue TAKE. The pulse is global and may apply other pending preset edits; it is not scoped to an individual screen/layer. Each screen send currently ends with this pulse. Always pulse on an explicit valid send, even if the staged geometry already matches and the change list is empty. A pulse-write failure is reported separately from geometry-write failure. Geometry readback follows the pulse; a readable store alone does not prove the physical video output updated. The trigger itself is not included in geometry comparisons, because it is a command rather than geometry.

Send all linked layers sends immediately using saved links and the current target and sizing settings, without opening the export window. The button shows progress and its tooltip reports completion. Invalid links or send failures open the export window with the error.

Load linked layers, beside the connection status and in Export, reads fresh Midra Preview geometry and crop framing into linked editor layers in the shared transfer scope. The default All layers ignores canvas selection; Only selected layers and Folder: … explicitly restrict the operation. The load button inside Midra mapping & transfer… uses that same scope and the saved links. Both actions are read-only on the device and always load Preview (independent of the send target). They do not recall device memories or presets. Loading is one atomic Undo step; links remain saved. Missing screens/layers, mismatched output resolutions, unsupported geometry, and hidden or locked editor destinations reject the complete import without changing the document. Unlock/show destinations before loading. Results appear in the transfer window or the load button’s status tooltip. No project or settings schema changes are involved.

Closing a device import review with chosen destinations offers Apply/Discard. Apply imports into the local editor atomically; it never writes to the device. Closing send configuration does not send. Local property edits that apply immediately still require an explicit device Send action.

Shared transfer scopes and folder layouts

The desktop keeps a session-only scope: All (default), Selected, or one folder name. Scope controls both direct linked send/load and the destination candidates in manual Midra import/export review. All does not depend on selection; Selected with no selection and Folder with no members are empty scopes, never implicit All. Scope changes do not edit viewport selection or saved links. In Folder mode, clicking a folder name changes the scope. Folder rename follows the renamed scope; a missing folder requires choosing another scope. The scope is omitted from project/settings/export representations.

Direct send/load captures stable layer IDs and their saved (screen, layer) links when clicked. Switching scope while a read is pending cannot redirect that import. Direct sends validate destination uniqueness within the chosen scope, across each screen. Duplicate destinations within or across folders are valid persistent links. Mapping warnings list other linked editor layers and folders, without preventing link edits. Conflicting sends are disabled before any writes and list every conflicting screen/layer and editor layer in the chosen scope. A conflict-free folder/selection or remapped/skipped review rows can send; out-of-scope links do not block that send. Loading the same device layer into multiple local linked copies is allowed; destination editor IDs must still be unique, visible, and unlocked. Existing geometry validation and atomic import guarantees are unchanged.

The send review lists all scoped editor layers on the currently browsed screen. Saved links on that screen populate editable destinations; empty rows are skipped. Browsing another screen does not rewrite existing links. An explicit destination change saves the new link; a scope change never removes out-of-scope links. Manual device import suggests unique saved links within scope, while retaining manual row remapping until scope/screen changes or refresh. Ambiguous/unlinked rows start skipped. Creating layers is explicit and available only in All/Folder scopes; new layers inherit the scope’s folder (root in All). A successful manual import saves reviewed device links, geometry, source/crop data and new-layer membership in one undoable transaction. Invalid mapping, link or geometry rejects the entire transaction. This uses existing layer fields (unchanged in project v10); there is no schema/version change. Source routing and device memories are not imported.

Layer properties → Mapping edits the existing per-layer midra_link.screen and midra_link.layer fields locally. Unmap saves midra_link: null, so linked sends and loads skip the layer. These edits are undoable and never issue device commands. Connected selectors use discovered screens/layers; offline editing accepts positive numeric IDs. Project schema and version are unchanged.

Opt-in advanced input edits (transient)

The Source tab’s device controls map one-for-one to the installed WebRCS Advanced Input settings. They are separate from the editor’s local source model and its existing combined layer-crop conversion above. Field names, enum values, ranges and input-crop update pulse were checked against the connected Eikos snapshot and app.e42fce4879f318b28cde.js; this change did not write to hardware.

Read the linked Preview layer’s source.pp.input, then the input’s status.pp.plug. The write root is device/inputList/items/INPUT_N/plugList/items/P/settings/:

SuffixEncoding / units
aspect/pp/signalNATIVE, 5_4, 4_3, 16_10, 15_9, 16_9, 21_9, 256_135, 64_27
aspect/pp/transformToSIGNAL, 5_4, 4_3, 16_10, 15_9, 16_9, 21_9, CUSTOM
aspect/pp/customRatioInteger ratio × 1000, 250–10000; UI displays 0.250–10.000
aspect/pp/layerFillLAYER_SETTING, 1_1, CENTERED, FULLSCREEN, CROPPED
cropping/control/pp/predefinedNONE, LETTERBOX_1_78, LETTERBOX_1_85, LETTERBOX_2_35, PILLARBOX_1_33
cropping/control/pp/left, right, top, bottomWhole input pixels, 0–8191

Input crop is processed before layer crop/zoom and does not set layer-container resolution. These settings are shared across consumers of the physical input; they are not bank-local. A Preview geometry send with opted-in input edits can therefore affect a Program layer using the same input. Layer exports continue to use their own Centered aspect override; input layer-fill edits may affect other layers configured to inherit input settings.

The checkbox defaults off; merely enabling it or opening the tab stages nothing. Only edited fields are retained; reverting to the captured value removes the edit. Plans include a staged field only when an explicitly mapped destination in the chosen physical bank currently uses that input and plug. A Program layer with different routing does not receive the Preview input’s edits. Duplicate mappings to one input add each field once per screen plan. Raw input edits are listed in Exact device changes and apply to both reviewed and direct linked sends. They never route sources or write unrelated input defaults.

Input field writes precede layer writes. After writes, each changed input crop gets its own cropping/control/pp/xUpdate false→true pulse, then the normal preset update pulse runs. Readback checks edited values, excluding intermediate pulse values. Existing partial-failure reporting applies; no automatic rollback or resend. Refresh/load reads resulting device content geometry; the input controls do not predict device resampling or update the local source model.

This is session-only state, not part of project JSON, SVG, preferences or recovery. Uncheck, disconnect, address change and project load discard staged input edits and reset opt-in. Existing files migrate without changes and never opt into shared input writes. No persistent format/version change is introduced.

Fractional device content reports

Native-source compatibility compares the editor’s integer resolution with the same rounded content dimensions used during snapshot import (nearest pixel, positive halves upward, original values bounded to 1–16384). Fractional reports such as 1919.7 × 1080.2 therefore match 1920 × 1080 instead of blocking a send. Actual resolution mismatches still fail. Snapshot feedback reports the rounding; raw device state is not rewritten. Existing whole-pixel size/position export and crop quantization remain unchanged.

All manuals

Midra input preview stills

The Rust adapter uses the configured IP and optional port for this endpoint (default 80), including emulator addresses such as 192.168.10.146:3000.

This is a device-read interface, not a new project or export format. Verified on Eikos 4K firmware 3.3.10, WebRCS app.e42fce4879f318b28cde.js.

Discovery and request

The connected snapshot’s /device/inputList/items/INPUT_N supplies:

  • status.pp.isAvailable: only existing hardware inputs appear.
  • status.pp.plug: selects plugList.items[plug].status.signal.pp.isValid for the last-read signal indicator.
  • snapshot.pp.enable: capture is disabled in the editor when WebRCS snapshots are disabled. The application does not write this field or snapshot size.

Each input-selection capture, explicit Capture still, or automatic timer request issues GET http://<configured-IP>/api/device/snapshots/inputs/N, with N an integer 1–16 and Cache-Control: no-cache. IPv4 and IPv6 literal addresses are accepted; no proxy or redirect is followed. No immediate retries, WebSocket subscription, still-library capture or source-routing/preset writes are involved.

Only one request may be in flight, with at least five seconds between starts. Closing the separate import dialog discards its pending dialog result; cancelling a request also discards its result. Neither permits another request until the first completes or times out. Closing layer properties does not cancel a direct layer capture. The request has a 5-second connection timeout and 20-second overall timeout. Device-provided resolution is retained; no request to increase resolution or refresh frequency is made.

Response and validation

A successful response must be a PNG, at most 16 MiB, and pass the common image decoder’s dimensions/allocation limits. HTTP errors, redirects, invalid PNGs, oversize responses and decode errors leave references unchanged. The active-input test returned 512 × 288 pixels; an inactive input returned a blank 128 × 128 PNG. The device controls image freshness (Last-Modified) and resolution; GET fetches the latest available snapshot, not a guaranteed new full-resolution frame. Signal indicators may be stale until reconnect/refresh.

Input picker filtering

Both the per-layer Preview picker and Import input snapshot picker hide inputs whose last-read active plug reports no valid signal. Show inputs without signal, inside each dropdown, reveals those available hardware inputs with a No signal label. The toggle is shared for the session and defaults off; it is not persisted. Unavailable hardware inputs remain excluded. An explicitly chosen input is retained and labelled if it loses signal or is hidden by this filter; filtering does not change assignments, capture availability or refresh eligibility. With no signal-bearing inputs, initial selection remains empty until the user reveals and chooses one. Signal status comes from the connection snapshot and updates when the connection is refreshed, not from PNG polling.

Editor and persistence

Import input snapshot… displays the image and its actual pixel dimensions. Its destination selector lists every editor layer by stable ID and a Reference image option, independently of current selection. Layer destinations offer Keep refreshing this layer; this is staged until Import into layer and sets that layer’s automatic-refresh flag. Reference destinations never expose or apply that flag and remain fixed images. Import does not alter selection or geometry. Add as reference is explicit and obeys the 32-image/64 MiB combined-reference limits. Existing upscale/aspect warnings apply. Capture in this separate import dialog only stages an image until Import into layer or Add as reference is chosen. Changing device address/disconnecting invalidates the pending preview; input changes clear the old preview. A cancelled/late result cannot become a new reference.

The initial image name contains the input number and configured device IP. Added stills use the existing project reference object: name, embedded PNG image_base64, visible, opacity, preserve_ratio, native_size, offset. No new fields, version or migration are needed. Import into layer assigns a session-only still texture to the destination editor layer’s stable ID and current local input. It uses the editor’s native source rectangle, input crop and dynamic crop/zoom mapping, including faded overflow while editing. It does not infer or change device routing. Changing the local input hides that assignment; opening/New/Recovery clears assignments. Reordering layers does not move an assignment to another layer.

In the layer Preview tab, the workflow is Enable input preview → Input → automatic first still → optional Capture still / Auto-refresh this preview. Enable and auto-refresh are separate per-layer booleans saved in project version 11. An enabled preview may have an input selected but no texture yet. Capture still directly replaces only that layer’s texture; repeating it recaptures. Auto-refresh can fetch the first image without a manual capture. The physical input picker uses available device inputs and is unrelated to the editor input identity or Midra layer mapping. Input changes discard the old image. Manual jobs bind to the layer’s stable ID, source identity, physical input and host at request time; selection changes do not redirect results. Changed/removed assignments and disabled previews reject late results. Disabling a preview hides its image and pauses requests without losing its still or chosen opacity. Crop guide opacity is a per-layer saved value from 0–100%, initially 35% when assigned. The source test-pattern guides paint above the image; selection borders/handles remain opaque. When the preview is hidden or absent, the slider is disabled at 100% and the original opaque pattern is used. Showing the preview again restores the chosen opacity. Outside-box content retains the existing 50% ghost treatment. The same mapping/compositing is used in the viewport and the dedicated Preview tab in Layer properties. That tab contains capture, auto-refresh, visibility and guide-opacity controls; Crop contains geometry controls. Opening Preview does not activate visual crop editing. The layer context menu also exposes preview controls.

Layer-preview assignments, original image bytes, visibility toggles and guide opacity are saved in project version 11, but omitted from geometry exports. Add as reference remains the fixed-reference path; generic artwork exports include those references only through the existing background option. Reloading a project makes no capture requests. Auto-refresh this preview is opt-in per layer and restored paused, with a shared request interval of 5–300 seconds (default 10). Assignments also retain the device address and physical input number in the project. Visible layers with enabled automatic previews, unchanged local inputs and the current device address are eligible; unavailable or snapshot-disabled inputs are skipped. Unique inputs refresh round-robin, one request per interval. Every completed capture (manual, selection or timer) shares one decoded texture across matching automatic previews and layers queued for a first still on the same device/input, including targets queued while the request was running. Matching one-shot requests are consumed together on success or failure, so a failed fetch does not retry once per layer. A queued snapshot-import preview can share the result too, but still requires explicit import. Changed, removed or disabled targets reject the result; other inputs keep their own requests. Existing manual stills without a queued capture are never replaced by another layer’s capture. Selecting an input queues a one-shot capture in either picker, including the first signal-bearing input selected when opening snapshot import. Selection captures use the shared five-second minimum rather than waiting the configured refresh interval, and take priority over periodic refreshes. While cooling down or fetching, only the latest choice per target is retained. Closing snapshot import, disabling a preview, changing its source/device or removing its layer cancels its queued request. Snapshot-disabled/unavailable inputs are not requested. A failed selection capture is not retried automatically unless auto-refresh is enabled. Capture still remains available for explicit recapture; importing the dialog image remains explicit. Manual, selection and automatic capture share one worker slot and the five-second minimum. Automatic capture pauses offline, during project loading and while the capture dialog is open. Errors retain the last good image and wait for the next interval; there are no immediate retries. Turning off refresh prevents applying an in-flight automatic result. Project replacement restores saved assignments and discards stale results. Automatic refresh never changes fixed references or device settings. Timer settings are persisted in project version 11. Saved automatic previews stay paused until an explicit capture or resume; opening a project makes no device requests. Live feeds and separate image-file saving are not implemented.

After successful connection/linked load or device-layer import, untouched layer preview controls preselect the linked device layer’s INPUT_n source when that physical input is available. Signal presence is not required. Existing selections are preserved; no texture, enabled flag, auto-refresh flag or capture-on-selection request is created. Opening/enabling these controls does not fetch the preselected input; Capture still or explicit auto-refresh starts capture. The preselected input is saved with the preview assignment in project version 11.

All manuals

Eikos connectivity and Preview check

Verified on 2026-11-13

User-authorized hardware check on an Eikos 4K, firmware 3.3.10. The unit reported this identity through GET /api/tpp/v1/system. Its WebRCS bundle was app.e42fce4879f318b28cde.js. The device address was supplied for this session; it is not a compiled-in application default.

  • HTTP read access and WebRCS WebSocket feedback worked without authentication on this configured device. Do not assume other installations permit this.
  • GET /api/stores/device returned the state tree used by WebRCS, including screen canvas dimensions, layer center positions/container sizes, source assignments, crop/mask fields and transition state.
  • The explicit REST read /api/tpp/v1/screens/2/live-layers/1/presets/preview reported input 4, matching the internal Preview bank. That REST response contained source/status, not the full geometry. Geometry was obtained from the WebRCS state endpoint.
  • Screen 2’s transition state was AT_DOWN: Program was DOWN, Preview UP. WebRCS’s own bank-selection code maps AT_UP the other way around. These are physical banks, not permanent Program/Preview identifiers.
  • A single Preview layer property was changed over the WebRCS WebSocket: screen 2, bank UP, layer 1, position.pp.posH, 1436 → 1437 → 1436. Readback confirmed the intermediate change and restoration. The complete tested layer matched its original state after restoration. All four screen Program preset trees matched before, during and after this test.
  • No TAKE, CUT, transition, Program, input/global crop, output configuration, source-routing or preset-memory command was sent. Raw snapshots remain temporary local artifacts and are not committed.

The message envelope observed and tested was channel: "DEVICE", with data.path an array of state-tree keys and data.value the new scalar value. The read path for the tested property was:

device/screenList/items/2/presetList/items/UP/liveLayerList/items/1/position/pp/posH

This is evidence of a working bidirectional link, not validation of either advanced-crop export strategy. Only horizontal center movement was exercised. The WebRCS internal endpoint/protocol is firmware-specific, rather than a promise of stable public REST geometry support. Manufacturer references are linked from the official Eikos downloads section. The linked API PDFs were not accessible during this check; protocol findings above come from the installed device and its own WebRCS bundle.

Read-only import bridge

Open Midra connection… in the main menu or Settings → Midra integration. Enter the device IP and click Connect. Then open the separate Import → Midra layers… window. Reads run in a worker thread; canceling discards late results. Choose a screen and choose a destination beside each device layer: Do not import, New layer, or an existing visible, unlocked editor layer. Click Import layers directly in this window; no prior selection or matching layer count is required. Duplicate or removed destinations are rejected without partial changes. The entire import, including new layers, is one undo step. Output resolutions must match. Reading never changes the document; only applying the reviewed import does. An optional Try autoconnecting at startup preference makes one background read attempt using the remembered address. No polling or automatic retries occur. The address is remembered in application settings; no credentials are stored. The footer shows ONLINE after a successful read (last-read status, not continuous monitoring), and OFFLINE when refreshing, after a failed read, or after editing the address.

The Rust adapter was tested against the same Eikos 3.3.10: two 1920×1080 screens; disabled zero-canvas screen slots are filtered. A CLI smoke check is available:

cargo run -p midra-layout --example read_midra -- DEVICE_IP

A standard-library Python helper remains available for snapshot capture/offline replay:

python3 tools/midra_probe.py --host DEVICE_IP --save-snapshot /tmp/eikos-state.json
python3 tools/midra_probe.py --host DEVICE_IP --screen 2 --layers 1 2 --svg /tmp/preview.svg
# Replay a saved snapshot without connecting:
python3 tools/midra_probe.py --snapshot /tmp/eikos-state.json --screen 2 --layers 1 2 --svg /tmp/replay.svg

Select the matching number of editor layers, choose Import → Geometry file…, and review mapping before applying. Match the editor output resolution to the device canvas; SVG geometry import does not replace the editor’s screen settings. The helper exports container geometry only: center minus half-size becomes top-left x/y, preserving half pixels. Source aspect fitting can make the visible picture differ from this container. Routing, source resolution, source cropping, effects, borders, opacity and zoom are not imported. Nonzero layer crop or mask is refused rather than silently imported as final visible bounds. Device slots are explicitly selected; unused slots are not assumed to be available layers.

The helper has no device write operation, bypasses system proxies, refuses redirects, bounds reads to 32 MiB and never overwrites an existing output file. Snapshots may contain network/private configuration; keep them out of Git and sanitize before sharing. Its exchange contract is documented in interfaces.

Reviewed send and cropped-layer round trip

The user’s later authorization permits Program changes and accepts the physical-bank TAKE race. This supersedes the earlier Preview-only restriction above.

Export → Configure Midra export… now supports explicit Preview or Program targeting, per-selected-layer destination mapping, output-sized or source-aspect containers, and exact before/after field review. Each send writes directly, then reads the device back; it does not reject changes made since the snapshot. A partial or uncertain result is reported without automatically repeating or rolling back writes. Local editing, importing, undo/redo, connection and project loading never send.

On Eikos 4K firmware 3.3.10, both sizing modes passed actual write/readback/restore checks on screen 2 Preview layer 1 (UP) and Program layer 2 (DOWN). Cases used a 301 × 251 visible box at 12.5, 34.5, 1920 × 1080 native input corrected to 1920 × 1000, 200% content zoom and offsets +30, −10. All nine fields (size, center, four crop edges, Centered aspect) matched readback; original values were restored after each case. A final snapshot confirmed all screen preset trees matched their pre-test state. The imported visible geometry matched within one pixel. Device-source routing, TAKE, input configuration, output configuration, masks and effects were not changed.

The installed WebRCS bundle maps crop edges linearly from 0–65535 to 0–100% or 0–contentWidth/contentHeight pixels. Its layer size limits are 0–65535 and center limits −67268–67268; this adapter requires positive dimensions. These findings support the device exchange contract.

These tests verify firmware acceptance, readback and mathematical import round trip. They do not replace visual comparison on a physical screen with a known test image; the tested device reported layer state OFF. Platform/display acceptance remains open.

The explicit hardware diagnostic (never part of automated CI) is:

cargo run -p midra-layout --example check_midra_send -- --apply-and-restore DEVICE_IP 2 1 preview
# Program writes are deliberate here:
cargo run -p midra-layout --example check_midra_send -- --apply-and-restore DEVICE_IP 2 2 program

Centered layers with valid content dimensions and no mask now import visible bounds and source-pixel crop framing. Their combined crop is stored in the local layer crop; the device does not reveal which part originated from this editor’s input correction. Other aspect modes retain container-only import and refuse nonzero cropping. Shared input settings and source routing are not synchronized.

The manufacturer’s REST API guide v3.0.13 was inspected. It documents logical Preview source assignment, but not geometry writes; this implementation therefore uses the installed WebRCS WebSocket protocol. The physical bank is captured in the review and remains fixed across the send.

Missing preset apply diagnosed

The operator reported that WebRCS geometry changed while the physical multiviewer Preview did not. The bundled WebRCS code calls z1() after geometry edits, which dispatches DEVICE_PRESET_CONTROL_SET_ONE for xUpdate false, then true. The device snapshot had device/preset/control/pp/enableAutoUpdate: false. Earlier tests checked only staging-store readback and therefore did not establish that geometry had reached video processing. The exporter now sends this apply pulse after geometry writes, even when no geometry fields differ. A direct pulse was sent to the connected Eikos to apply its already-staged layout. The operator confirmed that the physical multiviewer Preview then matched WebRCS, establishing the missing apply pulse as the cause. Layer status OFF is not sufficient evidence that the operator’s layers are disabled, and must not be used as that diagnosis.

Input preview capture checked on 2026-11-14

The same WebRCS client exposes GET /api/device/snapshots/inputs/:id. A read-only request to active input 3 returned HTTP 200, PNG, 512 × 288 (591155 bytes). Input 1, with no signal, returned a blank 128 × 128 PNG. The input state reported snapshots enabled with size 512_512; the active image retained its 16:9 aspect. The response included Last-Modified and Cache-Control max-age=0. No continuous stream or write was needed. Raw input images/state stay temporary and are not committed.

The implementation fetches a still only on demand, limits concurrent requests to one and enforces a five-second minimum interval. It does not change snapshot enable/size, input routing, capture-library commands or any preset. See input preview interface.

Allocated layers versus firmware slots

The snapshot contains eight live-layer slots per screen, even when the active configuration allocates only one or two. The Rust adapter reads device/preconfig/status/stateList/items/CURRENT/screenList/items/{screen}/pp/layerCount and exposes only IDs 1 through that count for import, mapping and sending. The cached Eikos state reported one allocated layer for screen 1 and two for screen 2; other screen allocations were zero. This is independent of input routing, signal presence, OFF state and the number of physical inputs. Background and foreground are not live-layer destinations. Staged NEW configuration is ignored.

All manuals

Viewport performance

Midra Layout · Guide contents · Starter files

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.

All manuals

Updating the Midra Layout screenshots

Midra Layout introduction · Detailed user guide

The introduction uses real application captures, not the design mockups in ../design/. Each image has an adjacent HTML comment in the introduction that points to its recipe below.

Capture provenance

Captured on 2026-11-14 from the default-feature debug build at source commit ba67f21, on Linux/X11 (XFCE). The app’s client area was 1440 × 940 pixels, at 100% display scaling, with the default dark theme. Screenshots are unedited PNG captures of the app client area, without desktop decorations or the mouse pointer. The original captures used ImageMagick import -window <window-id>; a temporary Python ctypes helper located the isolated process’s X11 window and used XTest clicks to select the controls. The helper is not required to reproduce the images: the same steps can be performed manually.

All images use the built-in example backdrop and the default 1920 × 1080 project. No external artwork, saved user project or device connection was used. The footer should read OFFLINE. No hardware reads or writes are needed.

Prepare a clean session

From the repository root, build the current app and start it with temporary user settings and recovery storage. Use a new temporary directory for each capture session so that earlier recovery data does not replace the default layout.

cargo build --locked -p midra-layout
MIDRA_DOC_SESSION=$(mktemp -d /tmp/midra-layout-docs.XXXXXX)
XDG_CONFIG_HOME="$MIDRA_DOC_SESSION/config" \
XDG_DATA_HOME="$MIDRA_DOC_SESSION/data" \
  target/debug/midra-layout

These isolation variables apply on Linux. On another platform, use an isolated user profile or restore the same default project and theme before capturing. Keep the default window size and 100% display scaling. The output canvas is 1920 × 1080; the two layers are 01 / Presenter and 02 / Slides, each 640 × 360. Select 01 / Presenter in the Layers list. Do not move or resize it.

After each action, move the pointer into empty space below the canvas, without clicking, and wait for the UI to settle. Clicking empty space clears selection. Dismiss any notification or tooltip before capturing.

With ImageMagick, run the following in a second terminal and click the Midra window to select it. Alternatively, use your desktop’s “capture window” action with the pointer and window border excluded.

import docs/midra-layout/images/01-workspace.png

For a known X11 client-window ID, the equivalent command is:

# Set MIDRA_DOC_WINDOW to the ID of this temporary Midra Layout window.
import -window "$MIDRA_DOC_WINDOW" docs/midra-layout/images/01-workspace.png

Capture each state below to its corresponding filename. Keep the full client area; do not crop, add annotations, or substitute a mockup. Close the temporary app after the last capture.

01-workspace.png

Start from the clean session with 01 / Presenter selected and no menus or dialogs open. Both layer boxes should be visible. The right inspector shows 640 × 360 dimensions and measurements from the top-right corner: 120 pixels from the right and 180 pixels from the top. Capture the workspace.

02-layer-properties.png

From the workspace state, click the 640.0 × 360.0 px / 16:9 resolution field in the right inspector. Keep the Layer tab selected in the Layer properties window, with Keep aspect when resizing checked and the original width and height unchanged. Do not move or resize the properties window. Capture it over the canvas.

03-crop.png

From the Layer properties state, click the Crop tab. This activates visual crop mode and displays the source pattern on the canvas. Leave the default 100% zoom and centered content unchanged. Capture the crop controls and preview. Do not connect a device or import an input snapshot to reproduce this picture.

Check the update

  • Open all three PNGs and confirm the intended controls and layer labels are readable.
  • Check that there are no tooltips, transient notifications, unrelated windows or private data.
  • Preview the introduction and keep its captions and image alt text consistent with the UI.
  • Update the capture date, source commit and any changed steps in this file; keep the adjacent screenshot comments current.
  • Commit the three PNGs and documentation changes together. Temporary settings and captures do not belong in Git.

All manuals

Midra layout helper: implementation status and backlog

Reconciled on 2026-11-14 against the current editor, device adapter, regression tests and recorded Eikos 4K firmware 3.3.10 hardware checks. This replaces the original draft checklist: unchecked items below are actual remaining work, not already implemented features awaiting a historical milestone.

The original visual proposals are retained below for design context. The user guide describes current controls; the device-send contract and hardware findings distinguish automated tests, device readback and physical-screen acceptance.

Completed implementation

  • Rust/egui workspace app; canonical pixel geometry, stable layer/input IDs, source/input/layer formats, custom output resolutions, corner/center conversion and full-precision geometry with one-decimal display/whole-pixel export.
  • Multi-layer viewport, selection/marquee, movement/nudging, pointer-centered zoom/pan, fit controls, eight resize handles, aspect lock, pivots, proportional group resizing (same, horizontal mirror, opposite), alignment and undo/redo.
  • Snapping during movement and resize, pixel grids/rulers, screen-center and quarter guides, other-layer edges and temporary modifier overrides.
  • Advanced input/layer cropping, content zoom/offset, visual crop handles, reset, double-click entry and translucent retained-content surroundings.
  • Layer add/remove/rename/order, lock/visibility, collapsible single-level folders, folder selection/rename/reorder and drag organization. Folder eye/lock currently edits member flags in bulk; it is not inherited state.
  • Multiple fixed reference images, drag/drop/picker, per-image visibility, opacity, native-size/offset, proportional fit/stretch warnings, outline-only layer display and adaptive image filtering.
  • Reference imports and project/recovery reads, parsing, validation and embedded-image decoding run off the UI thread. Loading is atomic; failures preserve the editor. Manual project loading is cancellable and recovery autosave pauses while loading.
  • Explicit Midra input snapshot capture: available-input picker, still preview, Use for selected layer, preview visibility and guide-opacity controls, plus Add as reference. Optional timed refresh (default 10 seconds), one request at a time and at least five seconds between requests; visible previews only.
  • Clipboard/import mapping review with per-row target/ignore, independent size/position/available-zoom toggles, draw.io stroke handling and own-copy round trips. Real draw.io clipboard sample and draw.io-exported SVG supported.
  • Ten-format file exchange: SVG, draw.io, geometry JSON, CSV, DXF/DWG, HTML, PPTX, FIG and AI through VectorCraft. Shared geometry, scope and review, optional artwork where supported, page/frame selection and licensing build flag. Two-layer Full HD and UHD templates exist for all ten formats.
  • Project JSON v11, tested legacy/recovery migration, saved layer links, central application preferences, full Settings, themes and recent-theme list.
  • Separate Midra connection and mapping/transfer controls, saved address, optional startup connection, online status, explicit direct linked send/load and configurable mapping review. Scope defaults to All with Selected/Folder. Unmapped rows skip; duplicate destinations within a send scope are rejected.
  • Persistent per-layer screen/layer links, Mapping properties and Unmap. Reordering/visibility do not alter links; alternative folders can reuse targets.
  • Multiple editor layers may share one Midra destination. Mapping warns with other linked layer names/folders; sends reject overlaps only within the chosen scope. This replaces the earlier extra-links-per-layer proposal. Nested folders and additional file codecs have been removed from scope at the user’s request.
  • Both device sizing strategies, Centered-crop imports, required preset apply pulse, rounding/reconstruction checks and readback. Preview/Program protocol checks on Eikos 3.3.10 are recorded; Program availability is a user preference.
  • Advanced shared-input settings are explicitly opt-in; only edited fields are sent while enabled. This supersedes the original “never write input settings” scope. Routing, TAKE and live playback control are not implicit geometry actions.
  • Geometry/import/UI/mock-device regression tests, workspace CI, coverage, documentation and release build configuration integration.

Remaining feature work

  • Aquilon / LivePremier adapter. Protocol investigation and implementation sequence completed. Next: emulator baseline, firmware-aware geometry import, family-aware saved links, send/apply/readback, then verified crop and capture support. Aquilon is not enabled yet.

  • Further export/workflow cleanup. Shared transfer scopes, mapping review and direct linked send/load are implemented; further changes await specifications.

  • Additional native clipboard adapters. Obtain actual software/version clipboard samples before implementing or claiming Inkscape, Illustrator, Figma, etc. clipboard support. File import is not native clipboard compatibility.

  • Non-Centered/masked Midra layer import. Expand conversion only after verifying those semantics. Source routing synchronization remains separate from the opt-in shared-input settings editor.

  • Optional capture extensions, if wanted. Standalone capture saving as separate image files is not implemented. Project version 11 saves layer-preview assignments, stills and refresh settings (restored paused); low device load remains a requirement for any refresh extension.

Confirmed format acceptance

User-confirmed working on 2026-11-14; these format issues are solved:

  • PPTX — working flawlessly.
  • draw.io — working.
  • SVG — working.

Remaining acceptance and release checks

  • Compare known test images on the physical output for both sizing strategies, asymmetric/extreme crops and source aspects. Device readback is not visual proof.
  • Broader firmware/source-format coverage, including exhaustive device limits, all corner/center placements and non-Centered/masked configurations.
  • Operator-laptop checks: dense reference at Fit/100%/400%/1600%, large-project loading, GPU memory and measured drag responsiveness; aim for a 60 Hz interaction budget. Worker decoding does not remove GPU texture upload cost.
  • Windows/macOS/Wayland clipboard, DPI/GPU presentation and native-dialog checks. Headless Linux interaction tests do not replace platform acceptance.
  • Accessibility/tab order, enlarged text, contrast and narrow-window review; verify complete setup → position → crop → paste → copy → undo → send/load workflows.
  • Exercise portable release bundles on target machines and complete the release checklist. Build/CI integration already exists; this is packaging acceptance.

Verification notes

Input capture was tested with the connected Eikos on 2026-11-14: a read-only GET returned a 512 × 288 PNG from active input 3; inactive input 1 returned a blank 128 × 128 PNG. See snapshot contract. No input routing, snapshot settings, still-library slot or layer was modified. Snapshot dimensions/freshness are device-controlled and broader firmware behavior remains unverified.

The remaining validation entries above deliberately stay open. Implemented code, passing regression tests and protocol readback do not substitute for operator acceptance or physical-screen inspection.

Coordinate model and historical visual proposals

Implemented internal model: screen origin at its top-left, X increases rightward, Y increases downward, and a layer’s final visible box is (x, y, width, height). Positive corner offsets point inward. Matching corners are the default; the current editor also supports independent screen/layer measurement points and center anchors.

For screen size W × H, layer size w × h, and offsets dx, dy:

Selected cornerLayer left xLayer top y
Top leftdxdy
Top rightW - dx - wdy
Bottom leftdxH - dy - h
Bottom rightW - dx - wH - dy - h

For uncropped geometry, the visible-box center values are horizontal = x + w/2, vertical = y + h/2. The inverse subtracts the half-size. The corresponding inward margins are left=x, top=y, right=W-x-w and bottom=H-y-h. Switching corner just chooses which margins to display.

Example used in every mockup: on a 1920 × 1080 screen, a 640 × 360 layer 120 px from the right and 180 px from the top has top-left 1160, 180 and center 1480, 360. The other layer is at 120, 180, center 440, 360. An odd width such as 641 produces a half-pixel center when the left edge is an integer; the device exporter quantizes geometry and verifies reconstruction error. See the device-send interface for container corrections. Advanced cropping must retain these visible-box coordinates while deriving any distinct device container through its adapter.

Visual proposals

These are original, editable SVG interface mockups, not application screenshots. Open them in a browser or image viewer to inspect at full size. The example background is illustrative artwork standing in for an imported picture. Labels such as “Copy” and “Paste” illustrate planned controls; nothing is interactive yet.

Dark slate surfaces, cyan selection, amber second-layer identity and a restrained purple primary action consistent with existing repository interfaces. A large viewport occupies the left; the fixed right inspector groups the layer list, corner selector, offsets, size and WebRCS outputs in reading order. Thin outlines, corner markers, center crosshairs and dimension guides make selection unambiguous.

Best for working beside show-control tools. The tradeoff is less contrast against dark reference images; add a contrasting outline halo and an outline-only mode. Keep the output card visible while upper inspector sections scroll. A compact bottom status line carries camera/pixel information and shortcut hints.

B. Precision desk

A light inspector and drafting surface with screen-coordinate rulers. The same placement workflow emphasizes measurements and field readability. The artwork retains its own colors independently of the UI theme.

Best for daytime preparation and detailed artwork matching. It uses more visible measurement marks and can feel busier; rulers and guides should be optional. Its useful features can be incorporated into A without maintaining two different apps.

C. Focus desk

A wider viewport and narrower contextual inspector. This proposal illustrates the multi-selection state: a named reference layer, explicit alignment actions and a compact per-layer coordinate table. The layer list remains on the right.

Best for repeated placement and comparison once the basic workflow is familiar. Less space for numeric explanations makes it weaker as the initial default. The alignment state is now available under step 7; the SVG remains a design concept.

Shared interaction and responsive behavior

Keep the screen aspect ratio exact, surround it with a neutral pan area, and use consistent screen-space selection markers. Display only relevant guides, with labels in screen pixels. Layer identity and selected state must be distinct. Always allow selecting a layer from the list when its outline is hard to hit.

The desktop window should retain a right inspector at normal working sizes. At narrow widths, reduce decorative padding and collapse secondary sections; below the proven minimum width, use a right drawer rather than crushing numeric fields. At short heights, scroll sections while retaining access to conversion outputs. Mouse and keyboard interaction are the first priority; a mobile UI is not part of this desktop tool.

Research and open decisions

The Analog Way Midra 4K V3.2 manual, July 2024, pp. 83–85 documents layer alignment, snapping, position and size controls. This supports the workflow research; it does not establish the precise coordinate convention or current firmware behavior for the user’s installation. Avoid portraying all WebRCS versions as lacking alignment. The proposed improvement is more explicit corner-based positioning and reference-image inspection.

Figma’s zoom/view documentation provides useful precedents for fit-to-view, selection zoom and pixel inspection. Borrow those interaction ideas, without introducing vector-editor features.

Analog Way’s Midra 4K FAQ identifies an offline simulator that may help verify behavior without connecting this helper to hardware. Simulator agreement should still be checked against the installed WebRCS version.

The installed firmware is recorded as Eikos 3.3.10. Primary operator OS/display scale and broader platform acceptance remain to verify. Concept A is approved; the user-supplied draw.io clipboard rectangle is retained as a regression fixture. The implementation and backlog at the top of this document supersede the original mockup assumptions.

All manuals

Development

Documentation · CI and coverage · Releases

Layout and workflow

DirectoryPurpose
tools/Python prototypes and document utilities
tests/Python regression and CI/packaging tests
crates/<tool>/Rust ports, each with its own source, tests and assets
scripts/Shared CI and release helpers
docs/Tool usage and specialized workflows

Prototype in Python, then add a Rust workspace member when the workflow is stable. Retire the Python implementation once the Rust port is validated. The PPTX reporter is now Rust-only; the document exporter remains Python. The rundown converter is a separate Rust workspace member with CLI and egui interfaces. Its implementation checklist and evaluation corpus track coverage and remaining limitations. Avoid speculative shared crates; extract common code when multiple tools need it.

The root Cargo.toml owns workspace metadata, the shared version and build profiles. Members inherit that metadata. Keep one root Cargo.lock and target/. The reporter is the default member; CI explicitly checks the entire workspace. Use -p pptx-reporter to select it when building from a multi-tool workspace.

Checks

Use a recent stable Rust toolchain. Python tools need 3.9+; CI helpers need 3.11+. Run from the repository root:

cargo fmt --all --check
cargo clippy --locked --workspace --all-targets --all-features -- -D warnings
cargo test --locked --workspace --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --locked --workspace --all-features --no-deps
python3 -m unittest discover -s tests -v
cargo build --locked --workspace --all-features

Rust regression tests cover archive parsing, trimming, loops, report formats, Ontime, CLI errors and GUI state; both PDF layouts compile with the embedded engine. Probe-process tests use a controlled stub. No external FFmpeg, FFprobe or Typst CLI is required for CI. The application still needs FFprobe at runtime. Python exporter tests mock external document applications. Inspect rendering changes visually as well.

cargo build -p pptx-reporter --no-default-features builds the CLI without the GUI or PDF engine; add --features pdf to restore embedded PDFs.

Keep generated files out of Git. Commit each completed task after checks; do not push without authorization. See CI and coverage and cross builds and packaging.

The converter can run without desktop dependencies using cargo run --locked -p rundown-converter --no-default-features --bin rundown-converter -- --help. Its tests generate synthetic XLSX inputs and never require private source files or network downloads. The existing workspace test, lint, Rustdoc and coverage commands include both tools; reporter release packaging remains separate.

The ASCII filename cleaner is a separate Rust workspace member. Run cargo run --locked -p ascii-names for its drag-and-drop window, or pass a folder for CLI cleanup. It uses the same workspace checks and coverage gates.

All manuals

Midra Layout changelog

All changelogs

Unreleased

  • Audit project persistence: version 11 now saves snapping/grid setup, group resize mode, collapsed folders, capture assignments/stills, guide opacity and refresh settings. Saved auto-refresh reopens paused. Versions 1–10 migrate explicitly; invalid previews leave current work intact. Added round-trip/migration and preview restoration regression tests; documented project/application/session ownership in the persistence audit.

  • Preselect linked Midra input sources in untouched capture controls after connection or layer import/load, without enabling previews or requesting images. Preserve operator selections and leave unassigned/non-input sources unselected; regression coverage checks the scheduler stays idle.

  • Replace the nested input-preview context submenu with Configure capture…, opening the layer properties Preview tab directly. Keep long input lists in the window instead of nested popups that can close while selecting near the canvas edge.

  • Group Load and Send mapped layers on the final row of Midra mapping & transfer, with vector down/up arrows and direction tooltips. Keep send preparation separate from the explicit Send click and retain scope-aware loading.

  • Round fractional device-reported content dimensions to whole pixels for centered crop import/readback and send compatibility, with nonblocking before/after warnings. Preserve raw state and fractional box geometry; invalid ranges and genuine source mismatches still fail. Regression tests cover cropped import, warning behavior, both send sizing strategies and invalid ranges.

  • Restore recovery sessions silently instead of opening a “Recovery restored” message. Keep recovery failures and retry information visible; regression coverage checks restored edits and absence of the success popup.

  • Investigate Aquilon/LivePremier compatibility against the upstream web-control implementation; document firmware-specific geometry, bank and apply paths, saved-link constraints, and the staged adapter/acceptance plan. Research only: no Aquilon support or hardware verification claimed.

  • Add a Recent machines picker for the last four successful connections, saved across restarts with distinct ports and most-recent-first ordering. Selecting an entry reads the device immediately; failed attempts do not displace history. Settings v8 migrates v1–v7 with empty history; tests cover ordering, deduplication, failures, persistence and validation.

  • Support optional device ports for HTTP state reads, input captures and WebSocket sends, preserving the address in preferences/autoconnect. Accept all four Midra 4K identities (Eikos, Pulse, QuickVu, QuickMatrix) with device-reported allocation. Read-checked Pulse 4K 3.3.7 at port 3000 (four layers); add address, model, capture and WebSocket port regressions. Other model hardware acceptance remains outstanding.

  • Replace the layer-header Folder, Add image and Manage text buttons with compact vector icons, grouped on the right, with tooltips and accessible action names.

v0.7.0 — 2026-11-14

  • Split the Midra mdBook into Quick start and Advanced sections, with a first-layout walkthrough and nested workflow/contract chapters. Keep the existing detailed chapters and screenshot capture notes linked.

  • Update the shared Rust application version to 0.7.0; see the release notes.

  • Add direct links to the published mdBook manual from the project README, tool guide and documentation indexes.

  • Mark PPTX, draw.io and SVG format acceptance as solved following the user’s confirmation that all three work (2026-11-14).

  • Replace the incomplete DXF skeleton with the official shared Craft DXF document writer/reader; add optional Craft DWG exchange with the same pixel geometry and canvas limits. Refresh CAD starter files and cover document structure, binary DXF and DWG round trips. Add a byte-preserving ZIP of the AI templates to bypass Gitea/browser PDF preview downloads.

  • Place insufficient import-destination warnings directly below the destination scope selector instead of repeating them near the Import button.

  • Simplify geometry/clipboard import into a shared review without repeated acquisition controls. Collapse clipboard and before/after details, emphasize destination mapping, and add independent All / Selected / Folder scopes plus per-item exclusion. Preserve compatible mappings and canvas selection; regression tests cover scope filtering, atomic import and review visibility.

  • Route supported geometry file drops through the regular asynchronous import/mapping review, including SVG/draw.io and native formats when available. Keep raster drops as references; support path/data drops and multiple documents through the file/page chooser, with a combined 16 MiB limit and atomic failure. Regression tests cover codecs, case-insensitive names, batches and invalid/oversized inputs.

  • Add an mdBook manual built from the existing guides, with local assets and downloads. Jenkins publishes successful main builds under /mnt/books/manuals/; staging, link validation and scoped publication have regression coverage.

  • Replace the long overview with a visual quick start, move detailed workflows into topic guides, and centralize all nine starter-file formats in one catalog. Add real application screenshots with reproducible capture notes; retain the existing template files and validation contracts.

  • Clarify shared Midra links: warn with other linked layer/folder names while allowing link edits; disable conflicting scoped sends and list all overlapping destinations. Preserve conflict-free folder/selection sends and remapping. Remove nested-folder/additional-codec backlog items and replace the extra-links proposal with this shared-destination workflow. Regression tests cover warning text, send blocking and scope isolation.

  • Remove duplicate overlay-grid controls from snapping menus; keep them in the adjacent Grid toolbar menu and a separate section in Editing preferences.

  • Move the background grid out of the sample artwork into a full-output overlay above reference images. Add a Grid toolbar menu, independent visibility/snapping, and 1–64 columns/rows (default 8 × 6). Persist these preferences in settings v7 with migration from v1–v6; share fractional grid positions across movement, resizing and pivot snapping. Regression tests cover rendering order, toggles, snapping and settings compatibility.

  • Keep the screen name and output resolution visible with reference images, reserving their fit-screen margin. Viewport tests check label visibility and clipping with and without imported images.

  • Double-click again in visual crop mode to finish editing; preserve selection and framing. Viewport regression coverage checks entering, exiting and reopening without geometry changes.

  • Pool input captures across matching queued layers and automatic previews, including requests queued during a fetch. Share one decoded texture and consume matching requests on failure to avoid per-layer retries; preserve existing manual stills. Regression tests cover direct, automatic and import captures, failure handling and different-input isolation.

  • Capture a first still automatically when selecting a preview input, in both pickers. Queue the latest choice behind the shared five-second throttle and active request, without waiting the auto-refresh cycle; retain explicit recapture/import. Regression tests cover throttling, coalescing and cancelling stale targets.

  • Hide no-signal inputs by default in both preview pickers; add a shared session-only Show inputs without signal toggle and explicit No signal labels. Preserve existing choices when filtering or signal loss occurs, and leave initial selection empty when no input has signal. UI tests cover both pickers and the empty state.

  • Add Import input snapshot… with an explicit destination picker for any editor layer or a fixed reference image. Layer imports optionally keep refreshing; references never auto-refresh. Preserve selection/geometry and existing snapshot limits; regression tests cover both destinations without a selection.

  • Simplify layer previews to Enable → Input → Capture still → Auto-refresh. Capture directly replaces that layer’s image; auto-refresh is per layer and can fetch the first image. Preserve serialized low-rate requests, bind manual results to their original target, and keep manual stills unchanged by other layers’ refreshes. Regression tests cover control order, recapture, stale results and automatic first capture.

  • Move captured-input controls and the image preview into a dedicated Preview properties tab, with a matching right-click entry. Crop keeps its geometry controls; the existing preview context submenu remains available. Tab-switch regression checks include Preview.

  • Keep Mapping limited to Midra screen/layer links; move editor input identity into the opt-in Advanced Source section. Offer editor Inputs 1–8 independently of layer count, with New editor input for additional local identities. Apply creates missing slots and assigns the source atomically with Undo; project round-trip tests cover shared Input 8, expansion and limits. Midra layer links and physical routing remain separate.

  • Filter Midra destinations by each screen’s CURRENT allocated layer count, not the eight firmware storage slots or physical inputs. Keep allocated layers available without assigned sources; exclude unallocated slots from import, mapping and sends, including saved links. Regression checks cover active versus staged allocation and Preview/Program sends.

  • Keep existing Midra layers available for mapping, import and send regardless of input assignment or OFF state. Uncropped layers without content dimensions import their container; sends use editor dimensions when hardware content dimensions are unavailable, preserving routing. Regression tests cover unassigned layers and both send strategies/targets.

  • Use absolute Gitea main-branch URLs for repository file links in the root README; verify linked files exist.

v0.6.0 — 2026-11-14

  • Synchronize the shared Cargo package version with the v0.6.0 milestone tag; see the release notes.

  • Add opt-in input-preview auto-refresh with a 5–300 second request interval (default 10). Visible previews refresh round-robin with shared input textures, one background request at a time; pause offline/manual capture, retain images on failures and keep fixed references unchanged. Timer controls and assignments remain session-only. Regression checks cover scheduling, throttling and response handling.

  • Use captured input stills as toggleable layer previews, with crop guides composited above them and a 0–100% opacity slider in Crop properties and the layer context menu. Guides return to full opacity without an enabled preview; source/input/dynamic crop and ghost overflow share the same mapping. Layer-preview assignments/settings are session-only; capture is throttled, with optional auto-refresh added above.

  • Group the guide and supporting documentation in this tool’s folder; update portal, cross-document and packaging links for the new paths.

  • Add manual Midra input-still capture through the verified WebRCS PNG endpoint, with preview/Add as reference, one request at a time and a five-second minimum interval. Device-setting writes are not involved; active-input 512 × 288 and inactive blank-image responses checked on the Eikos.

  • Load project/recovery files and decode embedded references in a background worker, install atomically, preserve work on errors/cancel and pause recovery autosave while loading. Reconcile the historical plan into completed implementation, remaining features and separate hardware/platform acceptance checks.

  • Add README-linked two-layer PPTX, Figma FIG and Illustrator AI templates in Full HD and UHD 4K. Extend the template generator with format selection and import verification; test native fixture geometry, with AI checked through VectorCraft 0.24.1.

  • Remove the redundant Copy coordinates button from the title header and right-align the device label. Existing copy commands remain available.

  • Move Menu from the title header to the toolbar immediately before Project, within the same wrapping group.

  • Place Load before Send in the status bar.

  • Align status-bar connection, mapping, send/load and scope controls in one vertically centered row with consistent spacing and button heights; let labels determine positions instead of fixed offsets.

  • Rename Apply changes and Configure Midra export to “Midra mapping & transfer…” so the action clearly opens layer mapping and send/load settings; actual sending remains a separate button.

  • Keep multiple reference images in a purple section of the layer list, with add, eye, remove, settings and Show only actions; references remain fixed and excluded from layer/device operations. Add removal to Import and viewport/reference context menus. Queue multi-file imports in order, composite visible guides in viewport/artwork exports, and save all images in project v10 with tested v1–v9/recovery migration. Corrupt additions or project images preserve existing work.

  • Add Paste layer values beside Copy layer values in the layer context menu, using the existing clipboard import and mapping review before applying changes.

  • Make Source an advanced, opt-in section with explanations of input aspect correction and pre-layer input crop. Show the linked device input’s actual WebRCS aspect/crop controls separately from the local geometry model. Stage only edited fields, include them in scoped sends only while enabled, and pulse input crop updates. The opt-in and staged device edits are session-only and clear on disconnect, address/project change or uncheck. Verified field names/ranges against the connected Eikos WebRCS; regression tests use mock devices, without hardware writes.

  • Add a Mapping properties tab and right-click entry with selectable Midra screen/layer links and Unmap. Unmapped layers are excluded from linked sends/loads; link edits are local, saved with projects and undoable. Move the separate editor input identity selector into Mapping.

  • Draw the snapping dropdown chevron and layer order arrows as vector icons, avoiding missing font glyphs while preserving tooltips, disabled states and button accessibility.

  • Default Midra transfers to All layers with a shared All/Selected/Folder selector. Folder mode follows clicked folders for quick alternate-layout sends/loads; links remain editable and out-of-scope links are preserved. Import suggests saved links and saves remapped/new-layer links and folder membership atomically with geometry. Tests cover scope isolation, reused destinations, in-flight reads and Undo; no hardware writes were needed.

  • Organize the flat layer sidebar into collapsible folder groups: select contents, double-click rename, group eye/lock controls, drag layers between folders/root, and reorder folders as blocks. Add new-folder and right-click actions, with atomic Undo and existing project compatibility; empty groups disappear and nesting is not introduced.

  • Reorder the viewport toolbar into shared bordered groups: Project/Import, Undo/Redo, Select/Move, view controls, Align/Snap/Pivot, and Output/Options. Groups wrap together on narrow windows and preserve optional icon captions.

  • Snap moving layers, resize handles and pivots to screen center and quarter guides on both axes. Moving layer centers also snap to these interior guides; the existing screen snapping option controls all screen guides.

  • Use a crisp, theme-aware magnet icon for the snapping dropdown; preserve snapping controls and active grid indicators.

  • Unify file exchange around shared geometry preparation, byte-oriented codecs and one Export layers window. Add optional native PPTX/FIG import/export with slide/frame selection and embedded artwork, plus local VectorCraft AI conversion. File conversions run off the UI thread. Document and test --no-default-features --features no_proprietary; CI covers both configurations and production coverage includes the codecs.

  • Add versioned geometry JSON, RFC-style CSV, DXF and HTML/CSS import/export alongside SVG and draw.io. All six formats have two-layer Full HD/UHD templates and round-trip tests; artwork support is explicit per format.

  • Add README-linked two-layer SVG and draw.io templates for Full HD and UHD 4K, generated by the application exporter and checked byte-for-byte in regression tests.

  • Import SVG rendered by draw.io Desktop, including its SVG 1.1 DOCTYPE, nested cell wrappers, symbol/image layers and generated label fallbacks. A background-preserved native 31.7.0 round trip was checked; draw.io’s cropped SVG exports necessarily retain their rebased coordinates.

  • Add current-layer SVG and draw.io exports with optional embedded backgrounds and source-pattern placeholders; import native/compressed draw.io files. Round-trip tests cover scopes/artwork and whole-pixel geometry; draw.io Desktop 31.7.0 rendering and XML re-save were checked. Use JSON for full source/crop fidelity.

  • Hide tiled source patterns outside crop editing, even with saved pattern display enabled. Double-click/Crop properties reveals the selected layer’s pattern; the existing preference now shows other layers’ patterns only while cropping.

  • Constrain Crop-tab X/Y offsets to the valid content bounds, including after zoom decreases; typed and dragged edits clamp to the edge instead of producing offset-range errors. Undo remains available.

  • Remove redundant position/size and output Apply buttons and their close prompts; names/folders commit on Enter or focus loss with Undo. Rename staged source and clipboard/SVG actions to “Apply source changes” and “Import mapped values”; Midra sends remain explicit.

  • Add ImageGen application artwork in PNG, Windows ICO and macOS ICNS formats. Embed native icons and support Linux/BSD desktop entries and macOS app launchers; native Windows/macOS visual checks remain required. Include artwork for the Python device probe.

  • Fix the crop-alignment regression test’s Clippy range-loop warning so CI passes with warnings denied; retain both offset assertions.

  • Rename the positioning toggle to “Use a different measure point”.

  • Keep the example presentation visible for every output format, adapting its title, grid, tagline and screen labels to the new dimensions.

  • Right-click a layer in the viewport or layer list to rename/delete it; list menus stay compact. Delete supports Undo and respects locked/hidden/last-layer protection.

  • Swap new-project default labels: top layer is 01 / Presenter, lower layer is 02 / Slides. Geometry, draw order and existing projects are unchanged.

  • Recover the last session automatically from a separate two-second autosave; named saves stay explicit. New project offers Save/Discard/Cancel and shows the last manual-save age. Failed/corrupt recovery is reported and preserved.

  • Measurement-point choices and the independent-point toggle autosave to the current project file; other unsaved edits remain untouched. New projects need a first Save.

  • Separate Select (V, previous behavior) from Move (M), which drags the existing selection without selecting, deselecting or resizing.

  • Layer properties’ Layer tab applies size/locked-ratio changes immediately; remove its Apply button. Drag edits undo together; Source edits remain explicit.

  • Layer properties’ Crop tab automatically enables visual crop editing and disables it on leaving/closing; remove its redundant toggle button.

  • Ctrl/Pivot now works on crop/zoom handles, keeping the source pixel under the saved gravity point fixed; crop limits prevent empty borders.

  • Group grid snapping tools and snapping options in a toolbar dropdown; the label shows the active grid. Pivot remains independently accessible.

  • Save gravity points per layer across selection changes and reopening; placement/reset supports Undo. Project v9 migrates older files to centered pivots.

  • Pivot dragging snaps to corners, side midpoints and center even with snapping off; also honors grid/pixel/screen/layer options. Alt bypasses built-in anchors; guides and linked pivots follow the result.

  • Optional “Use a different layer point” exposes independent screen/layer measurement points (e.g. screen top-left → layer center). Numeric sizing preserves the endpoint. Project v8 saves the choice; v1–7 retain matched points.

  • Hide bottom interaction hints when viewport space is tight, reclaiming their 40 px footer. Off-view layer warnings remain visible.

  • Fit screen now includes the example backdrop’s Screen 1/resolution labels, preventing clipping in shorter/wider viewports.

  • Move the reference drag/drop/import hint into the example artwork footer and reclaim its separate viewport status row. Image details and warnings remain above the view.

  • Default backdrop title is “Example Conference Name”; edit/reset it in Options → Example backdrop or Settings → Reference images. Project v7 saves the title and migrates v1–6.

  • Add persistent Move/Pan/Zoom icons (V/H/Z). Zoom supports click, Alt-click out and horizontal drag; Space/middle-drag pans from any tool. Escape cancels camera drags; grid/pivot choices stay independent.

  • Layer lists now show the topmost layer first; drag/drop and arrows match. Selection no longer raises layers temporarily. Saved project/SVG stacking stays compatible.

  • Show current aspect ratios beside dimensions and the ratio lock. Accept manual W:H, W/H or decimal ratios; locked edits keep width/reference and adjust height, unlocked edits wait for the lock. Layer properties initially remained Apply-based; subsequent automatic application is recorded above.

  • Add persistent 10 px/100 px grid and Pivot toolbar icons with shortcut tooltips. Grids exclude each other; Pivot combines with either. Matching modifiers temporarily invert toggles; choices last for the session.

  • Ctrl shows a movable resize pivot; Ctrl-resize keeps it fixed. Same/Mirror/Opposite modes share or reflect relative pivots. Double-click resets; Ctrl+Shift keeps the 100 px grid. Session-only, with snapping and Undo.

  • Hold Alt to temporarily invert movement/resize snapping (on ↔ off), overriding Shift grids without changing saved settings.

  • Add Snapping controls to viewport right-click and quick Options menus; share and automatically save the same editing settings.

  • In Adjust layer crop mode, alignment buttons move zoomed content within the fixed layer box; preserve zoom and support Undo.

  • Snap mirrored/opposite resizing to exact edge contact between both moving layers, including unequal sizes; preserve anchors/ratios, Alt bypass and Undo.

  • Distinguish completely out-of-view layers from partial/complete output-screen overflow; give navigation versus positioning advice. Rename Fit selected to Zoom to selection.

  • Give the canvas more space: compact reference hint/status, tighter viewport margins and footer. Warnings still wrap. Fix resize edge snapping at fractional viewport scales.

  • Add center to “Measure position from”; numeric resizing preserves center offsets. Project v6 saves the reference and migrates v1–5 corners.

  • Rename Preferences to Settings; menu actions now read “Open all settings…”.

  • Shift-drag moves/resizes on a 10 px grid; Ctrl+Shift uses 100 px, Alt bypasses. Replaces resize snap inversion; Shift-click and empty-canvas additive selection remain.

  • Add a subtle “Double-click to edit” reminder in the layer-list header.

  • Completed the input-preview backlog in this release: verified snapshot access, manual capture and optional timed refresh (see above).

  • Reject negative/non-finite crop entries; crop-edge dragging stops at zero and zoom stays within 100–10000%. Signed content offsets remain supported.

  • Keep the chosen resize mode through selection changes, Escape, Undo/Redo and project loads in the current session; single-layer resizing still works normally.

  • “Options save automatically” is non-selectable informational text.

  • Reorder layers with manager ↑/↓ buttons or drag-and-drop in the inspector. One-step Undo; IDs, links, crops and pending names follow the layer. Test save/reload and SVG order.

  • b251798: Crop zoom/offsets and output resolution apply on edit; position/size applies when leaving a field. Pending drafts prompt Apply/Discard on close; Apply buttons highlight changes. Device sends remain explicit.

  • Early apply-on-edit validation: workspace tests, fmt, Clippy and rustdoc passed; LLVM tools were unavailable then. Subsequent milestone checks include passing coverage (89.99%); see release notes for hardware/platform limitations.

v0.5.0 — 2026-11-14

  • 8322eab: Tagged baseline before the apply-on-edit changes. Editor, saved screen/layer links, Preview loading and explicit device sends.

All manuals

Aquilon compatibility investigation

Midra Layout plan · Device workflows

Investigated 2026-11-15. Aquilon is not yet enabled in the application. This review compared the current Rust adapter with upstream protocol references; it did not connect to an Aquilon or alter the Midra emulator being tested.

Finding

Aquilon (LivePremier) can reuse our HTTP state-read / WebSocket write approach, but needs a separate, firmware-aware adapter. Adding its name to the Midra model list would leave bank selection, geometry paths and the final apply command wrong. Start with firmware 4.x and later as a candidate profile; validate the actual firmware/state before extending that claim to later releases. Older firmware needs a separate profile, not guessed aliases.

The upstream Companion integration explicitly separates Midra, LivePremier and LivePremier 4. Its name mentions AWJ, but its implementation uses the web control transport. Analog Way’s documented AWJ TCP service is another transport, not the same socket or message framing as our WebSocket connection. We do not need to introduce AWJ TCP for the first adapter.

Evidence and differences

The source observations below are pinned to Companion revision 4df8677f912ce95b6e7e5c93f2fd51aa0ae33ff2. They are implementation evidence, not a substitute for Aquilon emulator/hardware acceptance.

AreaCurrent Midra adapterAquilon evidence / required work
ConnectionIP plus optional port; HTTP state read and root WebSocketUpstream uses /auth/status, /api/stores/device and root WebSocket, with authentication handling. Probe these separately from our /api/tpp/v1/system identity read.
IdentityFour Midra type stringsUpstream detects NLC device identifiers and firmware from system state, including linked-device roots.
Preset banksUP / DOWNAquilon uses A / B; resolve Preview/Program from transition state, independently for each screen/group.
ScreensNumeric screen IDsScreen and auxiliary IDs include S1 and A1. Firmware 4 separates screenList and auxiliaryList.
AllocationCURRENT preconfiguration layer countUpstream reads each screen’s status/pp/layerCount. Discover actual allocations and editable layers.
SizeLayer size/pp/sizeH and sizeVShared Aquilon constants put size under position/pp, beside position.
CoordinatesCenter-based posH / posVUpstream subtracts half-width/height to obtain top-left coordinates, matching our editor convention.
CropLayer crop/pp and mask/ppUpstream constants use cropping/classic/pp and cropping/mask/pp. Units, source correction and fit semantics still need verification.
Apply pulsedevice/preset/control/pp/xUpdateOlder Aquilon uses device/screenGroupList/control/pp/xUpdate; firmware 4 profile uses device/screenAuxGroupList/control/pp/xUpdate. Upstream pulses false then true.

Pinned implementation references:

Analog Way’s Aquilon downloads list separate AWJ guides for firmware 2.2–3.x and 4.x onwards, plus a REST guide. The current links resolve to AWJ guide V6.2 and REST guide v6.0, but their download server returned HTTP 403 during this investigation; their full contents were not verified. Use those guides alongside emulator state when implementing crop behavior. No upstream code or new dependency was copied into the application.

Implementation sequence

  1. Capture an Aquilon baseline. Obtain emulator IP:port and firmware, read identity/state, record screen and auxiliary allocation, and inspect authentication. Keep raw configuration private; derive minimal sanitized regression fixtures.
  2. Separate adapters from transport. Share address/history, bounded reads, timeouts, worker scheduling and WebSocket framing. Give each profile its own identity detection, screen enumeration, bank resolution, geometry paths, crop conversion and apply pulse. Make Program bank explicit rather than assuming the opposite of UP is DOWN.
  3. Import geometry first. Test differently sized canvases, multiple screens, inactive slots, unassigned inputs, A/B swaps and transitions. Preserve native device IDs. Do not substitute zeros or default dimensions for missing fields.
  4. Generalize saved links. MidraLink::validate currently accepts only positive decimal strings. Introduce family-aware destination identity with an explicit project migration and interface examples/tests; preserve existing Midra links. Never collapse S1 and A1 into the same destination. Keep shared-destination conflict checks and folder scopes working across the new identities.
  5. Send position/size with readback. Resolve the chosen bank, use Aquilon’s position/size fields and its apply pulse. Verify both application state and the emulator’s rendered Preview before declaring the send path complete.
  6. Verify crop independently. Compare source correction, classic crop, mask, fitting, zoom/offset and both export sizing strategies against known layouts. Reuse editor geometry math where appropriate; keep device conversion separate.
  7. Add capture and scale coverage. Our snapshot input limit is currently 16, and parsing caps allocated layers at 8. Replace family-specific limits with discovered capabilities plus explicit resource bounds. Reuse pooled low-rate capture scheduling; verify Aquilon snapshot IDs, endpoints and image dimensions.
  8. Acceptance matrix. Cover single and linked units, each tested firmware profile, multiple screens, mapping save/load, history/autoconnect, explicit Program opt-in and folder sends. Record tested models/firmwares rather than claiming the entire range from one identity string.

No persistent schema or device-send contract changes are made by this research. The next practical input is an Aquilon emulator address and firmware version; there is no need to interrupt Midra testing to obtain it now.