beffroi-tools/docs/midra-layout.md

303 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

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

# Midra Layout
A native Rust/egui workspace for positioning 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 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…** opens an SVG file in the
same review window; raw SVG XML can also be pasted.
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.
- **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 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** and can be changed.
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
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 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, 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.