mvtools ¶

def analyze(
    self, super: vs.VideoNode | None = None, 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
) -> 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.

    :param super:          The multilevel super clip prepared by :py:attr:`super`.
                           If None, super will be obtained from clip.
    :param blksize:        Size of a block. Larger blocks are less sensitive to noise, are faster, but also less accurate.
    :param 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.
    :param search:         Search algorithm to use at the finest level. See :py:class:`SearchMode` for options.
    :param 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.
    :param 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.
    :param truemotion:     Preset that controls the default values of motion estimation parameters to optimize for true motion.
                           For more information, see :py:class:`MotionMode`.
    :param 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.
    :param plevel:         Controls how the penalty factor (lambda) scales with hierarchical levels.
                           For more information, see :py:class:`PenaltyMode`.
    :param global_:        Whether to estimate global motion at each level and use it as an additional predictor.
                           This can help with camera motion.
    :param pnew:           Penalty multiplier (relative to 256) applied to the SAD cost when evaluating new candidate vectors.
                           Higher values make the search more conservative.
    :param pzero:          Penalty multiplier (relative to 256) applied to the SAD cost for the zero motion vector.
                           Higher values discourage using zero motion.
    :param pglobal:        Penalty multiplier (relative to 256) applied to the SAD cost when using the global motion predictor.
    :param 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.
    :param divide:         Whether to divide each block into 4 subblocks during post-processing.
                           This may improve accuracy at the cost of performance.
    :param 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.
    :param badrange:       Search radius for the secondary search when a block's SAD exceeds badsad.
    :param 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.
    :param trymany:        Whether to test multiple predictor vectors during the search process at coarser levels.
                           Enabling this can find better vectors but increases processing time.
    :param dct:            SAD calculation mode using block DCT (frequency spectrum) for comparing blocks.
                           For more information, see :py:class:`SADMode`.

    :return:               A :py:class:`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.get_super(fallback(super, self.search_clip))

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

    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,
        fields=self.fieldbased.is_inter, tff=self.fieldbased.is_tff, dct=dct
    )

    if self.mvtools is MVToolsPlugin.INTEGER and not any(
        (analyze_args.get('overlap'), analyze_args.get('overlapv'))
    ):
        self.disable_compensate = True

    if self.mvtools is MVToolsPlugin.FLOAT:
        self.vectors.vmulti = self.mvtools.Analyze(super_clip, radius=self.tr, **analyze_args)
    else:
        for i in range(1, self.tr + 1):
            for direction in MVDirection:
                vector = self.mvtools.Analyze(
                    super_clip, isb=direction is MVDirection.BACK, delta=i, **analyze_args
                )
                self.vectors.set_mv(direction, i, vector)

        self.vectors.analysis_data.clear()

def block_fps(
    self, clip: vs.VideoNode | None = None, super: vs.VideoNode | None = None,
    vectors: MotionVectors | MVTools | None = None, fps: Fraction | None = None,
    mode: int | None = None, ml: float | None = None, blend: bool | None = None,
    thscd: int | tuple[int | None, int | 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.

    :param clip:       The clip to process.
    :param super:      The multilevel super clip prepared by :py:attr:`super`.
                       If None, super will be obtained from clip.
    :param vectors:    Motion vectors to use. Can be a MotionVectors object or another MVTools instance.
                       If None, uses the vectors from this instance.
    :param fps:        Target output framerate as a Fraction.
    :param mode:       Processing mask mode for handling occlusions and motion failures.
    :param 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.
    :param blend:      Whether to blend frames at scene changes.
                       If True, frames will be blended. If False, frames will be copied.
    :param thscd:      Scene change detection thresholds.
                       First value is the block change threshold between frames.
                       Second value is the number of changed blocks needed for a scene change.

    :return:           Clip with its framerate resampled.
    """

    clip = fallback(clip, self.clip)
    super_clip = self.get_super(fallback(super, clip))

    if isinstance(vectors, MVTools):
        vectors = vectors.vectors
    elif vectors is None:
        vectors = self.vectors

    vect_b, vect_f = self.get_vectors(self.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 self.mvtools.BlockFPS(clip, super_clip, vect_b, vect_f, **block_fps_args)

def compensate(
    self, clip: vs.VideoNode | None = None, super: vs.VideoNode | None = None,
    vectors: MotionVectors | MVTools | None = None, direction: MVDirection = MVDirection.BOTH,
    tr: int | None = None, scbehavior: bool | None = None,
    thsad: int | None = None, thsad2: int | None = None,
    time: float | None = None, thscd: int | tuple[int | None, int | None] | None = None,
    interleave: bool = True, temporal_func: VSFunction | 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.

    :param clip:             The clip to process.
    :param super:            The multilevel super clip prepared by :py:attr:`super`.
                             If None, super will be obtained from clip.
    :param vectors:          Motion vectors to use. Can be a MotionVectors object or another MVTools instance.
                             If None, uses the vectors from this instance.
    :param direction:        Motion vector direction to use.
    :param tr:               The temporal radius. This determines how many frames are analyzed before/after the current frame.
    :param scbehavior:       Whether to keep the current frame on scene changes.
                             If True, the frame is left unchanged. If False, the reference frame is copied.
    :param thsad:            SAD threshold for safe compensation.
                             If block SAD is above thsad, the source block is used instead of the compensated block.
    :param thsad2:           Define the SAD soft threshold for frames with the largest temporal distance.
                             The actual SAD threshold for each reference frame is interpolated between thsad (nearest frames)
                             and thsad2 (furthest frames).
                             Only used with the FLOAT MVTools plugin.
    :param time:             Time position between frames as a percentage (0.0-100.0).
                             Controls the interpolation position between frames.
    :param thscd:            Scene change detection thresholds.
                             First value is the block change threshold between frames.
                             Second value is the number of changed blocks needed for a scene change.
    :param interleave:       Whether to interleave the compensated frames with the input.
    :param temporal_func:    Temporal function to apply to the motion compensated frames.

    :return:                 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.
    """

    if self.disable_compensate:
        raise CustomRuntimeError('Motion analysis was performed without block overlap!', self.compensate)

    clip = fallback(clip, self.clip)
    super_clip = self.get_super(fallback(super, clip))

    if isinstance(vectors, MVTools):
        vectors = vectors.vectors
    elif vectors is None:
        vectors = self.vectors

    tr = fallback(tr, self.tr)

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

    thscd1, thscd2 = normalize_thscd(thscd)

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

    comp_back, comp_fwrd = [
        [self.mvtools.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]
    n_clips = len(comp_clips)
    offset = (n_clips - 1) // 2

    interleaved = core.std.Interleave(comp_clips)

    if temporal_func:
        processed = temporal_func(interleaved)

        return processed.std.SelectEvery(n_clips, offset)

    return interleaved, (n_clips, offset)

def degrain(
    self, clip: vs.VideoNode | None = None, super: vs.VideoNode | None = None,
    vectors: MotionVectors | MVTools | None = None, tr: int | None = None,
    thsad: int | tuple[int | None, int | None] | None = None,
    thsad2: int | tuple[int | None, int | None] | None = None,
    limit: int | tuple[int | None, int | None] | None = None,
    thscd: int | tuple[int | None, int | None] | None = 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.

    :param clip:       The clip to process.
                       If None, the :py:attr:`workclip` attribute is used.
    :param super:      The multilevel super clip prepared by :py:attr:`super`.
                       If None, super will be obtained from clip.
    :param vectors:    Motion vectors to use. Can be a MotionVectors object or another MVTools instance.
                       If None, uses the vectors from this instance.
    :param tr:         The temporal radius. This determines how many frames are analyzed before/after the current frame.
    :param 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.
    :param thsad2:     Define the SAD soft threshold for frames with the largest temporal distance.
                       The actual SAD threshold for each reference frame is interpolated between thsad (nearest frames)
                       and thsad2 (furthest frames).
                       Only used with the FLOAT MVTools plugin.
    :param limit:      Maximum allowed change in pixel values.
    :param thscd:      Scene change detection thresholds:
                       - First value: SAD threshold for considering a block changed between frames.
                       - Second value: Number of changed blocks needed to trigger a scene change.

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

    if self.disable_degrain:
        raise CustomRuntimeError('Motion analysis was performed with a temporal radius of 1!', self.degrain)

    clip = fallback(clip, self.clip)
    super_clip = self.get_super(fallback(super, clip))

    if isinstance(vectors, MVTools):
        vectors = vectors.vectors
    elif vectors is None:
        vectors = self.vectors

    tr = fallback(tr, self.tr)

    thscd1, thscd2 = normalize_thscd(thscd)

    degrain_args = dict[str, Any](thscd1=thscd1, thscd2=thscd2, plane=self.mv_plane)

    if self.mvtools is MVToolsPlugin.FLOAT:
        degrain_args.update(thsad=thsad, thsad2=thsad2, limit=limit)
    else:
        vect_b, vect_f = self.get_vectors(vectors, tr=tr)

        thsad, thsadc = normalize_seq(thsad, 2)
        limit, limitc = normalize_seq(limit, 2)

        if limit is not None:
            limit = scale_delta(limit, 8, clip)  # type: ignore[assignment]

        if limitc is not None:
            limitc = scale_delta(limitc, 8, clip)  # type: ignore[assignment]

        degrain_args.update(thsad=thsad, thsadc=thsadc, limit=limit, limitc=limitc)

    degrain_args = self.degrain_args | KwargsNotNone(degrain_args)

    if self.mvtools is MVToolsPlugin.FLOAT:
        output = self.mvtools.Degrain()(clip, super_clip, vectors.vmulti, **degrain_args)
    else:
        output = self.mvtools.Degrain(tr)(
            clip, super_clip, *chain.from_iterable(zip(vect_b, vect_f)), **degrain_args
        )

    return output

def expand_analysis_data(self, vectors: MotionVectors | MVTools | None = None) -> None:
    """
    Expands the binary MVTools_MVAnalysisData frame prop into separate frame props for convenience.

    :param vectors:    Motion vectors to use. Can be a MotionVectors object or another MVTools instance.
                       If None, uses the vectors from this instance.
    """

    if self.disable_manipmv:
        raise CustomRuntimeError(
            f'Motion vector manipulation not supported with {self.mvtools}!', self.expand_analysis_data
        )

    if isinstance(vectors, MVTools):
        vectors = vectors.vectors
    elif vectors is None:
        vectors = self.vectors

    props_list = (
        'Analysis_BlockSize', 'Analysis_Pel', 'Analysis_LevelCount', 'Analysis_CpuFlags', 'Analysis_MotionFlags',
        'Analysis_FrameSize', 'Analysis_Overlap', 'Analysis_BlockCount', 'Analysis_BitsPerSample',
        'Analysis_ChromaRatio', 'Analysis_Padding'
    )

    if not vectors.analysis_data:
        analysis_props = dict[str, Any]()

        with vectors.get_mv(MVDirection.BACK, 1).manipmv.ExpandAnalysisData().get_frame(0) as clip_props:
            for i in props_list:
                analysis_props[i] = get_prop(clip_props, i, int | list)  # type: ignore

        vectors.analysis_data = analysis_props

def flow(
    self, clip: vs.VideoNode | None = None, super: vs.VideoNode | None = None,
    vectors: MotionVectors | MVTools | None = None,
    direction: MVDirection = MVDirection.BOTH,
    tr: int | None = None, time: float | None = None, mode: FlowMode | None = None,
    thscd: int | tuple[int | None, int | None] | None = None,
    interleave: bool = True, temporal_func: VSFunction | 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.

    :param clip:             The clip to process.
    :param super:            The multilevel super clip prepared by :py:attr:`super`.
                             If None, super will be obtained from clip.
    :param vectors:          Motion vectors to use. Can be a MotionVectors object or another MVTools instance.
                             If None, uses the vectors from this instance.
    :param direction:        Motion vector direction to use.
    :param tr:               The temporal radius. This determines how many frames are analyzed before/after the current frame.
    :param time:             Time position between frames as a percentage (0.0-100.0).
                             Controls the interpolation position between frames.
    :param mode:             Method for positioning pixels during motion compensation.
                             See :py:class:`FlowMode` for options.
    :param thscd:            Scene change detection thresholds as a tuple of (threshold1, threshold2).
                             threshold1: SAD difference threshold between frames to consider a block changed
                             threshold2: Number of changed blocks needed to trigger a scene change
    :param interleave:       Whether to interleave the compensated frames with the input.
    :param temporal_func:    Optional function to process the motion compensated frames.
                             Takes the interleaved frames as input and returns processed frames.

    :return:                 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.get_super(fallback(super, clip))

    if isinstance(vectors, MVTools):
        vectors = vectors.vectors
    elif vectors is None:
        vectors = self.vectors

    tr = fallback(tr, self.tr)

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

    thscd1, thscd2 = normalize_thscd(thscd)

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

    flow_back, flow_fwrd = [
        [self.mvtools.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]
    n_clips = len(flow_clips)
    offset = (n_clips - 1) // 2

    interleaved = core.std.Interleave(flow_clips)

    if temporal_func:
        processed = temporal_func(interleaved)

        return processed.std.SelectEvery(n_clips, offset)

    return interleaved, (n_clips, offset)

def flow_blur(
    self, clip: vs.VideoNode | None = None, super: vs.VideoNode | None = None,
    vectors: MotionVectors | MVTools | None = None, blur: float | None = None,
    prec: int | None = None, thscd: int | tuple[int | None, int | 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.

    :param clip:       The clip to process.
    :param super:      The multilevel super clip prepared by :py:attr:`super`.
                       If None, super will be obtained from clip.
    :param vectors:    Motion vectors to use. Can be a MotionVectors object or another MVTools instance.
                       If None, uses the vectors from this instance.
    :param blur:       Blur time interval between frames as a percentage (0.0-100.0).
                       Controls the simulated shutter time/motion blur strength.
    :param prec:       Blur precision in pixel units. Controls the accuracy of the motion blur.
    :param thscd:      Scene change detection thresholds.
                       First value is the block change threshold between frames.
                       Second value is the number of changed blocks needed for a scene change.

    :return:           Motion blurred clip.
    """

    clip = fallback(clip, self.clip)
    super_clip = self.get_super(fallback(super, clip))

    if isinstance(vectors, MVTools):
        vectors = vectors.vectors
    elif vectors is None:
        vectors = self.vectors

    vect_b, vect_f = self.get_vectors(self.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 self.mvtools.FlowBlur(clip, super_clip, vect_b, vect_f, **flow_blur_args)

def flow_fps(
    self, clip: vs.VideoNode | None = None, super: vs.VideoNode | None = None,
    vectors: MotionVectors | MVTools | None = None, fps: Fraction | None = None,
    mask: int | None = None, ml: float | None = None, blend: bool | None = None,
    thscd: int | tuple[int | None, int | 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.

    :param clip:       The clip to process.
    :param super:      The multilevel super clip prepared by :py:attr:`super`.
                       If None, super will be obtained from clip.
    :param vectors:    Motion vectors to use. Can be a MotionVectors object or another MVTools instance.
                       If None, uses the vectors from this instance.
    :param fps:        Target output framerate as a Fraction.
    :param mask:       Processing mask mode for handling occlusions and motion failures.
    :param 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.
    :param blend:      Whether to blend frames at scene changes.
                       If True, frames will be blended. If False, frames will be copied.
    :param thscd:      Scene change detection thresholds.
                       First value is the block change threshold between frames.
                       Second value is the number of changed blocks needed for a scene change.

    :return:           Clip with its framerate resampled.
    """

    clip = fallback(clip, self.clip)
    super_clip = self.get_super(fallback(super, clip))

    if isinstance(vectors, MVTools):
        vectors = vectors.vectors
    elif vectors is None:
        vectors = self.vectors

    vect_b, vect_f = self.get_vectors(self.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 self.mvtools.FlowFPS(clip, super_clip, vect_b, vect_f, **flow_fps_args)