Transform stage on a finished cut: trim, output crop, resize, and a looping result preview

docs/v1-scope.md

@@ -59,6 +59,7 @@ Nothing else gates V1. When that sentence is true end to end, V1 is done.
 | Accessibility | Full keyboard reachability, correct tab order, accessible names and values on **standard** widgets, no colour-only status. |
 | Persistence | `QSettings` primitives, window geometry, output directory. |
 | Cuts | Post-segmentation cuts are persisted, editable, selectable from a promoted cut-set picker, and reusable through Rebuild. **Scope reopened 2026-08-31:** re-rendering an edited clip otherwise repeats segmentation, including a 927 MiB model and 39 inferences, merely to re-encode. |
+| Transform | A finished cut can be trimmed to a frame range, cropped, and resized (explicit dimensions or a 7TV preset, with a keep/stretch/cover/pad mismatch policy) and re-encoded through Rebuild, without touching the stored cut frames or re-running segmentation. **Scope reopened 2026-09-04 (issue #25):** the transform is remembered per cut in a sidecar beside the cut directory, not in the manifest — the manifest modules are frozen and reject unknown keys, and a sidecar written inside the cut directory would invalidate the whole set for the picker. |
 
 ### Recorded design deviations
 

src/matteloop/app.py

@@ -71,6 +71,9 @@ def _run_gui() -> int:
         provider_options=provider_options,
     )
     controller.set_dialog_parent(window)
+    controller.attach_transform_stage(
+        window.inspector.transform_group, window.result_canvas
+    )
     application.aboutToQuit.connect(controller.shutdown)
     window.show()
     return application.exec()

src/matteloop/core/crop.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import math
+from fractions import Fraction
 
 from matteloop.core.geometry import (
     InteractionGeometry,
@@ -25,6 +26,8 @@
         "west",
     }
 )
+_CORNER_HANDLES = frozenset({"north_west", "north_east", "south_east", "south_west"})
+_EDGE_HANDLES = frozenset({"north", "south", "east", "west"})
 
 
 def crop_from_drag(
@@ -68,12 +71,23 @@ def nudge_crop(
 
 
 def clamp_crop(crop: CropSpec, source_width: int, source_height: int) -> CropSpec:
-    """Clamp an otherwise valid crop to a non-empty source rectangle."""
+    """Clamp an otherwise valid crop to fit inside a source rectangle.
+
+    A crop that still fits at its stored size (e.g. after the framed frame
+    shrank underneath it -- a padding change or a cut-set switch) is *slid*
+    inward to stay in bounds; its width/height are preserved. Only a crop
+    genuinely larger than the frame in an axis is shrunk on that axis. Doing
+    it in this order -- shrink to fit, then clamp the origin into what
+    remains -- naturally slides an origin that was fine before the frame
+    shrank, instead of trimming a corner down to nothing (issue #25: a crop
+    near the right/bottom edge collapsing below MIN_FINAL_DIMENSION and the
+    render being refused for a precondition the user cannot see or fix).
+    """
     _validate_dimensions(source_width, source_height)
-    left = min(max(crop.x, 0), source_width - 1)
-    top = min(max(crop.y, 0), source_height - 1)
-    width = min(max(crop.width, 1), source_width - left)
-    height = min(max(crop.height, 1), source_height - top)
+    width = min(max(crop.width, 1), source_width)
+    height = min(max(crop.height, 1), source_height)
+    left = min(max(crop.x, 0), source_width - width)
+    top = min(max(crop.y, 0), source_height - height)
     return CropSpec(left, top, width, height)
 
 
@@ -105,6 +119,107 @@ def oriented_point_from_widget(
     return _orientation_transform_from_media(transform).source_to_widget(raw)
 
 
+def fit_crop_aspect(
+    crop: CropSpec,
+    ratio: Fraction,
+    target: str,
+    *,
+    source_width: int,
+    source_height: int,
+) -> CropSpec:
+    """Re-fit *crop* to width:height == *ratio* after a handle/body move.
+
+    Corner handles keep the dragged corner's opposite corner fixed and
+    adjust whichever axis needs the smaller change to reach the ratio.
+    Edge handles adjust the perpendicular axis around the crop's centre.
+    A body move ("crop") is returned unchanged. The result is always
+    clamped to the source and has both dimensions >= 1.
+    """
+    _validate_dimensions(source_width, source_height)
+    _validate_ratio(ratio)
+    if target == "crop":
+        fitted = crop
+    elif target in _CORNER_HANDLES:
+        fitted = _fit_corner(crop, ratio, target)
+    elif target in _EDGE_HANDLES:
+        fitted = _fit_edge(
+            crop, ratio, target, source_width=source_width, source_height=source_height
+        )
+    else:
+        raise ValueError("unknown crop interaction target")
+    return clamp_crop(fitted, source_width, source_height)
+
+
+def centered_crop_for_aspect(
+    ratio: Fraction, *, source_width: int, source_height: int
+) -> CropSpec:
+    """Return the largest centred rectangle of *ratio* inside the source."""
+    _validate_dimensions(source_width, source_height)
+    _validate_ratio(ratio)
+    height_for_full_width = _rhu(Fraction(source_width) / ratio)
+    if height_for_full_width <= source_height:
+        width, height = source_width, max(1, height_for_full_width)
+    else:
+        width, height = max(1, _rhu(Fraction(source_height) * ratio)), source_height
+    x = (source_width - width) // 2
+    y = (source_height - height) // 2
+    return clamp_crop(CropSpec(x, y, width, height), source_width, source_height)
+
+
+def _fit_corner(crop: CropSpec, ratio: Fraction, target: str) -> CropSpec:
+    width, height = crop.width, crop.height
+    width_for_height = _rhu(Fraction(height) * ratio)
+    height_for_width = _rhu(Fraction(width) / ratio)
+    if abs(width_for_height - width) <= abs(height_for_width - height):
+        new_width, new_height = max(1, width_for_height), height
+    else:
+        new_width, new_height = width, max(1, height_for_width)
+    x = crop.x + width - new_width if "west" in target else crop.x
+    y = crop.y + height - new_height if "north" in target else crop.y
+    return CropSpec(x, y, new_width, new_height)
+
+
+def _fit_edge(
+    crop: CropSpec,
+    ratio: Fraction,
+    target: str,
+    *,
+    source_width: int,
+    source_height: int,
+) -> CropSpec:
+    width, height = crop.width, crop.height
+    if target in {"east", "west"}:
+        new_height = max(1, min(source_height, _rhu(Fraction(width) / ratio)))
+        y = _bounded_centered_origin(crop.y, height, new_height, source_height)
+        return CropSpec(crop.x, y, width, new_height)
+    new_width = max(1, min(source_width, _rhu(Fraction(height) * ratio)))
+    x = _bounded_centered_origin(crop.x, width, new_width, source_width)
+    return CropSpec(x, crop.y, new_width, height)
+
+
+def _bounded_centered_origin(
+    origin: int, old_size: int, new_size: int, extent: int
+) -> int:
+    """Re-centre a resized edge on its old midpoint, clamped inside *extent*.
+
+    Growing the perpendicular axis around the centre can otherwise place the
+    new origin outside [0, extent - new_size] and CropSpec would reject it
+    before `fit_crop_aspect`'s later clamp_crop ever runs.
+    """
+    proposed = origin + _rhu(Fraction(old_size - new_size, 2))
+    return min(max(proposed, 0), max(0, extent - new_size))
+
+
+def _validate_ratio(ratio: Fraction) -> None:
+    if not isinstance(ratio, Fraction) or ratio <= 0:
+        raise ValueError("aspect ratio must be a positive Fraction")
+
+
+def _rhu(value: Fraction) -> int:
+    """Round half up (towards +infinity) on an exact Fraction."""
+    return (2 * value.numerator + value.denominator) // (2 * value.denominator)
+
+
 def _move_crop(
     crop: CropSpec, dx: int, dy: int, source_width: int, source_height: int
 ) -> CropSpec:

src/matteloop/core/errors.py

@@ -13,6 +13,7 @@ class ErrorCode(StrEnum):
     INVALID_CROP = "invalid_crop"
     INVALID_SEGMENTATION = "invalid_segmentation"
     INVALID_FRAMING = "invalid_framing"
+    INVALID_TRANSFORM = "invalid_transform"
     INVALID_OUTPUT = "invalid_output"
     INVALID_RENDER_REQUEST = "invalid_render_request"
     INVALID_FINAL_DIMENSIONS = "invalid_final_dimensions"

src/matteloop/core/parameters.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from collections.abc import Callable, Mapping
-from dataclasses import dataclass, replace
+from dataclasses import dataclass, field, replace
 from decimal import Decimal, InvalidOperation
 from fractions import Fraction
 from pathlib import Path
@@ -20,6 +20,7 @@
     OutputSpec,
     SamplingSpec,
     SegmentationSpec,
+    TransformSpec,
     is_local_path_syntax,
 )
 
@@ -58,6 +59,7 @@ class ParameterState:
     output_filename: str | None = None
     max_mib: Decimal = Decimal("0")
     execution_provider: str = CPU_EXECUTION_PROVIDER
+    transform: TransformSpec = field(default_factory=TransformSpec)
 
     def __post_init__(self) -> None:
         if self.model_id not in V1_MODEL_IDS:
@@ -141,6 +143,11 @@ class OutputMaxSizeChanged:
     value: Decimal
 
 
+@dataclass(frozen=True, slots=True)
+class TransformChanged:
+    transform: TransformSpec
+
+
 ParameterEvent = (
     ModelChanged
     | EdgeModeChanged
@@ -153,6 +160,7 @@ class OutputMaxSizeChanged:
     | OutputDirectoryChanged
     | OutputFilenameChanged
     | OutputMaxSizeChanged
+    | TransformChanged
 )
 
 
@@ -184,6 +192,8 @@ def reduce_parameters(state: AppState, event: ParameterEvent) -> AppState:
         return _reduce_output_filename(state, event)
     if isinstance(event, OutputMaxSizeChanged):
         return _reduce_output_max_size(state, event)
+    if isinstance(event, TransformChanged):
+        return _reduce_transform(state, event)
     return state
 
 
@@ -318,6 +328,18 @@ def _reduce_output_max_size(
     return replace(state, parameters=updated)
 
 
+def _reduce_transform(state: AppState, event: TransformChanged) -> AppState:
+    """Replace the transform in place; a transform never stales the preview."""
+    if (
+        not isinstance(event.transform, TransformSpec)
+        or event.transform == state.parameters.transform
+    ):
+        return state
+    return replace(
+        state, parameters=replace(state.parameters, transform=event.transform)
+    )
+
+
 def _invalidate(
     state: AppState, parameters: ParameterState, category: str
 ) -> AppState: