MVUtensils

MVUtensils (namespace mvu) is a large refactoring and cleanup of the original VapourSynth mvtools port. It keeps the same overall workflow (build a super clip, estimate motion vectors with Analyse, then feed those vectors to filters like Degrain or Flow) but fixes a number of long-standing bugs, is faster, and adds full high-bit-depth and float support.

Goals

• Fix long-standing correctness bugs — most notably the right/bottom border not being processed.
• Be faster through more cache-friendly algorithms and wider SIMD (SSE2/AVX2/AVX-512 where it helps).
• Greatly reduce memory usage in Super, Analyse, Degrain and the Flow* filters.
• Full float (32-bit) support in every filter except the Depan* family.
• A smaller, more consistent API: arrays instead of cryptic per-direction arguments, and consistent frame-property propagation.

Notes

• Supported pixel formats are GRAY and YUV at 8–16 bit integer or 32 bit float. The bit depth and subsampling are taken from the input/super clip; masks derive their format from the vector clip.
• A vector clip stores block geometry and per-block SAD, never pixels, so it does not have to be analysed at the same bit depth as the clip it is later applied to. Analysing an 8-bit copy and using the result on the 16-bit or float original is a supported way to trade motion precision for analysis speed. Resolution, subsampling, pel and the super's padding must still match. Vectors analysed with chroma=False are the exception to the subsampling rule (e.g. analysed on a GRAY copy and applied to 4:2:0), as long as their overlap is divisible by the clip's subsampling, even if only luma is processed. SAD-derived arguments (thsad, thscd1) are interpreted against the depth the vectors were analysed at, so they keep their documented 8-bit 8×8 meaning either way. Recalculate is the one exception and still requires equal bit depths.
• Every frame of a super or vector clip must be made with the same arguments, and the vector clips passed to one filter together must match each other, including the chroma setting they were analysed with. Splicing clips made with different settings is not supported: filters stop with an error instead.
• The attached frame properties use the prefix MVUtensils by default. Every function accepts a prefix argument to change it, which lets two independent MVUtensils graphs coexist on one clip.
• Motion vectors are stored as frame properties: <prefix>AnalysisVectors (an int array where the low 32 bits hold x and the high 32 bits hold y) and <prefix>AnalysisSAD (the per-block SAD).
• On x86-64 the plugin is built for several instruction-set levels (baseline, AVX2 and znver4) and the matching build is loaded for the running CPU. Most of the SIMD gain comes from that choice — the Degrain kernels in particular are plain auto-vectorized C, so their width is whatever the loaded build was compiled for. A few hand-written kernels additionally pick a wider variant at runtime.

Porting from MVTools

MVUtensils is API-compatible in spirit but not verbatim. The main differences:

A typical denoise, before and after:

# MVTools
super  = core.mv.Super(clip, pel=2)
mvbw = core.mv.Analyse(super, isb=True,  delta=1)
mvfw = core.mv.Analyse(super, isb=False, delta=1)
out  = core.mv.Degrain1(clip, super, mvbw, mvfw)

# MVUtensils
super  = core.mvu.Super(clip, blksize=8, overlap=4, pel=2)  # blksize/overlap mandatory
mvbw = core.mvu.Analyse(super, delta=1)    # positive delta = backward
mvfw = core.mvu.Analyse(super, delta=-1)   # negative delta = forward (was isb=False)
out  = core.mvu.Degrain(clip, super, [mvbw, mvfw])  # vectors passed as a list

Table of Contents

• Quick start
• Common parameters
• Super
• Analyse
• AnalyseMany
• Recalculate
• Degrain
• Compensate
• Flow
• FlowInter
• FlowFPS
• FlowBlur
• VectorLengthMask / SADMask / OcclusionMask
• SCDetection
• Depan functions
  • DepanEstimate
  • DepanAnalyse
  • DepanStabilise
  • DepanCompensate

Quick start

The motion vector estimators (Analyse, AnalyseMany, Recalculate) consume a super clip and emit a vector clip; the consumers (Degrain, Compensate, Flow*, masks) take the super and the vector clip(s). AnalyseMany is the easy way to produce the list of forward/backward vectors that Degrain, FlowInter, FlowFPS and FlowBlur expect.

# Temporal denoise (radius 3 = 6 vector clips)
super = core.mvu.Super(clip, blksize=8, overlap=4)
out = core.mvu.Degrain(clip, super, core.mvu.AnalyseMany(super, radius=3))

# Motion-interpolated frame doubling
super = core.mvu.Super(clip, blksize=8, overlap=4)
out = core.mvu.FlowFPS(clip, super, core.mvu.AnalyseMany(super), num=clip.fps_num*2, den=clip.fps_den)

Only Analyse uses the full hierarchical pyramid (Super(..., onelevel=False), the default). For Recalculate and every consumer filter a single level is enough, so build their super with onelevel=True to save time and memory if it's not also used with Analyse.

Common parameters

prefix is accepted by every function; thscd1/thscd2 are accepted by the consumer filters (Compensate, Degrain, Flow, FlowInter, FlowFPS, FlowBlur, the mask functions and SCDetection). They behave identically everywhere and, to avoid repetition, are listed here once and omitted from the per-function tables below.

Porting: thscd2 is now a 0–100 float percentage of changed blocks instead of the old 0–256 integer count. The default went from 130 (≈51% of 256) to the equivalent 51; multiply an old value by 100/256 to convert. An out-of-range value (such as the old 130) is now rejected rather than silently disabling scene detection.

Validation: numeric arguments are checked when the filter is created — values outside the range shown here, and non-finite ones (nan/inf), are rejected with an error instead of silently producing wrong output. Degrain's limit is the deliberate exception: there inf/nan disables limiting.

Super

Prepares a clip for motion estimation: it pads the frame, optionally generates sub-pixel (pel) planes, and builds the hierarchical pyramid used by Analyse.

core.mvu.Super(vnode clip, int[] blksize, int[] overlap[, int[] pad=[16, 16], int pel=2, int sharp=2, int rfilter=1, bint onelevel=False, vnode pelclip=None, str prefix="MVUtensils"])

Porting: blksize/overlap were optional in mvtools and are now mandatory because the super clip pads itself to make edge blocks valid. hpad/vpad became pad=[h, v], and levels became the boolean onelevel.

Analyse

Estimates a field of motion vectors for one temporal direction/distance.

core.mvu.Analyse(vnode super[, int[] blksize=<from super>, int[] overlap=<from super>, int levels=0, int search=2, int searchparam=2, int pelsearch=<pel>, int mvlambda=1000, bint chroma=True, int delta=1, int lsad=400, int plevel=1, bint globalmv=True, int pnew=25, int pzero=<pnew>, int pglobal=0, int badsad=10000, int badrange=24, bint meander=True, int trymany=0, bint satd=False, str prefix="MVUtensils"])

Motion-coherence tuning: mvlambda, lsad, plevel

For every candidate vector Analyse minimises a combined cost rather than the block-matching error (SAD) alone:

cost(v) = mvlambda · |v − predictor|²  +  SAD(v)

where predictor is the vector predicted from already-processed neighbours (their median). The first term is a smoothness penalty that pulls each block toward its neighbours; the second is the photometric match. The three parameters shape that trade-off:

• mvlambda sets how hard coherence is enforced. High values produce smooth, physically plausible "true motion" fields — what Flow* interpolation wants — while mvlambda=0 ignores coherence and returns the lowest-SAD vector for every block, giving the smallest residual but a noisier field (often preferable for Degrain). It is the master switch: the other two only matter when it is non-zero. mvlambda is given in units of an 8×8 block — it is multiplied internally by blksizeh·blksizev/64 so a value tuned at one block size carries over to another (the same normalisation lsad and badsad use) — and is also rescaled for bit depth, pel and pyramid level so a given value behaves the same across formats.

• lsad makes the penalty adaptive to local match quality. Per block the effective mvlambda is multiplied by roughly (lsad / (lsad + blockSAD/2))², where blockSAD is an estimate of how well the neighbourhood is matching. Where a block already matches well (blockSAD ≪ lsad) the full penalty applies and coherence is enforced; where it matches badly (blockSAD ≫ lsad — e.g. occlusions, newly revealed detail) the penalty rolls off quadratically so the search is free to find the genuinely best vector instead of over-trusting a bad predictor. lsad is the SAD level at which that roll-off sets in: raise it to keep enforcing coherence even on hard blocks, lower it to surrender sooner. Because it only ever scales mvlambda, lsad does nothing when mvlambda=0.

• plevel controls how mvlambda grows toward the coarse pyramid levels, where each vector covers more pixels and benefits from extra smoothing.

Porting: isb is gone — direction is now the sign of delta (negative = forward). dct became the boolean satd (dct=0→satd=False, dct=5→satd=True). search modes lost the old 0 and 1, so subtract 2 from your old value (pelsearch is a radius and stays as it was). lambda→mvlambda, global→globalmv. trymany is now a 0–2 int instead of a bool — the old False/True map to 0/1, and the new 2 also tries multiple candidates on the finest level. fields/tff were removed: process SeparateFields output as is, vectors between fields of opposite parity already contain the half-line offset. The truemotion preset was removed in favour of fixed defaults: mvlambda=1000 (per 8×8 block, scaled by block area), lsad=400, plevel=1, globalmv=True, pnew=25. These are mostly the old truemotion=True values, except lsad (now 400, the old truemotion=False value — it was 1200 under truemotion=True) and pnew (now 25, midway between the old 50 / 0). The search_coarse and divide arguments were removed.

AnalyseMany

Convenience wrapper that produces the whole list of vector clips Degrain, FlowInter, FlowFPS and FlowBlur expect, in the right order. Takes every Analyse argument plus radius.

core.mvu.AnalyseMany(vnode super[, <all Analyse args>, int delta=1, int radius=1, str prefix="MVUtensils"])

With delta=1, radius=2 the result is [Analyse(delta=1), Analyse(delta=-1), Analyse(delta=2), Analyse(delta=-2)].

vectors = core.mvu.AnalyseMany(super, radius=3)   # 6 clips, ready for Degrain(..., radius 3)

Recalculate

Re-estimates an existing vector field at (typically) a finer block size, refining the vectors you already have instead of searching from scratch. Pair it with a halved blksize/overlap.

core.mvu.Recalculate(vnode super, vnode[] vectors[, int thsad=200, bint smooth=True, int[] blksize=<from super>, int search=2, int searchparam=2, int mvlambda=1000, bint chroma=True, int pnew=25, int[] overlap=<from super>, bint meander=True, bint satd=False, str prefix="MVUtensils"])

vectors takes a single vector clip or a whole list, and the result is the list of refined clips in the same order so an entire AnalyseMany set can be refined in one call:

super = core.mvu.Super(clip, blksize=8, overlap=4)
vectors = core.mvu.AnalyseMany(super, radius=2)                       # [bw1, fw1, bw2, fw2]
vectors = core.mvu.Recalculate(super, vectors, blksize=4, overlap=2)  # refine all at half block size
out = core.mvu.Degrain(clip, super, vectors)

search picks the algorithm as in Analyse, but since Recalculate works on a single level, searchparam is directly that algorithm's radius, in sub-pixel units (the role pelsearch plays in Analyse). Other parameters (mvlambda, chroma, pnew, meander, satd) behave exactly as in Analyse.

Recalculate deliberately has no lsad (nor plevel, globalmv, pzero, pglobal, badsad/badrange or trymany). It is not a from-scratch hierarchical search: it works on a single level, takes each existing vector as the sole predictor, and only re-searches a block when that predictor's SAD exceeds thsad. So thsad already does what lsad does in Analyse — decide where the current motion is too poor to keep — making a separate adaptive-mvlambda knee redundant, and the multi-level / multi-predictor machinery those other penalties tune simply isn't present here. mvlambda is still honoured: it biases each refined vector to stay near the one it started from.

Porting: Recalculate takes a list of vector clips (and returns a list), so a whole AnalyseMany set is refined in one call instead of recalculating each clip separately. It will also raise an error if the chosen blksize/overlap can't cover the whole frame (unlike Super, which pads). Halving blksize+overlap and reusing the existing super usually works, unusual splits may need a new super clip. fields/tff were removed; they never changed its vectors.

Recalculate and bit depth

Every other filter that takes a vector clip only reads it, so the vectors may come from an analysis at a different bit depth (see Notes). Recalculate is different because it writes vectors: it keeps the blocks whose SAD is already below thsad and replaces the rest, and the replacements get SADs measured against the super it was handed. Allowing a mismatch would therefore produce a single vector clip whose blocks carry SADs on two different scales, silently breaking every thsad/thscd1 comparison downstream. So Recalculate requires the super and the vectors to share a bit depth.

If you want to analyse cheaply at 8-bit and refine, do both steps at 8-bit and apply the final vectors to the deeper clip:

clip8 = core.resize.Bilinear(clip, format=vs.YUV420P8)
super8 = core.mvu.Super(clip8, blksize=8, overlap=4, pel=2)
vectors = core.mvu.AnalyseMany(super8, radius=3)
vectors = core.mvu.Recalculate(super8, vectors, blksize=4, overlap=2)

super16 = core.mvu.Super(clip, blksize=8, overlap=4, pel=2)   # clip is 16-bit
out = core.mvu.Degrain(clip, super16, vectors)                # vectors reused across depths

Degrain

Motion-compensated temporal denoiser. Averages each block with its motion-compensated counterparts from radius previous and radius following frames, weighted by how well they match.

Degrain auto-selects the radius from the number of vector clips; Degrain1…Degrain25 are explicit variants that take the same arguments. The radius may be 1–25, i.e. 2–50 vector clips.

core.mvu.Degrain(vnode clip, vnode super, vnode[] vectors[, int[] thsad=[400, 400], int[] thsad2=thsad, int[] planes=[0, 1, 2], float[] limit=[inf, inf], int thscd1=400, float thscd2=51, int[] weights=None, vnode centersuper=None, str prefix="MVUtensils"])

Porting: the per-direction mvbw*/mvfw* arguments are now the single vectors list, the thsad/thsadc pair became thsad=[luma, chroma], the thsad2/thsadc2 pair became thsad2=[luma, chroma], and limit/limitc became the float limit=[luma, chroma] (defaulting to no limit instead of 255). As in MDegrainN, thsad2 defaults to thsad. The centre frame comes from super, not clip: scripts that build super from a different clip need centersuper to match mvtools, see the centre frame.

# MVTools:    core.mv.Degrain2(clip, super, mvbw1, mvfw1, mvbw2, mvfw2, thsad=400, thsadc=300)
# MVUtensils:
v = core.mvu.AnalyseMany(super, radius=2)
out = core.mvu.Degrain(clip, super, v, thsad=[400, 300])

The centre frame

Degrain blends the current frame (the centre) with the motion compensated references. mvtools takes that centre from clip, while mvutensils takes it from super so that the partial blocks at the right and bottom edges can be denoised too (mvtools leaves them untouched). The two are the same whenever super is built from the clip being denoised, which covers QTGMC, MCTemporalDenoise, TemporalDegrain and SMDegrain with its default settings.

Scripts that deliberately build the render super from a different clip are affected: MCDegrainSharp (a soft clip is denoised with the super of a sharpened copy, so good matches pull the result towards the sharp references while the centre stays soft), SMDegrain with mfilter and MLDegrain with soft > 0. Here the centre silently becomes the super's clip. Pass a super of clip as centersuper to get mvtools' behaviour:

vectors = core.mvu.AnalyseMany(core.mvu.Super(clip, blksize=8, overlap=4), radius=2)
references = core.mvu.Super(sharpened, blksize=8, overlap=4, onelevel=True)
centre = core.mvu.Super(clip, blksize=8, overlap=4, onelevel=True)
out = core.mvu.Degrain(clip, references, vectors, centersuper=centre)

Degrain is the only filter that needs this. Compensate fills poorly matched blocks from the super's current frame in mvtools too, the Flow filters render from the super in both, and FlowInter and FlowFPS already blend from clip at scene changes.

Compensate

Builds a single motion-compensated frame: each block is copied from the reference frame at its motion vector.

core.mvu.Compensate(vnode clip, vnode super, vnode vectors[, int thsad=10000, float time=100.0, int thscd1=400, float thscd2=51, str prefix="MVUtensils"])

Porting: the scbehavior, fields and tff arguments were removed; vectors between fields of opposite parity already contain the half-line offset, which fields=True added a second time.

Flow

Pixel-accurate motion compensation: instead of copying whole blocks it warps the reference frame using a per-pixel vector field interpolated from the block vectors.

core.mvu.Flow(vnode clip, vnode super, vnode vectors[, float time=100.0, int thscd1=400, float thscd2=51, str prefix="MVUtensils"])

Porting: the mode argument was removed (only the former mode=0 remains), and so were fields and tff: vectors between fields of opposite parity already contain the half-line offset, which fields=True added a second time.

FlowInter

Interpolates a new frame between two existing frames by warping both halves of the motion field toward the requested time.

core.mvu.FlowInter(vnode clip, vnode super, vnode[] vectors[, float time=50.0, float ml=100.0, bint blend=True, int thscd1=400, float thscd2=51, str prefix="MVUtensils"])

Porting: the mvbw/mvfw arguments became vectors=[mvbw, mvfw].

FlowFPS

Motion-compensated frame-rate conversion, building each output frame with FlowInter-style warping.

core.mvu.FlowFPS(vnode clip, vnode super, vnode[] vectors[, int num=25, int den=1, bint extramask=True, float ml=100.0, bint blend=True, int thscd1=400, float thscd2=51, str prefix="MVUtensils"])

Porting: the mask integer became the boolean extramask, and mvbw/mvfw became vectors=[mvbw, mvfw].

FlowBlur

Creates motion blur by smearing each pixel along its motion vector.

core.mvu.FlowBlur(vnode clip, vnode super, vnode[] vectors[, float blur=50.0, int prec=1, int thscd1=400, float thscd2=51, str prefix="MVUtensils"])

Porting: the mvbw/mvfw arguments became vectors=[mvbw, mvfw].

VectorLengthMask / SADMask / OcclusionMask

These three functions replace the old Mask(kind=…). Each produces a full-range grayscale mask derived from a vector clip; the output bit depth/format is taken from the vector clip (float masks are clamped to 0–1).

• VectorLengthMask — brightness proportional to motion-vector magnitude (old kind=0).
• SADMask — brightness proportional to per-block SAD (old kind=1).
• OcclusionMask — brightness proportional to occlusion / divergence of the field (old kind=2).

core.mvu.VectorLengthMask(vnode vectors[, float ml=100.0, float gamma=1.0, float time=100.0, float scval=0.0, int thscd1=400, float thscd2=51, str prefix="MVUtensils"])
core.mvu.SADMask(vnode vectors[, ...same...])
core.mvu.OcclusionMask(vnode vectors[, ...same...])

Porting: Mask(kind=…) is split into the three named functions, the pointless clip argument was removed, and ysc became the float scval. Output is always a single grayscale plane rather than the original's UV trickery.

SCDetection

Marks scene-change frames (using the vector clip's SAD statistics) by setting the _SceneChangePrev/_SceneChangeNext frame properties.

core.mvu.SCDetection(vnode clip, vnode vectors[, int thscd1=400, float thscd2=51, str prefix="MVUtensils"])

Depan functions

The Depan filters deal with global (whole-frame) motion — camera pan, zoom and rotation — rather than the per-block local motion the rest of MVUtensils estimates. They are the only filters without float support, and are otherwise carried over from mvtools largely unchanged, with fixed edge handling and minor speedups. Fine-grained parameter meanings also match the mvtools MDepan* filters in the mvtools2 documentation.

They work in two stages:

1. Measure the global motion of every frame, producing a small data clip that carries the transform (dx, dy, zoom, rotation) as frame properties. Use DepanEstimate to measure it directly from the image, or DepanAnalyse to fit it from an existing MVUtensils vector clip.
2. Apply that data clip: DepanStabilise smooths the camera trajectory to remove shake (while keeping deliberate motion), and DepanCompensate shifts/zooms frames by the (optionally scaled) global motion — e.g. to undo, re-apply or align a camera move.

# Stabilise shaky footage, estimating motion using whole frame correlation
data = core.mvu.DepanEstimate(clip)
out  = core.mvu.DepanStabilise(clip, data)

# Or derive the global motion from block vectors instead
sup  = core.mvu.Super(clip, blksize=8, overlap=4)
data = core.mvu.DepanAnalyse(clip, core.mvu.Analyse(sup))
out  = core.mvu.DepanStabilise(clip, data)

DepanEstimate

Measures each frame's global motion (pan, optional zoom) directly from the image content and stores it as frame properties. Outputs a data clip for DepanStabilise/DepanCompensate.

core.mvu.DepanEstimate(vnode clip[, float trust=4.0, int winx=0, int winy=0, int wleft=-1, int wtop=-1, int dxmax=-1, int dymax=-1, float zoommax=1.0, float stab=1.0, float pixaspect=1.0, bint info=False, bint show=False, bint fields=False, bint tff=False])

DepanAnalyse

Fits a single global transform (pan, optional zoom and rotation) to the per-block motion vectors of an MVUtensils vectors clip, producing the same kind of data clip as DepanEstimate.

core.mvu.DepanAnalyse(vnode clip, vnode vectors[, vnode mask=None, bint zoom=True, bint rot=True, float pixaspect=1.0, float error=15.0, bint info=False, float wrong=10.0, float zerow=0.05, int thscd1=400, float thscd2=51, bint fields=False, bint tff=False])

DepanStabilise

Smooths the global-motion trajectory from a data clip (inertial high-pass filtering) and applies the inverse transform to remove camera shake while preserving intentional motion. Outputs the stabilised video.

core.mvu.DepanStabilise(vnode clip, vnode data[, float cutoff=1.0, float damping=0.9, float initzoom=1.0, bint addzoom=False, int prev=0, int next=0, int mirror=0, int blur=0, float dxmax=60.0, float dymax=30.0, float zoommax=1.05, float rotmax=1.0, int subpixel=2, float pixaspect=1.0, int fitlast=0, float tzoom=3.0, bint info=False, int method=0, bint fields=False])

DepanCompensate

Warps each frame by the global motion in a data clip (scaled by offset) — e.g. to compensate for or reproduce a camera move, or to align frames. Outputs the warped video.

core.mvu.DepanCompensate(vnode clip, vnode data[, float offset=0.0, int subpixel=2, float pixaspect=1.0, bint matchfields=True, int mirror=0, int blur=0, bint info=False, bint fields=False, bint tff=False])