14 KiB
Midra formats, resolutions and advanced cropping
Status: planned scope, not implemented. Companion to the task list and visual proposals. Basic source/output format selection and manual viewport dimensions belong in the first positioning draft. Input cropping and virtual layer resolution follow that draft; design their geometry now so the viewport and device conversion do not need to be conflated.
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 proposed interpretation of Custom input resolution, to review with the user.
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
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:
- Source: source identity, Source format and native dimensions; Input resolution preset/custom and its crop placement. Shared-input effects visible.
- Layer resolution: final width/height and optional ratio lock, followed by the existing corner positioning controls.
- Framing: Content zoom, Offset X/Y, Recenter and Reset framing. An explicit “Edit content” mode makes dragging reframe content inside the fixed box; ordinary dragging still moves the complete box. Escape leaves framing mode.
- 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.