517 lines
31 KiB
Markdown
517 lines
31 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. Choose independently what to paste: **Format (width / height)**, **Position**,
|
||
and **Crop zoom**. Zoom is enabled only when present in the data (new Midra
|
||
clipboard values include it; older copies, draw.io and SVG do not). All
|
||
available values are initially enabled. Unchecked values retain destination
|
||
settings; format-only paste keeps its top-left position. Choose **Include
|
||
outline in bounds** if the layer should cover the rectangle's outline too.
|
||
Zoom applies to the resulting layer size; existing crop offsets clamp if
|
||
necessary. Mixed batches keep destination zoom where the source lacks it.
|
||
At least one available value must be enabled.
|
||
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. Selected layers appear in the foreground. In overlaps, the frontmost selectable
|
||
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
|
||
offsets are not copied. Crop zoom is included separately as a percentage and
|
||
can be toggled on paste. This is not a native WebRCS clipboard payload.
|
||
|
||
Right-click a layer for **Source properties**, **Layer properties**, **Crop properties**,
|
||
**Adjust layer crop**, alignment, copying values, and lock/hide actions. Right-clicking a layer
|
||
already in a selection keeps the whole selection and offers **Resize together**.
|
||
Right-clicking an unselected layer selects it first. Locked/hidden layers remain
|
||
protected; use the layer list to unlock/show them. Right-click empty canvas for
|
||
**Output format**.
|
||
|
||
## Resize selected layers together
|
||
|
||
Select multiple layers, then choose **Same handles**, **Mirror horizontally**, or **Opposite handles** in the
|
||
right-hand inspector’s resize dropdown. Drag a corner or side handle on any
|
||
selected layer to scale the selection together. All three modes use **equal
|
||
proportional scaling**, not equal pixel additions: a 10% width increase applies
|
||
to every selected layer’s own width.
|
||
|
||
- **Same handles** uses the matching handle on every layer.
|
||
- **Mirror horizontally** requires exactly two layers. Left/right handles are
|
||
mirrored: bottom-right matches bottom-left, and top-right matches top-left.
|
||
Top and bottom midpoint handles remain top and bottom respectively.
|
||
- **Opposite handles** requires exactly two layers. The other layer uses the
|
||
opposite handle: right/left, top/bottom, and diagonally opposite corners
|
||
(bottom-right matches top-left). This was previously called Mirror resize.
|
||
- Each layer keeps the opposite edge or corner fixed. With aspect ratio locked,
|
||
both dimensions use the same scale; otherwise width and height scale
|
||
independently. Side handles affect only their axis when the ratio is unlocked.
|
||
- Minimum sizes constrain the shared scale. Invalid geometry rejects the whole
|
||
update. Crops adjust with sizing, and one Undo restores all layers and crops.
|
||
- **Escape** cancels an active drag and exits the mode. Choose **Resize: individual
|
||
layer** to return to normal handles; reducing the selection below two also
|
||
leaves group resize. Locking/hiding during a drag cancels the entire gesture.
|
||
|
||
## Align selected layers
|
||
|
||
Open the **Align selected layers** icon menu beside the view/history toolbar.
|
||
The **Align to** dropdown automatically uses **Screen (one selected layer)**
|
||
for a single layer and **Selected layers** (their combined bounds) for multiple
|
||
layers. Screen alignment uses the current output resolution.
|
||
It also lists **Layer 1: Presenter**, **Layer 2: Slides**, and any future layers.
|
||
An explicitly chosen reference layer takes precedence, stays fixed and does not
|
||
need to be selected. There is no separate Screen option for multi-selection.
|
||
|
||
The compact icon grid offers four corners, top/bottom/left/right edges, center
|
||
on both axes, and separate horizontal/vertical centering. The top-right button
|
||
centers horizontally (X); the bottom-right button centers vertically (Y). 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
|
||
one layer for numeric size editing, or use a shared resize mode for the selection.
|
||
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 and verified hardware container/crop conversion remain future work.
|
||
Project JSON save/load and SVG geometry export are implemented (see below).
|
||
|
||
[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 device-targeted export of a **specific layer** or
|
||
**visible layers only**. SVG already supports all or visible layers. 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 the **Output format** icon (screen with sliders), first in the toolbar, 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.
|
||
|
||
Apply buttons are muted and disabled when their values already match the layout.
|
||
Pending changes make Apply solid purple. This applies to position/size, output
|
||
resolution, source/input/layer formats, crop framing, and mapped imports. Each
|
||
section tracks its own values; reverting an edit clears its pending state.
|
||
|
||
Layer properties has three tabs: **Source** for native/input resolution and input
|
||
crop, **Layer** for the final visible box, and **Crop** for content zoom and offset.
|
||
The three right-click properties entries open their matching tab directly.
|
||
Switching tabs retains pending edits. Source and Layer changes still apply together
|
||
with their shared Apply button; Crop has its own Apply button.
|
||
|
||
While adjusting a layer crop, click empty canvas or another layer to leave crop
|
||
mode and select normally. Clicking or dragging the visible image or its faded
|
||
outside preview keeps crop mode active. Property controls remain usable while
|
||
editing the crop.
|
||
|
||
In visual crop mode, an accent-colored bounding box surrounds the full usable input image,
|
||
including the faded preview. Drag any corner or side midpoint to zoom the content
|
||
through cropping; the gold visible layer box stays fixed. Content always keeps
|
||
its proportions, independently of the layer resize ratio toggle. The opposite
|
||
content corner or edge stays anchored where possible; offsets clamp to keep the visible
|
||
box filled when zooming out. Zoom is limited to 100–10000%. Drag the image to pan
|
||
its content. Each zoom gesture is one undo step; Escape cancels an active gesture.
|
||
Use viewport zoom/pan to reach content handles beyond the current view.
|
||
|
||
## Save, open and export
|
||
|
||
Use the **Project** toolbar menu to **Save project…** or **Open project…**.
|
||
Projects use readable, versioned `.midra.json` files and preserve applied output,
|
||
inputs, layer bounds/crops, source assignments, locks, visibility, selection,
|
||
viewport preferences, and the embedded reference image. Apply pending edits
|
||
before saving. Opening asks before replacing current work and starts a fresh
|
||
undo history. Existing files require confirmation before replacement.
|
||
|
||
**Project → Export SVG** offers **All layers** and **Visible layers only**.
|
||
These exports contain whole-pixel layer boxes. Import them with **Import → SVG
|
||
file** and map the detected rectangles to the same number of selected layers.
|
||
SVG exchanges geometry; JSON preserves the complete project, including crops
|
||
and the reference image.
|
||
|
||
The [save/export interface specification](interfaces/midra-layout.md) documents
|
||
both formats, their limitations, validation, and compatibility policy, with a
|
||
[complete JSON example](interfaces/midra-layout-v1.example.json).
|
||
|
||
Visual crop mode also provides **Reset crop** beside **Done adjusting crop** in
|
||
layer properties. It restores 100% content zoom and centered offsets, keeps the
|
||
visible box and source/input crop unchanged, and leaves visual editing active.
|
||
The reset is undoable.
|
||
|
||
The toolbar’s **Viewport options** cog contains **Keep aspect ratio when resizing**
|
||
and **Show source-coordinate test pattern in viewport**. Both apply immediately
|
||
and are preserved in saved projects. Crop editing always previews source content
|
||
and keeps its proportions, independently of these layer/view preferences.
|
||
|
||
The toolbar’s **Import** button uses a downward arrow into a tray. Hover for its
|
||
label; its dropdown contains SVG, clipboard values, and reference-image actions.
|
||
|
||
## Application menu
|
||
|
||
The header’s **Menu** brings the application’s commands together:
|
||
|
||
- **Project**: open/save JSON and export SVG.
|
||
- **Import**: SVG, clipboard layer values, and reference images.
|
||
- **Edit**: undo/redo, copy values, select all editable layers, or deselect.
|
||
- **View**: fit screen/selection, 1:1 pixels, output format, and reference settings.
|
||
- **Layers**: selected-layer properties, crop/reset, alignment, shared resizing,
|
||
lock/hide, and per-layer selection/visibility/lock controls.
|
||
- **Options**: resize aspect ratio and the source-coordinate preview.
|
||
|
||
The toolbar, cog and right-click shortcuts use the same commands and preferences.
|
||
Detailed numeric controls remain in their existing properties dialogs.
|
||
|
||
Enable **Options → Show toolbar icon names** (also available from the toolbar cog)
|
||
to display captions beneath the icons. It is off by default and saved with the
|
||
project; older projects open with captions off.
|
||
|
||
### Application themes
|
||
|
||
**Menu → Options → Theme** (also in the toolbar cog) shows up to three recently
|
||
used themes, newest first. **More themes…** opens the complete picker with color
|
||
swatches: Midra Dark plus all 18 themes from the SOTV song-database theme folder.
|
||
A fresh installation lists only Midra Dark until other themes are selected.
|
||
Selecting a theme updates the UI and viewport immediately and saves the recent
|
||
history across restarts. Reusing a theme moves it to the top without duplicates.
|
||
Closing the picker without choosing leaves the theme and history unchanged.
|
||
|
||
The viewport, grid, layer boxes and source test patterns use the selected palette;
|
||
selected layers remain gold (darker gold for contrast in light themes). Imported
|
||
reference images retain their colors. Theme and history survive opening projects
|
||
and are not included in project JSON or SVG exports.
|
||
|
||
The SOTV palettes are bundled with the app from
|
||
`sotv/song_database/styles/themes/` in the sibling `SOTV_Websites` repository;
|
||
Corporate Light uses `styles/base/variables.css`. No sibling repository is needed
|
||
to build or run Midra Layout. See the [theme catalog and settings contract](interfaces/midra-layout-settings.md)
|
||
for names, source files, stable IDs and palette adaptations.
|
||
|
||
### Saved application options
|
||
|
||
Options save automatically when changed: theme, toolbar icon names, aspect-ratio
|
||
lock and source-coordinate preview. No separate Apply or Save is needed.
|
||
The `directories` crate selects the OS configuration directory:
|
||
|
||
- Linux: `$XDG_CONFIG_HOME/midra-layout/settings.json`, or
|
||
`~/.config/midra-layout/settings.json` when XDG_CONFIG_HOME is unset.
|
||
- Windows: `%APPDATA%\beffroi\midra-layout\config\settings.json`.
|
||
- macOS: `~/Library/Application Support/org.beffroi.midra-layout/settings.json`.
|
||
|
||
Hover **Options save automatically** in Options to see the actual path. These are
|
||
startup defaults. Existing project files still restore their saved aspect-ratio,
|
||
caption and source-preview settings for the open document, without rewriting the
|
||
application defaults. A subsequent explicit Options change saves the current set
|
||
of options as the new defaults. Theme always remains an application preference.
|
||
|
||
Missing settings use defaults; the file is created on the first option change.
|
||
Unreadable, malformed or unsupported settings use defaults and show an Options
|
||
error; the original file is preserved and saving is disabled until the file is
|
||
repaired or moved and the application restarted. Write failures keep options
|
||
active in memory and offer **Retry saving options**. No project data, images or
|
||
clipboard contents are stored here. The [settings interface](interfaces/midra-layout-settings.md)
|
||
documents the file and compatibility rules.
|
||
|
||
**Keep aspect ratio when resizing** is also available directly above
|
||
**Apply position / size** in the selected layer's right panel and in the layer
|
||
right-click menu (including multiple selections). These controls share the
|
||
Options setting and save changes automatically. They do not apply or discard
|
||
pending size/position edits. Crop zoom remains proportional.
|
||
|
||
## Preferences window
|
||
|
||
Open **Menu → Preferences…**, **Options → Preferences…**, the toolbar cog's
|
||
**Preferences…** entry, or **Ctrl/Cmd+,**. The window groups the available controls:
|
||
|
||
- **Appearance:** themes, recent choices, icon captions and source-coordinate preview.
|
||
- **Editing:** aspect-ratio lock, movement snapping and a keyboard/mouse reference.
|
||
- **Reference images:** import and access to the current project's image settings.
|
||
- **Files & settings:** the settings-file path, copy-path action and restore defaults.
|
||
- **Midra integration:** current offline status and compatibility limitations.
|
||
|
||
Changes apply and save immediately, sharing state with quick menus and inspector
|
||
shortcuts. Close simply dismisses the window. Restore defaults resets preferences
|
||
without altering geometry or pending position/size edits. Device controls are not
|
||
presented as implemented until their mapping and transport are available.
|
||
|
||
### Movement snapping
|
||
|
||
Enable **Preferences → Editing → Snap while moving layers** and choose pixel,
|
||
screen-edge and/or other-visible-layer-edge targets. Nearby edges show a guide;
|
||
the proximity radius stays six logical pixels at any zoom. A selection moves as
|
||
a rigid group. Hidden layers are ignored; visible locked layers can be targets.
|
||
Hold **Alt** to bypass snapping. Turning snapping on/off alone never moves layers.
|
||
Exact numeric entry and nudges bypass proximity snapping; resize and crop handles
|
||
retain their existing behavior. One drag remains one undo step, with Escape to cancel.
|
||
|
||
## Hardware connectivity check
|
||
|
||
The [Eikos 3.3.10 check](midra-layout-device-check.md) records the authorized
|
||
Preview-only round trip and a read-only snapshot/SVG import helper. The desktop
|
||
editor remains offline; full device crop mapping and GUI connectivity are pending.
|