beffroi-tools/docs/midra-layout.md

12 KiB
Raw Blame History

Midra Layout

A native Rust/egui workspace for positioning two rectangular layers offline. Select layers, paste draw.io geometry, move them visually or enter exact corner positions and dimensions. Center coordinates update for manual transfer to WebRCS. No device connection or REST calls are made.

cargo run --locked -p midra-layout

Paste from draw.io

  1. Select the target layer on the canvas or in the right-hand list.
  2. Copy an ungrouped rectangle in draw.io, then press Ctrl/Cmd-V with the viewport focused. Alternatively, click Paste draw.io…, paste into the text area and click Read geometry.
  3. Review the target layer, before/after position and size. If multiple rectangles were copied, choose one explicitly; the importer does not guess a mapping to the two layers.
  4. Leave Include size / format checked to import width and height along with position, or uncheck it for position only. Choose Include outline in bounds if the layer should cover the rectangle's outline too, then click Apply to selected target. The before/after preview updates with your choice.

The first adapter accepts raw or once-percent-encoded mxGraphModel 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 1 MiB; geometry must have finite coordinates within ±1,000,000 px and positive sizes up to 1,000,000 px. These are application limits, not verified Eikos limits.

Draw.io also exposes raw page XML through Extras → Edit Diagram, as described in its source-editing documentation. Support is based on the supplied clipboard data and regression fixtures; live clipboard testing against a running draw.io instance remains to be done.

Move and edit layers

  • Click a layer or its list entry to select it alone. Shift-click toggles that layer in the selection. In overlaps, the upper layer wins; the list lets you reach the lower layer. Clicking empty canvas clears selection; Shift-clicking empty canvas preserves it.
  • Left-drag on empty canvas draws a selection box, selecting every rectangle it intersects, in either drag direction. Shift-drag draws an additive box, including when starting over a layer. Escape cancels the box and restores the previous selection.
  • Drag a selected layer to move the whole selection together; dragging an unselected layer selects and moves it alone. Movement uses whole-screen-pixel deltas and preserves fractional starting positions, sizes and relative spacing. Drag a corner handle to resize that layer, or use the single-layer numeric fields.
  • Arrow keys move the selection by 1 px; Shift-arrow moves it by 10 px.
  • Choose one of the four corner markers. Switching corner changes the displayed offsets without moving the layer. Enter offsets, width and height, then click Apply position / size or press Enter in a field. Resizing preserves that corner's offsets. Invalid values leave the document unchanged.
  • Escape cancels a drag or restores uncommitted numeric fields. In the paste dialog it closes the preview without applying it. Group drags cancel atomically.
  • Undo/Redo buttons 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. Fit screen resets the view; Fit selected frames the entire selection. 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. This is not a native WebRCS clipboard payload.

Align selected layers

Select both layers to reveal the alignment inspector. Choose an explicit target:

  • Selection bounds uses the selected rectangles' combined bounds at the time of the action. Align left/top uses the minimum left/top; right/bottom uses the maximum right/bottom. Selection order has no effect.
  • Screen aligns to the screen edges or center lines.
  • Reference: Presenter / Slides aligns to that selected layer's edges or center lines. The named reference remains fixed.

Use Align left, Align right, Align top, Align bottom, Center X (horizontal centers) or Center Y (vertical centers). Each action changes only the relevant position axis, never size, and is one undo step. The inspector lists each layer's resulting center coordinates. Single-layer numeric fields are replaced by alignment controls during multi-selection; no mixed values are shown as if they belonged to one layer. Select exactly one layer to paste or resize.

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 its target explicitly and changes only that layer.

Current limits

The screen is currently fixed to 1920 × 1080, with two live rectangles. The initial backdrop is illustrative; importing a reference picture replaces it. Live video, source/input formats, custom output resolution, cropping and persistent session files are future work. Sessions currently live only in memory.

Layer management and export scope are also later stretch goals: Add layer, Midra layer mapping in Options, and export of a specific layer or visible layers only. Optional folders would organize local layers. Visibility and organization will not send commands or change the live device.

Applying layer format through the WebRCS REST API is a later stretch goal. The currently connected Eikos is live: this work must remain offline, with no device probing or commands. A future integration must preview changes and require an explicit send action; local editing must never update the device automatically.

The displayed WebRCS values use the planned center-from-top-left convention. Actual firmware coordinate limits, crop behavior and decimal acceptance are not verified yet. Fractional values remain visible rather than silently rounded.

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

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

See the project plan and resolution/cropping specification for future 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

Drop one PNG, JPEG or BMP into the window, or open Reference image… → Import picture…. The image is fixed behind the layers in screen coordinates; zooming and panning keep it aligned. Layer fills become translucent to reveal the image. Use the reference window to hide it, adjust opacity, replace it or remove it.

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

Files are limited to 64 MiB and dimensions to 8192 pixels per side or the GPU's texture limit, whichever is smaller. Invalid imports keep the previous image. Reference settings are session-only and independent of layer undo/redo.

Resizing with corner handles

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

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