beffroi-tools/docs/midra-layout.md

122 lines
7.1 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 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.
```sh
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](../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. In overlaps, the upper layer wins;
the list lets you reach the lower layer. Clicking empty canvas clears selection.
- Drag to move. Movement uses whole-screen-pixel deltas and preserves any fractional
starting position and dimensions. Selection handles currently indicate bounds;
resizing uses the numeric width/height fields.
- Arrow keys move by **1 px**; Shift-arrow moves 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.
- **Undo/Redo** buttons or Ctrl/Cmd-Z, Ctrl/Cmd-Shift-Z (also Ctrl/Cmd-Y) reverse
edits. Each drag, 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 layer** frames the selected layer.
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** copies labeled plain text with center position and
dimensions. This is not a native WebRCS clipboard payload.
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.
Reference artwork is illustrative, not a loaded image or live video. Source/input
formats, custom output resolution, image import, cropping, alignment and persistent
session files are future work. Sessions currently live only in memory.
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, drag/undo, selection, and GUI paste/focus behavior.
See the [project plan](midra-layout-plan.md) and
[resolution/cropping specification](midra-layout-resolutions.md) for future work.