Plan Midra formats and advanced cropping geometry

This commit is contained in:
Dandaedre 2026-11-13 11:16:30 +01:00
parent 3446e4ca35
commit 31456b31a1
2 changed files with 320 additions and 9 deletions

View File

@ -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

View File

@ -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.