Skip to content

various

Classes:

  • ClampScaler

    Clamp a reference Scaler.

  • DPID

    Rapid, Detail-Preserving Image Downscaler for VapourSynth

  • SSIM

    SSIM downsampler is an image downscaling technique that aims to optimize

ClampScaler

ClampScaler(
    base_scaler: ScalerLike,
    reference: ScalerLike | VideoNode,
    strength: int = 80,
    overshoot: float | None = None,
    undershoot: float | None = None,
    limit: Mode | bool = True,
    operator: Literal[MAX, MIN] | None = MIN,
    masked: bool = True,
    *,
    kernel: KernelLike = Catrom,
    scaler: ScalerLike | None = None,
    shifter: KernelLike | None = None,
    **kwargs: Any
)

Bases: GenericScaler

Clamp a reference Scaler.

Parameters:

  • base_scaler

    (ScalerLike) –

    Scaler to clamp.

  • reference

    (ScalerLike | VideoNode) –

    Reference Scaler used to clamp base_scaler

  • strength

    (int, default: 80 ) –

    Strength of clamping. Default to 80. Must be between 0 and 100 (exclusive)

  • overshoot

    (float | None, default: None ) –

    Overshoot threshold within the 0.0 - 1.0 range.

  • undershoot

    (float | None, default: None ) –

    Undershoot threshold within the 0.0 - 1.0 range.

  • limit

    (Mode | bool, default: True ) –

    Whether to use under/overshoot limit (True) or a reference repaired clip for limiting.

  • operator

    (Literal[MAX, MIN] | None, default: MIN ) –

    Whether to take the brightest or darkest pixels in the merge. Defaults to ExprOp.MIN.

  • masked

    (bool, default: True ) –

    Whether to mask with a ringing mask or not. Defaults to True

  • kernel

    (KernelLike, default: Catrom ) –

    Base kernel to be used for certain scaling/shifting/resampling operations. Defaults to Catrom.

  • scaler

    (ScalerLike | None, default: None ) –

    Scaler used for scaling operations. Defaults to kernel.

  • shifter

    (KernelLike | None, default: None ) –

    Kernel used for shifting operations. Defaults to kernel.

Classes:

Methods:

  • ensure_obj

    Ensure that the input is a scaler instance, resolving it if necessary.

  • from_param

    Resolve and return a scaler type from a given input (string, type, or instance).

  • get_scale_args

    Generate the keyword arguments used for scaling.

  • kernel_radius
  • multi

    Deprecated alias for supersample.

  • pretty_string

    Cached property returning a user-friendly string representation.

  • scale
  • supersample

    Supersample a clip by a given scaling factor.

Attributes:

Source code
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
def __init__(
    self,
    base_scaler: ScalerLike,
    reference: ScalerLike | vs.VideoNode,
    strength: int = 80,
    overshoot: float | None = None,
    undershoot: float | None = None,
    limit: Repair.Mode | bool = True,
    operator: Literal[ExprOp.MAX, ExprOp.MIN] | None = ExprOp.MIN,
    masked: bool = True,
    *,
    kernel: KernelLike = Catrom,
    scaler: ScalerLike | None = None,
    shifter: KernelLike | None = None,
    **kwargs: Any
) -> None:
    """
    :param base_scaler:     Scaler to clamp.
    :param reference:       Reference Scaler used to clamp base_scaler
    :param strength:        Strength of clamping. Default to 80. Must be between 0 and 100 (exclusive)
    :param overshoot:       Overshoot threshold within the 0.0 - 1.0 range.
    :param undershoot:      Undershoot threshold within the 0.0 - 1.0 range.
    :param limit:           Whether to use under/overshoot limit (True) or a reference repaired clip for limiting.
    :param operator:        Whether to take the brightest or darkest pixels in the merge. Defaults to ExprOp.MIN.
    :param masked:          Whether to mask with a ringing mask or not. Defaults to True
    :param kernel:          Base kernel to be used for certain scaling/shifting/resampling operations.
                            Defaults to Catrom.
    :param scaler:          Scaler used for scaling operations. Defaults to kernel.
    :param shifter:         Kernel used for shifting operations. Defaults to kernel.
    """
    self.base_scaler = Scaler.ensure_obj(base_scaler, self.__class__)

    self.reference: Scaler | vs.VideoNode

    if not isinstance(reference, vs.VideoNode):
        self.reference = Scaler.ensure_obj(reference, self.__class__)
    else:
        self.reference = reference

    if not 0 < strength < 100:
        raise CustomOverflowError("`strength` must be between 0 and 100 (exclusive)!", self.__class__)

    self.strength = strength

    if overshoot is None:
        self.overshoot = self.strength / 100
    else:
        self.overshoot = overshoot

    if undershoot is None:
        self.undershoot = self.overshoot
    else:
        self.undershoot = undershoot

    self.limit = limit
    self.operator = operator
    self.masked = masked

    super().__init__(None, kernel=kernel, scaler=scaler, shifter=shifter, **kwargs)

base_scaler instance-attribute

base_scaler = ensure_obj(base_scaler, __class__)

func instance-attribute

func = _func_no_op if func is None else func

kernel instance-attribute

kernel = ensure_obj(kernel, __class__)

kwargs instance-attribute

kwargs: dict[str, Any] = kwargs

Arguments passed to the implemented funcs or internal scale function.

limit instance-attribute

limit = limit

masked instance-attribute

masked = masked

operator instance-attribute

operator = operator

overshoot instance-attribute

overshoot = strength / 100

reference instance-attribute

reference: Scaler | VideoNode

scale_function instance-attribute

scale_function: Callable[..., VideoNode]

Scale function called internally when performing scaling operations.

scaler instance-attribute

scaler = ensure_obj(scaler or kernel, __class__)

shifter instance-attribute

shifter = ensure_obj(shifter or kernel, __class__)

strength instance-attribute

strength = strength

undershoot instance-attribute

undershoot = overshoot

cached_property

cached_property(func: Callable[Concatenate[_BaseScalerT, P], T_co])

Bases: cached_property[T_co]

Read only version of functools.cached_property.

Source code
265
def __init__(self, func: Callable[Concatenate[_BaseScalerT, P], T_co]) -> None: ...

ensure_obj classmethod

ensure_obj(
    scaler: str | type[Self] | Self | None = None,
    /,
    func_except: FuncExceptT | None = None,
) -> Self

Ensure that the input is a scaler instance, resolving it if necessary.

Parameters:

  • scaler

    (str | type[Self] | Self | None, default: None ) –

    Scaler identifier (string, class, or instance).

  • func_except

    (FuncExceptT | None, default: None ) –

    Function returned for custom error handling.

Returns:

  • Self

    Scaler instance.

Source code
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
@classmethod
def ensure_obj(
    cls,
    scaler: str | type[Self] | Self | None = None,
    /,
    func_except: FuncExceptT | None = None,
) -> Self:
    """
    Ensure that the input is a scaler instance, resolving it if necessary.

    :param scaler:          Scaler identifier (string, class, or instance).
    :param func_except:     Function returned for custom error handling.
    :return:                Scaler instance.
    """
    return _base_ensure_obj(cls, scaler, func_except)

from_param classmethod

from_param(
    scaler: str | type[Self] | Self | None = None,
    /,
    func_except: FuncExceptT | None = None,
) -> type[Self]

Resolve and return a scaler type from a given input (string, type, or instance).

Parameters:

  • scaler

    (str | type[Self] | Self | None, default: None ) –

    Scaler identifier (string, class, or instance).

  • func_except

    (FuncExceptT | None, default: None ) –

    Function returned for custom error handling.

Returns:

  • type[Self]

    Resolved scaler type.

Source code
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
@classmethod
def from_param(
    cls,
    scaler: str | type[Self] | Self | None = None,
    /,
    func_except: FuncExceptT | None = None,
) -> type[Self]:
    """
    Resolve and return a scaler type from a given input (string, type, or instance).

    :param scaler:          Scaler identifier (string, class, or instance).
    :param func_except:     Function returned for custom error handling.
    :return:                Resolved scaler type.
    """
    return _base_from_param(cls, scaler, cls._err_class, func_except)

get_scale_args

get_scale_args(
    clip: VideoNode,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    width: int | None = None,
    height: int | None = None,
    **kwargs: Any
) -> dict[str, Any]

Generate the keyword arguments used for scaling.

Parameters:

  • clip

    (VideoNode) –

    The source clip.

  • shift

    (tuple[TopShift, LeftShift], default: (0, 0) ) –

    Subpixel shift (top, left).

  • width

    (int | None, default: None ) –

    Target width.

  • height

    (int | None, default: None ) –

    Target height.

  • kwargs

    (Any, default: {} ) –

    Extra parameters to merge.

Returns:

  • dict[str, Any]

    Final dictionary of keyword arguments for the scale function.

Source code
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
def get_scale_args(
    self,
    clip: vs.VideoNode,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    width: int | None = None,
    height: int | None = None,
    **kwargs: Any,
) -> dict[str, Any]:
    """
    Generate the keyword arguments used for scaling.

    :param clip:    The source clip.
    :param shift:   Subpixel shift (top, left).
    :param width:   Target width.
    :param height:  Target height.
    :param kwargs:  Extra parameters to merge.
    :return:        Final dictionary of keyword arguments for the scale function.
    """
    return dict(width=width, height=height, src_top=shift[0], src_left=shift[1]) | self.kwargs | kwargs

kernel_radius

kernel_radius() -> int
Source code
148
149
150
151
152
@Scaler.cached_property
def kernel_radius(self) -> int:
    if not isinstance(self.reference, vs.VideoNode):
        return max(self.reference.kernel_radius, self.base_scaler.kernel_radius)
    return self.base_scaler.kernel_radius

multi

multi(
    clip: VideoNodeT,
    multi: float = 2.0,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    **kwargs: Any
) -> VideoNodeT

Deprecated alias for supersample.

Parameters:

  • clip

    (VideoNodeT) –

    The source clip.

  • multi

    (float, default: 2.0 ) –

    Supersampling factor.

  • shift

    (tuple[TopShift, LeftShift], default: (0, 0) ) –

    Subpixel shift (top, left) applied during scaling.

  • kwargs

    (Any, default: {} ) –

    Additional arguments forwarded to the scale function.

Returns:

Source code
451
452
453
454
455
456
457
458
459
460
461
462
463
464
@deprecated('The "multi" method is deprecated. Use "supersample" instead.', category=DeprecationWarning)
def multi(
    self, clip: VideoNodeT, multi: float = 2.0, shift: tuple[TopShift, LeftShift] = (0, 0), **kwargs: Any
) -> VideoNodeT:
    """
    Deprecated alias for `supersample`.

    :param clip:    The source clip.
    :param multi:   Supersampling factor.
    :param shift:   Subpixel shift (top, left) applied during scaling.
    :param kwargs:  Additional arguments forwarded to the scale function.
    :return:        The supersampled clip.
    """
    return self.supersample(clip, multi, shift, **kwargs)

pretty_string

pretty_string() -> str

Cached property returning a user-friendly string representation.

Returns:

  • str

    Pretty-printed string with arguments.

Source code
368
369
370
371
372
373
374
375
@cached_property
def pretty_string(self) -> str:
    """
    Cached property returning a user-friendly string representation.

    :return: Pretty-printed string with arguments.
    """
    return self._pretty_string()

scale

scale(
    clip: VideoNode,
    width: int | None = None,
    height: int | None = None,
    shift: tuple[float, float] = (0, 0),
    **kwargs: Any
) -> ConstantFormatVideoNode
Source code
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
def scale(
    self,
    clip: vs.VideoNode,
    width: int | None = None,
    height: int | None = None,
    shift: tuple[float, float] = (0, 0),
    **kwargs: Any
) -> ConstantFormatVideoNode:

    width, height = self._wh_norm(clip, width, height)

    base = self.base_scaler.scale(clip, width, height, shift, **kwargs)

    if isinstance(self.reference, vs.VideoNode):
        smooth = self.reference

        if shift != (0, 0):
            smooth = self.kernel.shift(smooth, shift)
    else:
        smooth = self.reference.scale(clip, width, height, shift)

    check_ref_clip(base, smooth)

    if TYPE_CHECKING:
        from vstools import check_variable_format
        assert check_variable_format(base, self.__class__)
        assert check_variable_format(smooth, self.__class__)

    merge_weight = self.strength / 100

    if self.limit is True:
        expression = 'x {merge_weight} * y {ref_weight} * + a {undershoot} - z {overshoot} + clip'

        merged = norm_expr(
            [base, smooth, smooth.std.Maximum(), smooth.std.Minimum()],
            expression,
            merge_weight=merge_weight,
            ref_weight=1.0 - merge_weight,
            undershoot=scale_delta(self.undershoot, 32, clip),
            overshoot=scale_delta(self.overshoot, 32, clip),
            func=self.__class__
        )
    else:
        merged = smooth.std.Merge(base, merge_weight)

        if isinstance(self.limit, Repair.Mode):
            merged = self.limit(merged, smooth)

    if self.operator is not None:
        merge2 = combine([smooth, base], self.operator)

        if self.masked:
            merged = merged.std.MaskedMerge(merge2, ringing_mask(smooth))
        else:
            merged = merge2
    elif self.masked:
        merged = merged.std.MaskedMerge(smooth, ringing_mask(smooth))

    return merged

supersample

supersample(
    clip: VideoNodeT,
    rfactor: float = 2.0,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    **kwargs: Any
) -> VideoNodeT

Supersample a clip by a given scaling factor.

Parameters:

  • clip

    (VideoNodeT) –

    The source clip.

  • rfactor

    (float, default: 2.0 ) –

    Scaling factor for supersampling.

  • shift

    (tuple[TopShift, LeftShift], default: (0, 0) ) –

    Subpixel shift (top, left) applied during scaling.

  • kwargs

    (Any, default: {} ) –

    Additional arguments forwarded to the scale function.

Returns:

Raises:

  • CustomValueError

    If resulting resolution is non-positive.

Source code
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
def supersample(
    self, clip: VideoNodeT, rfactor: float = 2.0, shift: tuple[TopShift, LeftShift] = (0, 0), **kwargs: Any
) -> VideoNodeT:
    """
    Supersample a clip by a given scaling factor.

    :param clip:                The source clip.
    :param rfactor:             Scaling factor for supersampling.
    :param shift:               Subpixel shift (top, left) applied during scaling.
    :param kwargs:              Additional arguments forwarded to the scale function.
    :raises CustomValueError:   If resulting resolution is non-positive.
    :return:                    The supersampled clip.
    """
    assert check_variable_resolution(clip, self.supersample)

    dst_width, dst_height = ceil(clip.width * rfactor), ceil(clip.height * rfactor)

    if max(dst_width, dst_height) <= 0.0:
        raise CustomValueError(
            'Multiplying the resolution by "rfactor" must result in a positive resolution!',
            self.supersample,
            rfactor,
        )

    return self.scale(clip, dst_width, dst_height, shift, **kwargs)  # type: ignore[return-value]

DPID

DPID(
    sigma: float = 0.1,
    ref: VideoNode | ScalerLike = Catrom,
    planes: PlanesT = None,
    **kwargs: Any
)

Bases: BaseGenericScaler

Rapid, Detail-Preserving Image Downscaler for VapourSynth

Parameters:

  • sigma

    (float, default: 0.1 ) –

    The power factor of range kernel. It can be used to tune the amplification of the weights of pixels that represent detail—from a box filter over an emphasis of distinct pixels towards a selection of only the most distinct pixels.

  • ref

    (VideoNode | ScalerLike, default: Catrom ) –

    VideoNode or Scaler to obtain the downscaled reference for DPID.

  • planes

    (PlanesT, default: None ) –

    Sets which planes will be processed. Any unprocessed planes will be simply copied from ref.

Classes:

Methods:

  • ensure_obj

    Ensure that the input is a scaler instance, resolving it if necessary.

  • from_param

    Resolve and return a scaler type from a given input (string, type, or instance).

  • get_scale_args

    Generate the keyword arguments used for scaling.

  • kernel_radius
  • multi

    Deprecated alias for supersample.

  • pretty_string

    Cached property returning a user-friendly string representation.

  • scale
  • supersample

    Supersample a clip by a given scaling factor.

Attributes:

Source code
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
def __init__(
    self,
    sigma: float = 0.1,
    ref: vs.VideoNode | ScalerLike = Catrom,
    planes: PlanesT = None,
    **kwargs: Any
) -> None:
    """
    :param sigma:       The power factor of range kernel. It can be used to tune the amplification
                        of the weights of pixels that represent detail—from a box filter over an emphasis
                        of distinct pixels towards a selection of only the most distinct pixels.
    :param ref:         VideoNode or Scaler to obtain the downscaled reference for DPID.
    :param planes:      Sets which planes will be processed. Any unprocessed planes will be simply copied from ref.
    """
    super().__init__(**kwargs)

    self.sigma = sigma
    self.ref = ref
    self.planes = planes

    if isinstance(ref, vs.VideoNode):
        self._ref_scaler = self.scaler
    else:
        self._ref_scaler = Scaler.ensure_obj(ref, self.__class__)

kernel instance-attribute

kernel = ensure_obj(kernel, __class__)

kwargs instance-attribute

kwargs: dict[str, Any] = kwargs

Arguments passed to the implemented funcs or internal scale function.

planes instance-attribute

planes = planes

ref instance-attribute

ref = ref

scale_function instance-attribute

scale_function: Callable[..., VideoNode]

Scale function called internally when performing scaling operations.

scaler instance-attribute

scaler = ensure_obj(scaler or kernel, __class__)

shifter instance-attribute

shifter = ensure_obj(shifter or kernel, __class__)

sigma instance-attribute

sigma = sigma

cached_property

cached_property(func: Callable[Concatenate[_BaseScalerT, P], T_co])

Bases: cached_property[T_co]

Read only version of functools.cached_property.

Source code
265
def __init__(self, func: Callable[Concatenate[_BaseScalerT, P], T_co]) -> None: ...

ensure_obj classmethod

ensure_obj(
    scaler: str | type[Self] | Self | None = None,
    /,
    func_except: FuncExceptT | None = None,
) -> Self

Ensure that the input is a scaler instance, resolving it if necessary.

Parameters:

  • scaler

    (str | type[Self] | Self | None, default: None ) –

    Scaler identifier (string, class, or instance).

  • func_except

    (FuncExceptT | None, default: None ) –

    Function returned for custom error handling.

Returns:

  • Self

    Scaler instance.

Source code
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
@classmethod
def ensure_obj(
    cls,
    scaler: str | type[Self] | Self | None = None,
    /,
    func_except: FuncExceptT | None = None,
) -> Self:
    """
    Ensure that the input is a scaler instance, resolving it if necessary.

    :param scaler:          Scaler identifier (string, class, or instance).
    :param func_except:     Function returned for custom error handling.
    :return:                Scaler instance.
    """
    return _base_ensure_obj(cls, scaler, func_except)

from_param classmethod

from_param(
    scaler: str | type[Self] | Self | None = None,
    /,
    func_except: FuncExceptT | None = None,
) -> type[Self]

Resolve and return a scaler type from a given input (string, type, or instance).

Parameters:

  • scaler

    (str | type[Self] | Self | None, default: None ) –

    Scaler identifier (string, class, or instance).

  • func_except

    (FuncExceptT | None, default: None ) –

    Function returned for custom error handling.

Returns:

  • type[Self]

    Resolved scaler type.

Source code
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
@classmethod
def from_param(
    cls,
    scaler: str | type[Self] | Self | None = None,
    /,
    func_except: FuncExceptT | None = None,
) -> type[Self]:
    """
    Resolve and return a scaler type from a given input (string, type, or instance).

    :param scaler:          Scaler identifier (string, class, or instance).
    :param func_except:     Function returned for custom error handling.
    :return:                Resolved scaler type.
    """
    return _base_from_param(cls, scaler, cls._err_class, func_except)

get_scale_args

get_scale_args(
    clip: VideoNode,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    width: int | None = None,
    height: int | None = None,
    **kwargs: Any
) -> dict[str, Any]

Generate the keyword arguments used for scaling.

Parameters:

  • clip

    (VideoNode) –

    The source clip.

  • shift

    (tuple[TopShift, LeftShift], default: (0, 0) ) –

    Subpixel shift (top, left).

  • width

    (int | None, default: None ) –

    Target width.

  • height

    (int | None, default: None ) –

    Target height.

  • kwargs

    (Any, default: {} ) –

    Extra parameters to merge.

Returns:

  • dict[str, Any]

    Final dictionary of keyword arguments for the scale function.

Source code
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
def get_scale_args(
    self,
    clip: vs.VideoNode,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    width: int | None = None,
    height: int | None = None,
    **kwargs: Any,
) -> dict[str, Any]:
    """
    Generate the keyword arguments used for scaling.

    :param clip:    The source clip.
    :param shift:   Subpixel shift (top, left).
    :param width:   Target width.
    :param height:  Target height.
    :param kwargs:  Extra parameters to merge.
    :return:        Final dictionary of keyword arguments for the scale function.
    """
    return dict(width=width, height=height, src_top=shift[0], src_left=shift[1]) | self.kwargs | kwargs

kernel_radius

kernel_radius() -> int
Source code
215
216
217
@Scaler.cached_property
def kernel_radius(self) -> int:
    return self._ref_scaler.kernel_radius

multi

multi(
    clip: VideoNodeT,
    multi: float = 2.0,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    **kwargs: Any
) -> VideoNodeT

Deprecated alias for supersample.

Parameters:

  • clip

    (VideoNodeT) –

    The source clip.

  • multi

    (float, default: 2.0 ) –

    Supersampling factor.

  • shift

    (tuple[TopShift, LeftShift], default: (0, 0) ) –

    Subpixel shift (top, left) applied during scaling.

  • kwargs

    (Any, default: {} ) –

    Additional arguments forwarded to the scale function.

Returns:

Source code
451
452
453
454
455
456
457
458
459
460
461
462
463
464
@deprecated('The "multi" method is deprecated. Use "supersample" instead.', category=DeprecationWarning)
def multi(
    self, clip: VideoNodeT, multi: float = 2.0, shift: tuple[TopShift, LeftShift] = (0, 0), **kwargs: Any
) -> VideoNodeT:
    """
    Deprecated alias for `supersample`.

    :param clip:    The source clip.
    :param multi:   Supersampling factor.
    :param shift:   Subpixel shift (top, left) applied during scaling.
    :param kwargs:  Additional arguments forwarded to the scale function.
    :return:        The supersampled clip.
    """
    return self.supersample(clip, multi, shift, **kwargs)

pretty_string

pretty_string() -> str

Cached property returning a user-friendly string representation.

Returns:

  • str

    Pretty-printed string with arguments.

Source code
368
369
370
371
372
373
374
375
@cached_property
def pretty_string(self) -> str:
    """
    Cached property returning a user-friendly string representation.

    :return: Pretty-printed string with arguments.
    """
    return self._pretty_string()

scale

scale(
    clip: VideoNode,
    width: int | None = None,
    height: int | None = None,
    shift: tuple[float, float] = (0, 0),
    **kwargs: Any
) -> ConstantFormatVideoNode
Source code
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
def scale(
    self,
    clip: vs.VideoNode,
    width: int | None = None,
    height: int | None = None,
    shift: tuple[float, float] = (0, 0),
    **kwargs: Any
) -> ConstantFormatVideoNode:
    assert check_variable(clip, self.__class__)

    width, height = self._wh_norm(clip, width, height)

    ref = clip

    if isinstance(self.ref, vs.VideoNode):
        check_ref_clip(clip, self.ref)

        if TYPE_CHECKING:
            assert check_variable_format(self.ref, self.__class__)

        ref = self.ref

    if (ref.width, ref.height) != (width, height):
        ref = self._ref_scaler.scale(ref, width, height)  # type: ignore[assignment]

    kwargs = {
        'lambda': self.sigma, 'planes': self.planes,
        'src_left': shift[1], 'src_top': shift[0]
    } | self.kwargs | kwargs | {'read_chromaloc': True}

    return core.dpid.DpidRaw(clip, ref, **kwargs)

supersample

supersample(
    clip: VideoNodeT,
    rfactor: float = 2.0,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    **kwargs: Any
) -> VideoNodeT

Supersample a clip by a given scaling factor.

Parameters:

  • clip

    (VideoNodeT) –

    The source clip.

  • rfactor

    (float, default: 2.0 ) –

    Scaling factor for supersampling.

  • shift

    (tuple[TopShift, LeftShift], default: (0, 0) ) –

    Subpixel shift (top, left) applied during scaling.

  • kwargs

    (Any, default: {} ) –

    Additional arguments forwarded to the scale function.

Returns:

Raises:

  • CustomValueError

    If resulting resolution is non-positive.

Source code
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
def supersample(
    self, clip: VideoNodeT, rfactor: float = 2.0, shift: tuple[TopShift, LeftShift] = (0, 0), **kwargs: Any
) -> VideoNodeT:
    """
    Supersample a clip by a given scaling factor.

    :param clip:                The source clip.
    :param rfactor:             Scaling factor for supersampling.
    :param shift:               Subpixel shift (top, left) applied during scaling.
    :param kwargs:              Additional arguments forwarded to the scale function.
    :raises CustomValueError:   If resulting resolution is non-positive.
    :return:                    The supersampled clip.
    """
    assert check_variable_resolution(clip, self.supersample)

    dst_width, dst_height = ceil(clip.width * rfactor), ceil(clip.height * rfactor)

    if max(dst_width, dst_height) <= 0.0:
        raise CustomValueError(
            'Multiplying the resolution by "rfactor" must result in a positive resolution!',
            self.supersample,
            rfactor,
        )

    return self.scale(clip, dst_width, dst_height, shift, **kwargs)  # type: ignore[return-value]

SSIM

SSIM(
    scaler: ScalerLike = Hermite,
    smooth: (
        int
        | float
        | VSFunctionNoArgs[VideoNode, ConstantFormatVideoNode]
        | None
    ) = None,
    **kwargs: Any
)

Bases: LinearScaler

SSIM downsampler is an image downscaling technique that aims to optimize for the perceptual quality of the downscaled results.

Image downscaling is considered as an optimization problem where the difference between the input and output images is measured using famous Structural SIMilarity (SSIM) index.

The solution is derived in closed-form, which leads to the simple, efficient implementation. The downscaled images retain perceptually important features and details, resulting in an accurate and spatio-temporally consistent representation of the high resolution input.

Parameters:

  • scaler

    (ScalerLike, default: Hermite ) –

    Scaler to be used for downscaling, defaults to Hermite.

  • smooth

    (int | float | VSFunctionNoArgs[VideoNode, ConstantFormatVideoNode] | None, default: None ) –

    Image smoothening method. If you pass an int, it specifies the "radius" of the internally-used boxfilter, i.e. the window has a size of (2smooth+1)x(2smooth+1). If you pass a float, it specifies the "sigma" of gauss_blur, i.e. the standard deviation of gaussian blur. If you pass a function, it acts as a general smoother. Default uses a gaussian blur based on the scaler's kernel radius.

Classes:

Methods:

  • ensure_obj

    Ensure that the input is a scaler instance, resolving it if necessary.

  • from_param

    Resolve and return a scaler type from a given input (string, type, or instance).

  • get_scale_args

    Generate the keyword arguments used for scaling.

  • kernel_radius
  • multi

    Deprecated alias for supersample.

  • pretty_string

    Cached property returning a user-friendly string representation.

  • scale

    Scale a clip to the given resolution with optional linearization.

  • supersample

    Supersample a clip by a given scaling factor.

Attributes:

Source code
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
def __init__(
    self,
    scaler: ScalerLike = Hermite,
    smooth: int | float | VSFunctionNoArgs[vs.VideoNode, ConstantFormatVideoNode] | None = None,
    **kwargs: Any
) -> None:
    """
    :param scaler:      Scaler to be used for downscaling, defaults to Hermite.
    :param smooth:      Image smoothening method.
                        If you pass an int, it specifies the "radius" of the internally-used boxfilter,
                        i.e. the window has a size of (2*smooth+1)x(2*smooth+1).
                        If you pass a float, it specifies the "sigma" of gauss_blur,
                        i.e. the standard deviation of gaussian blur.
                        If you pass a function, it acts as a general smoother.
                        Default uses a gaussian blur based on the scaler's kernel radius.
    """
    super().__init__(**kwargs)

    self.scaler = Scaler.from_param(scaler)()

    if smooth is None:
        smooth = (self.scaler.kernel_radius + 1.0) / 3

    if callable(smooth):
        self.filter_func = smooth
    elif isinstance(smooth, int):
        self.filter_func = partial(box_blur, radius=smooth)
    elif isinstance(smooth, float):
        self.filter_func = partial(gauss_blur, sigma=smooth)

filter_func instance-attribute

filter_func = smooth

kwargs instance-attribute

kwargs: dict[str, Any] = kwargs

Arguments passed to the implemented funcs or internal scale function.

scale_function instance-attribute

scale_function: Callable[..., VideoNode]

Scale function called internally when performing scaling operations.

scaler instance-attribute

scaler = from_param(scaler)()

cached_property

cached_property(func: Callable[Concatenate[_BaseScalerT, P], T_co])

Bases: cached_property[T_co]

Read only version of functools.cached_property.

Source code
265
def __init__(self, func: Callable[Concatenate[_BaseScalerT, P], T_co]) -> None: ...

ensure_obj classmethod

ensure_obj(
    scaler: str | type[Self] | Self | None = None,
    /,
    func_except: FuncExceptT | None = None,
) -> Self

Ensure that the input is a scaler instance, resolving it if necessary.

Parameters:

  • scaler

    (str | type[Self] | Self | None, default: None ) –

    Scaler identifier (string, class, or instance).

  • func_except

    (FuncExceptT | None, default: None ) –

    Function returned for custom error handling.

Returns:

  • Self

    Scaler instance.

Source code
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
@classmethod
def ensure_obj(
    cls,
    scaler: str | type[Self] | Self | None = None,
    /,
    func_except: FuncExceptT | None = None,
) -> Self:
    """
    Ensure that the input is a scaler instance, resolving it if necessary.

    :param scaler:          Scaler identifier (string, class, or instance).
    :param func_except:     Function returned for custom error handling.
    :return:                Scaler instance.
    """
    return _base_ensure_obj(cls, scaler, func_except)

from_param classmethod

from_param(
    scaler: str | type[Self] | Self | None = None,
    /,
    func_except: FuncExceptT | None = None,
) -> type[Self]

Resolve and return a scaler type from a given input (string, type, or instance).

Parameters:

  • scaler

    (str | type[Self] | Self | None, default: None ) –

    Scaler identifier (string, class, or instance).

  • func_except

    (FuncExceptT | None, default: None ) –

    Function returned for custom error handling.

Returns:

  • type[Self]

    Resolved scaler type.

Source code
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
@classmethod
def from_param(
    cls,
    scaler: str | type[Self] | Self | None = None,
    /,
    func_except: FuncExceptT | None = None,
) -> type[Self]:
    """
    Resolve and return a scaler type from a given input (string, type, or instance).

    :param scaler:          Scaler identifier (string, class, or instance).
    :param func_except:     Function returned for custom error handling.
    :return:                Resolved scaler type.
    """
    return _base_from_param(cls, scaler, cls._err_class, func_except)

get_scale_args

get_scale_args(
    clip: VideoNode,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    width: int | None = None,
    height: int | None = None,
    **kwargs: Any
) -> dict[str, Any]

Generate the keyword arguments used for scaling.

Parameters:

  • clip

    (VideoNode) –

    The source clip.

  • shift

    (tuple[TopShift, LeftShift], default: (0, 0) ) –

    Subpixel shift (top, left).

  • width

    (int | None, default: None ) –

    Target width.

  • height

    (int | None, default: None ) –

    Target height.

  • kwargs

    (Any, default: {} ) –

    Extra parameters to merge.

Returns:

  • dict[str, Any]

    Final dictionary of keyword arguments for the scale function.

Source code
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
def get_scale_args(
    self,
    clip: vs.VideoNode,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    width: int | None = None,
    height: int | None = None,
    **kwargs: Any,
) -> dict[str, Any]:
    """
    Generate the keyword arguments used for scaling.

    :param clip:    The source clip.
    :param shift:   Subpixel shift (top, left).
    :param width:   Target width.
    :param height:  Target height.
    :param kwargs:  Extra parameters to merge.
    :return:        Final dictionary of keyword arguments for the scale function.
    """
    return dict(width=width, height=height, src_top=shift[0], src_left=shift[1]) | self.kwargs | kwargs

kernel_radius

kernel_radius() -> int
Source code
293
294
295
@Scaler.cached_property
def kernel_radius(self) -> int:
    return self.scaler.kernel_radius

multi

multi(
    clip: VideoNodeT,
    multi: float = 2.0,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    **kwargs: Any
) -> VideoNodeT

Deprecated alias for supersample.

Parameters:

  • clip

    (VideoNodeT) –

    The source clip.

  • multi

    (float, default: 2.0 ) –

    Supersampling factor.

  • shift

    (tuple[TopShift, LeftShift], default: (0, 0) ) –

    Subpixel shift (top, left) applied during scaling.

  • kwargs

    (Any, default: {} ) –

    Additional arguments forwarded to the scale function.

Returns:

Source code
451
452
453
454
455
456
457
458
459
460
461
462
463
464
@deprecated('The "multi" method is deprecated. Use "supersample" instead.', category=DeprecationWarning)
def multi(
    self, clip: VideoNodeT, multi: float = 2.0, shift: tuple[TopShift, LeftShift] = (0, 0), **kwargs: Any
) -> VideoNodeT:
    """
    Deprecated alias for `supersample`.

    :param clip:    The source clip.
    :param multi:   Supersampling factor.
    :param shift:   Subpixel shift (top, left) applied during scaling.
    :param kwargs:  Additional arguments forwarded to the scale function.
    :return:        The supersampled clip.
    """
    return self.supersample(clip, multi, shift, **kwargs)

pretty_string

pretty_string() -> str

Cached property returning a user-friendly string representation.

Returns:

  • str

    Pretty-printed string with arguments.

Source code
368
369
370
371
372
373
374
375
@cached_property
def pretty_string(self) -> str:
    """
    Cached property returning a user-friendly string representation.

    :return: Pretty-printed string with arguments.
    """
    return self._pretty_string()

scale

scale(
    clip: VideoNode,
    width: int | None = None,
    height: int | None = None,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    *,
    linear: bool | None = None,
    sigmoid: bool | tuple[Slope, Center] = False,
    **kwargs: Any
) -> VideoNode | ConstantFormatVideoNode

Scale a clip to the given resolution with optional linearization.

This method behaves like the base Scaler.descale() but adds support for linear or sigmoid-based preprocessing and postprocessing. When enabled, the clip is linearized before the scaling operation and de-linearized afterward.

Keyword arguments passed during initialization are automatically injected here, unless explicitly overridden by the arguments provided at call time. Only arguments that match named parameters in this method are injected.

Parameters:

  • clip

    (VideoNode) –

    The source clip.

  • width

    (int | None, default: None ) –

    Target width (defaults to clip width if None).

  • height

    (int | None, default: None ) –

    Target height (defaults to clip height if None).

  • shift

    (tuple[TopShift, LeftShift], default: (0, 0) ) –

    Subpixel shift (top, left) applied during scaling.

  • linear

    (bool | None, default: None ) –

    Whether to linearize the input before scaling. If None, inferred from sigmoid.

  • sigmoid

    (bool | tuple[Slope, Center], default: False ) –

    Whether to use sigmoid transfer curve. Can be True, False, or a tuple of (slope, center). True applies the defaults values (6.5, 0.75). Keep in mind sigmoid slope has to be in range 1.0-20.0 (inclusive) and sigmoid center has to be in range 0.0-1.0 (inclusive).

  • kwargs

    (Any, default: {} ) –

    Additional arguments forwarded to the scale function.

Returns:

  • VideoNode | ConstantFormatVideoNode

    Scaled video clip.

Source code
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
def scale(
    self,
    clip: vs.VideoNode,
    width: int | None = None,
    height: int | None = None,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    *,
    # LinearScaler adds `linear` and `sigmoid` parameters
    linear: bool | None = None,
    sigmoid: bool | tuple[Slope, Center] = False,
    **kwargs: Any,
) -> vs.VideoNode | ConstantFormatVideoNode:
    """
    Scale a clip to the given resolution with optional linearization.

    This method behaves like the base `Scaler.descale()` but adds support for
    linear or sigmoid-based preprocessing and postprocessing. When enabled, the clip
    is linearized before the scaling operation and de-linearized afterward.

    Keyword arguments passed during initialization are automatically injected here,
    unless explicitly overridden by the arguments provided at call time.
    Only arguments that match named parameters in this method are injected.

    :param clip:        The source clip.
    :param width:       Target width (defaults to clip width if None).
    :param height:      Target height (defaults to clip height if None).
    :param shift:       Subpixel shift (top, left) applied during scaling.
    :param linear:      Whether to linearize the input before scaling. If None, inferred from sigmoid.
    :param sigmoid:     Whether to use sigmoid transfer curve. Can be True, False, or a tuple of (slope, center).
                        `True` applies the defaults values (6.5, 0.75).
                        Keep in mind sigmoid slope has to be in range 1.0-20.0 (inclusive)
                        and sigmoid center has to be in range 0.0-1.0 (inclusive).
    :param kwargs:      Additional arguments forwarded to the scale function.
    :return:            Scaled video clip.
    """
    return _linearize(
        self,
        clip,
        linear,
        sigmoid,
        partial(super().scale, width=width, height=height, shift=shift),
        self.scale,
        **kwargs
    )

supersample

supersample(
    clip: VideoNodeT,
    rfactor: float = 2.0,
    shift: tuple[TopShift, LeftShift] = (0, 0),
    **kwargs: Any
) -> VideoNodeT

Supersample a clip by a given scaling factor.

Parameters:

  • clip

    (VideoNodeT) –

    The source clip.

  • rfactor

    (float, default: 2.0 ) –

    Scaling factor for supersampling.

  • shift

    (tuple[TopShift, LeftShift], default: (0, 0) ) –

    Subpixel shift (top, left) applied during scaling.

  • kwargs

    (Any, default: {} ) –

    Additional arguments forwarded to the scale function.

Returns:

Raises:

  • CustomValueError

    If resulting resolution is non-positive.

Source code
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
def supersample(
    self, clip: VideoNodeT, rfactor: float = 2.0, shift: tuple[TopShift, LeftShift] = (0, 0), **kwargs: Any
) -> VideoNodeT:
    """
    Supersample a clip by a given scaling factor.

    :param clip:                The source clip.
    :param rfactor:             Scaling factor for supersampling.
    :param shift:               Subpixel shift (top, left) applied during scaling.
    :param kwargs:              Additional arguments forwarded to the scale function.
    :raises CustomValueError:   If resulting resolution is non-positive.
    :return:                    The supersampled clip.
    """
    assert check_variable_resolution(clip, self.supersample)

    dst_width, dst_height = ceil(clip.width * rfactor), ceil(clip.height * rfactor)

    if max(dst_width, dst_height) <= 0.0:
        raise CustomValueError(
            'Multiplying the resolution by "rfactor" must result in a positive resolution!',
            self.supersample,
            rfactor,
        )

    return self.scale(clip, dst_width, dst_height, shift, **kwargs)  # type: ignore[return-value]