Files
2026-08-24 14:24:25 +09:00

132 lines
5.2 KiB
Python

"""Small decoded-boundary patches for the V3.5 direct-write assembler.
The established V3.4 seam analyzer remains the source of all boundary
decisions. This module reproduces only the correction step while avoiding the
full physical-group clone performed by ``correct_decoded_boundaries``.
"""
from __future__ import annotations
from typing import Any
import torch
from .plan import validate_assembly_plan
from .video_seam import VideoBoundaryAnalysis, _validate_frames
def build_boundary_patches(
images: list[Any],
assembly_plan: dict[str, Any],
analyses: list[VideoBoundaryAnalysis],
*,
enable_exposure_ramp: bool = False,
) -> tuple[dict[int, torch.Tensor], dict[int, str]]:
"""Return qualified 1--4 frame corrections without changing ``images``.
Patch keys are the existing one-based ``boundary_index`` values. They are
also the zero-based index of the current physical decode group, so the
direct writer can add its natural-frame cursor without this module knowing
the final buffer layout.
The result is transactional: all patches and actions are built in local
containers and are returned only after every requested boundary succeeds.
Any exception therefore leaves the caller with no partial correction set.
"""
plan = validate_assembly_plan(assembly_plan)
groups = list(
plan["decode_groups"] if "decode_groups" in plan else plan["chunks"]
)
if len(images) != len(groups):
raise ValueError("decoded image count does not match the assembly plan")
patches: dict[int, torch.Tensor] = {}
actions: dict[int, str] = {}
for analysis in analyses:
boundary = int(analysis.boundary_index)
correction_kind = "transient flash"
replace_frames = int(analysis.recommended_rewind)
if analysis.micro_flash_candidate:
correction_kind = "micro-flash"
replace_frames = 1
elif enable_exposure_ramp and analysis.exposure_ramp_candidate:
correction_kind = "exposure ramp"
replace_frames = 4
if replace_frames <= 0:
actions[boundary] = "kept native boundary"
continue
if analysis.scene_cut or not (
analysis.transient_flash_candidate
or analysis.micro_flash_candidate
or (enable_exposure_ramp and analysis.exposure_ramp_candidate)
):
actions[boundary] = (
"kept native boundary; correction guard rejected candidate"
)
continue
previous_index = boundary - 1
current_index = boundary
if previous_index < 0 or current_index >= len(images):
raise ValueError("video seam boundary index is outside decoded chunks")
previous_raw = images[previous_index]
current_raw = images[current_index]
_validate_frames(
previous_raw,
f"decoded image chunk {previous_index + 1}",
)
_validate_frames(
current_raw,
f"decoded image chunk {current_index + 1}",
)
previous_plan = groups[previous_index]
current_plan = groups[current_index]
previous_total = int(previous_plan["total_frames"])
previous_trim = int(previous_plan["trim_frames"])
current_total = int(current_plan["total_frames"])
current_trim = int(current_plan["trim_frames"])
if current_trim + replace_frames >= current_total:
raise ValueError("video seam correction has no retained recovery frame")
previous_segment = previous_raw[:previous_total][previous_trim:]
if int(previous_segment.shape[0]) < 1:
raise ValueError("video seam correction has no previous retained frame")
# Only the frames that may be changed are cloned. The recovery frame
# and previous anchor remain read-only views of their physical groups.
patch = current_raw[
current_trim : current_trim + replace_frames
].detach().to(device="cpu").clone()
if int(patch.shape[0]) != replace_frames:
raise ValueError("video seam correction frames are outside the current chunk")
previous_anchor = previous_segment[-1].detach().to(
device="cpu",
dtype=torch.float32,
)
recovery_anchor = current_raw[current_trim + replace_frames].detach().to(
device="cpu",
dtype=torch.float32,
)
if tuple(previous_anchor.shape) != tuple(recovery_anchor.shape):
raise ValueError("decoded image geometry changed at video seam")
for offset in range(replace_frames):
alpha = float(offset + 1) / float(replace_frames + 1)
original = patch[offset].to(dtype=torch.float32)
target = torch.lerp(previous_anchor, recovery_anchor, alpha)
original_mean = original.mean(dim=(0, 1), keepdim=True)
target_mean = target.mean(dim=(0, 1), keepdim=True)
normalized = (original + target_mean - original_mean).clamp(0.0, 1.0)
patch[offset].copy_(normalized.to(dtype=patch.dtype))
patches[boundary] = patch
actions[boundary] = (
f"normalized exposure/color on {replace_frames} {correction_kind} "
"boundary frame(s)"
)
return patches, actions