beffroi-tools/docs/canvas-pilot/resolutions.md

280 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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`:
```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
Implemented device adapter: supports both an **output-sized Midra layer with internal
cropping** and a **source-aspect layer container with derived sizing
and cropping**. These use distinct container sizing algorithms, described in
[the device exchange contract](../interfaces/midra-device-send.md), with hardware
write/readback checks on Eikos 3.3.10. Physical-screen comparison remains outstanding. See
[remaining acceptance checks](plan.md#remaining-tests).
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
“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.