Convert

From Avisynth

ConvertToRGB(clip [, string matrix] [, bool interlaced] [, string chromaplacement] [, string chromaresample])
ConvertToRGB24(clip [, string matrix] [, bool interlaced] [, string chromaplacement] [, string chromaresample])
ConvertToRGB32(clip [, string matrix] [, bool interlaced] [, string chromaplacement] [, string chromaresample])
ConvertToY8(clip [, string matrix])
ConvertToYUY2(clip [, bool interlaced] [, string matrix] [, string chromaplacement] [, string chromaresample])
ConvertToYV411(clip [, bool interlaced] [, string matrix] [, string chromaplacement] [, string chromaresample])
ConvertToYV12(clip [, bool interlaced] [, string matrix] [, string chromaplacement] [, string chromaresample])
ConvertToYV16(clip [, bool interlaced] [, string matrix] [, string chromaplacement] [, string chromaresample])
ConvertToYV24(clip [, bool interlaced] [, string matrix] [, string chromaplacement] [, string chromaresample])
ConvertBackToYUY2(clip [, string matrix])

colorformats = ...	planar/interleaved	chroma resolution
RGB	interleaved	full chroma - 4:4:4
RGB24	interleaved	full chroma - 4:4:4
RGB32	interleaved	full chroma - 4:4:4
YUY2	interleaved	chroma shared between 2 pixels - 4:2:2
Y8	planar/interleaved	no chroma - 4:0:0
YV411	planar	chroma shared between 4 pixels - 4:1:1
YV12	planar	chroma shared between 2x2 pixels - 4:2:0
YV16	planar	chroma shared between 2 pixels - 4:2:2
YV24	planar	full chroma - 4:4:4

matrix: Default "Rec601", scaled to TV range [16,235].

• "PC.601" : Uses Rec.601 coefficients, keep full range [0,255].
• "Rec709" : Uses Rec.709 coefficients, scaled to TV range.
• "PC.709" : Uses Rec.709 coefficients, keep full range.
• "AVERAGE" : Uses averaged coefficients, keep full range (added in v2.60). (So the luma becomes the average of the RGB channels.)

interlaced: Default false. Use interlaced layout for YV12 <-> non-YV12 conversions.

chromaplacement (added in v2.60): This determines the chroma placement when converting to or from YV12. It can be "MPEG2" (default), "MPEG1" and "DV".

chromaresample (added in v2.60): This determines which resizer is used in the conversion. It is used when the chroma resolution of the source and target is different. It can be all resamplers, default is "bicubic".

AviSynth prior to v2.5 can deal internally with two color formats, RGB and YUY2. Starting from v2.50 AviSynth can also deal with a third color format, YV12. These six filters convert between them. If the video is already in the specified format, it will be passed through unchanged. (RGB is assumed throughout this doc to mean RGBA.) ConvertToRGB converts to RGB32 unless your clip is RGB24. If you need 24-bit RGB for some reason, use ConvertToRGB24 explicitly and ConvertToRGB32 to do the reverse.

In v2.60 the following additional formats are supported: Y8 greyscale (it is both planar and interleaved since it contains no chroma; 4:0:0), YV411 (planar; YUV 4:1:1), YV16 (a planar version of YUY2; 4:2:2) and YV24 (planar; YUV 4:4:4).

Syntax and operation of ConvertToRGB24 are identical to ConvertToRGB, except that the output format is 24-bit; if the source is RGB32, the alpha channel will be stripped.

Since v2.51/v2.52 an optional interlaced parameter is added (interlaced=false is the default operation). When set to false it is assumed that clip is progressive, when set to true it is assumed that clip is interlaced. This option is added because for example (assuming clip is interlaced YV12):

SeparateFields(clip)
ConvertToYUY2()
Weave()

is upsampled incorrectly. Instead it is better use:

ConvertToYUY2(clip, interlaced=true)

Note, the interlaced=true setting only does something if the conversion YV12 <-> YUY2/RGB is requested, otherwise it's simply ignored. More about it can be found here.

Contrary to what one might expect, there is no unique way of converting YUV to RGB. In AviSynth the two most common ones are implemented: Rec.601 and Rec.709 (named after their official specifications). Although it will not be correct in all cases, the following should be correct in most cases:

The first one (Rec.601) should be used when your source is DivX/XviD or some analogue capture:

ConvertToRGB(clip)

The second one (Rec.709) should be used when your source is DVD or HDTV:

ConvertToRGB(clip, matrix="rec709")

In v2.56, the reverse is also available, that is

ConvertToYUY2(clip, matrix="rec709") or ConvertToYV12(clip, matrix="rec709")

In v2.56, matrix="pc.601" (and matrix="pc.709") enables you to do the RGB <-> YUV conversion while keeping the luma range, thus RGB [0,255] <-> YUV [0,255] (instead of the usual/default RGB [0,255] <-> YUV [16,235]).

All VirtualDub filters (loaded with LoadVirtualdubPlugin) support only RGB32 input.

If you try to use any of these filters with RGB input, you will get an error. Putting ConvertToYUY2 just before the offending filter should resolve the problem. All AviSynth filters support YUY2 input.

Conversion back and forth is not lossless, so use as few conversions as possible. If multiple conversions are necessary, use ConvertBackToYUY2() to convert back to YUY2, when you applied a YUY2->RGB conversion prior to that in your script. This will reduce color-blurring, but there are still some precision lost.

In most cases, the ConvertToRGB filter should not be necessary. If AviSynth's output is in YUY2 format and an application expects RGB, the system will use the installed YUY2 codec to make the conversion. However, if there's no installed YUY2 codec, or if (as is the case with ATI's YUY2 codec) the codec converts from YUY2 to RGB incorrectly, you can use Avisynth's built-in filter to convert instead.

[edit] YUY2 codecs

HuffYUV will act as the system YUY2 codec if there's no other codec installed, so if you install HuffYUV and uninstall all other YUY2 codecs, then you'll never need ConvertToRGB.

You can also edit the registry to force your system to use HuffYUV as the system YUY2 codec. Look under

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Drivers32

(the location will be different for Win9x). You should find a string named VIDC.YUY2; its value will vary according to your software and hardware configuration (for example, installation of an ATI All-In-Wonder Radeon set this to ATIVYUY.DLL). Change this to huffyuv.dll and HuffYUV will be called upon for YUY2 conversions. Encoding quality from an Avisynth script with TMPGEnc is much better with HuffYUV as the YUY2 decoder than with some other codecs; with ATIVYUY.DLL, for instance, subtle color variations became posterized. Acceptable results were possible with the ConvertToRGB filter, but this increased encoding time substantially as TMPGEnc needed to convert back to YUV as it encoded. Changing the system YUY2 codec to HuffYUV eliminates the expensive (and lossy) YUV->RGB->YUV conversion while maintaining the quality of the encoded output.

Sometimes the colors are distorted (black is green, white is purple) when loading an MJPEG clip in AviSynth v2.5. You can work around it by calling ConvertToYV12, and forcing your avi to open as YUY2:

AviSource("c:\clip.avi", pixel_type="YUY2")
ConvertToYV12()  # if necessary

[edit] Examples

There is a slight distortion caused by the conversion between YUY2 and RGB.
Let's see if we can see it.

control = ConvertToYUY2()
test = control.ConvertToRGB().ConvertToYUY2().ConvertToRGB().ConvertToYUY2()
test = test.ConvertToRGB().ConvertToYUY2()
return Subtract(test, control)

[edit] Changelog

v2.60	Added ConvertToY8, ConvertToYV411, ConvertToYV16, ConvertToYV24, chromaplacement, chromaresample, matrix="AVERAGE".
v2.50	Added ConvertToYV12.