beffroi-tools/docs/midra-layout-resolutions.md

15 KiB
Raw Blame History

Midra formats, resolutions and advanced cropping

Status: offline geometry and UI implemented. Source/native formats, shared input cropping, virtual layer resolution, content zoom/offset, content dragging, dynamic output resolution, reference remapping and atomic undo are available. Crops are authoritative; zoom/offset are derived controls. Hardware container behavior, firmware crop limits and quantization remain unverified and are never presented as a validated device recipe. No REST calls are made.

Implementation limits: integer native/output dimensions 1–16384 per side; positive finite layer/input dimensions up to 1,000,000 px; content zoom 100–10000%. These are planning limits, not claimed hardware capabilities. Invalid edits are rejected atomically. If framing must shift after a resize/source change, the crop offsets adjust automatically to fit the new dimensions. Undo restores size and crop together. Layer properties exposes crop adjustment and reset controls.

Names and coordinate spaces

User-facing name Meaning Internal representation
Source format Original aspect, e.g. 4:3, 16:9, 16:10, with explicit native pixel dimensions Source identity, native width/height, selected aspect
Output format Aspect of the screen represented by the viewport Derived from output width/height; optional preset/ratio lock
Viewport resolution Output screen pixels, selected from a preset or entered manually Positive integer screen width/height
Input resolution Usable source area after input-level cropping; Custom retains the original Source format selection Four crop edges in native source pixels; remaining dimensions derived
Layer resolution Final visible box on the screen, e.g. 300 × 250 Final width/height plus advanced cropping, stored as four crop edges relative to the usable input
Content zoom How tightly that usable input is framed inside the final box Derived from crop rectangle and final size; 100% means minimum crop needed to fill the box
Offset X / Y Movement of content inside the final box Derived from asymmetric crop; positive values move the picture right/down
Viewport zoom Magnification of the editor view only Camera state; never changes output pixels or cropping

Assume square pixels for the initial implementation. A source format such as 16:9 does not establish whether its native size is 1280 × 720 or 1920 × 1080. Require native dimensions before converting pixel crops. Non-square-pixel or aspect-corrected inputs need an explicit later mapping; never infer one.

Cropping a 1920 × 1080 source to 1920 × 1000 changes the usable aspect to 1.92:1. The Source format still reads 16:9 because it describes the original source. It must not force the cropped area back to 16:9 or distort its pixels. This is the implemented interpretation of Custom input resolution.

Output controls in the first draft

Provide HD 1280 × 720, Full HD 1920 × 1080 and UHD 4K 3840 × 2160 as explicit resolution labels. Do not use “4K” alone where it could mean 4096 × 2160. Offer format choices such as 4:3, 16:9 and 16:10, and always display the actual width and height. A locked ratio links dimension edits; an unlocked custom pair sets its own ratio. Changing a format with a ratio lock preserves width and proposes the corresponding height, showing any integer rounding before commit. Choosing a resolution preset sets both dimensions and its ratio in one action.

Custom width/height are first-class, not hidden behind a device-preset list. Reject zero, negative, noninteger and nonfinite viewport dimensions. Enforce documented implementation limits, but distinguish these from supported device output modes. An arbitrary planning resolution is not a promise that the device can be configured to produce it.

Changing viewport resolution preserves layer positions and sizes in screen pixels. Recompute displayed right/bottom offsets; do not silently reposition or scale layers to preserve margins. Revalidate image mapping and off-screen status. Changing the application window size only changes the camera/layout.

Input resolution: source-level crop

For native dimensions Nw × Nh and input crops Il, Ir, It, Ib:

Iw = Nw - Il - Ir
Ih = Nh - It - Ib

All crop amounts are nonnegative and the remaining area must be positive. Custom dimensions may reduce either axis but cannot manufacture additional source pixels. Initially center the retained area, dividing removed pixels equally; provide explicit crop placement so black bars or unwanted edges need not be symmetric. Preserve fractional results internally until device quantization.

Example: native 1920 × 1080, input 1920 × 1000 gives input crops left 0, right 0, top 40, bottom 40. Source format remains 16:9.

Input cropping belongs to the source identity. If both layers use the same physical input, they share its input-resolution correction, while each has its own advanced crop. Show which layers an input edit affects and apply it as one undoable transaction. Different proposed input crops cannot be exported as if they were independent settings for the same physical input.

Layer resolution: advanced cropping

The visible layer box Bw × Bh is fixed while its content is reframed, just like an avatar crop. Cropping followed by proportional fitting produces the apparent zoom. There is no independent image-zoom transform to export to WebRCS.

The baseline uses cover geometry: scale proportionally until both box dimensions are covered, then remove overflow. It is not sufficient to choose the numerically largest side; compare both scale ratios. This avoids blank bars for landscape, portrait and unusually wide boxes.

Let the usable input be Iw × Ih, content zoom be z ≥ 1, and offsets ox, oy be in final output pixels. At 100%, z = 1; viewport camera zoom is unrelated.

k0 = max(Bw / Iw, Bh / Ih)       # minimum proportional scale that covers box
k  = k0 * z                    # output pixels per usable-input pixel
Rw = Bw / k                    # retained source region width
Rh = Bh / k                    # retained source region height

L = (Iw - Rw) / 2 - ox / k
R = (Iw - Rw) / 2 + ox / k
T = (Ih - Rh) / 2 - oy / k
B = (Ih - Rh) / 2 + oy / k

These four advanced crop edges are in post-input-crop source pixels, not screen pixels or percentages. The retained region starts at (L, T). It has aspect Bw / Bh, so proportional fitting reproduces the final box exactly.

The source-to-box mapping makes the offset sign explicit:

box_x = k * (input_x - L)
box_y = k * (input_y - T)
screen_x = visible_box_left + box_x
screen_y = visible_box_top  + box_y

Valid content offsets keep every crop nonnegative:

abs(ox) <= (k * Iw - Bw) / 2
abs(oy) <= (k * Ih - Bh) / 2

At baseline, one axis usually has no panning range. Increased zoom creates more room to pan. Dragging stops at these explicit limits; invalid typed values show an error rather than silently changing. Never reveal pixels removed by the input crop. Actual firmware crop limits may impose stricter bounds or maximum zoom.

Authoritative state and inverse controls

Store native source metadata, input crops, layer advanced crops, final visible size and visible position. The crops are authoritative; do not persist a second, independent zoom/offset transform that can disagree with them. The UI derives:

Rw = Iw - L - R
Rh = Ih - T - B
k  = Bw / Rw                    # must also equal Bh / Rh
z  = k / max(Bw / Iw, Bh / Ih)
ox = k * (R - L) / 2
oy = k * (B - T) / 2

Reject imported crop tuples that do not satisfy positive remaining area, matching aspect and supported precision. Do not silently stretch mismatched crops. Preserve exact/rational values where practical; never round the intermediate 444.444… width to 445 before computing a crop.

Composing the two crop stages gives native-source retained bounds:

native_left   = Il + L
native_top    = It + T
native_right  = Nw - Ir - R
native_bottom = Nh - Ib - B

This is a geometric identity, not an instruction to send the same crop twice. Keep input and layer settings separate. The device adapter must establish whether layer pixel crops use native dimensions, corrected input dimensions or another reference and convert once. Percent crop denominators also need verification.

Worked examples and expected values

All examples center the crop unless an offset is specified. Native dimensions are 1920 × 1080 and the final layer box is 300 × 250.

Case Input area Content zoom Projected full usable input Advanced crops L / R / T / B, in usable-input pixels
Uncorrected 16:9 1920 × 1080 100% 444.444… × 250 312 / 312 / 0 / 0
Custom input 1920 × 1000 100% 480 × 250 360 / 360 / 0 / 0
Custom input, tighter framing 1920 × 1000 200% 960 × 500 660 / 660 / 250 / 250
Same, content moved right 30 px 1920 × 1000 200% 960 × 500 600 / 720 / 250 / 250

The uncorrected example removes 144.444… output pixels in total horizontally, or 72.222… on either side. The custom-input example removes 180 output pixels, or 90 per side. These are equivalent projected crop amounts, not the stored source-pixel values in the table. Every resulting visible box is 300 × 250.

At 200% with Custom input, the native combined crops are left/right 660 and top/bottom 290: the original 40-pixel input correction plus the 250-pixel layer crop on each vertical side. The retained native region is 600 × 500, scaled by 0.5 to fill the 300 × 250 box. This checks that input correction is applied once.

Device mapping: keep the container separate

Deferred requirement: support both an output-sized Midra layer with internal cropping and a specified-format Midra input (likely 16:9) with derived sizing and cropping. These require distinct export algorithms; neither is implemented or validated by the current provisional calculations. See the two-strategy export backlog.

The intended hardware aspect choice is Centered, as requested. The Analog Way Midra 4K V3.2 manual, pp. 66 and 87 describes input crops in pixels and layer cropping with resizing, with a separate layer aspect selection. It does not establish every processing-order or rounding detail needed here for the installed firmware.

The adapter must return input crop settings, layer crop settings and units, aspect mode, device layer width/height and device center position. Keep these derived values distinct from the visible layer box. Verify whether a crop with the exact target aspect allows the device container to equal that box in Centered mode. If the device uses a different container, derive its size and position from the measured mapping. An asymmetric crop may require a position correction.

The projected full-input sizes in the example table are explanatory geometry, not automatically the layer sizes to enter into WebRCS. Do not confuse the helper's cover calculation with the device's named Centered/Cropped settings. Until verified, show calculations as provisional and do not label them a validated device recipe. Unsupported results must not be approximated with masking.

Quantize only at the device boundary. Check the reconstructed visible rectangle and sampled source region after quantization. Show the requested and achievable values and residual error; block a supposedly exact recipe when its error exceeds the verified device precision. Never silently alter the user's final box.

Interaction and changes to the inspector

Retain the A/B/C positioning layouts. Add sections in this order after the draft:

  1. Source: source identity, Source format and native dimensions; Input resolution preset/custom and its crop placement. Shared-input effects visible.
  2. Layer resolution: final width/height and optional ratio lock, followed by the existing corner positioning controls.
  3. Framing: Content zoom, Offset X/Y, Recenter and Reset framing. An explicit “Adjust layer crop” mode makes dragging reframe content inside the fixed box; ordinary dragging still moves the complete box. Escape leaves framing mode.
  4. WebRCS values: derived size/position, crop settings and aspect mode, with an expandable explanation of units and any representability error.

Recenter preserves zoom and clears offsets. Reset framing sets baseline zoom and centered crops; neither changes input correction or final visible bounds. Pointer-wheel zoom remains camera zoom; content zoom uses its own control to avoid accidental geometry edits. Each drag/edit is one undoable operation.

Cropping requires a content illustration: a source-coordinate test pattern can show framing without live video. A user-provided source still may optionally be added later and must remain distinct from the screen-wide reference image. Do not suggest the screen reference picture is the layer's source content.

Moving or aligning a layer leaves crop settings untouched. Resizing the final box preserves its selected positioning anchor; preserve content zoom and the normalized center of the retained source region, then recompute the required crop aspect. If that center becomes infeasible, show the necessary adjustment before applying. Source/input-resolution changes use the same explicit adjustment policy and affect all layers sharing the source. Do not mutate the crop merely because the inspector's units or selected screen corner change.

Acceptance matrix for implementation

  • Round-trip crop ↔ zoom/offset for all worked examples without accumulating drift.
  • Equal source/box aspect at baseline gives zero advanced crop; landscape-to- portrait and portrait-to-landscape use the correct constrained axis.
  • Increasing zoom preserves final size and crop aspect; content pan changes opposite crop edges equally and oppositely while preserving retained dimensions.
  • Moving the box changes only its screen position; changing camera zoom changes no source, input, layer or device geometry.
  • Test zero/negative dimensions, oversized input custom dimensions, zoom below baseline, nonfinite values, exhausted crop area and out-of-range offsets.
  • Test odd dimensions, fractional edges, extreme aspect ratios, device rounding and repeated zoom/reset cycles without drift or premature integer rounding.
  • Input-crop changes affect shared-source layers consistently; independent layer crops remain independent. Undo restores all affected geometry atomically.
  • Test resizing, source-format changes and reference-image mapping changes with off-screen layers and mixed selections; no implicit proportional repositioning.
  • Compare the final visible bounds and sampled source corners with manual WebRCS results for centered/asymmetric crops and nonzero input correction. Verify both crop stages, aspect mode and device container rather than checking numbers alone.
  • Keep these checks independent of UI rendering; add interaction verification for mode switching, focus, framing limits, preview and undo when the UI is built.