From 31456b31a11d7e1bdda16afd170afcba9401ac73 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Fri, 13 Nov 2026 11:16:30 +0100 Subject: [PATCH] Plan Midra formats and advanced cropping geometry --- docs/midra-layout-plan.md | 66 ++++++-- docs/midra-layout-resolutions.md | 263 +++++++++++++++++++++++++++++++ 2 files changed, 320 insertions(+), 9 deletions(-) create mode 100644 docs/midra-layout-resolutions.md diff --git a/docs/midra-layout-plan.md b/docs/midra-layout-plan.md index 9d07a03..3109f04 100644 --- a/docs/midra-layout-plan.md +++ b/docs/midra-layout-plan.md @@ -7,7 +7,7 @@ from a different Midra generation's documentation. Working name: **Midra Layout* ## Intended workflow -Set the screen resolution, optionally load a reference picture, then place one or +Set the output format and preset or custom screen resolution, optionally load a reference picture, then place one or two rectangular live layers visually or by entering exact offsets from a chosen screen corner. Read or copy their equivalent WebRCS position values. Select layers on the canvas or in the right-hand list. All work is local and offline. @@ -19,14 +19,19 @@ more later without promising that every device configuration supports them. The reference image is an editing aid, not an additional hardware layer. Screen resolution is independent of the application window size, zoom and image size. -Source routing, transitions, playback, cropping, masking, rotation, keying, live -preview and device control are outside this project phase. Width and height are -needed for positioning, but this is not an image or presentation editor. +Source routing, transitions, playback, masking, rotation, keying, live preview +and device control remain outside scope. Input cropping and virtual layer +resolutions are now planned, with support deferred until after the first draft. +Their coordinate spaces must be designed from the start. See the +[resolution and advanced-cropping specification](midra-layout-resolutions.md). ## Ordered task list Complete each acceptance gate before broadening the scope. The first usable -release comprises steps 1–6 and release checks in step 8. Step 7 is later work. +positioning draft comprises steps 1–6, including source/output format selection +and custom viewport dimensions, and the applicable checks in step 8. Steps 7 +and 9 follow the draft. Step 9 is committed scope; its device compatibility +checks must pass before presenting advanced-crop values as usable in WebRCS. ### 1. Establish the Eikos 4K coordinate contract @@ -36,6 +41,10 @@ release comprises steps 1–6 and release checks in step 8. Step 7 is later work - [ ] Verify whether the editable bounds refer to the layer rectangle rather than cropped source content. Start with an unmasked, uncropped live layer. - [ ] Check odd widths/heights and half-pixel centers; do not round silently. +- [ ] Establish input-crop and layer-crop coordinate spaces, units, processing + order, limits and Centered aspect behavior for the later resolution milestone. + Separate final visible bounds from any device layer container; do not infer + container size or position from the uncropped image's projected dimensions. - [ ] Record examples at all four screen corners and at screen center using a simulator or manual entry in an appropriate test setup, without API calls. @@ -64,7 +73,11 @@ toolkit cannot meet these needs, resolve that before building the rest. - [ ] Add the future workspace member `crates/midra-layout/` with shared geometry and a desktop binary. Do not add placeholder workspace members during planning. - [ ] Model screen dimensions and stable layer IDs with canonical top-left - position and size. Keep selection, camera and reference image separate. + position and final visible size. Keep selection, camera and reference image separate. +- [ ] Define source format/native dimensions, input crop, advanced crop and + derived device geometry as distinct concepts from day one. Store crop edges + and final size as authoritative geometry; content zoom/offset are derived + controls. Do not implement crop interactions until after the first draft. - [ ] Implement four-corner offset conversion and inverse WebRCS conversion under the verified device contract. - [ ] Switching corner changes the displayed offsets without moving the layer. @@ -80,6 +93,16 @@ Gate: viewport scale and UI state cannot affect geometry or conversion results. - [ ] Add screen resolution controls, one/two-layer setup, persistent layer IDs and names, and a right-hand layer list with a selected-layer inspector. +- [ ] Add source format choices (including 4:3, 16:9 and 16:10) with explicit + native pixel dimensions; an aspect ratio alone is not a pixel resolution. +- [ ] Add output format choices and clearly labeled viewport resolution presets + (HD 1280 × 720, Full HD 1920 × 1080, UHD 4K 3840 × 2160), plus manual width + and height. Derive the output ratio from custom dimensions, never silently + stretch them to match a preset. Other formats can be added after validation. +- [ ] Changing output dimensions preserves existing layer pixel bounds, flags + out-of-screen layers and rechecks reference-image mapping. Validate positive + integer dimensions independently of verified device output support; custom + planning geometry must not imply that Eikos accepts every output mode. - [ ] Support click selection, Shift-click multi-selection, clear selection and list selection for overlapped or off-screen rectangles. Define deterministic overlap hit testing; list order represents preview stacking, not device routing. @@ -183,10 +206,34 @@ regardless of selection order except when explicitly choosing a reference layer. Session-file save/load can follow if needed; it is not required to demonstrate precise positioning. No networking work is included in this plan. +### 9. After the first draft: input and layer resolutions + +- [ ] Implement the separate input-crop and advanced-crop stages defined in the + [resolution specification](midra-layout-resolutions.md), with no device calls. +- [ ] Keep Source format selected when Input resolution is Custom. Support exact + input dimensions and crop placement, defaulting to equal opposite-side crops. +- [ ] Expose Layer resolution as the final visible width/height, with optional + aspect lock. Add Content zoom and Offset X/Y controls and an explicit content + framing mode; moving the layer and moving its content must be distinct actions. +- [ ] Keep the final box fixed during content framing; store four crop edges and + final size, derive zoom/offset, and compose input/layer crops without applying + either stage twice. Preserve source-level sharing when two layers use one input. +- [ ] Test the documented numerical examples, inverse transforms, offset limits, + extreme ratios, fractional crops, resizing, shared inputs and undo behavior. +- [ ] Verify the device adapter's crop units, Centered mode, layer container size + and center position with the actual firmware. Show rounding error; block values + that cannot preserve the requested box within the verified device precision. +- [ ] Add UI review, documentation and release checks for these features before + claiming them as supported. Existing A/B/C mockups depict the positioning draft. + +Gate: the user's 1920 × 1080 source → 1920 × 1000 input → 300 × 250 layer +workflow retains a 300 × 250 selectable box through zoom, content offset and +placement. The WebRCS settings reproduce the same visible result without masking. + ## Coordinate contract to verify Proposed internal model: screen origin at its top-left, X increases rightward, -Y increases downward, and a layer is `(x, y, width, height)`. Positive corner +Y increases downward, and a layer's final visible box is `(x, y, width, height)`. Positive corner offsets point inward. A corner means the matching corner of the layer measured from that screen corner; there are not two independent anchor selectors in v1. @@ -199,7 +246,7 @@ For screen size `W × H`, layer size `w × h`, and offsets `dx, dy`: | Bottom left | `dx` | `H - dy - h` | | Bottom right | `W - dx - w` | `H - dy - h` | -Under the user's described center-position convention, WebRCS values are +For the uncropped positioning draft, under the user's described center-position convention, WebRCS values are `horizontal = x + w/2`, `vertical = y + h/2`. The inverse subtracts the half-size. The corresponding inward margins are `left=x`, `top=y`, `right=W-x-w` and `bottom=H-y-h`. Switching corner just chooses which margins to display. @@ -209,7 +256,8 @@ Example used in every mockup: on a **1920 × 1080** screen, a **640 × 360** lay and center **1480, 360**. The other layer is at **120, 180**, center **440, 360**. An odd width such as 641 produces a half-pixel center when the left edge is an integer; hardware acceptance/rounding is a compatibility question, not something -to hide with display formatting. +to hide with display formatting. Advanced cropping must retain these visible-box +coordinates while deriving any distinct device container through its adapter. ## Visual proposals diff --git a/docs/midra-layout-resolutions.md b/docs/midra-layout-resolutions.md new file mode 100644 index 0000000..b35d708 --- /dev/null +++ b/docs/midra-layout-resolutions.md @@ -0,0 +1,263 @@ +# Midra formats, resolutions and advanced cropping + +Status: planned scope, not implemented. Companion to the +[task list and visual proposals](midra-layout-plan.md). 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`: + +```text +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. + +```text +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: + +```text +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: + +```text +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: + +```text +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: + +```text +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](https://www.bhphotovideo.com/lit_files/1168243.pdf#page=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 + “Edit content” 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.