Tweak

Revision as of 23:11, 10 November 2015

Tweak(clip clip [, float hue] [, float sat] [, float bright] [, float cont] [, bool coring] [, bool sse] [, float startHue] [, float endHue] [, float maxSat] [, float minSat] [, float interp] [, bool dither])

This filter provides the means to adjust the hue, saturation, brightness, and contrast of a video clip. In v2.60, both the saturation and hue can be adjusted for saturations in the range [minSat, maxSat] and hues in the range [startHue, endHue].

hue

Adjust the color hue of the image. Positive values shift the image towards red. Negative values shift it towards green. (-180.0 to +180.0, default 0.0)

sat

Adjust the color saturation of the image. Values above 1.0 increase the saturation. Values below 1.0 reduce the saturation. Use sat=0 to convert to GreyScale. (0.0 to 10.0, default 1.0)

bright

Change the brightness of the image. Positive values increase the brightness (the clip gets brighter). Negative values decrease the brightness (the clip gets darker). If the clip is too dark or too bright you can use this setting to correct it. (-255.0 to 255.0, default 0.0)

cont

Change the contrast of the image. Values above 1.0 increase the contrast (the luma range will be stretched). Values below 1.0 decrease the contrast (the luma range will be contracted). If details can't be seen in dark or bright areas, you can increase the contrast to make those details more visible. (0.0 to 10.0, default 1.0)

coring

When true (the default), the luma (Y) is clipped to [16,235] and the chroma (U, V) is clipped to [16,240]; when set to false, the luma and chroma are unconstrained. [Added in v2.53].

sse

Only available for YUY2 with coring=false and only using the standard hue, sat, bright and cont options. It re-enables the SSE code if required. (default false)

startHue, endHue

The hue and saturation will be adjusted for values in the range [startHue, endHue] when startHue<endHue. Note that the hue is periodic, thus a hue of 360 degrees corresponds with a hue of zero degrees. If endHue<startHue then the range [endHue, 360] and [0, startHue] will be selected (thus anti-clockwise). If you need to select a range of [350, 370] for example, you need to specify startHue=350 and endHue=10, (370-360). Thus when using the default values all pixels will be processed. (both from 0 to 360, given in degrees; default 0, 360)

As a guide, the following table shows approximate startHue and endHue values for the basic colors:

Color	startHue	endHue
Red	075	115
Yellow	150	172
Green	191	258
Cyan	279	300
Blue	316	004
Magenta	028	052

maxSat, minSat

The hue and saturation will be adjusted for values in the range [minSat, maxSat]. Practically the percentage saturation of a pixel will be in the range [0,100], since these correspond to valid RGB pixels (100% corresponds to R=255, G=B=0, which has a saturation of 119 in units of chroma). An overshoot (up to 150%) is allowed for non-valid RGB pixels (150% corresponds to U=V=255, which has a saturation of sqrt(127^2+127^2) = 180). Thus when using the default values all pixels will be processed. (both from 0 to 150 with minSat<maxSat, given in percentages; default 150, 0)

interp

Interpolate the saturation adjustment at the edges of the chosen range to prevent banding. The adjustment is interpolated between 1.0 and sat in the range [minS-interp, minS] and between sat and 1.0 in [maxS, maxS+interp], where minS and maxS are the equivalents of minSat and maxSat in chroma units (100% = 119 units). There is no interpolation for interp=0, which can be useful when a clip consists of uniform colors and you want a hard cutoff. The interpolation is linear. (0 to 32, default 16; given in units of chroma, rather than a percentage)

dither

When true, ordered dithering is applied when doing the adjustment. (default false)

Usage and examples: adjusting contrast and brightness

original

There are two problems with this picture. It is too dark, and the contrast is too small (the details of the tree are not visible for example). First, we will higher the brightness to make the picture less dark (left picture below). Second, we will higher the contrast to make details in the dark areas more visible (right picture below). Make sure that the bright parts don't get too bright though.

bright=20	bright=20, cont=1.2

Usage and examples: adjusting saturation

original	sat=0.75

Suppose we want to lower the saturation of the skin of the girl, and the background should be left intact. The proper way to do this is to set sat=0, and lower the hue range till you found the correct hue range which should be processed. This can be done by using a Vectorscope, but also manually. (If it is needed the saturation range can also be specified if the dark and white parts of that hue should not be processed.) The result is below.

sat=0, startHue=105, endHue=138	sat=0.75, startHue=105, endHue=138

Instead, we can also try to "select" the skin of the girl by narrowing the saturation range only. The result is below. In this case the result is pretty much identical.

sat=0, maxSat=75, minSat=55	sat=0.75, maxSat=75, minSat=55

Usage: YUV to YIQ conversion

The NTSC analog television system used the YUV color space with its axes rotated by 33 degrees, a color space called YIQ. In YIQ, orange and teal are along the in-phase (I) axis, while green and magenta are along the quadrature (Q) axis. The eye is far more sensitive to detail along the I axis than along the Q axis, and NTSC traditionally used more bandwidth for I than for Q.

The Tweak filter can be used to convert YUV to YIQ, where the V axis represents I and U represents Q. The following example, based on an example at Swap, converts a YUV clip to YIQ, blanks the Q channel, and converts back to YUV. This produces the "orange and teal" color scheme that became a cliché.

# AviSource() etc. goes above here

yiqclip = Tweak(hue=33) # at this point v and u represent i and q
u_chroma = BlankClip(UToY(yiqclip),color=$808080)
YToUV(u_chroma, yiqclip.VToY)
MergeLuma(yiqclip)
Tweak(hue=-33)  # convert back to yuv
AudioDub(yiqclip)

This allows processing the I and Q signals separately

Changes