163 lines
9.7 KiB
Markdown
163 lines
9.7 KiB
Markdown
# 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 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.
|
||
Selection handles indicate bounds; resizing uses 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.
|
||
Reference artwork is illustrative, not a loaded image or live video. Source/input
|
||
formats, custom output resolution, image import, cropping 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 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.
|