rstdoc: AddBorders, LetterBox new options

Author: pinterf

distrib/docs/english/source/avisynthdoc/corefilters/addborders.rst

@@ -7,6 +7,7 @@ Add black or colored borders, increasing frame size. This has several common use
 * Adjust the `aspect ratio`_ (make a 4:3 clip into 16:9 without stretching)
 * :doc:`Splice <splice>` a smaller resolution clip to a larger one without resizing
 * Together with :doc:`Crop <crop>`, shift a clip horizontally or vertically – see below.
+* Optionally filters the transient areas. (3.7.4-)
 
 See also: :doc:`letterbox`, which adds borders without changing frame size.
 
@@ -16,7 +17,8 @@ Syntax and Parameters
 
 ::
 
-    AddBorders (clip clip, int left, int top, int right, int bottom, int "color", int "color_yuv")
+    AddBorders (clip clip, int left, int top, int right, int bottom, int "color", int "color_yuv",
+                string "resample", float "param1", float "param2", float "param3", int "r" )
 
 .. describe:: clip
 
@@ -48,11 +50,82 @@ Syntax and Parameters
 
 .. describe:: color_yuv
 
-    Specifies the border color using YUV values. Input clip must be YUV;
-    otherwise an error is raised. See the :ref:`YUV colors <yuv-colors>` for
-    more information.
-
-
+    | Specifies the border color using YUV values. Input clip must be YUV;
+      otherwise an error is raised.
+    | Similar to ``color_yuv`` in :doc:`BlankClip <blankclip>` 
+
+.. describe:: resample
+
+    string  resample = "gauss"
+
+    When `r` radius is not zero, then determines which resampler is used in the transient filtering. 
+    All AviSynth :doc:`resizers <resize>` are allowed:
+    ("point", "bilinear", "bicubic", "lanczos", "lanczos4", "blackman", "spline16", "spline36", "spline64", 
+    "gauss" and "sinc", "sinpow", "sinclin2" and "userdefined2"). 
+    
+    Default is "gauss". 
+
+.. describe:: param1, param2, param3
+
+    These 'float' type parameters can be the additional parameters for the
+    resampler. Some resizer algorithms would need and can be fine tuned with up to 3 parameters.
+    Their default values depend on the selected chromaresample resizer kernel.
+    
+    default (when "gauss"): 
+    
+    * param1 (p), param2(b), param3(s): p=10, b=2.71828182, s=0
+    
+    for other resizer algoritms see  in :doc:`resizers <resize>`. 
+    
+.. describe:: r
+    
+    int  r = 0
+
+    The radius of the transient treatment in pixels. The value is meant as +/- around the border line.
+
+    When `r` radius is not zero, transient filtering occurs.
+    Even ``r=1`` is giving sufficient protection for some next processing stages.
+    
+    Why: by filtering the transient areas (boundary of the new borders), we can prevent 
+    artifacts e.g. ringing after a subsequent upscale.
+    
+    This is how it works:
+    
+    Eight crops are taken from around the transient areas: 
+    
+    - left and right rectangles, which cover +/- 10 (but at least ``r``) pixels 
+      horizontally around the new border line.
+    - top and bottom rectangles, which cover +/- 10 (but at least ``r``) pixels 
+      vertically around the new border line.
+    - four corners, top left, top right, bottom left, bottom right, dimension rules
+      as seen above.
+    
+    These eight rectangles are "resized", using the given resizer in convolution mode.
+    No dimension is changed, just we'll get a blurred area.
+    
+    Since 3.7.4 resizers can accept a ``force`` parameter, so we use it. 
+    
+    - left and right parts need only horizontal treatment.
+    - top and bottom parts need only vertical treatment.
+    - corners get both H and V processing.
+    
+    Then, from this larger area only a central ``r`` (radius)-wide rectangle is copied over the transient area.
+    
+    The left and right side will be overwritten by a ``r * original_height`` sized part.
+    At the top and bottom an ``original_width * r`` sized rectangle will be copied back.
+    And a ``r * r`` rectangle is copied over the corners.
+    
+    The exact dimensions can be a bit different, e.g. if ``r`` is larger than the actually added left border.
+    Then the radius is reduced accordingly.
+    
+    The ``r`` radius is automatically adjusted with the video format subsampling requirements.
+    AddBorders won't give error if e.g. for a YV12 ``r=1`` is given: due to the chroma subampling it will be 
+    automatically promoted to 2.
+    
+    Other notes:
+    
+    This copy-paste of the up-to eight area is using a new :doc:`MultiOverlay <multioverlay>` filter.
+    
 Examples
 --------
 
@@ -86,13 +159,75 @@ Examples
     on color format.
   * You can shift in sub-pixel increments with :doc:`Resize <resize>`.
 
+* AddBorders with filtering
+
+  ::
+
+    # Add 20 black pixels around the clip, filters (blurs) 1 pixel with the default "gauss" method
+    AddBorders(20, 20, 20, 20, r=1)
+
+* AddBorders filtering test script
+  ::
+  
+    Function AddBordersHF(clip c, int left, int right, int flt_rad)
+    {
+      unflt=AddBorders(c, left, 0, right, 0)
+      flt=GaussResize(unflt, unflt.width, unflt.height, p=10, b=2.71828, s=0, force=1)
+      uf_internal=Crop(c, flt_rad, 0, c.width-flt_rad*2, c.height)
+      return Overlay(flt, uf_internal, x=left+flt_rad, y=0)
+    }
+
+    Function AddBordersVF(clip c, int top, int bottom, int flt_rad)
+    {
+      unflt=AddBorders(c, 0, top, 0, bottom)
+      flt=GaussResize(unflt, unflt.width, unflt.height, p=10, b=2.71828, s=0, force=2)
+      uf_internal=Crop(c, 0, flt_rad, 0, c.height - flt_rad*2)
+      return Overlay(flt, uf_internal, x=0, y=top+flt_rad)
+    }
+
+    Function Diff(clip src1, clip src2)
+    {
+      return Subtract(src1.ConvertBits(8),src2.ConvertBits(8)).Levels(120, 1, 255-120, 0, 255, coring=false)
+    }
+
+    ColorBarsHD(2000,2000)
+    UserDefined2Resize(width/10, height/10)
+
+    # filtering area, means +/- around the border boundaries
+    r1=2
+    r2=2
+
+    left=20
+    top=20
+    right=20
+    bottom=20
+
+    std=AddBorders(left, top, right, bottom)
+    a=last
+    a=AddBordersHF(a, left, right, r1)
+    a=AddBordersVF(a, top, bottom, r1).SubTitle("Scriptbased", align=5)
+
+    b=last
+    b=AddBorders(b, left, top, right, bottom, param1=10, param2=2.71828, param3=0, r=r2).SubTitle("AVS 3.7.4", align=5)
+
+    d1 = Diff(a,b)
+    d2 = Diff(std,a)
+    d3 = Diff(std,b)
+
+    StackHorizontal(StackVertical(std, a, b), Stackvertical(d1, d2, d3))
+
+    LanczosResize(width*4, height*2, taps=16)
+
+
 
 Changelog
 ----------
 
 +-----------------+------------------------------------------------------------------+
 | Version         | Changes                                                          |
 +=================+==================================================================+
+| 3.7.4           | Add filtering. resample, param1, param2, param3, r parameters    |
++-----------------+------------------------------------------------------------------+
 | AviSynth+ 3.6.2 | Fix: AddBorders did not pass frame properties                    |
 +-----------------+------------------------------------------------------------------+
 | AviSynth+ 3.5.0 | New ``color_yuv`` parameter like in BlankClip                    |

distrib/docs/english/source/avisynthdoc/corefilters/letterbox.rst

@@ -10,13 +10,14 @@ Fills the top and bottom *rows* of each frame, and optionally the left and right
 * Black out the video noise at the bottom of the frame in `VHS`_ tape sources.
 * Black out overscan areas in `VCD`_ or `SVCD`_ sources.
 * Create a quick rectangular mask for other filters – a so-called "`garbage matte`_". 
+* Optionally filters the transient areas. (3.7.4-)
 
 See also: :doc:`AddBorders <addborders>`, which increases frame size. 
 **Letterbox** does not change frame size.
 
-The functionality of **Letterbox** can be duplicated with a combination of 
+Actually, the functionality of **Letterbox** is performed with a combination of 
 :doc:`Crop <crop>` and :doc:`AddBorders <addborders>`, but **Letterbox** is 
-faster and easier.
+easier to use.
 
 Generally, it's better to **Crop** video noise off than to black it out; many 
 older lossy compression algorithms don't deal well with solid-color borders, 
@@ -30,7 +31,8 @@ Syntax and Parameters
 
 ::
 
-    Letterbox (clip, int top, int bottom, int "x1", int "x2", int "color", int "color_yuv")
+    Letterbox (clip, int top, int bottom, int "x1", int "x2", int "color", int "color_yuv"
+               string "resample", float "param1", float "param2", float "param3", int "r" )
 
 .. describe:: clip
 
@@ -42,13 +44,19 @@ Syntax and Parameters
 
     * For YUV420 sources, top and bottom must be `mod2`_ (divisible by 2).
 
+    ``top+bottom`` must be less than the frame height, or else the first phase (Crop) would 
+    result in error with a zero-height clip.
+
 .. describe:: x1, x2
 
     Number of *left* (``x1``) and *right* (``x2``) columns to blank out.
 
     * For YUV422 and YUV420 sources, left and right must be `mod2`_ (divisible by 2).
     * For YUV411 sources, left and right must be `mod4`_ (divisible by 4).
 
+    ``x1+x2`` must be less than the frame width, or else the first phase (Crop) would 
+    result in error with a zero-width clip.
+
     Default: 0, 0
 
 .. describe:: color
@@ -68,8 +76,35 @@ Syntax and Parameters
 
 .. describe:: color_yuv
 
-    | Specifies the fill color using YUV values. Input clip must be YUV.
-    | See the :ref:`YUV colors <yuv-colors>` section for more information.
+    | Specifies the color of the border using YUV values. Input clip must be YUV,
+      otherwise it does nothing. 
+    | Similar to ``color_yuv`` in :doc:`BlankClip <blankclip>` 
+
+.. describe:: resample
+
+    string  resample = "gauss"
+
+    When `r` radius is not zero, then determines which resampler is used in the transient filtering. 
+    
+    Default is "gauss". 
+    
+    For detailed description see :doc:`AddBorders <addborders>`.
+
+
+.. describe:: param1, param2, param3
+
+    These 'float' type parameters can be the additional parameters for the
+    resampler. 
+
+    For detailed description see :doc:`AddBorders <addborders>`.
+
+.. describe:: r
+    
+    int  r = 0
+
+    The radius of the transient treatment in pixels. The value is meant as +/- around the border line.
+    
+    For detailed description see :doc:`AddBorders <addborders>`.
 
 
 Changelog
@@ -78,6 +113,8 @@ Changelog
 +-----------------+---------------------------------------------------------------+
 | Version         | Changes                                                       |
 +=================+===============================================================+
+| 3.7.4           | Add filtering. resample, param1, param2, param3, r parameters |
++-----------------+---------------------------------------------------------------+
 | AviSynth+ 3.4.1 | Added ``color_yuv`` option.                                   |
 +-----------------+---------------------------------------------------------------+
 | AviSynth+ r2487 | Added support for RGB48/64 and all Planar RGB(A)/YUV(A) color |
@@ -88,7 +125,7 @@ Changelog
 | AviSynth 2.0.6  | Added optional left and right parameters (``x1`` and ``x2``). |
 +-----------------+---------------------------------------------------------------+
 
-$Date: 2022/02/08 11:37:04 $
+$Date: 2025/03/14 14:00:00 $
 
 .. _VHS:
     https://en.wikipedia.org/wiki/VHS

distrib/docs/english/source/avisynthdoc/corefilters/resize.rst

@@ -137,6 +137,19 @@ with nondefault settings.
   * 'param1', 'param2' and "param3" are always float. For 'taps' 'param1' is truncated to integer internally.
     When a resizer does not use one or more parameters they are simply ignored.
 
+Resizers in AddBorders and LetterBox
+------------------------------------
+
+Optionally, when a filtering radius is given, a custom resizer can be added to :doc:`AddBorders <addborders>` and
+:doc:`LetterBox <letterbox>`. In these filters the transient areas (boundary of the new borders) are filtered, 
+in order to prevent ringing e.g. in a subsequent upscale.
+
+The filters are used purely as convolution filters, no real resize happens.
+
+Everything is the same as mentioned above in ``Resizers in ConvertToXXXX`` section, except, that 
+``'gauss'`` default parameters are tunes for blurring:
+
+* p,b,s: gauss (p=10, b=2.71828182, s=0)
 
 
 Syntax and Parameters