TCombMask

From Avisynth wiki
Jump to: navigation, search
Abstract
Author tritical
Version v0.9.4
Download TCombMaskv094.zip
Category Masking
License GPLv2
Discussion Doom9 Forum


Contents

Description

TCombMask is a set of filters to create and process comb masks.

Requirements


Syntax and Parameters

TCombMask

TCombMask is a simple filter that creates a comb map that can (could) be used by other filters. It currently supports optional motion adaption, optional spatial adaption, optional luma <-> chroma linking, different thresholds for chroma and luma, and much more.

TCombMask SYNTAX:


   TCombMask(clip, int athreshL, int athreshC, int mthreshL, int mthreshC, int edgethreshL, int edgethreshC, 
             bool denoise, bool lcLinked, int map, int mtnChk, int ametric, int field, int low, int high,
             bool chkPrg, int athreshLP, int athreshCP, int mthreshLP, int mthreshCP, int edgethreshLP,
             int edgethreshCP, bool denoiseP, int mtnChkP, int ametricP, bool chroma, int MI, bool debug)


TCombMask PARAMETERS:


   athreshL/athreshC - (int/int)
       
      These are the spatial (area) combing thresholds (athreshL for luma, athreshC for chroma).
      These thresholds are exactly the same as dthreshold in fielddeinterlace or the threshold 
      in smart deinterlacer.  Set these values below 0 to disable spatial adaption.  A good
      range for these values is between 5 and 10, it depends a lot on personal preference.  Lower
      values will detect more combing, but will also result in more false positives.

         Defaults =>  athreshL - 6
                      athreshC - 6


   mthreshL/mthreshC - (int/int)

      These are the motion thresholds (mthreshL for luma, mthreshC for chroma).  These set how
      much a pixel's value can change from one frame to another and still be considered static.  
      Set these values below 0 (or better yet, set mtnChk to 0) to disable motion adaption.  A
      good range for these values is between 4 and 8, again it depends a lot on personal
      preference.

         Defaults =>  mthreshL - 6
                      mthreshC - 6


   egdethreshL/edgethreshC - (int/int)

      These parameters are somewhat experimental.  They correspond to the following, assume
      we have the following three pixels arranged vertically on a frame.

               A
               B
               C

      edgethresh is the maximum abs() difference between pixels A and C.  So if the difference
      between pixels A and C is greater then edgethresh it is considered to be detail and not
      combing.  So set this value to greater then 255 to effectively disable this parameter.
      Note:  this can tend to leave a lot of artifacts around moving edges.

        Default =>  300  (disabled)


   denoise - (bool)
 
      Enables denoising of the comb map.  This denoising routine is pretty weak and simply 
      removes pixels that were detected as combed but that have no nieghbor pixels that were.
      It is quite useful, however, and its use is recommended.

        Default => true


   lcLinked - (bool)
 
      This enables linking between the three planes (Y, U, V).  If any part of one plane is
      detected as combed, the spatially corresponding parts of the other two planes will also
      be marked as combed.  (*NOTE:  Each plane is processed independently, so unless this option
      is turned on no one plane effects any other plane.)

        Default => false


   map - (int)

      Sets the type of output.  Set to 0 to get a straight low and high (binary mask) output map, i.e. 
      pixels that are detected as combed will be set to the value of the high parameter and those that 
      are not will be set to the value of the low parameter.  Set this to 1 to have the pixels that are 
      determined to be combed be set to the value of the high parameter on the original source frame... 
      meaning pixels that aren't detected as combed will simply be the original source pixels.
  
         0 - regular binary mask
         1 - mark combed pixels on original source frame

        Default => 0


   mtnChk - (int)

      Sets the type of motion check used.  The middle options aren't really too useful but
      are there for playing around with ;)  Set this to 0 to disable motion adaption.  If
      this is set to 0, then the mthreshL/mthreshC parameters become meaningless.

         0 - no motion check is performed
         1 - backwards only motion check (previous to current)
         2 - forwards only motion check (current to next)
         3 - bidirectional motion check (previous to current and current to next)

        Default => 3


   ametric - (int)
        
      Sets the type of spatial (area) combing metric used.  If you have disabled spatial 
      adaption then changing this wont effect anything.  As you could probably guess,
      metric 1 is slower to compute then metric 0, but more noise resilient. At the same time
      though Metric 1 is less sensitive to combing then Metric 0 as well as the other 2 metrics,
      thus you may need lower athreshL and athreshC settings then you do with the other metrics.
      Metric 1 is recommended, but each metric has its own good and bad points...  Metrics 0 and 1
      actually incorporate metric 2 with a value of 0, to check that values are off in the 
      same direction before applying the actual 3 or 5 point metrics.  Metric 3 is probably the most
      noise resilient, but will also leave the most residual combing.  Metrics 0 and 2 are the most
      sensitive to combing at specific athreshL and athreshC settings and will leave the least 
      residual combing.  If your source is pure interlaced video you may want to simply disable
      spatial adaption by setting athreshL and athreshC below zero so that any moving pixels are
      counted as combed.

         0 - 3 point metric (simulates a linear bob and subtract) 
         1 - 5 point metric (simulates a linear bob + blur and subtract)
         2 - Multiplication metric =  (a-b)*(c-b) > athresh
         3 - Subtraction metric =  ((a-b) < -athresh && (c-b) < -athresh) || ((a-b) > athresh && (c-b) > athresh)

        Default => 1


   field - (int)

      Sets whether or not every pixel in the frame is checked for combing or only those pixels 
      in the top field or the bottom field.  Useful for building masked deinterlacers that use
      sharp deinterlacering methods where you only interpolate pixels for one field.

         0 - every pixel
         1 - bottom field only
         2 - top field only
 
        Default => 0


   low - (int)

      Value that pixels not detected as combed will be set to.

        Default => 0  (must be in the range 0 - 255)


   high - (int)

      Value that pixels detected as combed will be set to.

        Default => 255  (must be in the range 0 - 255)
   

   chkPrg - (bool)

      If this is enabled TCombMask will first create a combmask using the P versions of the
      mthresh, athresh, edgethresh, denoise, mtnChk, and ametric parameters.  It will then
      check if the frame is combed using the IsCombedT() function.  If the frame is determined
      to be combed TCombMask will output a comb map created using the regular mthresh, athresh,
      edgethresh, denoise, mtnChk, and ametric parameters.  If the frame is determined not to
      be combed a blank mask (as if no pixels were detected as combed) will be output.

        Default => false



     --****   The Following Parameters are only used in conjunction with the chkPrg option  ****--


   athreshLP/athreshCP - (int/int)
       
      Same as athreshL and athreshC, but used to create the initial comb mask that is checked
      for combing if chkPrg is enabled.

         Defaults =>  athreshLP - 14
                      athreshCP - 14


   mthreshLP/mthreshCP - (int/int)

      Same as mthreshL and mthreshC, but used to create the initial comb mask that is checked
      for combing if chkPrg is enabled.

         Defualts =>  mthreshLP - 9
                      mthreshCP - 9


   edgethreshLP/edgethreshCP - (int/int)

      Same as edgethreshL and edgethreshC, but used to create the initial comb mask that is
      checked for combing if chkPrg is enabled.

         Defaults =>  300  (disabled)


   denoiseP - (bool)

      Same as denoise, but used to create the initial comb mask that is checked for combing 
      if chkPrg is enabled.

         Default => true


   mtnChkP - (int)

      Same as mtnChk, but used to create the initial comb mask that is checked for combing 
      if chkPrg is enabled.

         Default => 3


   ametricP - (int)
	
      Same as ametric, but used to create the initial comb mask that is checked for combing 
      if chkPrg is enabled.

         Default =>  1


   chroma - (bool)

      Sets whether or not chroma information is included in the combed frame decision if chkPrg
      is enabled.

         Default => false


   MI - (int)

      This sets how many pixels must be detected as combed inside any 4x8 block on the
      frame for the frame to be considered combed.  For reference, this parameter is set to 15 
      for the IsCombed() function built into Donald Graft's decomb package.  Also, since it is a 
      4x8 window, setting MI to over 31 means no frame will ever be detected as combed and setting
      MI to below 0 means every frame will be detected as combed.

         Default => 15


   debug - (bool)
 
      Will cause the frame decision (combed or not combed) to be output for each frame via
      OutputDebugString().  A program called DebugView is available to view this output.

         Default => false



IsCombedT

TCombMask also includes a conditional function named IsCombedT() that can be used with ConditionalFilter. It runs a fixed window over the generated comb map and if enough pixels in one area are detected as combed then the frame is declared combed. It is basically the same exact thing as IsCombed() in Donald Graft's Decomb package, except that it uses the comb mask generated by TCombMask and makes one variable user adjustable that is not adjustable in IsCombed().

IsCombedT SYNTAX:

   IsCombedT(clip, int athreshL, int athreshC, int mthreshL, int mthreshC, int edgethreshL, int edgethreshC, 
             bool denoise, bool chroma, int mtnChk, int ametric, int MI, bool debug)


IsCombedT PARAMETERS:


   athreshL/athreshC - (int/int)
       
      Same as in TCombMask and same defaults... read the description of these parameters in
      the TCombMask description above for more info.


   mthreshL/mthreshC - (int/int)

      Same as in TCombMask and same defaults... read the description of these parameters in
      the TCombMask description above for more info.


   edgethreshL/edgethreshC - (int/int)

      Same as in TCombMask and same defaults... read the description of these parameters in
      the TCombMask description above for more info.


   denoise - (bool)
 
      Same as in TCombMask and same default... read the description of this parameter in
      the TCombMask description above for more info.


   chroma - (bool)
 
      This sets whether or not chroma combing is included in the decision as to whether
      or not a frame is combed.  If your clip suffers from y/c separation problems
      (a.k.a. rainbowing, etc..) then setting this to false will help prevent false positives.
      If your clip doesn't suffer from these problems you may get better results if this is
      enabled.

        Default => false


   mtnChk - (int)

      Same as in TCombMask and same default... read the description of this parameter in
      the TCombMask description above for more info.


   ametric - (int)
        
      Same as in TCombMask and same default... read the description of this parameter in
      the TCombMask description above for more info.


   MI - (int)

      This sets how many pixels must be detected as combed inside any 4x8 block on the
      frame for the frame to be considered combed.  To decide if a frame is combed, a fixed
      window of size 4x8 is run over the comb map and if more then MI number of pixels are
      detected as combed inside any block then the frame is considered combed.  For reference,
      this parameter is set to 15 for the IsCombed() function built into Donald Graft's decomb 
      package.  Also, since it is a 4x8 window, setting MI to over 31 means no frame will ever 
      be detected as combed and setting MI to below 0 means every frame will be detected as 
      combed.

         Default => 15


   debug - (bool)

      Will cause the frame decision for each frame (combed or not combed) to be output via
      OutputDebugString().  You can use a program called DebugView to view this output.

         Default => false



TMaskedMerge

TMaskedMerge takes three clips and an int value as parameters. Based on the mask clip and the given value, TMaskedMerge chooses pixels from the other two clips. In other words, if you input a binary mask clip (all 255's and 0's) and use a value of 0, for whatever pixels in the mask are 0 TMaskedMerge will use pixels from clip as output and for whatever pixels aren't 0 TMaskedMerge will use pixels from the other clip (clip1). This function is pretty fast, to begin with as it is a pretty simple operation and it has been MMX/SSE2 optimized.

TMaskedMerge SYNTAX:

     TMaskedMerge(clip, clip1, clip2, int value)


TMaskedMerge PARAMETERS:

     
     clip 

        The clip pixels will be taken from when pixels in the mask clip match the value of the
        value parameter.

        Default => none


     clip1

        The clip pixels will be taken from when pixels in the mask clip do not match the value of
        the value parameter.

        Default => none


     clip2
 
        The mask clip used to determine where pixels are taken from.

        Default => none


     value - (int)

        The pixel value compared against the mask clip.  (must be in the range 0-255)

        Default => 255


          Example:

             TMaskedMerge(clip, clip1, maskclip, 255)



TMaskedMerge3

TMaskedMerge3 is similiar to TMaskedMerge, but instead of only using one value to choose pixels from one of two clips, it uses two values to choose pixels from one of three clips.

TMaskedMerge3 SYNTAX:

     TMaskedMerge3(clip, clip1, clip2, clip3, int value1, int value2)


TMaskedMerge3 PARAMETERS:

     
     clip 

        The clip pixels will be taken from when pixels in the mask clip match the value of the
        value1 parameter.

        Default => none


     clip1

        The clip pixels will be taken from when pixels in the mask clip match the value of the
        value2 parameter.

        Default => none


     clip2
 
        The clip pixels will be taken from when pixels in the mask clip do not match either the
        value1 or value2 parameter.

        Default => none


     clip3
 
        The clip pixels will be taken from when pixels in the mask clip do not match either the
        value1 or value2 parameter.

        Default => none


     value1 - (int)

        The pixel value compared against the mask clip for taking pixels from source 1.  (must be in the range 0-255)

        Default => 255


     value2 - (int)

        The pixel value compared against the mask clip for taking pixels from source 2.  (must be in the range 0-255)

        Default => 128


          Example:

             TMaskedMerge3(clip, clip1, clip2, maskclip, 255, 128)



TFieldBlank

TFieldBlank sets the selected field (top or bottom) to the given value. Does both chroma and luma (probably will work other then intended for non-interlaced yv12 sources. Supports YV12 and YUY2.

TFieldBlank SYNTAX:

     TFieldBlank(clip, int field, int value)


TFieldBlank PARAMETERS:

      
     field - (int)

        Sets which field will be set to the given value.

        0 - top field
        1 - bottom field

        Default => 0


     value - (int)

        Sets the value that the pixels in the specified field will be set to.  Must be in
        the range (0-255).

         Default => 0



TMaskBlank

TMaskBlank sets all pixels in a frame (both chroma and luma) to the specified value. This is probably pretty useless, as it can be accomplished with other fuctions like BlankClip, but someone might find it useful. Supports YUY2 and YV12.

TMaskBlank SYNTAX:

     TMaskBlank(clip, int value)


TMaskBlank PARAMETERS:
         
     
     value - (int)

        Sets the value that the pixels in the specified field will be set to.  Must be in
        the range (0-255).

        Default => 0



Extra Notes

     For debugging/testing purposes all filters take the "opt" parameter to force certain
     optimizations.  It is an int. Do not select options that your cpu does not support!!

       0 - no opts all C++ code only
       1 - MMX
       2 - iSSE/MMX
       3 - SSE2/iSSE/MMX
       4 - auto detect  (default)


Examples

Here is little example script of how TCombMask can be used to build a cubic deinterlacer:

mpeg2source("source.d2v")
clip1 = last.bob().selecteven()
# or  clip1 = last.blur(0,1)  for blend deinterlacing
clip2 = last.tcombmask()
tmaskedmerge(last,clip1,clip2,0)

Here is an example of how to use it as a post-processor for IVTCed material:

mpeg2source("source.d2v")
clip1 = last.bob().selecteven()   #make this selectodd() to interpolate the top field
clip2 = last.tcombmask(chkPrg=true)
tmaskedmerge(last,clip1,clip2,0)


Changelog

   05/21/2004  v0.9.4
       - Added TMaskedMerge3 function
       + fixed some __int64 variables in the assembly code not being set to the correct
            values
       + fixed TMaskedMerge only checking that each clip is either YV12 or YUY2 and
            not checking to make sure that they were also all of the same colorspace


   05/19/2004  v0.9.3
       - Added TMaskedMerge function
       - Added TFieldBlank function
       - Added TMaskBlank function
       - Some MMX/SSE2 optimizations
       - Changed some default values (MI, athreshL, athreshC, chroma)
       + Fixed the bi-Directional motion check not detecting combing
            under certain conditions (it was too strict)
       + Fixed the prev only and next only motion checks being too strict
       + Metric 1 now uses metric 0 to process the second line and height-2 line
            instead of not checking them at all
       + Some other bugfixes


   05/06/2004  v0.9.2 (not released)
       - Added debug output for IsCombedT(), and for TCombMask when chkPrg is used
       - Added chkPrg option and P version of related parameters
       - Added field option
       - Output pixel values for combed pixels and non-combed pixels are now
            user definable.  (high and low parameters)
       - Added two new area combing metrics (ametric 2-3)
       - Added edgethresh parameter for all metrics
       + Fixed some other bugs (testing is usually a good idea)


   04/18/2004  v0.9.1
       - Changed metric parameter name to ametric
       - Changed ametric 1 slightly to better simulate the desired vertical blur
       - Added conditional IsCombedT() function
       - various code and help file cleanups
       

   04/16/2004  v0.9.0
       - Initial Release


External Links

  • Doom9 Forum - Code/script wizard challenge - comb mask




Back to External Filters


Personal tools