beffroi-tools/docs/midra-layout/guide/formats-and-crop.md

162 lines
11 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.

# Formats, crop and precision
[Midra Layout](../README.md) · [Guide contents](README.md) · [Starter files](../../templates/midra-layout/README.md)
## 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.
Valid output presets and numeric resolution edits apply immediately; invalid drafts
leave the output unchanged and are retained for correction.
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. Enable advanced editing in **Source**, choose a local **Editor input**, then its original **Source format** and native
dimensions. Editor inputs 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. Crop edges stop at zero
when dragging; negative or non-finite typed/pasted values are not accepted. 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. Layer changes apply immediately;
the selected measurement anchor stays fixed. Source/input changes require Apply.
4. Use **Layer crop / zoom & position** for zoom (100–10000%) and X/Y offsets in output pixels.
Zoom is bounded to 100–10000%; negative or non-finite entries are rejected.
X/Y offsets remain signed for left/up positioning; they are not crop amounts.
These controls operate on the applied formats and update immediately as edited.
A continuous zoom/offset drag is one Undo step;
**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; double-click again or 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.
**Layer properties → Crop** activates visual crop editing while the tab is open.
Switching to Source/Layer or closing the window turns it off; no extra button is needed.
The standalone inspector and context-menu crop controls remain available.
**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](../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 drafts, source/input formats, names/folders, and mapped imports. Each
section tracks its own values; reverting an edit clears its pending state.
**Source is an advanced section**, disabled until **Edit advanced input settings
and include my edits when sending** is checked. Its device controls mirror the
linked Preview layer's current input and active plug in WebRCS Advanced Input:
content ratio, transform ratio, custom ratio, layer fill, input crop preset and
four pixel crop edges. Usually keep these settings on the Midra. Input crop
runs before dynamic layer crop/zoom without resizing the layer bounding box;
this is device processing, not an editor-only effect. Inputs are shared, so an
input edit can also affect other layers and Program.
Opening Source, checking the box, or changing a value does not send. Only fields
actually edited are staged for the next explicit Send, and only when that send
includes a destination routed to the same input/plug. Untouched aspect/crop
settings stay as they are on the machine. Unchecking discards staged edits.
The opt-in and device edits are session-only: disconnecting, changing the device
address or loading a project clears them. Source routing is never changed.
Refresh/load after sending to inspect the resulting device content dimensions.
The separately labeled **Editor source model (local geometry)** retains the
existing offline format/input-resolution calculations, also gated by the checkbox.
Its native dimensions are metadata, not device timing commands. Its local input
correction still folds into exported *layer* crop; it does not configure the
shared hardware input. Apply source changes commits this local model, whereas
the device controls above wait for Send.
Layer properties has five tabs: **Source** for native/input resolution and input
crop, **Layer** for the final visible box, **Crop** for content zoom and offset,
**Mapping** for the saved Midra screen/layer link, and **Preview** for capture, timed refresh, preview visibility, guide opacity and the cropped image preview. Editor input identity belongs to the opt-in **Source** tab.
The right-click properties entries open their matching tab directly.
Mapping offers device screen/layer selectors when connected, or numeric IDs offline.
Link edits apply locally immediately and support Undo. **Unmap** removes the link,
excluding the layer from linked sends and loads; it does not change the device.
Editor input identity remains a separate source setting requiring Apply.
Switching tabs retains pending Source edits, which require Apply. Layer size and
Crop changes apply immediately; each continuous drag is one Undo step.
Position/size edits commit on Enter or focus loss, output resolution changes
apply as edited, and names/folders commit on Enter or focus loss (also before
closing or changing the layer list). These controls have no Apply button.
Invalid geometry stays unchanged and errors appear inline. Closing output
settings discards invalid uncommitted values without a confirmation dialog.
Source edits remain staged; **Apply source changes** commits them. Closing with
pending Source edits, a rename, invalid batch names/folders, or mapped Midra
imports asks **Would you like to apply changes?**, with **Apply** and **Discard**.
Invalid Apply keeps the draft and error. Clipboard/SVG review uses **Import mapped
values**; Escape or clicking outside asks Apply/Discard, while Cancel discards.
Pending property/name edits temporarily disable the main workspace to preserve
the edited layer. Switching property tabs keeps pending Source edits.
Reference display, camera, theme and preference controls already apply immediately.
Device destination links also save to the local document immediately. Device
sends remain explicit: closing export configuration never sends, and local
Apply/Discard prompts never write to Midra. This does not change project save or
application-exit behavior. Applied edits recover automatically on launch; use Save project for a separate named copy.
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.