314 lines
19 KiB
Markdown
314 lines
19 KiB
Markdown
# Midra Layout
|
||
|
||
A native Rust/egui workspace for positioning two rectangular layers offline.
|
||
Select layers, paste draw.io or import SVG geometry, move them visually or enter exact corner
|
||
positions and dimensions. Configure source/input formats and content framing;
|
||
visible-box coordinates and provisional crop calculations update together.
|
||
No device connection or REST calls are made.
|
||
|
||
```sh
|
||
cargo run --locked -p midra-layout
|
||
```
|
||
|
||
## Paste layer values and import SVG
|
||
|
||
1. Select the destination layers on the canvas or in the right-hand list
|
||
(Shift-click to select both).
|
||
2. Copy layer values in Midra Layout or rectangles in draw.io, then press **Ctrl/Cmd-V** with the viewport
|
||
focused. Alternatively, click **Paste layer(s) values**, paste into the text
|
||
area and click **Read geometry**. **Import → SVG file…** opens an SVG file in the
|
||
same review window; raw SVG XML can also be pasted. **Import → Clipboard values**
|
||
reads the clipboard directly and opens the mapping review.
|
||
3. Review each detected rectangle and choose its destination layer. Initial
|
||
mapping follows document order and the selected layer list. Every selected
|
||
destination must receive exactly one rectangle: count mismatches and duplicate
|
||
mappings block Apply and explain what needs changing. Nothing changes yet.
|
||
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.
|
||
5. Click **Apply mapped values** to update the entire selection in one undo step.
|
||
Cancel leaves all layers unchanged. Invalid geometry
|
||
blocks the whole batch, without partial changes.
|
||
|
||
The current workspace has two layers; the import review handles all selected
|
||
layers rather than choosing one rectangle from a larger clipboard selection.
|
||
|
||
### SVG bounds
|
||
|
||
SVG import accepts square-corner rectangles and simple closed rectangular
|
||
paths/polygons, including translated/scaled groups and inline styles. It applies
|
||
page dimensions and `viewBox` transforms, using CSS units at 96 px/in. Coordinates
|
||
are relative to the SVG page; exporting only a selection may lose its original
|
||
document position. The SVG is used for bounds, not rendered as a reference image.
|
||
|
||
A first full-page rectangle or image is marked as a possible background. Check
|
||
**Ignore full-page background** to exclude it from the count and mapping. This
|
||
is explicit: a full-page rectangle can also be a real layer. Image backgrounds
|
||
must be excluded; their contents and external links are never loaded.
|
||
|
||
Other visible artwork, rotation/skew, rounded rectangles, clipping, masks,
|
||
filters, stylesheets, and unsupported SVG features are refused with an error.
|
||
Hidden objects and definitions are ignored. Export simple rectangles with inline
|
||
styles for predictable results. Files are limited to 1 MiB, 256 rectangles, and
|
||
64 levels of nesting. SVG imports retain the same outline and position-only
|
||
choices as draw.io imports.
|
||
|
||
### draw.io clipboard
|
||
|
||
The first adapter accepts raw or once-percent-encoded `mxGraphModel` XML, like
|
||
[the supplied clipboard fixture](../crates/midra-layout/tests/fixtures/drawio-rectangle.txt).
|
||
Draw.io coordinates map **1:1 to screen pixels**, with a top-left origin. This is
|
||
an explicit import convention; no page-scale, physical-unit or viewport-size
|
||
conversion is inferred. Missing X/Y means zero. Decimal dimensions are preserved.
|
||
|
||
The supplied example imports **X 12, Y 271, width 945, height 531.58**. The center
|
||
is **484.5, 536.79**. The visible box has its exact imported ratio; it is not rounded
|
||
or coerced into a 16:9 preset. “Format” here means the visible rectangle's width,
|
||
height and aspect, not native source format or advanced cropping.
|
||
|
||
**Include outline in bounds** is off by default on each paste. For an outline of
|
||
width `s`, enabling it subtracts `s/2` from X and Y and adds `s` to width and
|
||
height, preserving the center. This follows the half-stroke expansion in
|
||
[mxGraph's bounding-box calculation](https://github.com/jgraph/mxgraph/blob/master/javascript/src/js/shape/mxShape.js).
|
||
Your sample's 5 px outline gives **950 × 536.58 at (9.5, 268.5)**. Only the bounds
|
||
are imported; no border is drawn or configured on the device.
|
||
|
||
The option is disabled for position-only paste: that mode uses the original
|
||
geometry's top-left and keeps the target layer's dimensions. Zero-width,
|
||
`strokeColor=none`/`transparent`, zero stroke opacity and zero overall opacity
|
||
produce no outline expansion. A missing width uses the standard 1 px default;
|
||
the detected width is shown in the preview. Each rectangle in a multi-object
|
||
paste uses its own width. Shadows, sketch effects and raster antialiasing fringes
|
||
are not included. Invalid thickness/opacity values or bounds beyond the
|
||
application limits are rejected without changing the document.
|
||
|
||
The adapter otherwise ignores colors, text, style aspect locks and other
|
||
appearance settings. It currently rejects grouped/nested geometry, connections,
|
||
nonrectangular shapes, relative coordinates, alternate bounds, rotated/flipped
|
||
objects, named/inherited styles, wrapped objects and compressed `.drawio` files.
|
||
Mixed selections containing unsupported objects are rejected as a whole. Invalid
|
||
input makes no document changes. Text is limited to 1 MiB; geometry must have
|
||
finite coordinates within ±1,000,000 px and positive sizes up to 1,000,000 px.
|
||
These are application limits, not verified Eikos limits.
|
||
|
||
Draw.io also exposes raw page XML through **Extras → Edit Diagram**, as described
|
||
in its [source-editing documentation](https://www.drawio.com/docs/manual/advanced/diagram-source-edit/).
|
||
Support is based on the supplied clipboard data and regression fixtures; live
|
||
clipboard testing against a running draw.io instance remains to be done.
|
||
|
||
## Move and edit layers
|
||
|
||
- Click a layer or its list entry to select it alone. **Shift-click** toggles that
|
||
layer in the selection. 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.
|
||
- The history toolbar icons (**Undo/Redo**) or Ctrl/Cmd-Z, Ctrl/Cmd-Shift-Z (also Ctrl/Cmd-Y) reverse
|
||
edits. Each drag, alignment, applied paste or numeric edit is one step; retain 100 undo
|
||
records. View changes and selection are not document edits.
|
||
- Scroll over the viewport to zoom around the pointer. Space-drag or middle-drag
|
||
pans. In the compact toolbar’s view group, **Fit screen** resets the view and
|
||
**Fit selected** frames the entire selection. A divider separates view tools from Undo/Redo. Hover an icon for its label.
|
||
Camera changes do not modify coordinates. Off-screen layers retain their exact
|
||
coordinates, display a warning and remain selectable through the layer list.
|
||
- **Copy position values** (or **Copy selected positions** for multiple layers)
|
||
copies labeled plain text with each selected layer's center position and
|
||
dimensions. **Ctrl/Cmd-C** does the same when the viewport has focus. These
|
||
values can be pasted back using **Ctrl/Cmd-V** or **Paste layer(s) values**, with
|
||
the usual destination mapping and exact layer-count requirement. Center values
|
||
are converted back to top-left bounds; whole-pixel export rounding still applies
|
||
(an odd width/height can produce a half-pixel top-left). Source formats and crop
|
||
settings are not copied. This is not a native WebRCS clipboard payload.
|
||
|
||
## Align selected layers
|
||
|
||
Open the **Align selected layers** icon menu beside the view/history toolbar.
|
||
The **Align to** dropdown defaults to **Selected layers** (their combined bounds).
|
||
It also lists **Layer 1: Presenter**, **Layer 2: Slides**, and any future layers.
|
||
A reference layer stays fixed and does not need to be selected. Screen alignment
|
||
is not offered in this menu.
|
||
|
||
The compact icon grid offers four corners, top/bottom/left/right edges, center
|
||
on both axes, and separate horizontal/vertical centering. 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
|
||
exactly one layer to resize. Paste/import accepts the full selection.
|
||
|
||
Text inputs receive normal text paste and arrow navigation while focused; they
|
||
never interpret these actions as geometry import or layer movement. Paste preview
|
||
identifies every destination explicitly and applies the mapped selection together.
|
||
|
||
## Current limits
|
||
|
||
The document currently has two local rectangles and two source identities.
|
||
Output resolution defaults to **1920 × 1080 (16:9)** and can be changed.
|
||
The output dialog identifies standard aspect ratios from the current resolution;
|
||
nonstandard ratios display as Custom.
|
||
The initial backdrop is illustrative; importing a reference picture replaces it.
|
||
Live video, verified hardware container/crop conversion and persistent session
|
||
files are future work. Sessions currently live only in memory.
|
||
|
||
[Layer management and export scope](midra-layout-plan.md#11-later-stretch-goal-layer-management-and-export-scope)
|
||
are also later stretch goals: **Add layer**, Midra layer
|
||
mapping in **Options**, and 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](midra-layout-plan.md#10-later-stretch-goal-apply-layer-format-through-the-webrcs-rest-api).
|
||
The currently connected Eikos is live: this work must remain offline, with no
|
||
device probing or commands. A future integration must preview changes and require
|
||
an explicit send action; local editing must never update the device automatically.
|
||
|
||
The displayed WebRCS values use the planned center-from-top-left convention.
|
||
Actual firmware coordinate limits, crop behavior and decimal acceptance are not
|
||
verified yet. Fractional values remain visible rather than silently rounded.
|
||
|
||
The window can be resized; the screen keeps its aspect ratio, and the right
|
||
inspector scrolls on shorter windows. Minimum size is 1000 × 720 logical points.
|
||
A graphical desktop session is required to launch.
|
||
|
||
The Cargo workspace includes this crate in lint, tests, docs and coverage.
|
||
Regression tests cover the supplied clipboard, malformed/unsupported input,
|
||
corner conversion, group drag/undo, selection boxes, alignment targets, and GUI
|
||
paste/focus behavior. Layer-list scrolling uses the wheel or scrollbar so dragging
|
||
across list entries cannot accidentally scroll while selecting.
|
||
|
||
See the [project plan](midra-layout-plan.md) and
|
||
[resolution/cropping specification](midra-layout-resolutions.md) for the implemented
|
||
geometry model and remaining hardware-verification work.
|
||
|
||
Each layer row has **Lock / Locked** and **Hide / Show** buttons. Locked layers
|
||
remain visible but cannot be selected, dragged, nudged, aligned or edited. Hidden
|
||
layers keep their geometry and stay in the list, but are excluded from drawing
|
||
and selection. Locking or hiding clears that layer's selection; showing it does
|
||
not unlock it. These are local session controls, separate from geometry undo/redo
|
||
(which can still restore earlier geometry), and never send device commands.
|
||
|
||
Selected layers use gold outlines, labels, handles and position guides; unselected
|
||
layers use muted outlines and labels. Gold in the layer list follows the same
|
||
selection state, including when several layers are selected.
|
||
|
||
### Reference pictures
|
||
|
||
The **Import** dropdown groups layer-value imports and screen references.
|
||
Layer imports require selected destinations. After importing a reference picture,
|
||
**Import → Reference settings…** opens its visibility, opacity and scaling controls.
|
||
|
||
Drop one PNG, JPEG or BMP into the window, or choose **Import → Reference image…**. The image is fixed behind the layers in screen coordinates; zooming
|
||
and panning keep it aligned. Layer fills become translucent to reveal the image.
|
||
Use the reference window to hide it, adjust opacity, replace it or remove it.
|
||
|
||
**Fill screen** maps the entire image to the current output resolution. An exact
|
||
pixel match needs no warning. Scaling up or down with matching proportions shows
|
||
an amber warning; a different aspect ratio (such as 16:10) shows a red **SEVERE
|
||
WARNING** because the image is distorted. Neither warning blocks importing or
|
||
moving layers. **Fit inside** preserves proportions and centers the image with
|
||
empty margins where needed; scaling still produces an amber warning.
|
||
|
||
Files are limited to 64 MiB and dimensions to 8192 pixels per side or the GPU's
|
||
texture limit, whichever is smaller. Invalid imports keep the previous image.
|
||
Reference settings are session-only and independent of layer undo/redo.
|
||
|
||
### Resizing with corner handles
|
||
|
||
Drag a selected layer's gold corner handles to resize it; the opposite corner
|
||
stays fixed. **Keep aspect ratio when resizing**, above the viewport, is enabled
|
||
by default. Clear it to adjust width and height independently against the reference
|
||
picture. The same toggle links numeric width/height edits. Pasted dimensions
|
||
remain exactly as supplied by the source.
|
||
|
||
Dragging a handle in a multiple selection selects and resizes only that layer.
|
||
Sizes cannot flip or shrink below one pixel during dragging. Escape cancels;
|
||
one Undo restores the complete resize. Locked or hidden layers cannot be resized.
|
||
|
||
## Formats and content framing
|
||
|
||
Open **Output format…** for HD (1280 × 720), Full HD (1920 × 1080), UHD 4K
|
||
(3840 × 2160), aspect presets or a custom whole-pixel resolution. Output/native
|
||
sizes support 1–16384 pixels per side as an implementation limit, not a promise
|
||
of hardware support. Layer positions/sizes remain unchanged; screen-corner
|
||
coordinates, alignment, reference-image mapping and warnings use the new output.
|
||
The same window offers numeric camera zoom relative to fit-to-screen and a
|
||
**1:1 display pixels** action; camera changes never modify crop geometry.
|
||
|
||
Select one layer and click its **Layer resolution** card to open **Layer properties**:
|
||
|
||
1. Choose a local **Source identity** and its original **Source format** and native
|
||
dimensions. Input 1/2 are planning identities, not device routing commands.
|
||
2. Set **Input resolution** to the usable size. Typing a custom size centers the
|
||
input crop; edit L/R/T/B for asymmetric placement. Native-size changes reset
|
||
the draft crop to the full source before review. A custom input retains the
|
||
original Source format, e.g. 16:9 native 1920 × 1080 cropped to 1920 × 1000.
|
||
3. Set **Layer resolution** to the final visible box. Use the aspect toggle to
|
||
enter an independent custom width and height. Apply source/input/layer changes
|
||
together; the selected screen-corner anchor stays fixed.
|
||
4. Use **Layer crop / zoom & position** for zoom (100–10000%) and X/Y offsets in output pixels.
|
||
These controls operate on the applied formats. **Apply crop** is one edit;
|
||
**Recenter** preserves zoom; **Reset crop** returns to the minimum centered
|
||
cover crop. Invalid typed offsets show the permitted range and do not apply.
|
||
5. Click **Adjust layer crop** in the selected layer’s parameters, below its format
|
||
summary, or **double-click a layer on the canvas**, to drag or arrow-nudge
|
||
content inside the fixed box. The button
|
||
highlights while active; click **Done adjusting crop** to leave the mode.
|
||
Drags clamp at valid crop boundaries; Escape cancels a drag and leaves this
|
||
mode. Wheel zoom still controls the camera. A source-coordinate test pattern
|
||
illustrates framing; it is deliberately separate from the screen reference.
|
||
While editing, cropped-out content appears at 50% opacity outside the box,
|
||
behind other layers. This preview stops at the usable input boundary; input
|
||
cropping remains excluded. The content inside the box stays fully opaque.
|
||
Grab the faded area to reframe content too; other visible layers covering it
|
||
take precedence. Empty space beyond the usable input is not draggable content.
|
||
|
||
Sources shared by both layers share the input crop. The dialog names affected
|
||
layers; each keeps its independent layer crop. Shared changes undo atomically,
|
||
and edits affecting a locked layer require it to be unlocked first.
|
||
|
||
Moving/alignment preserves crops. Resizing keeps content zoom and the retained
|
||
center where possible, automatically shifting the crop when needed to fit the
|
||
new size. Source/input changes do the same when applied in Layer properties.
|
||
No recentering or extra acceptance is needed. Undo restores both size and crop.
|
||
**Adjust layer crop** changes the crop values inside the layer while keeping its
|
||
visible box fixed; **Reset crop** returns to the minimum centered crop.
|
||
|
||
|
||
**Calculated crops / provisional WebRCS mapping** shows input crops in native
|
||
pixels, advanced crops in usable-input pixels, combined retained native bounds,
|
||
visible size/center, and projected full-input geometry. These values are not a
|
||
verified device recipe: Centered-mode container behavior, crop units/limits and
|
||
quantization still require offline firmware verification. No hardware commands
|
||
are generated or sent. See [the resolution model](midra-layout-resolutions.md)
|
||
for equations and worked examples.
|
||
|
||
## Display/export precision and midpoint handles
|
||
|
||
Geometry in the viewport, inspector and calculation view is shown to the nearest
|
||
0.1 pixel. Copied positions and provisional calculation exports use whole pixels
|
||
(round-half-away-from-zero). Internal geometry and crops retain full precision;
|
||
viewing/copying or applying unchanged rounded fields does not quantize the document.
|
||
This presentation rule does not validate the hardware's crop/container mapping.
|
||
|
||
Each selected box also has a handle at the middle of every side. Dragging top or
|
||
bottom resizes height with the opposite edge fixed; left or right does the same
|
||
for width. With the aspect lock enabled, the other dimension scales around its
|
||
center, keeping the opposite edge’s midpoint fixed. Disable it to change just
|
||
one axis. Corner handles still keep the
|
||
opposite corner fixed. Crop preservation, lock protection, Escape and Undo apply
|
||
to both kinds of resize handles.
|