motion ¶

@analysis_data.deleter  # type: ignore[no-redef]
def analysis_data(self) -> None:
    cachedproperty.clear_cache(self, "analysis_data")

def clear(self) -> None:
    """
    Clear all stored motion vectors.
    """

    for v in self.values():
        v.clear()

    self._blksize = None
    self._overlap_div = None
    cachedproperty.clear_cache(self)

def get_vector(self, direction: MVDirection, delta: int) -> vs.VideoNode:
    """
    Get a single motion vector.

    Args:
        direction: Motion vector direction to get.
        delta: Motion vector delta to get.

    Returns:
        A single motion vector VideoNode
    """

    if delta not in self[direction]:
        raise CustomRuntimeError(
            "Tried to get a motion vector delta that does not exist!", self.get_vector, f"{delta}"
        )

    return self[direction][delta]

def get_vectors(
    self,
    direction: MVDirection = MVDirection.BOTH,
    tr: int | None = None,
    delta: int | Sequence[int] | None = None,
) -> tuple[list[vs.VideoNode], list[vs.VideoNode]]:
    """
    Get the backward and forward vectors.

    Args:
        direction: Motion vector direction to get.
        tr: The number of frames to get the vectors for.
        delta: Specific delta(s) of motion vectors to retrieve.

    Returns:
        A tuple containing two lists of motion vectors.
        The first list contains backward vectors and the second contains forward vectors.
    """
    if delta is not None:
        deltas = to_arr(delta)
    elif tr is not None:
        deltas = range(1, tr + 1)
    else:
        deltas = self.deltas

    vectors_backward = list[vs.VideoNode]()
    vectors_forward = list[vs.VideoNode]()

    for d in deltas:
        if direction in [MVDirection.BACKWARD, MVDirection.BOTH] and d in self[MVDirection.BACKWARD]:
            vectors_backward.append(self[MVDirection.BACKWARD][d])
        if direction in [MVDirection.FORWARD, MVDirection.BOTH] and d in self[MVDirection.FORWARD]:
            vectors_forward.append(self[MVDirection.FORWARD][d])

    if not vectors_backward and not vectors_forward:
        raise CustomRuntimeError(
            "No motion vectors available! Did you forget to call analyze()?",
            func=self.get_vectors,
            reason={"direction": direction, "deltas": list(deltas)},
        )

    return (vectors_backward, vectors_forward)

def scale_vectors(self, scale: int | tuple[int, int], strict: bool = True) -> None:
    """
    Scales image_size, block_size, overlap, padding, and the individual motion_vectors contained in Analyse output
    by arbitrary and independent x and y factors.

    Args:
        scale: Factor to scale motion vectors by.
    """

    raise NotImplementedError("scale_vectors is not supported with MVUtensils.")

def set_vector(self, vector: vs.VideoNode, direction: MVDirection, delta: int) -> None:
    """
    Store a motion vector.

    Args:
        vector: Motion vector clip to store.
        direction: Direction of the motion vector (forward or backward).
        delta: Frame distance for the motion vector.
    """

    self[direction][delta] = vector

def show_vector(
    self,
    clip: vs.VideoNode,
    direction: Literal[MVDirection.FORWARD, MVDirection.BACKWARD] = MVDirection.FORWARD,
    delta: int = 1,
    scenechange: bool | None = None,
) -> vs.VideoNode:
    """
    Draws generated vectors onto a clip.

    Args:
        clip: The clip to overlay the motion vectors on.
        direction: Motion vector direction to use.
        delta: Motion vector delta to use.
        scenechange: Skips drawing vectors if frame props indicate they are from a different scene than the current
            frame of the clip.

    Returns:
        Clip with motion vectors overlaid.
    """

    raise NotImplementedError("show_vector is not supported with MVUtensils.")