Files
DumasNodes/v3/resolution.py
T
chris.dumas bf8f76505f Squashed 'vendor/dumas_h3_continuum/' content from commit d07ed31
git-subtree-dir: vendor/dumas_h3_continuum
git-subtree-split: d07ed31b442d283d6a1740f875a843b9feda4c91
2026-10-20 13:43:38 +00:00

249 lines
8.0 KiB
Python

"""Shared H3 resolution presets for Easy and V3.8 sampler facades."""
from __future__ import annotations
from dataclasses import dataclass
import math
from typing import Any
H3_ASPECT_AUTO = "Auto from First Image"
H3_ASPECT_LANDSCAPE = "Landscape 16:9"
H3_ASPECT_PORTRAIT = "Portrait 9:16"
H3_ASPECT_SQUARE = "Square 1:1"
H3_ASPECT_OPTIONS = (
H3_ASPECT_AUTO,
H3_ASPECT_LANDSCAPE,
H3_ASPECT_PORTRAIT,
H3_ASPECT_SQUARE,
)
H3_SIZE_SOURCE_FIRST_IMAGE = "First Image"
H3_SIZE_SOURCE_MANUAL = "Manual"
H3_SIZE_SOURCE_LEGACY = "Legacy Aspect"
H3_SIZE_SOURCE_OPTIONS = (
H3_SIZE_SOURCE_FIRST_IMAGE,
H3_SIZE_SOURCE_MANUAL,
H3_SIZE_SOURCE_LEGACY,
)
H3_PRESET_DRAFT = "Draft — 0.30 MP"
H3_PRESET_BALANCED = "Balanced — 0.60 MP"
H3_PRESET_NATIVE = "Native 768"
H3_PRESET_CUSTOM = "Custom"
H3_PRESET_OPTIONS = (
H3_PRESET_DRAFT,
H3_PRESET_BALANCED,
H3_PRESET_NATIVE,
H3_PRESET_CUSTOM,
)
H3_DRAFT_MP = 0.30
H3_BALANCED_MP = 0.60
H3_CUSTOM_MP_DEFAULT = 0.30
H3_CUSTOM_MP_MIN = 0.10
H3_CUSTOM_MP_MAX = 16.0
H3_CUSTOM_MP_STRONG_WARNING = 2.50
H3_MP_PIXELS = 1_000_000.0
H3_CANVAS_MULTIPLE = 32
H3_NATIVE_SHORT_EDGE = 768
H3_NATIVE_LONG_EDGE_CAP = 1344
H3_MANUAL_WIDTH_DEFAULT = 736
H3_MANUAL_HEIGHT_DEFAULT = 416
H3_CANVAS_MIN = 32
H3_CANVAS_MAX = 16384
@dataclass(frozen=True)
class H3ResolutionPlan:
width: int
height: int
aspect_ratio: float
aspect_source: str
preset: str
target_mp: float | None
warnings: tuple[str, ...]
@property
def actual_mp(self) -> float:
return float(self.width * self.height) / H3_MP_PIXELS
def _round_canvas(value: float) -> int:
units = math.floor(float(value) / H3_CANVAS_MULTIPLE + 0.5)
return max(H3_CANVAS_MULTIPLE, int(units) * H3_CANVAS_MULTIPLE)
def _first_image_aspect(first_frame: Any) -> float | None:
shape = getattr(first_frame, "shape", None)
if shape is None or len(shape) != 4:
return None
height = int(shape[1])
width = int(shape[2])
if width < 1 or height < 1:
return None
return float(width) / float(height)
def _manual_dimension(value: Any, name: str) -> int:
if isinstance(value, bool):
raise TypeError(f"Manual {name} must be an integer")
resolved = int(value)
if float(value) != float(resolved):
raise ValueError(f"Manual {name} must be an integer")
if not H3_CANVAS_MIN <= resolved <= H3_CANVAS_MAX:
raise ValueError(
f"Manual {name} must be between {H3_CANVAS_MIN} and {H3_CANVAS_MAX}"
)
if resolved % H3_CANVAS_MULTIPLE:
raise ValueError(
f"Manual {name} must be aligned to {H3_CANVAS_MULTIPLE} pixels"
)
return resolved
def _manual_resolution(width: Any, height: Any, *, warning: str | None = None) -> H3ResolutionPlan:
resolved_width = _manual_dimension(width, "Width")
resolved_height = _manual_dimension(height, "Height")
return H3ResolutionPlan(
width=resolved_width,
height=resolved_height,
aspect_ratio=float(resolved_width) / float(resolved_height),
aspect_source="Manual Width / Height",
preset="Manual",
target_mp=None,
warnings=(warning,) if warning else (),
)
def resolve_h3_aspect(aspect: str, first_frame: Any = None) -> tuple[float, str]:
"""Resolve the existing Easy aspect policy without creating a second fallback."""
if aspect == H3_ASPECT_AUTO:
image_aspect = _first_image_aspect(first_frame)
if image_aspect is not None:
return image_aspect, "First Image"
return 16.0 / 9.0, "Landscape 16:9 fallback"
if aspect == H3_ASPECT_LANDSCAPE:
return 16.0 / 9.0, H3_ASPECT_LANDSCAPE
if aspect == H3_ASPECT_PORTRAIT:
return 9.0 / 16.0, H3_ASPECT_PORTRAIT
if aspect == H3_ASPECT_SQUARE:
return 1.0, H3_ASPECT_SQUARE
return 16.0 / 9.0, "Landscape 16:9 fallback"
def _area_resolution(aspect_ratio: float, megapixels: float) -> tuple[int, int]:
target_pixels = float(megapixels) * H3_MP_PIXELS
raw_width = math.sqrt(target_pixels * float(aspect_ratio))
raw_height = math.sqrt(target_pixels / float(aspect_ratio))
return _round_canvas(raw_width), _round_canvas(raw_height)
def _native_resolution(aspect_ratio: float) -> tuple[int, int]:
landscape = float(aspect_ratio) >= 1.0
major_ratio = float(aspect_ratio) if landscape else 1.0 / float(aspect_ratio)
short_edge = float(H3_NATIVE_SHORT_EDGE)
long_edge = short_edge * major_ratio
if long_edge > H3_NATIVE_LONG_EDGE_CAP:
long_edge = float(H3_NATIVE_LONG_EDGE_CAP)
short_edge = long_edge / major_ratio
long_px = min(H3_NATIVE_LONG_EDGE_CAP, _round_canvas(long_edge))
short_px = min(H3_NATIVE_SHORT_EDGE, _round_canvas(short_edge))
if landscape:
return long_px, short_px
return short_px, long_px
def resolve_h3_resolution(
*,
aspect: str,
preset: str,
custom_mp: float = H3_CUSTOM_MP_DEFAULT,
first_frame: Any = None,
) -> H3ResolutionPlan:
"""Resolve decimal-MP or Native 768 dimensions on the H3 32-pixel grid."""
aspect_ratio, aspect_source = resolve_h3_aspect(aspect, first_frame)
warnings: list[str] = []
target_mp: float | None
if preset == H3_PRESET_DRAFT:
target_mp = H3_DRAFT_MP
width, height = _area_resolution(aspect_ratio, target_mp)
elif preset == H3_PRESET_BALANCED:
target_mp = H3_BALANCED_MP
width, height = _area_resolution(aspect_ratio, target_mp)
elif preset == H3_PRESET_NATIVE:
target_mp = None
width, height = _native_resolution(aspect_ratio)
else:
preset = H3_PRESET_CUSTOM
if isinstance(custom_mp, bool):
raise TypeError("Custom MP must be numeric")
target_mp = float(custom_mp)
if not H3_CUSTOM_MP_MIN <= target_mp <= H3_CUSTOM_MP_MAX:
raise ValueError(
f"Custom MP must be between {H3_CUSTOM_MP_MIN:.2f} and "
f"{H3_CUSTOM_MP_MAX:.2f}"
)
width, height = _area_resolution(aspect_ratio, target_mp)
native_width, native_height = _native_resolution(aspect_ratio)
native_pixels = native_width * native_height
if width * height > native_pixels:
warnings.append(
"Above Native 768: processing time and memory usage may increase."
)
if target_mp > H3_CUSTOM_MP_STRONG_WARNING:
warnings.append(
"High Custom MP: substantial VRAM use and generation time are possible."
)
return H3ResolutionPlan(
width=width,
height=height,
aspect_ratio=aspect_ratio,
aspect_source=aspect_source,
preset=preset,
target_mp=target_mp,
warnings=tuple(warnings),
)
def resolve_h3_size_source(
*,
size_source: str,
width: Any = H3_MANUAL_WIDTH_DEFAULT,
height: Any = H3_MANUAL_HEIGHT_DEFAULT,
aspect: str = H3_ASPECT_AUTO,
preset: str = H3_PRESET_DRAFT,
custom_mp: float = H3_CUSTOM_MP_DEFAULT,
first_frame: Any = None,
) -> H3ResolutionPlan:
"""Resolve the V3.8 two-choice Size Source while retaining legacy API input."""
if size_source == H3_SIZE_SOURCE_MANUAL:
return _manual_resolution(width, height)
if size_source == H3_SIZE_SOURCE_FIRST_IMAGE:
if _first_image_aspect(first_frame) is None:
return _manual_resolution(
width,
height,
warning=(
"First Image is unavailable for Size Source = First Image; "
"the displayed Manual Width / Height were used."
),
)
return resolve_h3_resolution(
aspect=H3_ASPECT_AUTO,
preset=preset,
custom_mp=custom_mp,
first_frame=first_frame,
)
# Existing API prompts and saved workflows omit size_source. Preserve their
# exact V3.8 aspect resolver until the frontend migrates the visible widgets.
return resolve_h3_resolution(
aspect=aspect,
preset=preset,
custom_mp=custom_mp,
first_frame=first_frame,
)