User:Raffriff42/Utils-r41 Quick Reference

AVS+ utilities

Download: Utils-r41.avsi

Some of the most useful functions (a short selection)

Deep Color Argument Scaling Functions

sc8x

• Autoscale filter arguments to high bit depth; scale an 8-bit value for target clip T.

For example, if clip C's bit depth = 10, C.sc8x(255) == 255 × 2^(10-8) == 1023.

See also, sc8s – same as sc8x but with String result, suitable for use in MaskTools expressions

## @ T - clip with target bit depth
## @ returns int for int formats, float for 32-bit float
##
function sc8x(clip T, float f)

Utility Filters

ToRGB

• Convert from anything to planar RGB[A]

Attempts YUV→RGB conversion with best possible quality;

hides the details of conversion from Interleaved to Planar.

## @ matrix   - ignored if not converting from YUV; default "Rec601"
## @ bits_out - output bit depth, one of (8|10|12|14|16); default same as source
## @ A - if supplied, becomes the alpha channel of the resulting clip;
##       overrides any existing alpha channel.
##       * if 'A' is RGBA or YUVA, the A channel is used;
##       * if 'A' YUV or Y-only,   the Y channel is used;
##       * if 'A' == "none", any existing alpha channel is removed;
##       * if 'A' == "add", a new opaque alpha channel is added;
##       * else, 'A' is ignored.
##
function ToRGB(clip C, string "matrix", int "bits_out", clip "A")

To444

• Convert from anything to YUV[A]444

Attempts RGB→YUV conversion with best possible quality;

hides the details of conversion from Interleaved to Planar.

## @ matrix   - ignored if not converting from RGB; default "Rec601"
## @ bits_out - output bit depth, one of (8|10|12|14|16); default same as source
## @ A - if supplied, becomes the alpha channel of the resulting clip;
##       overrides any existing alpha channel.
##       * if 'A' is RGBA or YUVA, the A channel is used;
##       * if 'A' YUV or Y-only,   the Y channel is used;
##       * if 'A' == "none", any existing alpha channel is removed;
##       * if 'A' == "add", a new opaque alpha channel is added;
##       * else, 'A' is ignored.
##
## Return YUV(A)444, max 16-bit (no float output)
##
function To444(clip C, string "matrix", int "bits_out", clip "A")

To16bit

• Convert from anything to best equivalent 16-bit version; no RGB↔YUV conversions

## @ A - if supplied, becomes the alpha channel of the resulting clip;
##       overrides any existing alpha channel.
##       * if 'A' is RGBA or YUVA, the A channel is used;
##       * if 'A' YUV or Y-only,   the Y channel is used;
##       * else, 'A' is ignored.
##
## Returns:
##   any RGB(A) -> RGB(A)P16
##   any 444    -> YUV(A)444P16
##   any 422    -> YUV(A)422P16
##   any 420    -> YUV(A)420P16
##   any Yxx    -> YxxP16 // no alpha  
##
function To16bit(clip C, clip "A")

To8bit

• Convert from anything to 'best' (v2.6.x compatible) equivalent 8-bit version

Automatically converts Planar RGB to RGB24/RGB32; removes any alpha channel on YUV.

## @ dither  - if true, add dither when applicable; default false
##
## Returns:
##   any RGBA -> RGB32
##   any RGB  -> RGB24
##   any 444  -> YV24
##   any 422  -> YUY2
##   any 420  -> YV12
##   any Yxx  -> Y8
##   YV411 (no change)
## (no YUVA output, so save your alpha channel elsewhere)
##
function To8bit(clip C, bool "dither")

ToVdubFM

• Make minimal color format conversion needed to view in VirtualDub FilterMod.

## @ dither - if true, reduce bit depth to 8 bit with dithering if applicable;
##            default false
##
## vdubFM does not currently (AFAIK) support all AVS+ color spaces; 
## ToVdubFM does minimally-destructive translation
## per docs, vdubFM accepts:
##      10-bit 422 (v210 interleaved)
##      16-bit 422, 444, 420 (planar)
##      16-bit RGBA
## this filter returns:
##       8-bit formats unchanged, except YV411->YV420
##      10-bit 422 (planar, not interleaved)
##      16-bit 422 (planar)
##      16-bit RGBA
##
function ToVdubFM(clip C, bool "dither")

MatchColorFormat

• Match color format of source C to template T

Useful when temporarily changing color format and to splice disparate clips together.

## @ matrix    - ignored if not converting between RGB<>YUV; default "Rec601"
## @ keepbits  - if true, retain original bit depth; 
##               else (default) force bit depth to match 'T'
## @ dither    - if true, add dither when converting to lower bit depth; default false
##
function MatchColorFormat(clip C, clip T, string "matrix", 
\                         bool "keepbits", bool "dither")

MatchAudioFormat

• Match audio properties of source C to template T

For ease of splicing, interleaving etc.

##  Properties matched:
##  number of channels (see note), bit depth, sample rate
##
## AudioChannels handling:
##   if 'T' has no audio, returns 'C'.KillAudio;
##   if 'C' has no audio, copies silenced audio from 'T';
##   if 'T' and 'C' have the same channel count, no change is made;
##   if 'T' has 1 channel, returns 'C'.ConvertToMono;
##   if 'T' has 2 channels and 'C' has 1, returns 'C' with split mono;
##   otherwise, an error is raised (manual intervention is needed)
##
## @ allowresample - if true, resample audio to match template if needed;
##                   if false (the default), use AssumeSampleRate,
##                   which may affect audio/video sync.
##
function MatchAudioFormat(clip C, clip T, bool "allowresample")

remove_gamma

• Remove sRGB gamma transfer function (if bit depth > 8)

Improves appearance of certain filters like Resize; must call restore_gamma before final output; requires MaskTools v2.2.x

## @ enable - default true; if false, do nothing (bypass)
function remove_gamma(clip C, bool enable)

restore_gamma

• Apply standard gamma transfer function (if bit depth > 8)

Reverses effect of remove_gamma.

## @ enable - default true; if false, do nothing (bypass)
function restore_gamma(clip C, bool enable)

Color And Overlay Filters

LevelsPlus

• Scale 0-255_d Levels arguments to current bit depth.

coring=false by default.

## @ input_x, output_x - now Float to allow fractional values
## @ coring - unlike 'legacy' Levels, 'coring' now defaults to false
## @ chroma - if true (default) process chroma like Levels; else bypass YUV chroma
##
function LevelsPlus(clip C, 
\             float input_low, float gamma, float input_high,
\             float output_low, float output_high, 
\             bool "coring", bool "dither", bool "chroma")

Crop, Resize And Transform Filters

ScaleSize

• Switch (or fade) between three Resize clips depending on scale factor.

Resizers may be user-specified; default resizers are gamma-aware.

• default 'small' (< 65%) resizer: gamma-aware BicubicResize (b=-0.5, c=0.25)
• default 'medium'   resizer:       gamma-aware Spline64Resize
• default 'large' (> 133%) resizer: gamma-aware GaussResize (p=50)

## @ fwid  - new width
## @ fhgt  - new height
##             (if 'fwid' <= 0, it is calculated from 'fhgt' and aspect ratio)
##             (if 'fhgt' <= 0, it is calculated from 'fwid' and aspect ratio)
##             (if both <= 0, an error is raised)
## @ mod   - new size modulo; if <= 0, 
##             'mod'=1 if source is RGB or YUV 4:4:4 or Y-only; else 'mod'=2
##
## (see script for more, advanced options)
##
function ScaleSize(clip C, float fwid, float fhgt, int mod, 
\             string "sm", string "med", string "lg",  
\             float "thrSm", float "thrLg", bool "fade", bool "ident", bool "gamma")

CropEx

• Symmetrically crop or expand a clip to ensure it is a certain size, with size forced to mod-4, mod-8 etc.

Quick & easy way to splice or stack disparate clips together.

## @ wid, hgt - New desired width & height (will be rounded to nearest 'mod')
## @ mod      - Mod value; one of (1|2|4|8|16|32); default 2
## @ border   - Border color; default 0 (black border)
## @ mode     - Expand method: (extend|mirror|blur|border) 
##               default/fallback="border"
## @ align    - @see Subtitle ("number pad notation"); position clip within frame.
##              Default 5 (centered)
## @ dx, dy   - Shift output in x/y direction. Positive = right/down. Default 0. 
##              Note output shift rounded to nearest mod-2 unless 'mod'=1.
##
function CropEx(clip C, float wid, float hgt, int "mod",   
\             int "border", string "mode", 
\             int "align", int "dx", int "dy", bool "debug")

Debugging Filters

EvalShow

• Evaluate a script snippet; display the script and its result on screen.

## @ s - a snippet of AviSynth code; any string allowed as an argument to Eval. 
## @ size, align - cf. Subtitle. 'size' is quite small by default; 
##                 you may prefer size=24. Disable subtitle w/ size = 0.
## @ opacity     - 1.0 = opaque text, 0.0 = transparent. Default 0.7
##
function EvalShow(clip C, string s, float "size", int "align", float "opacity")

Grayramp

• Return grayscale ramp clip w/ same specs as template clip T

Useful for measuring luma response curve when used in combination with HistogramTurn.

See script for ColorRampEx – ramp between any two colors.

## @ T      - Any color format (8, 10, 12, 14 or 16-bit);
##            determines all properties except Height. 
## @ height - default 80
## @ zigs   - if true, 8 pixels on left and right reverse ramp direction;
##            useful for determining whether clipping has occurred.
## @ stack  - if true, stack on top of clip 'T';
##            resulting audio is taken from 'T'
## @ noise  - if > 0, add fixed, random noise; range 0_4, default 0
##
function Grayramp(clip T, int "height", bool "zigs", bool "stack", int "noise")

ScopeR

• Show waveform + vectorscope; accepts RGB or YUV

Rotate waveform 90° CCW and make brighter; rotate vector 180°.

## @ shrink - if true, shrink clip+scopes & add side borders so output size = input;
##            if false (default), height increases by 264 px 
## @ vector - if true, show Histogram("color2") (inverted so red is top-left)
## @ matrix - if source is RGB and 'vector'=true, use this matrix; default "Rec709"
##            otherwise 'matrix' is ignored (does not affect waveform or main image)
## @ parade - if true, show RGB waveforms side-by-side;
##            else (default), show RGB waveforms superimposed
## @ bottom - if true, put scopes below video (default false)
##
function ScopeR(clip C, bool "shrink", bool "vector", string "matrix", 
\               bool "parade", bool "bottom")

ScopeY

• Simple waveform + vector scope. Accepts 8-bit, YUV only.

Rotate waveform 90° CCW and make brighter; rotate vector 180°.

## @ shrink - if true, shrink clip+scopes & add side borders so 
##              output size = input (within range 360_1440);
##            if false (default), height increases by 264 px 
## @ vector - if true (default), show Histogram("color2") 
##              (inverted so red is top-left) 
## @ levels - if true, show Histogram("levels", 1.0); default false.
## @ bottom - if true, put scopes below video (default false)
##
## * Smaller heights are faster to process; scopes look relatively bigger; 
##   (at height=512, scopes occupy the bottom half of the output; 
##    at 720, about 1/3; at 1080, 1/4)
##
function ScopeY(clip C, bool "shrink", bool "vector", bool "levels", bool "bottom")

HistogramTurn

• Classic Histogram, waveform on top (or on bottom); supports RGB

Rotate waveform 90° CCW and make brighter.

## @ parade - if true (default), show RGB waveforms side-by-side;
##            else, show RGB waveforms superimposed 
## @ shrink - if true, shrink clip+waveform & add side borders so output size = input
##            if false (default), height increases by 264 px 
## @ bottom - if true, put histogram below video (default false)
##
function HistogramTurn(clip C, bool "parade", bool "shrink", bool "bottom")

File history

see File:Utils-r41.avsi.