mvtools ¶

def analyze(
    self,
    super: vs.VideoNode | None = None,
    tr: int = 1,
    blksize: int | tuple[int | None, int | None] | None = None,
    levels: int | None = None,
    search: SearchMode | None = None,
    searchparam: int | None = None,
    pelsearch: int | None = None,
    lambda_: int | None = None,
    truemotion: MotionMode | None = None,
    lsad: int | None = None,
    plevel: PenaltyMode | None = None,
    global_: bool | None = None,
    pnew: int | None = None,
    pzero: int | None = None,
    pglobal: int | None = None,
    overlap: int | tuple[int | None, int | None] | None = None,
    divide: bool | None = None,
    badsad: int | None = None,
    badrange: int | None = None,
    meander: bool | None = None,
    trymany: bool | None = None,
    dct: SADMode | None = None,
    scale_lambda: bool = True,
) -> None:
    """
    Analyze motion vectors in a clip using block matching.

    Takes a prepared super clip (containing hierarchical frame data) and estimates motion by comparing blocks
    between frames.
    Outputs motion vector data that can be used by other functions for motion compensation.

    The motion vector search is performed hierarchically, starting from a coarse image scale and progressively
    refining to finer scales.
    For each block, the function first checks predictors like the zero vector and neighboring block vectors.

    This method calculates the Sum of Absolute Differences (SAD) for these predictors,
    then iteratively tests new candidate vectors by adjusting the current best vector.
    The vector with the lowest SAD value is chosen as the final motion vector,
    with a penalty applied to maintain motion coherence between blocks.

    Args:
        super: The multilevel super clip prepared by [super][vsdenoise.MVTools.super].
            If None, super will be obtained from clip.
        tr: The temporal radius. This determines how many frames are analyzed before/after the current frame.
            Default: 1.
        blksize: Size of a block. Larger blocks are less sensitive to noise, are faster, but also less accurate.
        levels: Number of levels used in hierarchical motion vector analysis. A positive value specifies how many
            levels to use. A negative or zero value specifies how many coarse levels to skip. Lower values generally
            give better results since vectors of any length can be found. Sometimes adding more levels can help
            prevent false vectors in CGI or similar content.
        search: Search algorithm to use at the finest level. See [SearchMode][vsdenoise.SearchMode] for options.
        searchparam: Additional parameter for the search algorithm. For NSTEP, this is the step size. For
            EXHAUSTIVE, EXHAUSTIVE_H, EXHAUSTIVE_V, HEXAGON and UMH, this is the search radius.
        lambda_: Controls the coherence of the motion vector field. Higher values enforce more coherent/smooth
            motion between blocks. Too high values may cause the algorithm to miss the optimal vectors.
        truemotion: Preset that controls the default values of motion estimation parameters to optimize for true
            motion. For more information, see [MotionMode][vsdenoise.MotionMode].
        lsad: SAD limit for lambda. When the SAD value of a vector predictor (formed from neighboring blocks)
            exceeds this limit, the local lambda value is decreased. This helps prevent the use of bad predictors,
            but reduces motion coherence between blocks.
        plevel: Controls how the penalty factor (lambda) scales with hierarchical levels. For more information, see
            [PenaltyMode][vsdenoise.PenaltyMode].
        global_: Whether to estimate global motion at each level and use it as an additional predictor. This can
            help with camera motion.
        pnew: Penalty multiplier (relative to 256) applied to the SAD cost when evaluating new candidate vectors.
            Higher values make the search more conservative.
        pzero: Penalty multiplier (relative to 256) applied to the SAD cost for the zero motion vector. Higher
            values discourage using zero motion.
        pglobal: Penalty multiplier (relative to 256) applied to the SAD cost when using the global motion
            predictor.
        overlap: Block overlap value. Can be a single integer for both dimensions or a tuple of (horizontal,
            vertical) overlap values. Each value must be even and less than its corresponding block size dimension.
        divide: Whether to divide each block into 4 subblocks during post-processing. This may improve accuracy at
            the cost of performance.
        badsad: SAD threshold above which a wider secondary search will be performed to find better motion vectors.
            Higher values mean fewer blocks will trigger the secondary search.
        badrange: Search radius for the secondary search when a block's SAD exceeds badsad.
        meander: Whether to use a meandering scan pattern when processing blocks. If True, alternates between left-
            to-right and right-to-left scanning between rows to improve motion coherence.
        trymany: Whether to test multiple predictor vectors during the search process at coarser levels. Enabling
            this can find better vectors but increases processing time.
        dct: SAD calculation mode using block DCT (frequency spectrum) for comparing blocks. For more information,
            see [SADMode][vsdenoise.SADMode].
        scale_lambda: Whether to scale lambda_ value according to truemotion's default value formula.

    Returns:
        A [MotionVectors][vsdenoise.MotionVectors] object containing the analyzed motion vectors for each frame.
        These vectors describe the estimated motion between frames and can be used for motion compensation.
    """

    super_clip = self.super(
        fallback(super, self.search_clip), levels=fallback(levels, self.analyze_args.get("levels"), 0)
    )

    blksize, blksizev = normalize_seq(blksize, 2)
    overlap, overlapv = normalize_seq(overlap, 2)

    if scale_lambda and lambda_ and blksize:
        lambda_ = lambda_ * blksize * fallback(blksizev, blksize) // 64

    analyze_args = self.analyze_args | KwargsNotNone(
        blksize=blksize,
        blksizev=blksizev,
        levels=levels,
        search=search,
        searchparam=searchparam,
        pelsearch=pelsearch,
        lambda_=lambda_,
        chroma=self.chroma,
        truemotion=truemotion,
        lsad=lsad,
        plevel=plevel,
        global_=global_,
        pnew=pnew,
        pzero=pzero,
        pglobal=pglobal,
        overlap=overlap,
        overlapv=overlapv,
        divide=divide,
        badsad=badsad,
        badrange=badrange,
        meander=meander,
        trymany=trymany,
        dct=dct,
        fields=self.fields,
        tff=self.tff,
    )

    self.vectors.clear()

    for delta in range(1, tr + 1):
        for direction in MVDirection:
            self.vectors.set_vector(
                core.mv.Analyse(super_clip, isb=direction is MVDirection.BACKWARD, delta=delta, **analyze_args),
                direction,
                delta,
            )

def block_fps(
    self,
    clip: vs.VideoNode | None = None,
    super: vs.VideoNode | None = None,
    vectors: MotionVectors | None = None,
    fps: Fraction | None = None,
    mode: int | None = None,
    ml: float | None = None,
    blend: bool | None = None,
    thscd: int | tuple[int | None, float | None] | None = None,
) -> vs.VideoNode:
    """
    Changes the framerate of the clip by interpolating frames between existing frames
    using block-based motion compensation.

    Uses both backward and forward motion vectors to estimate motion and create frames at any time position between
    the current and next frame. Occlusion masks are used to handle areas where motion estimation fails, and time
    weighting ensures smooth blending between frames to minimize artifacts.

    Args:
        clip: The clip to process.
        super: The multilevel super clip prepared by [super][vsdenoise.MVTools.super].
            If None, super will be obtained from clip.
        vectors: Motion vectors to use. If None, uses the vectors from this instance.
        fps: Target output framerate as a Fraction.
        mode: Processing mask mode for handling occlusions and motion failures.
        ml: Mask scale parameter that controls occlusion mask strength. Higher values produce weaker occlusion
            masks. Used in MakeVectorOcclusionMaskTime for modes 3-5. Used in MakeSADMaskTime for modes 6-8.
        blend: Whether to blend frames at scene changes. If True, frames will be blended. If False, frames will be
            copied.
        thscd: Scene change detection thresholds:

               - First value: SAD threshold for considering a block changed between frames.
               - Second value: Percentage of changed blocks needed to trigger a scene change.

    Returns:
        Clip with its framerate resampled.
    """

    clip = fallback(clip, self.clip)
    super_clip = self.super(fallback(super, clip), levels=1)

    vectors = fallback(vectors, self.vectors)
    vect_b, vect_f = vectors.get_vectors(tr=1)

    thscd1, thscd2 = normalize_thscd(thscd)

    block_fps_args: dict[str, Any] = KwargsNotNone(mode=mode, ml=ml, blend=blend, thscd1=thscd1, thscd2=thscd2)

    if fps is not None:
        block_fps_args.update(num=fps.numerator, den=fps.denominator)

    block_fps_args = self.block_fps_args | block_fps_args

    return core.mv.BlockFPS(clip, super_clip, vect_b[0], vect_f[0], **block_fps_args)

def compensate(
    self,
    clip: vs.VideoNode | None = None,
    super: vs.VideoNode | None = None,
    vectors: MotionVectors | None = None,
    direction: MVDirection = MVDirection.BOTH,
    tr: int | None = None,
    scbehavior: bool | None = None,
    thsad: int | None = None,
    time: float | None = None,
    thscd: int | tuple[int | None, float | None] | None = None,
    interleave: bool = True,
    temporal_func: VSFunctionNoArgs | None = None,
) -> vs.VideoNode | tuple[list[vs.VideoNode], list[vs.VideoNode]] | tuple[vs.VideoNode, tuple[int, int]]:
    """
    Perform motion compensation by moving blocks from reference frames to the current frame
    according to motion vectors.

    This creates a prediction of the current frame by taking blocks from neighboring frames
    and moving them along their estimated motion paths.

    Args:
        clip: The clip to process.
        super: The multilevel super clip prepared by [super][vsdenoise.MVTools.super].
            If None, super will be obtained from clip.
        vectors: Motion vectors to use. If None, uses the vectors from this instance.
        direction: Motion vector direction to use.
        tr: The temporal radius. This determines how many frames are analyzed before/after the current frame.
        scbehavior: Whether to keep the current frame on scene changes. If True, the frame is left unchanged. If
            False, the reference frame is copied.
        thsad: SAD threshold for safe compensation. If block SAD is above thsad, the source block is used instead of
            the compensated block.
        time: Time position between frames as a percentage (0.0-100.0). Controls the interpolation position between
            frames.
        thscd: Scene change detection thresholds:

               - First value: SAD threshold for considering a block changed between frames.
               - Second value: Percentage of changed blocks needed to trigger a scene change.

        interleave: Whether to interleave the compensated frames with the input.
        temporal_func: Temporal function to apply to the motion compensated frames.

    Returns:
        Motion compensated frames if func is provided, otherwise returns a tuple containing:

               - The interleaved compensated frames.
               - A tuple of (total_frames, center_offset) for manual frame selection.
    """

    clip = fallback(clip, self.clip)
    super_clip = self.super(fallback(super, clip), levels=1)

    vectors = fallback(vectors, self.vectors)
    vect_b, vect_f = vectors.get_vectors(direction, tr)

    thscd1, thscd2 = normalize_thscd(thscd)

    compensate_args = self.compensate_args | KwargsNotNone(
        scbehavior=scbehavior,
        thsad=thsad,
        time=time,
        thscd1=thscd1,
        thscd2=thscd2,
        fields=self.fields,
        tff=self.tff,
    )

    comp_back, comp_fwrd = [
        [core.mv.Compensate(clip, super_clip, vectors=vect, **compensate_args) for vect in vectors]
        for vectors in (reversed(vect_b), vect_f)
    ]

    if not interleave:
        return (comp_back, comp_fwrd)

    comp_clips = [*comp_fwrd, clip, *comp_back]
    cycle = len(comp_clips)
    offset = (cycle - 1) // 2

    interleaved = core.std.Interleave(comp_clips)

    if temporal_func:
        return core.std.SelectEvery(temporal_func(interleaved), cycle, offset)

    return interleaved, (cycle, offset)

def degrain(
    self,
    clip: vs.VideoNode | None = None,
    super: vs.VideoNode | None = None,
    vectors: MotionVectors | None = None,
    tr: int | None = None,
    thsad: int | tuple[int | None, int | None] | None = None,
    limit: float | tuple[float | None, float | None] | None = None,
    thscd: int | tuple[int | None, float | None] | None = None,
    planes: Planes = None,
) -> vs.VideoNode:
    """
    Perform temporal denoising using motion compensation.

    Motion compensated blocks from previous and next frames are averaged with the current frame.
    The weighting factors for each block depend on their SAD from the current frame.

    Args:
        clip: The clip to process. If None, the [clip][vsdenoise.MVTools.clip] attribute is used.
        super: The multilevel super clip prepared by [super][vsdenoise.MVTools.super].
            If None, super will be obtained from clip.
        vectors: Motion vectors to use. If None, uses the vectors from this instance.
        tr: The temporal radius. This determines how many frames are analyzed before/after the current frame.
        thsad: Defines the soft threshold of block sum absolute differences. Blocks with SAD above this threshold
            have zero weight for averaging (denoising). Blocks with low SAD have highest weight. The remaining
            weight is taken from pixels of source clip.
        limit: Maximum allowed change in pixel values (8 bits scale).
        thscd: Scene change detection thresholds:

               - First value: SAD threshold for considering a block changed between frames.
               - Second value: Percentage of changed blocks needed to trigger a scene change.
        planes: Which planes to process. Default: None (all planes).

    Returns:
        Motion compensated and temporally filtered clip with reduced noise.
    """

    clip = fallback(clip, self.clip)
    super_clip = self.super(fallback(super, clip), levels=1)

    vectors = fallback(vectors, self.vectors)
    tr = fallback(tr, vectors.tr)
    vect_b, vect_f = vectors.get_vectors(tr=tr)

    thscd1, thscd2 = normalize_thscd(thscd)

    thsad, thsadc = normalize_seq(thsad, 2)
    nlimit, nlimitc = normalize_seq(limit, 2)

    if nlimit is not None:
        nlimit = scale_delta(nlimit, 8, clip)

    if nlimitc is not None:
        nlimitc = scale_delta(nlimitc, 8, clip)

    degrain_args = self.degrain_args | KwargsNotNone(
        thsad=thsad,
        thsadc=thsadc,
        plane=planes_to_mvtools(clip, planes),
        limit=nlimit,
        limitc=nlimitc,
        thscd1=thscd1,
        thscd2=thscd2,
    )

    return getattr(core.mv, f"Degrain{tr}")(
        clip, super_clip, *chain.from_iterable(zip(vect_b, vect_f)), **degrain_args
    )

def flow(
    self,
    clip: vs.VideoNode | None = None,
    super: vs.VideoNode | None = None,
    vectors: MotionVectors | None = None,
    direction: MVDirection = MVDirection.BOTH,
    tr: int | None = None,
    time: float | None = None,
    mode: FlowMode | None = None,
    thscd: int | tuple[int | None, float | None] | None = None,
    interleave: bool = True,
    temporal_func: VSFunctionNoArgs | None = None,
) -> vs.VideoNode | tuple[list[vs.VideoNode], list[vs.VideoNode]] | tuple[vs.VideoNode, tuple[int, int]]:
    """
    Performs motion compensation using pixel-level motion vectors interpolated from block vectors.

    Unlike block-based compensation, this calculates a unique motion vector for each pixel
    by bilinearly interpolating between the motion vectors of the current block and its neighbors
    based on the pixel's position.
    The pixels in the reference frame are then moved along these interpolated vectors
    to their estimated positions in the current frame.

    Args:
        clip: The clip to process.
        super: The multilevel super clip prepared by [super][vsdenoise.MVTools.super].
            If None, super will be obtained from clip.
        vectors: Motion vectors to use. If None, uses the vectors from this instance.
        direction: Motion vector direction to use.
        tr: The temporal radius. This determines how many frames are analyzed before/after the current frame.
        time: Time position between frames as a percentage (0.0-100.0). Controls the interpolation position between
            frames.
        mode: Method for positioning pixels during motion compensation.
            See [FlowMode][vsdenoise.FlowMode] for options.
        thscd: Scene change detection thresholds:

               - First value: SAD threshold for considering a block changed between frames.
               - Second value: Percentage of changed blocks needed to trigger a scene change.
        interleave: Whether to interleave the compensated frames with the input.
        temporal_func: Optional function to process the motion compensated frames. Takes the interleaved frames as
            input and returns processed frames.

    Returns:
        Motion compensated frames if func is provided, otherwise returns a tuple containing:

               - The interleaved compensated frames.
               - A tuple of (total_frames, center_offset) for manual frame selection.
    """

    clip = fallback(clip, self.clip)
    super_clip = self.super(fallback(super, clip), levels=1)

    vectors = fallback(vectors, self.vectors)
    vect_b, vect_f = vectors.get_vectors(direction, tr)

    thscd1, thscd2 = normalize_thscd(thscd)

    flow_args = self.flow_args | KwargsNotNone(
        time=time,
        mode=mode,
        thscd1=thscd1,
        thscd2=thscd2,
        fields=self.fields,
        tff=self.tff,
    )

    flow_back, flow_fwrd = [
        [core.mv.Flow(clip, super_clip, vectors=vect, **flow_args) for vect in vectors]
        for vectors in (reversed(vect_b), vect_f)
    ]

    if not interleave:
        return (flow_back, flow_fwrd)

    flow_clips = [*flow_fwrd, clip, *flow_back]
    cycle = len(flow_clips)
    offset = (cycle - 1) // 2

    interleaved = core.std.Interleave(flow_clips)

    if temporal_func:
        return core.std.SelectEvery(temporal_func(interleaved), cycle, offset)

    return interleaved, (cycle, offset)

def flow_blur(
    self,
    clip: vs.VideoNode | None = None,
    super: vs.VideoNode | None = None,
    vectors: MotionVectors | None = None,
    blur: float | None = None,
    prec: int | None = None,
    thscd: int | tuple[int | None, float | None] | None = None,
) -> vs.VideoNode:
    """
    Creates a motion blur effect by simulating finite shutter time, similar to film cameras.

    Uses backward and forward motion vectors to create and overlay multiple copies of motion compensated pixels
    at intermediate time positions within a blurring interval around the current frame.

    Args:
        clip: The clip to process.
        super: The multilevel super clip prepared by [super][vsdenoise.MVTools.super].
            If None, super will be obtained from clip.
        vectors: Motion vectors to use. If None, uses the vectors from this instance.
        blur: Blur time interval between frames as a percentage (0.0-100.0). Controls the simulated shutter
            time/motion blur strength.
        prec: Blur precision in pixel units. Controls the accuracy of the motion blur.
        thscd: Scene change detection thresholds:

               - First value: SAD threshold for considering a block changed between frames.
               - Second value: Percentage of changed blocks needed to trigger a scene change.

    Returns:
        Motion blurred clip.
    """

    clip = fallback(clip, self.clip)
    super_clip = self.super(fallback(super, clip), levels=1)

    vectors = fallback(vectors, self.vectors)
    vect_b, vect_f = vectors.get_vectors(tr=1)

    thscd1, thscd2 = normalize_thscd(thscd)

    flow_blur_args = self.flow_blur_args | KwargsNotNone(blur=blur, prec=prec, thscd1=thscd1, thscd2=thscd2)

    return core.mv.FlowBlur(clip, super_clip, vect_b[0], vect_f[0], **flow_blur_args)

def flow_fps(
    self,
    clip: vs.VideoNode | None = None,
    super: vs.VideoNode | None = None,
    vectors: MotionVectors | None = None,
    fps: Fraction | None = None,
    mask: int | None = None,
    ml: float | None = None,
    blend: bool | None = None,
    thscd: int | tuple[int | None, float | None] | None = None,
) -> vs.VideoNode:
    """
    Changes the framerate of the clip by interpolating frames between existing frames.

    Uses both backward and forward motion vectors to estimate motion and create frames at any time position between
    the current and next frame. Occlusion masks are used to handle areas where motion estimation fails, and time
    weighting ensures smooth blending between frames to minimize artifacts.

    Args:
        clip: The clip to process.
        super: The multilevel super clip prepared by [super][vsdenoise.MVTools.super].
            If None, super will be obtained from clip.
        vectors: Motion vectors to use. If None, uses the vectors from this instance.
        fps: Target output framerate as a Fraction.
        mask: Processing mask mode for handling occlusions and motion failures.
        ml: Mask scale parameter that controls occlusion mask strength. Higher values produce weaker occlusion
            masks. Used in MakeVectorOcclusionMaskTime for modes 3-5. Used in MakeSADMaskTime for modes 6-8.
        blend: Whether to blend frames at scene changes. If True, frames will be blended. If False, frames will be
            copied.
        thscd: Scene change detection thresholds:

               - First value: SAD threshold for considering a block changed between frames.
               - Second value: Percentage of changed blocks needed to trigger a scene change.

    Returns:
        Clip with its framerate resampled.
    """

    clip = fallback(clip, self.clip)
    super_clip = self.super(fallback(super, clip), levels=1)

    vectors = fallback(vectors, self.vectors)
    vect_b, vect_f = vectors.get_vectors(tr=1)

    thscd1, thscd2 = normalize_thscd(thscd)

    flow_fps_args: dict[str, Any] = KwargsNotNone(mask=mask, ml=ml, blend=blend, thscd1=thscd1, thscd2=thscd2)

    if fps is not None:
        flow_fps_args.update(num=fps.numerator, den=fps.denominator)

    flow_fps_args = self.flow_fps_args | flow_fps_args

    return core.mv.FlowFPS(clip, super_clip, vect_b[0], vect_f[0], **flow_fps_args)