Files
ComfyUI-H3-Continuum-Tiled/v3/refine_window.py
T

422 lines
16 KiB
Python

"""Pure visible-timeline resolution for Experimental temporal refinement."""
from __future__ import annotations
import hashlib
import json
import math
from collections.abc import Mapping, Sequence
from dataclasses import dataclass
from types import MappingProxyType
from typing import Any
from ..temporal import audio_latent_t, latent_slot_offsets, pixel_frames_for_latent_t
MAGIC = "H3_CONTINUUM_REFINE_WINDOW"
SCHEMA_VERSION = 1
MODE_TIME_WINDOW = "time_window"
class RefineWindowError(ValueError):
"""Raised before preparation when a visible time window is invalid."""
@dataclass(frozen=True)
class GroupTemporalWindow:
"""One physical group's immutable temporal mask ranges."""
group_index: int
logical_chunks: tuple[int, ...]
terminal_merged: bool
visible_frame_ranges: tuple[tuple[int, int], ...]
physical_frame_ranges: tuple[tuple[int, int], ...]
video_slot_ranges: tuple[tuple[int, int], ...]
audio_tick_ranges: tuple[tuple[int, int], ...]
@dataclass(frozen=True)
class RefineWindow:
"""One versioned visible-output window with no Tensor or runtime object."""
selected_group_indices: tuple[int, ...]
groups: tuple[GroupTemporalWindow, ...]
contract: Mapping[str, Any]
def group(self, group_index: int) -> GroupTemporalWindow | None:
for group in self.groups:
if group.group_index == int(group_index):
return group
return None
def _identity(payload: Mapping[str, Any]) -> str:
encoded = json.dumps(
dict(payload),
sort_keys=True,
separators=(",", ":"),
).encode("utf-8")
return hashlib.sha256(encoded).hexdigest()
def _merge_ranges(values: Sequence[tuple[int, int]]) -> tuple[tuple[int, int], ...]:
ordered = sorted(
(int(start), int(stop))
for start, stop in values
if int(stop) > int(start)
)
merged: list[list[int]] = []
for start, stop in ordered:
if merged and start <= merged[-1][1]:
merged[-1][1] = max(merged[-1][1], stop)
else:
merged.append([start, stop])
return tuple((start, stop) for start, stop in merged)
def _indices_to_ranges(indices: Sequence[int]) -> tuple[tuple[int, int], ...]:
ordered = sorted(set(int(value) for value in indices))
if not ordered:
return ()
ranges: list[tuple[int, int]] = []
start = previous = ordered[0]
for value in ordered[1:]:
if value == previous + 1:
previous = value
continue
ranges.append((start, previous + 1))
start = previous = value
ranges.append((start, previous + 1))
return tuple(ranges)
def _overlaps(
start: int,
stop: int,
ranges: Sequence[tuple[int, int]],
) -> bool:
return any(start < range_stop and stop > range_start for range_start, range_stop in ranges)
def _contract_groups(assembly_plan: Mapping[str, Any]) -> list[Mapping[str, Any]]:
if not isinstance(assembly_plan, Mapping):
raise RefineWindowError("assembly_plan must be a mapping")
contract = assembly_plan.get("second_pass_contract")
if not isinstance(contract, Mapping) or contract.get("version") != 1:
raise RefineWindowError("assembly_plan has no Second Pass contract version 1")
groups = contract.get("physical_groups")
if (
not isinstance(groups, Sequence)
or isinstance(groups, (str, bytes))
or not groups
or not all(isinstance(group, Mapping) for group in groups)
):
raise RefineWindowError("assembly_plan has no physical groups")
return list(groups)
def _logical_chunks(group: Mapping[str, Any], group_index: int) -> tuple[int, ...]:
values = group.get("logical_chunks")
if (
not isinstance(values, Sequence)
or isinstance(values, (str, bytes))
or not values
or any(type(value) is not int or value <= 0 for value in values)
):
raise RefineWindowError(
f"physical group {group_index + 1} has invalid logical chunk identity"
)
chunks = tuple(int(value) for value in values)
if tuple(sorted(chunks)) != chunks or len(set(chunks)) != len(chunks):
raise RefineWindowError(
f"physical group {group_index + 1} logical chunks are not ordered and unique"
)
return chunks
def _visible_units(
assembly_plan: Mapping[str, Any],
groups: Sequence[Mapping[str, Any]],
) -> tuple[list[dict[str, int]], int]:
decode_groups = assembly_plan.get("decode_groups")
if isinstance(decode_groups, Sequence) and not isinstance(
decode_groups, (str, bytes)
):
if len(decode_groups) != len(groups) or not all(
isinstance(group, Mapping) for group in decode_groups
):
raise RefineWindowError(
"assembly_plan decode groups differ from Second Pass physical groups"
)
source_units: Sequence[Mapping[str, Any]] = decode_groups
else:
source_units = groups
cursor = 0
units: list[dict[str, int]] = []
for group_index, (group, source) in enumerate(zip(groups, source_units, strict=True)):
physical_frames = int(group.get("physical_frames", 0))
trim_frames = int(group.get("trim_prefix_frames", -1))
source_latent_t = int(group.get("source_latent_t", 0))
audio_shape = group.get("source_audio_shape")
if physical_frames <= 0 or trim_frames < 0 or trim_frames >= physical_frames:
raise RefineWindowError(
f"physical group {group_index + 1} frame geometry is invalid"
)
if source_latent_t <= 0 or pixel_frames_for_latent_t(source_latent_t) != physical_frames:
raise RefineWindowError(
f"physical group {group_index + 1} Video latent T differs from its frame grid"
)
if (
not isinstance(audio_shape, Sequence)
or isinstance(audio_shape, (str, bytes))
or len(audio_shape) != 4
or int(audio_shape[-1]) != audio_latent_t(physical_frames)
):
raise RefineWindowError(
f"physical group {group_index + 1} Audio latent T differs from its frame grid"
)
net_frames = physical_frames - trim_frames
source_total = int(source.get("total_frames", physical_frames))
source_trim = int(source.get("trim_frames", trim_frames))
source_net = int(source.get("net_frames", source_total - source_trim))
source_start = int(source.get("frame_start", cursor))
source_stop = int(source.get("frame_stop", source_start + source_net))
if (
source_total != physical_frames
or source_trim != trim_frames
or source_net != net_frames
or source_start != cursor
or source_stop != cursor + net_frames
):
raise RefineWindowError(
f"physical group {group_index + 1} visible range is inconsistent"
)
units.append(
{
"group_index": group_index,
"visible_start": source_start,
"visible_stop": source_stop,
"physical_frames": physical_frames,
"trim_frames": trim_frames,
"video_t": source_latent_t,
"audio_t": int(audio_shape[-1]),
}
)
cursor = source_stop
return units, cursor
def _output_to_natural_ranges(
output_start: int,
output_stop: int,
*,
natural_frames: int,
target_frames: int,
preserve_final_frame: bool,
) -> tuple[tuple[int, int], ...]:
mappings: list[tuple[int, int, int, bool]] = []
if target_frames >= natural_frames:
mappings.append((0, natural_frames, 0, False))
if target_frames > natural_frames:
mappings.append((natural_frames, target_frames, natural_frames - 1, True))
elif preserve_final_frame and target_frames >= 2:
mappings.extend(
(
(0, target_frames - 1, 0, False),
(target_frames - 1, target_frames, natural_frames - 1, True),
)
)
else:
mappings.append((0, target_frames, 0, False))
natural_ranges: list[tuple[int, int]] = []
for destination_start, destination_stop, source_start, repeated in mappings:
overlap_start = max(output_start, destination_start)
overlap_stop = min(output_stop, destination_stop)
if overlap_stop <= overlap_start:
continue
if repeated:
natural_ranges.append((source_start, source_start + 1))
else:
mapped_start = source_start + overlap_start - destination_start
mapped_stop = source_start + overlap_stop - destination_start
natural_ranges.append((mapped_start, mapped_stop))
return _merge_ranges(natural_ranges)
def _group_window(
group: Mapping[str, Any],
unit: Mapping[str, int],
natural_ranges: Sequence[tuple[int, int]],
) -> GroupTemporalWindow | None:
visible_start = int(unit["visible_start"])
visible_stop = int(unit["visible_stop"])
visible_ranges = _merge_ranges(
(
max(start, visible_start),
min(stop, visible_stop),
)
for start, stop in natural_ranges
if start < visible_stop and stop > visible_start
)
if not visible_ranges:
return None
trim_frames = int(unit["trim_frames"])
physical_ranges = _merge_ranges(
(
trim_frames + start - visible_start,
trim_frames + stop - visible_start,
)
for start, stop in visible_ranges
)
video_t = int(unit["video_t"])
offsets = latent_slot_offsets(video_t)
selected_slots = []
for slot, slot_start in enumerate(offsets):
slot_stop = offsets[slot + 1] if slot + 1 < video_t else int(unit["physical_frames"])
if _overlaps(slot_start, slot_stop, physical_ranges):
selected_slots.append(slot)
video_ranges = _indices_to_ranges(selected_slots)
if video_ranges and offsets[video_ranges[0][0]] < trim_frames:
raise RefineWindowError(
f"physical group {int(unit['group_index']) + 1} Video grid would expose "
"the protected continuation prefix"
)
audio_ranges = _merge_ranges(
(
max(0, min(int(unit["audio_t"]), audio_latent_t(start))),
max(0, min(int(unit["audio_t"]), audio_latent_t(stop))),
)
for start, stop in physical_ranges
)
protected_audio_stop = audio_latent_t(trim_frames)
if audio_ranges and audio_ranges[0][0] < protected_audio_stop:
raise RefineWindowError(
f"physical group {int(unit['group_index']) + 1} Audio grid would expose "
"the protected continuation prefix"
)
if not video_ranges or not audio_ranges:
raise RefineWindowError(
f"physical group {int(unit['group_index']) + 1} window resolves to an empty AV grid"
)
return GroupTemporalWindow(
group_index=int(unit["group_index"]),
logical_chunks=_logical_chunks(group, int(unit["group_index"])),
terminal_merged=bool(group.get("terminal_merged", False)),
visible_frame_ranges=visible_ranges,
physical_frame_ranges=physical_ranges,
video_slot_ranges=video_ranges,
audio_tick_ranges=audio_ranges,
)
def resolve_refine_window(
start_sec: float,
end_sec: float,
assembly_plan: Mapping[str, Any],
) -> RefineWindow:
"""Resolve final visible output time to protected physical AV ranges.
The requested interval is half-open. Fractions select every output frame
interval they overlap. Continuation trim prefixes are never selected.
"""
try:
requested_start = float(start_sec)
requested_end = float(end_sec)
except (TypeError, ValueError) as exc:
raise RefineWindowError("refine window seconds must be numeric") from exc
if not math.isfinite(requested_start) or not math.isfinite(requested_end):
raise RefineWindowError("refine window seconds must be finite")
if requested_start >= requested_end:
raise RefineWindowError("refine window start must be less than end")
groups = _contract_groups(assembly_plan)
units, natural_frames = _visible_units(assembly_plan, groups)
fps = int(assembly_plan.get("fps", 0))
target_frames = int(assembly_plan.get("target_frames", 0))
if fps <= 0 or target_frames <= 0 or natural_frames <= 0:
raise RefineWindowError("assembly_plan visible timeline is invalid")
clamped_start = min(max(requested_start, 0.0), target_frames / fps)
clamped_end = min(max(requested_end, 0.0), target_frames / fps)
output_start = max(0, min(target_frames, math.floor(clamped_start * fps + 1e-9)))
output_stop = max(0, min(target_frames, math.ceil(clamped_end * fps - 1e-9)))
if output_stop <= output_start:
raise RefineWindowError("refine window does not overlap the visible output")
natural_ranges = _output_to_natural_ranges(
output_start,
output_stop,
natural_frames=natural_frames,
target_frames=target_frames,
preserve_final_frame=bool(assembly_plan.get("preserve_final_frame", False)),
)
if not natural_ranges:
raise RefineWindowError("refine window has no natural timeline source")
resolved_groups = tuple(
group_window
for group, unit in zip(groups, units, strict=True)
if (
group_window := _group_window(
group,
unit,
natural_ranges,
)
)
is not None
)
if not resolved_groups:
raise RefineWindowError("refine window selects no physical group")
selected = tuple(group.group_index for group in resolved_groups)
group_contracts = [
{
"group_index": group.group_index,
"physical_group": group.group_index + 1,
"logical_chunks": list(group.logical_chunks),
"terminal_merged": group.terminal_merged,
"visible_frame_ranges": [list(value) for value in group.visible_frame_ranges],
"physical_frame_ranges": [list(value) for value in group.physical_frame_ranges],
"video_slot_ranges": [list(value) for value in group.video_slot_ranges],
"audio_tick_ranges": [list(value) for value in group.audio_tick_ranges],
}
for group in resolved_groups
]
contract: dict[str, Any] = {
"magic": MAGIC,
"schema_version": SCHEMA_VERSION,
"mode": MODE_TIME_WINDOW,
"timeline": "final_visible_output",
"interval": "half_open",
"requested_start_sec": requested_start,
"requested_end_sec": requested_end,
"effective_start_sec": output_start / fps,
"effective_end_sec": output_stop / fps,
"output_frame_range": [output_start, output_stop],
"target_frames": target_frames,
"natural_frames": natural_frames,
"natural_frame_ranges": [list(value) for value in natural_ranges],
"selected_physical_groups": [index + 1 for index in selected],
"groups": group_contracts,
"continuation_prefix_policy": "always_protected",
"outside_window_policy": "mask_zero_then_bit_exact_restore",
"physical_group_atomicity": "preserved",
"temporal_quantization": "intersecting_video_slots_and_audio_ticks",
}
contract["window_hash"] = _identity(contract)
return RefineWindow(
selected_group_indices=selected,
groups=resolved_groups,
contract=MappingProxyType(contract),
)
def serializable_window_contract(window: RefineWindow) -> dict[str, Any]:
if not isinstance(window, RefineWindow):
raise RefineWindowError("refine_window must be a RefineWindow")
return json.loads(json.dumps(dict(window.contract)))