Plan Midra formats and advanced cropping geometry
This commit is contained in:
parent
3446e4ca35
commit
31456b31a1
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue