View Single Post
Old 13th October 2014, 01:07   #37  |  Link
StainlessS
HeartlessS Usurer
 
StainlessS's Avatar
 
Join Date: Dec 2009
Location: Over the rainbow
Posts: 10,980
v1.13 Docs, part 1 of 2 (Post #1 only has v1.0 docs due to draconian D9 post size restrictions)
Code:
RoboCrop()

To Protect And Serve - by StainlessS @ Doom9:- http://forum.doom9.org/showthread.php?t=168053
Requires VS2008 CPP Runtimes.

VIDEO: Planar, YUY2, RGB (Must be Seekable ie best not DivX or XVid).
AUDIO: No change.

Plugin's for both Avisynth v2.58 and v2.6 (avs+ x86 & x64).

RoboCrop is an automatic cropping solution to crop black borders from video clips, loosely based on (but using no code from)
Autocrop by Glenn Bussell.

For the most part, you can just call it with RoboCrop(clip) and not bother with any other arguements, it is intended to be pretty
much autonomous in its decisions. You might however want to alter eg WMod/HMod if your encoder has special requirements, and
perhaps Laced if your source is likely to be fully progressive.

Borders are detected by sampling at Samples frames, at scanlines (h/v) using AverageLuma (RGB is converted to Luma Y at either TV or
PC levels, See Matrix). This sampling is done on all 4 sides of the frame.
If a scanline Average luma is below or equal to Thresh, then is considered possible black border, above considered possible image,
if Baffle [default=4] adjacent scanlines above Thresh, then it IS image.

Function RoboCrop(clip c,int "Samples"=40,Float "Thresh"=-40.0,bool "Laced"=true,int "WMod",int "HMod",int "RLBT"=15,bool "Debug"=false, \
    float "Ignore"=0.4,int "Matrix"=(c.Width>1100||c.Height>600?3:2), int "Baffle"=4, bool "ScaleAutoThreshRGB"=true,
    bool "ScaleAutoThreshYUV"=false, int "CropMode"=2,bool "Blank"=false,bool "BlankPC"=false,bool "Align"=True,bool "Show"=false, \
    String "LogFn"="",bool "LogAppend"=false, Float "ATM"=4.0,int "Start"=Undefined,Int "End"=Undefined, \
    Int "LeftAdd"=0,Int "TopAdd"=0,Int "RightAdd"=0,Int "BotAdd"=0, \
    Int "LeftSkip"=0,Int "TopSkip"=0,Int "RightSkip"=0,Int "BotSkip"=0 \
    Float "ScanPerc=49.0,String "Prefix"="ROBOCROP_" )


 Args:-

   Samples=40, Number of frames to sample from source clip c. v1.06 changed default from 32 to 40.
    As an observation, most clips have good border recogition within the 1st 2 or 3 sampled frames using the default -40.0 AUTOTHRESH
    although have noticed some dark clips that required ~8 samples (maybe more) for full recognition @ default Thresh = -40.0
    We use a default Samples=40, because we are intrinsically paranoid.
      If number of frames between frame at 5% of framecount and frame at 90% of framecount is greater than 250 and is also greater
    than Samples, will ignore the first 5% and last 10% of frames when both auto-thresholding and crop sampling to try to negate
    effects of artificial black in titles and end credits. Can override the Auto Credits skipping by setting Start and/or End frame
    of the range to sample.
      Samples = 0, will be converted to Samples = FrameCount, ie auto credits skipping disabled  and ALL FRAMES SAMPLED,
    of use for very short scenes, not for general full movie clips.
    Set eg Samples = Int(FrameCount * 2.0 / 100.0 + 0.5) to sample 2.0% of frames in clip.

   Thresh: Default= -40.0 (==DEFAULT AUTOTHRESH, any -ve (or 0.0) Thresh is AUTOTHRESH where Thresh adjustments are automatic).
    v1.06, Changed DEFAULT AUTOTHRESH from -32.0 to -40.0.
    v1.07, Changed to recognise a Thresh of either -32.0 or -40.0 as DEFAULT_AUTOTHRESH (fully automatic).

    Thresh > 0: (Explicit Threshold)
      A user supplied +ve Thresh should be at correct TV/PC levels for the the clip being worked on ie 16->235 for TV levels and
      0->255 for PC Levels (RGB, as appropriate for matrix being used).

    Thresh <= 0: (AUTOTHRESH)
      When Thresh <= 0, the clip will be sampled over Samples frames to find the minimum YPlaneMin (using Matrix if RGB) which
      we will call MINLUMA and an Explicit Threshold calculated by adding MINLUMA to abs(Thresh), after that it is processed
      as for Thresh > 0: (Explicit Threshold) as noted above, but, before adding MINLUMA, some AUTOTHRESH massaging and scaling occurs.

      Here AUTOTHRESH Thresh massaging and scaling occurs in sequence:-
      1 ) if (Thresh == DEFAULT AUTOTHRESH && ATM < abs(thresh))
              (DEFAULT AUTOTHRESH = exactly -40.0, defaulted OR user supplied, v1.07 also recognises -32.0 as DEFAULT_AUTOTHRESH):
            Let sampstart and sampend, be starting and ending frames numbers after any Auto Credits skipping and/or user set Start or End.
            Let Samples be limited to sampend-sampstart+1.
            Let SampRange (Sample Range) = SampEnd-SampStart+1.
            samples_massage =(Samples>=20)           ? 1.0 : (Samples-1)   * (1.0/(20-1))           # No massaging if Samples >= 20
            range_massage   =(SampRange >= (250*20)) ? 1.0 : (SampRange-1) * (1.0/((250*20)-1))     # No massaging if SampRange >= 5000
             Both samples_massage and range_massage will be in range 0.0 to 1.0.
             Thresh = -(((samples_massage * range_massage) * (abs(Thresh) - ATM)) + ATM)
              This adjustment to Auto Thresh is to reduce the possibility of overcropping on eg a dark low 'Samples' clip, or where
              source SampRange (ie temporal frame set) is too small to take a reliable sample from.
              Resulting massaged Thresh will range between -ATM and DEFAULT_AUTOTHRESH.
              Although massaging is intended to reduce overcropping, it could result in not cropping enough border (less disastrous),
              its a bit of a balancing act really. See also ATM.
      2 ) If RGB AND PC matrix(default) AND ScaleAutoThreshRGB==True(default) then
            Thresh= Thresh*(255.0/(235-16))
      3 ) If YUV AND ScaleAutoThreshYUV==True(default=false) then
            Thresh= Thresh*(255.0/(235-16))

      Steps 2) and 3) above, by default treat a -ve AUTOTHRESH as being @ TV Levels and so Scale RGB Thresh to PC levels but not YUV.
      If you want to supply a PC levels AUTOTHRESH Thresh for RGB, then simply set ScaleAutoThreshRGB=false to inhibit scaling.
      Note, if a TV levels Matrix is supplied for RGB, then scaling will always be inhibited.
       If your clip is YUV at PC levels and you want to use eg DEFAULT AUTOTHRESH (-40.0, which is considered to be @ TV levels),
      then set ScaleAutoThreshYUV=True to enable Thresh scaling.
       If your clip is YUV at PC levels and you want to use a PC levels AUTOTHRESH (-ve) then leave ScaleAutoThreshYUV at default false
      which does not scale Thresh.
      After any scaling, MINLUMA is then added to abs(Thresh) and processed as for +ve Explicit Threshold as noted above.
      NOTE, Above RoboCrop step 1) 'massages' DEFAULT_AUTOTHRESH (exactly -40.0 or v1.07 exactly -32.0) if low samples count or if short clip.
      Reason being to avoid overcropping when insufficient data available for reliable cropping. It is considered better to not crop enough
      or at all, than to overcrop. You can override by simply setting an explicit threshold (+ve) of eg 40.0, or setting a NON-DEFAULT auto thresh
       (-ve) eg -16.0 or -40.1, where YPlaneMin is established for the sampled frames and then abs(thresh) is added to that value which
       is then used as an explicit thresh.
      NOTE, v1.07 recognises a Thresh of either -40.0 OR -32.0 as DEFAULT_AUTOTHRESH, so user can provide either value and
      DEFAULT_AUTOTHRESH massaging will be applied for low samples count and/or low frame ranges.

   Laced:, Default=true, true for Interlaced.
          RoboCrop automatically deduces colorspace cropping restrictions and sets internal XMod and YMod,
          eg XMod and YMod would both be set to 2 for YV12, for YUY2 Xmod=2, YMod=1, etc.
          If Laced==true(default), then internal YMod is doubled so as not to destroy interlaced chroma.
          Below HMod is defaulted to internal YMod after the Laced hint is applied to YMod.
          You can set Laced=False if your source is known Progressive, if your dont then you may lose a few scanlines.

   WMod:, Default=Max(XMOD,4), Where XMOD is the natural chroma cropping restriction of the colorspace concerned, eg 2 for YV12.
       WMod MUST be a multiple of internal XMOD as described above, or it will throw an error.
         v1.06, Changed default from XMOD to Max(XMOD,4), this is for several reasons, some encoders, media players and VDubMod
       demand WMOD==4 ie width an exact multiple of 4 (some Mpeg encoders may demand WMOD=16 which you would have to set yourself).
       In addition to above, Avisynth v2.58 kicks up a fuss if any YUV colorspace clip with Width not an exact multiple of 4 is
       returned as final result clip (intermediate clips only have to comply with colorspace XMOD requirment). It is not really
       the job of any plugin to guess whether it's result will be the final return clip and so is not really for RoboCrop to
       enforce WMOD=4 for eg YV12, BUT, combined with the other reasons above, it was decided to change default WMOD to Max(XMOD,4),
       you will have to set eg WMOD=2 manually if required for eg YV12 or YUY2, or WMOD=1 for eg RGB32 if that is what you want.
       Avisynth has no problem returning eg RGB32 with an odd width, but at least one player had problems when RGB32 was XMOD=2
       about 12 months prior to writing this (now fixed). WMOD set to 4 [as Max(XMOD,4) will likely be] will be least problematic
       choice but you know what you require and can set WMOD to suit.
         Some encoders may require an WMod/HMod of eg 8 or 16, and if set thus, would crop off more or less depending upon
       which CropMode is set, if later resizing will be done, then encoder requirements can be satisfied during the resize.
       NOTE, Some players and VirtualDubMod (Helix YV12 decoder) dont like WMOD less than 4 (Vdub latest, OK, internal decoder).
       If eg VDMod shows blank frame, OR eg player halts saying eg "No combination of filters cound be found to render frame"
       then WMod needs to be a multiple of 4.
       NOTE, RT_Stats has a function RT_GetProcessName() which could be used to set WMod=4 only for specific programs eg,
          RoboCrop(WMod=(RT_GetProcessName=="VirtualDubMod.exe") ? 4 : Last.RT_ColorspaceXMod) # Where VDubMod opened Avisynth
       v1.08, limited WMod to max 16.

   HMod:, Default=The natural chroma cropping restriction of the colorspace concerned, BUT, doubled if laced=true.
    HMod MUST be a multiple of internal YMod as described under Laced above, or it will throw an error. If eg colorspace is
      YV12 then YMod would be set to 2, and if Laced, then YMod would be doubled to 4, so HMod MUST be a multiple of 4.
    v1.08, limited HMod to max 16.

    RLBT:=15=All Borders, Bitflags of borders to detect, 15 ($0F) crops all four. Each letter in the name 'RLBT' represents an edge and bit position
      starting with 'R' in bit 3 representing the value 8 (2^3=8). 'L' = bit 2=4 (2^2=4), 'B' = bit 1=2 (2^1=2), 'T' = bit 0=1 (2^0=1).
      To calculate the RLBT bitflags, for 'R'(Right) add 8, for 'L'(Left) add 4, for 'B'(Bottom) add 2, and for 'T'(Top) add 1.
      Add all of the bit flags together 8+4+2+1 (=15) crops all four edges, 8+4 crops only Right & Left, and 2+1 crops only Bottom & Top.
      RLBT affects border detection.
      User Skips eg LeftSkip are applied irrespective of what RLBT is set to.
      User adjustments eg LeftAdd are applied irrespective of what RLBT is set to.

    DEBUG:=False=No Debug. Set True for debugging info, need DebugView: http://technet.microsoft.com/en-gb/sysinternals/bb545027
      The debug info output shows eg range limiting of Samples and sample info and resultant auto set Thresh. You are encouraged
      to use debug to see the eg the auto Thresh massaging in action, it may help to understand usage of the plugin. MS DebugView
      can also be used to view output from other plugins and programs that can also be useful.

    Ignore:=0.4, Percentage of darkest pixels to ignore during AutoThresh scan to detect minimum luma pixel of all sampled frames.
     (ignores a few extreme pixel values ie noise, as for Threshold arg in YPlaneMin).
     v1.05, changed default from 0.2% to 0.4%.

    Matrix:, RGB ONLY. For conversion of RGB to YUV-Y, 0 = Rec601, 1 = Rec709, 2 = PC601, 3 = PC709
      Default for RGB is:- If clip Width > 1100 OR clip Height > 600 Then 3(PC709) , else 2(PC601) : YUV not used
      The defaults are for PC601 & PC709 range 0-255.
      So as to not require different AutoThresh for RGB, if clip c is RGB AND matrix is PC Levels AND Thresh < 0.0 and ScaleAutoThreshRGB=true,
      then Thresh will be scaled to RGB full range ie Thresh = Thresh * (255.0/(235.0-16.0)) ONLY when AutoThresh (ie Thresh < 0.0,
      YPlaneMin relative).
      When +ve Thresh is explicitly supplied (Thresh > 0.0) it is not scaled and assumed to be already correct range TV or PC levels.
__________________
I sometimes post sober.
StainlessS@MediaFire ::: AND/OR ::: StainlessS@SendSpace

"Some infinities are bigger than other infinities", but how many of them are infinitely bigger ???

Last edited by StainlessS; 7th February 2020 at 06:06. Reason: Update
StainlessS is offline   Reply With Quote