MVTools

From Avisynth wiki
(Difference between revisions)
Jump to: navigation, search
m (1 revision)
(mvtools2)
Line 1: Line 1:
MVTools, MVTools v2
+
{{FilterCat|External_filters|Other_filters|Support_filters}}
 +
{{Filter
 +
|Manao, Fizick, Tsp, TSchniede, SEt
 +
|v2.5.11.3
 +
|[http://avisynth.org.ru/mvtools/mvtools-v2.5.11.3.zip mvtools-v2.5.11.3.zip]
 +
|Support filters
 +
|
 +
* Avisynth 2.58+
 +
* YV12
 +
* YUY2
 +
|[http://www.gnu.org/licenses/gpl-2.0.txt GPLv2]}}
 +
<br>
 +
<span style="color:red">'''Official documentation:</span> http://avisynth.org.ru/mvtools/mvtools2.html'''
 +
== About MVTools ==
 +
MVTools plugin for AviSynth 2.5 is a collection of functions for estimation and compensation of objects motion in video clips. Motion compensation may be used for strong temporal denoising, advanced framerate conversions, image restoration and other tasks.
  
The MVTools plugin for AviSynth 2.5 is a collection of functions for estimation and compensation of an objects' motion in video clips. Motion compensation may be used for strong temporal denoising, advanced framerate conversions, image restoration and other tasks.  
+
The plugin contains the motion estimation server-function MAnalyse to find the motion vectors and several motion compensation client-functions (MCompensate, MMask and others) which use these vectors.
  
It is an essential requirement of many denoising, framerate changing, and deinterlacing scripts, along with other uses. The new version 2 is also compatible with version 1 scripts, so this plugin is all you need.
+
Plugin uses block-matching method of motion estimation (similar methods are used in MPEG2, MPEG4, etc). At analysis stage plugin divides frames by small blocks and try to find for every block in current frame the most similar (matching) block in second frame (previous or next). The relative shift of these blocks is motion vector. The main measure of block similarity is sum of absolute differences (SAD) of all pixels of these two blocks compared. SAD is a value which says how good the motion estimation was.
  
If your script contains some error messages about xxx function not defined, where xxx is one of the mvtools functions listed below, then you need to load the mvtools plugin.
+
The output of MAnalyse (server) is special clip with motion vector information in some format.
  
Please see [http://avisynth.org.ru/mvtools/mvtools2.html] for more information.
+
At compensation stage the plugin client functions read the motion vectors and use them to move blocks and form motion compensated frame (or realize some other full or partial motion compensation or interpolation function). Every object (block) in this (fully) compensated frame is placed in the same position as this object in current frame. So, we may (for example) use strong temporal denoising even for quite fast moving objects without producing annoying artifacts and ghosting (object's features and edges are coincide if compensation is perfect). Plugin can create compensated neighbor frames for every current frame, and denoise it by internal function. Alternatively, you can use compensated and original frames to create interleaved clip, denoise it by any external temporal filter, and select central cleaned original frames for output (see examples).
  
MSuper (clip, int "hpad", int "vpad", int "pel", int "levels", bool "chroma", int "sharp", int "rfilter", clip "pelclip", bool "isse", bool "planar")  
+
Of course, the motion estimation and compensation is not ideal and precise. In some complex cases (video with fading, ultra-fast motion, or periodic structures) the motion estimation may be completely wrong, and compensated frame will be blocky and (or) ugly. Severe difficulty is also due to objects mutual screening (occlusion) or reverse opening. Complex Avisynth scripts with many motion compensation functions may eat huge amount of memory and result in very slow processing. It is not simple but quite advanced plugin. Use it for appropriate cases only, and try to tune its parameters. There are many discussions about motion compensation using at doom9 Avisynth forum. In particular see [http://forum.doom9.org/showthread.php?t=76041 old MVTools thread], [http://forum.doom9.org/showthread.php?t=102071 true motion thread], [http://forum.doom9.org/showthread.php?t=84770 new MVTools thread] and some other. Try to read the postings in addition to this documentation and ask for support there. If you really interested in motion estimation and compensation topics, you can easy find numerous scientific publications (use WWW search).
  
MAnalyse (clip super, int "blksize", int "blksizeV", int "levels", int "search", int "searchparam", int "pelsearch", bool "isb", int "lambda", bool "chroma", int "delta", bool "truemotion", int "lsad", int "plevel", bool "global", int "pnew", int "pzero", int "pglobal", int "overlap", int "overlapV", string "outfile", int "dct", int "divide", int "sadx264", int "badSAD", int "badrange", bool "isse", int "full", bool "meander", bool "temporal")
+
Notes: The plugin is still under development. Current version has some limitations. Only progressive YV12, YUY2 video is supported. Use color format conversion and try use (smart) bob-deinterlace for interlaced video (SeparateFields may works too with or without SelectEven/SelectOdd). Some complex scripts (MVBOB, MCBOB, TempGaussMC) use MVTools for motion compensated deinterlace.
 +
Alternatively you can try to use Motion plugin by mg262.
 +
<br>
 +
<br>
 +
== Common parameters ==
 +
<br>
 +
Filters that use motion vectors have common parameters. Those are the scene-change detection thresholds, and the isse mmx flag. They also use one or several vectors stream, which are produced by MAnalyse.
  
MCompensate (clip source, clip super, clip vectors, bool "scbehavior", float "recursion", int "thSAD", bool "fields", int "thSCD1", int "thSCD2", bool "isse", bool "planar")
+
{{Template:FuncDef2|thSCD1}} (int): threshold which decides whether a block has changed between the previous frame and the current one. When a block has changed, it means that motion estimation for it isn't relevant. It occurs for example at scene changes. So it is one of the thresholds used to tweak the scene changes detection engine. Raising it will lower the number of blocks detected as changed. It may be useful for noisy or flickered video. The threshold is compared to the SAD (Sum of Absolute Differences, a value which says how bad the motion estimation was ) value. For exactly identical blocks we have SAD=0. But real blocks are always different because of objects complex movement (zoom, rotation, deformation), discrete pixels sampling, and noise. Suppose we have two compared 8x8 blocks with every pixel different by 5. It this case SAD will be 8x8x5 = 320 (block will not detected as changed for thSCD1=400). If you use 4x4 blocks, SAD will be 320/4. If you use 16x16 blocks, SAD will be 320*4. Really this parameter is scaled internally in MVTools, and you must always use reduced to block size 8x8 value. Default is 400 (since v.1.4.1).
  
MMask (clip source, clip vectors, float "ml", float "gamma", int "kind", int "Ysc", int "thSCD1", int "thSCD2", bool "isse", bool "planar")  
+
{{Template:FuncDef2|thSCD2}} (int): threshold which sets how many blocks have to change for the frame to be considered as a scene change. It is ranged from 0 to 255, 0 meaning 0 %, 255 meaning 100 %. Default is 130 ( which means 51 % ).
  
MSCDetection (clip source, clip vectors, int "Ysc", int "thSCD1", int "thSCD2", bool "isse")  
+
{{Template:FuncDef2|isse}} (int): flag which allows to enable (if set to True) or disable (if set to False) ISSE, MMX and other CPU optimizations (for debugging). Default is True. If your processor doesn't support CPU optimizations, it will be disabled anyway ( and you won't be able to activate them ).
  
MShow (clip super, clip vectors, int "scale", int "sil", int "tol", bool "showsad", int "number", int "thSCD1", int "thSCD2", bool "isse", bool "planar")  
+
{{Template:FuncDef2|planar}} (bool): flag to use special planar color format for YUY2 clips both for input and output of function. It uses special trick for storing of frames with planar color data organization (separate Y, U, V planes in memory) in normal interleaved YUY2 frames format as a container. This way we can avoid numerous internal interleaved to planar conversions and increase speed. You can convert normal interleaved YUY2 source clip to planar format with Interleaved2planar function from RemoveGrain plugin by kassandro, and convert final result by Planar2interleaved function. This special planar YUY2 format is also supported by Removegrain plugin by Kassandro, MaskTools2 plugin by Manao and some others. This trick will not be needed in Avisynth v2.6 with native support of planar YV16 format. This parameter is ignored for YV12 clips. Note: super clip is always planar. Default is planar=false.
 
+
<br>
MDepan (clip, clip vectors, clip "mask", bool "zoom", bool "rot", float "pixaspect", float "error", bool "info", string "log", float "wrong", float "zerow", int "range", int "thSCD1", int "thSCD2", bool "isse", bool "planar")
+
<br>
 
+
== Filters ==
MFlow (clip source, clip super, clip vectors, float "time", int "mode", bool "fields", int "thSCD1", int "thSCD2", bool "isse", bool "planar")
+
{{PluginFilterTable}}
 
+
|-
MFlowInter (clip source, clip super, clip mvbw, clip mvfw, float "time", float "mL", bool "blend", int "thSCD1", int "thSCD2", bool "isse", bool "planar")
+
{{PluginFilterRow|MVTools2|MSuper|
 
+
Get source clip and prepare special "super" clip with multilevel (hierarchical scaled) frames data.
MFlowFps (clip source, clip super, clip mvbw, clip mvfw, int "num", int "den", int "mask", float "ml", bool "blend", int "thSCD1", int "thSCD2", bool "isse", bool "planar")
+
| [[YV12]], [[YUY2]]
 
+
}}
MBlockFps (clip, clip super, clip mvbw, clip mvfw, int "num", int "den", int "mode", float "thres", bool "blend", int "thSCD1", int "thSCD2", bool "isse", bool "planar")
+
{{PluginFilterRow|MVTools2|MAnalyse|
 
+
Get prepared multilevel super clip, estimate motion by block-matching method and produce special output clip with motion vectors data.
MFlowBlur (clip, clip super, clip mvbw, clip mvfw, float "blur", int "prec", int "thSCD1", int "thSCD2", bool "isse", bool "planar")  
+
| [[YV12]], [[YUY2]]
 
+
}}
MDeGrain1 (clip, clip super, clip mvbw, clip mvfw, int "thSAD", int "thSADC", int "plane", int "limit", int "thSCD1", int "thSCD2", bool "isse", bool "planar")
+
|-
 
+
{{PluginFilterRow|MVTools2|MCompensate|
MDeGrain2 (clip, clip super, clip mvbw, clip mvfw, clip mvbw2, clip mvfw2, int "thSAD", int "thSADC", int "plane", int "limit", int "thSCD1", int "thSCD2", bool "isse", bool "planar")
+
Do a full motion compensation of the frame.
 
+
| [[YV12]], [[YUY2]]
MDeGrain3 (clip, clip super, clip mvbw, clip mvfw, clip mvbw2, clip mvfw2, clip mvbw3, clip mvfw3,int "thSAD", int "thSADC", int "plane", int "limit", int "thSCD1", int "thSCD2", bool "isse", bool "planar")
+
}}
 
+
{{PluginFilterRow|MVTools2|MMask|
MRecalculate (clip super, clip vectors, int "thSAD", int "smooth", int "blksize", int "blksizeV", int "search", int "searchparam", int "lambda", bool "chroma", bool "truemotion", int "pnew", int "overlap", int "overlapV", string "outfile", int "dct", int "divide", int "sadx264", bool "isse")
+
Creates a mask clip from source clip with motion vectors data.
 
+
| [[YV12]], [[YUY2]]
{{FilterCat|Plugins|External_filters|Other_filters|Meta_filters}}
+
}}
 +
{{PluginFilterRow|MVTools2|MSCDetection|
 +
Creates scene detection mask clip from motion vectors data.
 +
| [[YV12]], [[YUY2]]
 +
}}
 +
{{PluginFilterRow|MVTools2|MShow|
 +
Shows the motion vectors on padded source by super clip opening.
 +
| [[YV12]], [[YUY2]]
 +
}}
 +
|-
 +
{{PluginFilterRow|MVTools2|MDepan|
 +
Get the motion vectors, estimate global motion and put data to output frame in special format for [[DePan]] plugin.
 +
| [[YV12]], [[YUY2]]
 +
}}
 +
|-
 +
{{PluginFilterRow|MVTools2|MFlow|
 +
Do a motion compensation of the frame not by blocks (like MCompensate), but by pixels.
 +
| [[YV12]], [[YUY2]]
 +
}}
 +
{{PluginFilterRow|MVTools2|MFlowInter|
 +
Motion interpolation function.
 +
| [[YV12]], [[YUY2]]
 +
}}
 +
{{PluginFilterRow|MVTools2|MFlowFps|
 +
Will change the frame rate (fps) of the clip. The function can be used for frame rate conversion, slow-motion effect, etc.
 +
| [[YV12]], [[YUY2]]
 +
}}
 +
{{PluginFilterRow|MVTools2|MBlockFps|
 +
The function uses block-based partial motion compensation to change the framerate (fps) of the clip.
 +
| [[YV12]], [[YUY2]]
 +
}}
 +
|-
 +
{{PluginFilterRow|MVTools2|MFlowBlur|
 +
Experimental simple motion blur function. It may be used for FILM-effect (to simulate finite shutter time)..
 +
| [[YV12]], [[YUY2]]
 +
}}
 +
{{PluginFilterRow|MVTools2|MDeGrain1|
 +
Temporal denoising with motion compensation. MDeGrain1 has a temporal radius of 1.
 +
| [[YV12]], [[YUY2]]
 +
}}
 +
{{PluginFilterRow|MVTools2|MDeGrain2|
 +
Temporal denoising with motion compensation. MDeGrain2 has a temporal radius of 2.
 +
| [[YV12]], [[YUY2]]
 +
}}
 +
{{PluginFilterRow|MVTools2|MDeGrain3|
 +
Temporal denoising with motion compensation. MDeGrain3 has a temporal radius of 3.
 +
| [[YV12]], [[YUY2]]
 +
}}
 +
{{PluginFilterRow|MVTools2|MRecalculate|
 +
Refines and recalculates motion data of previously estimated motion vectors.
 +
| [[YV12]], [[YUY2]]
 +
}}
 +
|}
 +
<br>
 +
== Changelog ==
 +
http://avisynth.org.ru/mvtools/mvtools2.html#revisions
 +
<br>
 +
<br>
 +
== Links ==
 +
*http://forum.doom9.org/showthread.php?t=84770
 +
[[Category:Plugins]]

Revision as of 14:07, 11 June 2014

Abstract
Author Manao, Fizick, Tsp, TSchniede, SEt
Version v2.5.11.3
Download mvtools-v2.5.11.3.zip
Category Support filters
Requirements
  • Avisynth 2.58+
  • YV12
  • YUY2
License GPLv2
Discussion


Official documentation: http://avisynth.org.ru/mvtools/mvtools2.html

Contents

About MVTools

MVTools plugin for AviSynth 2.5 is a collection of functions for estimation and compensation of objects motion in video clips. Motion compensation may be used for strong temporal denoising, advanced framerate conversions, image restoration and other tasks.

The plugin contains the motion estimation server-function MAnalyse to find the motion vectors and several motion compensation client-functions (MCompensate, MMask and others) which use these vectors.

Plugin uses block-matching method of motion estimation (similar methods are used in MPEG2, MPEG4, etc). At analysis stage plugin divides frames by small blocks and try to find for every block in current frame the most similar (matching) block in second frame (previous or next). The relative shift of these blocks is motion vector. The main measure of block similarity is sum of absolute differences (SAD) of all pixels of these two blocks compared. SAD is a value which says how good the motion estimation was.

The output of MAnalyse (server) is special clip with motion vector information in some format.

At compensation stage the plugin client functions read the motion vectors and use them to move blocks and form motion compensated frame (or realize some other full or partial motion compensation or interpolation function). Every object (block) in this (fully) compensated frame is placed in the same position as this object in current frame. So, we may (for example) use strong temporal denoising even for quite fast moving objects without producing annoying artifacts and ghosting (object's features and edges are coincide if compensation is perfect). Plugin can create compensated neighbor frames for every current frame, and denoise it by internal function. Alternatively, you can use compensated and original frames to create interleaved clip, denoise it by any external temporal filter, and select central cleaned original frames for output (see examples).

Of course, the motion estimation and compensation is not ideal and precise. In some complex cases (video with fading, ultra-fast motion, or periodic structures) the motion estimation may be completely wrong, and compensated frame will be blocky and (or) ugly. Severe difficulty is also due to objects mutual screening (occlusion) or reverse opening. Complex Avisynth scripts with many motion compensation functions may eat huge amount of memory and result in very slow processing. It is not simple but quite advanced plugin. Use it for appropriate cases only, and try to tune its parameters. There are many discussions about motion compensation using at doom9 Avisynth forum. In particular see old MVTools thread, true motion thread, new MVTools thread and some other. Try to read the postings in addition to this documentation and ask for support there. If you really interested in motion estimation and compensation topics, you can easy find numerous scientific publications (use WWW search).

Notes: The plugin is still under development. Current version has some limitations. Only progressive YV12, YUY2 video is supported. Use color format conversion and try use (smart) bob-deinterlace for interlaced video (SeparateFields may works too with or without SelectEven/SelectOdd). Some complex scripts (MVBOB, MCBOB, TempGaussMC) use MVTools for motion compensated deinterlace. Alternatively you can try to use Motion plugin by mg262.

Common parameters


Filters that use motion vectors have common parameters. Those are the scene-change detection thresholds, and the isse mmx flag. They also use one or several vectors stream, which are produced by MAnalyse.

thSCD1 (int): threshold which decides whether a block has changed between the previous frame and the current one. When a block has changed, it means that motion estimation for it isn't relevant. It occurs for example at scene changes. So it is one of the thresholds used to tweak the scene changes detection engine. Raising it will lower the number of blocks detected as changed. It may be useful for noisy or flickered video. The threshold is compared to the SAD (Sum of Absolute Differences, a value which says how bad the motion estimation was ) value. For exactly identical blocks we have SAD=0. But real blocks are always different because of objects complex movement (zoom, rotation, deformation), discrete pixels sampling, and noise. Suppose we have two compared 8x8 blocks with every pixel different by 5. It this case SAD will be 8x8x5 = 320 (block will not detected as changed for thSCD1=400). If you use 4x4 blocks, SAD will be 320/4. If you use 16x16 blocks, SAD will be 320*4. Really this parameter is scaled internally in MVTools, and you must always use reduced to block size 8x8 value. Default is 400 (since v.1.4.1).

thSCD2 (int): threshold which sets how many blocks have to change for the frame to be considered as a scene change. It is ranged from 0 to 255, 0 meaning 0 %, 255 meaning 100 %. Default is 130 ( which means 51 % ).

isse (int): flag which allows to enable (if set to True) or disable (if set to False) ISSE, MMX and other CPU optimizations (for debugging). Default is True. If your processor doesn't support CPU optimizations, it will be disabled anyway ( and you won't be able to activate them ).

planar (bool): flag to use special planar color format for YUY2 clips both for input and output of function. It uses special trick for storing of frames with planar color data organization (separate Y, U, V planes in memory) in normal interleaved YUY2 frames format as a container. This way we can avoid numerous internal interleaved to planar conversions and increase speed. You can convert normal interleaved YUY2 source clip to planar format with Interleaved2planar function from RemoveGrain plugin by kassandro, and convert final result by Planar2interleaved function. This special planar YUY2 format is also supported by Removegrain plugin by Kassandro, MaskTools2 plugin by Manao and some others. This trick will not be needed in Avisynth v2.6 with native support of planar YV16 format. This parameter is ignored for YV12 clips. Note: super clip is always planar. Default is planar=false.

Filters

Filter Description Color format
MSuper

Get source clip and prepare special "super" clip with multilevel (hierarchical scaled) frames data.

YV12, YUY2
MAnalyse

Get prepared multilevel super clip, estimate motion by block-matching method and produce special output clip with motion vectors data.

YV12, YUY2
MCompensate

Do a full motion compensation of the frame.

YV12, YUY2
MMask

Creates a mask clip from source clip with motion vectors data.

YV12, YUY2
MSCDetection

Creates scene detection mask clip from motion vectors data.

YV12, YUY2
MShow

Shows the motion vectors on padded source by super clip opening.

YV12, YUY2
MDepan

Get the motion vectors, estimate global motion and put data to output frame in special format for DePan plugin.

YV12, YUY2
MFlow

Do a motion compensation of the frame not by blocks (like MCompensate), but by pixels.

YV12, YUY2
MFlowInter

Motion interpolation function.

YV12, YUY2
MFlowFps

Will change the frame rate (fps) of the clip. The function can be used for frame rate conversion, slow-motion effect, etc.

YV12, YUY2
MBlockFps

The function uses block-based partial motion compensation to change the framerate (fps) of the clip.

YV12, YUY2
MFlowBlur

Experimental simple motion blur function. It may be used for FILM-effect (to simulate finite shutter time)..

YV12, YUY2
MDeGrain1

Temporal denoising with motion compensation. MDeGrain1 has a temporal radius of 1.

YV12, YUY2
MDeGrain2

Temporal denoising with motion compensation. MDeGrain2 has a temporal radius of 2.

YV12, YUY2
MDeGrain3

Temporal denoising with motion compensation. MDeGrain3 has a temporal radius of 3.

YV12, YUY2
MRecalculate

Refines and recalculates motion data of previously estimated motion vectors.

YV12, YUY2


Changelog

http://avisynth.org.ru/mvtools/mvtools2.html#revisions

Links

Personal tools