Convert

From Avisynth wiki
(Difference between revisions)
Jump to: navigation, search
m (more fixes)
(Changelog: Frame prop _ChromaLocation)
 
(11 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
:{| class="wikitable"
 
:{| class="wikitable"
 
|-
 
|-
! Version 
 
 
! Color format 
 
! Color format 
 
! Image format 
 
! Image format 
Line 10: Line 9:
 
!style="text-align:left"|  Description
 
!style="text-align:left"|  Description
 
|-  
 
|-  
|
 
 
| '''[[RGB24]]'''
 
| '''[[RGB24]]'''
 
| [[Interleaved|interleaved]]
 
| [[Interleaved|interleaved]]
Line 17: Line 15:
 
| (full chroma)
 
| (full chroma)
 
|-  
 
|-  
|
 
 
| '''[[RGB32]]'''
 
| '''[[RGB32]]'''
 
| interleaved
 
| interleaved
Line 24: Line 21:
 
| (full chroma + alpha)
 
| (full chroma + alpha)
 
|-  
 
|-  
|style="text-align:center"| {{AvsPluscon}}
+
| '''[[YV24]]''' ♦
 +
| planar
 +
| 8
 +
| 4:4:4
 +
| (full chroma)
 +
|-
 +
| '''[[YV16]]''' ♦
 +
| planar
 +
| 8
 +
| 4:2:2
 +
| (chroma shared between 2 pixels)
 +
|-
 +
| '''[[YUY2]]'''
 +
| interleaved
 +
| 8
 +
| 4:2:2
 +
| (chroma shared between 2 pixels)
 +
|-
 +
| '''[[YV12]]'''
 +
| planar
 +
| 8
 +
| 4:2:0
 +
| (chroma shared between 2x2 pixels) 
 +
|-
 +
| '''[[YV411]]''' ♦
 +
| planar
 +
| 8
 +
| 4:1:1
 +
| (chroma shared between 4 pixels)
 +
|-
 +
| '''[[Y8]]''' ♦
 +
| (both)
 +
| 8
 +
| 4:0:0
 +
| (no chroma)
 +
|-
 +
!colspan="5" style="text-align:left; font-weight:normal;"|  (♦ = not supported in AviSynth version 2.58 or below)
 +
|}
 +
 
 +
{{AvsPluscon}} supports all of the above, plus:
 +
:{| class="wikitable"
 +
|-
 +
! Color format 
 +
! Image format 
 +
! Bit depth 
 +
! Sample ratio 
 +
!style="text-align:left"|  Description
 +
|-
 
| '''[[Avisynthplus_color_formats|RGB48]]'''
 
| '''[[Avisynthplus_color_formats|RGB48]]'''
 
| interleaved
 
| interleaved
Line 31: Line 75:
 
| (full chroma)
 
| (full chroma)
 
|-  
 
|-  
|style="text-align:center"| {{AvsPluscon}}
 
 
| '''[[Avisynthplus_color_formats|RGB64]]'''
 
| '''[[Avisynthplus_color_formats|RGB64]]'''
 
| interleaved
 
| interleaved
Line 38: Line 81:
 
| (full chroma + alpha)
 
| (full chroma + alpha)
 
|-  
 
|-  
|style="text-align:center"| {{AvsPluscon}}
 
 
| '''[[Avisynthplus_color_formats|RGBPxx]]'''
 
| '''[[Avisynthplus_color_formats|RGBPxx]]'''
 
| [[Planar|planar]]
 
| [[Planar|planar]]
Line 45: Line 87:
 
| (full chroma)
 
| (full chroma)
 
|-  
 
|-  
|style="text-align:center"| {{AvsPluscon}}
 
 
| '''[[Avisynthplus_color_formats|RGBAPxx]]'''
 
| '''[[Avisynthplus_color_formats|RGBAPxx]]'''
 
| [[Planar|planar]]
 
| [[Planar|planar]]
Line 52: Line 93:
 
| (full chroma + alpha)
 
| (full chroma + alpha)
 
|-  
 
|-  
|style="text-align:center"| v2.6
 
| '''[[YV24]]'''
 
| planar
 
| 8
 
| 4:4:4
 
| (full chroma)
 
|-
 
|style="text-align:center"| {{AvsPluscon}}
 
 
| '''[[Avisynthplus_color_formats|YUV444Pxx]]'''
 
| '''[[Avisynthplus_color_formats|YUV444Pxx]]'''
 
| planar
 
| planar
Line 66: Line 99:
 
| (full chroma)
 
| (full chroma)
 
|-  
 
|-  
|style="text-align:center"| {{AvsPluscon}}
 
 
| '''[[Avisynthplus_color_formats|YUVA444Pxx]]'''
 
| '''[[Avisynthplus_color_formats|YUVA444Pxx]]'''
 
| planar
 
| planar
Line 73: Line 105:
 
| (full chroma + alpha)
 
| (full chroma + alpha)
 
|-  
 
|-  
|style="text-align:center"| v2.6
 
| '''[[YV16]]'''
 
| planar
 
| 8
 
| 4:2:2
 
| (chroma shared between 2 pixels)
 
|-
 
|style="text-align:center"| {{AvsPluscon}}
 
 
| '''[[Avisynthplus_color_formats|YUV422Pxx]]'''
 
| '''[[Avisynthplus_color_formats|YUV422Pxx]]'''
 
| planar
 
| planar
Line 87: Line 111:
 
| (chroma shared between 2 pixels)
 
| (chroma shared between 2 pixels)
 
|-  
 
|-  
|style="text-align:center"| {{AvsPluscon}}
 
 
| '''[[Avisynthplus_color_formats|YUVA422Pxx]]'''
 
| '''[[Avisynthplus_color_formats|YUVA422Pxx]]'''
 
| planar
 
| planar
Line 94: Line 117:
 
| (chroma shared between 2 pixels + alpha)
 
| (chroma shared between 2 pixels + alpha)
 
|-  
 
|-  
|
 
| '''[[YUY2]]'''
 
| interleaved
 
| 8
 
| 4:2:2
 
| (chroma shared between 2 pixels)
 
|-
 
|
 
| '''[[YV12]]'''
 
| planar
 
| 8
 
| 4:2:0
 
| (chroma shared between 2x2 pixels) 
 
|-
 
|style="text-align:center"| {{AvsPluscon}}
 
 
| '''[[Avisynthplus_color_formats|YUV420Pxx]]'''
 
| '''[[Avisynthplus_color_formats|YUV420Pxx]]'''
 
| planar
 
| planar
Line 115: Line 123:
 
| (chroma shared between 2x2 pixels) 
 
| (chroma shared between 2x2 pixels) 
 
|-  
 
|-  
|style="text-align:center"| {{AvsPluscon}}
 
 
| '''[[Avisynthplus_color_formats|YUVA420Pxx]]'''
 
| '''[[Avisynthplus_color_formats|YUVA420Pxx]]'''
 
| planar
 
| planar
Line 122: Line 129:
 
| (chroma shared between 2x2 pixels + alpha) 
 
| (chroma shared between 2x2 pixels + alpha) 
 
|-  
 
|-  
|style="text-align:center"| v2.6
 
| '''[[YV411]]'''
 
| planar
 
| 8
 
| 4:1:1
 
| (chroma shared between 4 pixels)
 
|-
 
|style="text-align:center"| v2.6
 
| '''[[Y8]]'''
 
| (both)
 
| 8
 
| 4:0:0
 
| (no chroma)
 
|-
 
|style="text-align:center"| {{AvsPluscon}}
 
 
| '''[[Avisynthplus_color_formats|Y10..Y32]]'''  
 
| '''[[Avisynthplus_color_formats|Y10..Y32]]'''  
 
| (both)
 
| (both)
Line 143: Line 135:
 
| (no chroma)
 
| (no chroma)
 
|-  
 
|-  
!colspan="6" style="text-align:left; font-weight:normal;"|  '''*''' 8-16 = ''8,10,12,14,16 bit integer;''   32 = ''32 bit float''
+
!colspan="5" style="text-align:left; font-weight:normal;"|  '''*''' 8-16 = ''8,10,12,14,16 bit integer;''  32 = ''32 bit float''
 
|}
 
|}
  
Line 149: Line 141:
 
When the target format is the same as the source format, the original clip will be returned unchanged, except for the case of '''ConvertToYV12''' where the {{FuncArg|ChromaInPlacement}} and {{FuncArg|ChromaOutPlacement}} parameters are different.
 
When the target format is the same as the source format, the original clip will be returned unchanged, except for the case of '''ConvertToYV12''' where the {{FuncArg|ChromaInPlacement}} and {{FuncArg|ChromaOutPlacement}} parameters are different.
  
<!-- div {{NotaBeneWidthIndent|56|2}} -->
 
 
{{BlueBox}}
 
{{BlueBox}}
 
There is no unique way of [[Color_conversions|converting]] YUV to RGB or vice-versa. There are different ''conversion matrices'' in use; the two most common ones are available in AviSynth, namely ''Rec.601'' and ''Rec.709'', plus some others. The following should be correct in ''most'' cases (see [[Colorimetry#How_can_I_see_if_the_correct_standard_is_used_upon_playback.3F|'''here''']] for more)
 
There is no unique way of [[Color_conversions|converting]] YUV to RGB or vice-versa. There are different ''conversion matrices'' in use; the two most common ones are available in AviSynth, namely ''Rec.601'' and ''Rec.709'', plus some others. The following should be correct in ''most'' cases (see [[Colorimetry#How_can_I_see_if_the_correct_standard_is_used_upon_playback.3F|'''here''']] for more)
Line 157: Line 148:
 
:<code>ConvertToRGB(clip, matrix="Rec709")</code>
 
:<code>ConvertToRGB(clip, matrix="Rec709")</code>
 
*The special-purpose matrices ''PC.601'' and ''PC.709'' keep the ''range'' unchanged,  
 
*The special-purpose matrices ''PC.601'' and ''PC.709'' keep the ''range'' unchanged,  
:instead of converting between 0-255<sub>8</sub>&nbsp;RGB and 16<sub>8</sub>-235<sub>8</sub>&nbsp;YUV, as is the normal practice.
+
:instead of converting between 0{{D}}-255{{D}}&nbsp;RGB and 16{{D}}-235{{D}}&nbsp;YUV, as is the normal practice.
 
*The special-purpose matrix ''AVERAGE'' is used for (rarely found) sources with ''unweighted'' luma,  
 
*The special-purpose matrix ''AVERAGE'' is used for (rarely found) sources with ''unweighted'' luma,  
 
:where ''Y'' = (R + G + B) / 3.
 
:where ''Y'' = (R + G + B) / 3.
Line 166: Line 157:
 
Use '''ConvertBackToYUY2''' to convert ''back'' to YUY2 with minimal color-blurring when you have previously applied a YUY2&rarr;RGB conversion.
 
Use '''ConvertBackToYUY2''' to convert ''back'' to YUY2 with minimal color-blurring when you have previously applied a YUY2&rarr;RGB conversion.
  
{{AvsPluscon}} See also [[ConvertBits]] to convert between bit depths.
+
{{AvsPluscon}} See also [[ConvertBits]] to convert between bit depths and/or between full-limited range.
 
</div>
 
</div>
  
Line 173: Line 164:
 
==== Syntax and Parameters ====
 
==== Syntax and Parameters ====
 
<div style="max-width:62em" >
 
<div style="max-width:62em" >
===== ''RGB interleaved'' =====
+
===== ''RGB interleaved'' ===== __NOEDITSECTION__
 
{{FuncDef
 
{{FuncDef
 
|ConvertToRGB(clip [, string ''matrix'', bool ''interlaced'',  <br>  
 
|ConvertToRGB(clip [, string ''matrix'', bool ''interlaced'',  <br>  
Line 200: Line 191:
 
}}
 
}}
  
===== ''RGB planar'' =====
+
===== ''RGB planar'' ===== __NOEDITSECTION__
 
{{FuncDef
 
{{FuncDef
 
|ConvertToPlanarRGB(clip, [ string ''matrix'', bool ''interlaced'',  <br>  
 
|ConvertToPlanarRGB(clip, [ string ''matrix'', bool ''interlaced'',  <br>  
Line 212: Line 203:
 
}}
 
}}
  
===== ''YUV444'' =====
+
===== ''YUV444'' ===== __NOEDITSECTION__
 
{{FuncDef
 
{{FuncDef
 
|ConvertToYV24(clip [, bool ''interlaced'', string ''matrix'',  <br>  
 
|ConvertToYV24(clip [, bool ''interlaced'', string ''matrix'',  <br>  
Line 222: Line 213:
 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''ChromaInPlacement'',  <br>  
 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''ChromaInPlacement'',  <br>  
 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''chromaresample'' ] ) {{AvsPluscon}}  
 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''chromaresample'' ] ) {{AvsPluscon}}  
}} <br>
+
}}
  
===== ''YUV422'' =====
+
===== ''YUV422'' ===== __NOEDITSECTION__
 
{{FuncDef
 
{{FuncDef
 
|ConvertToYV16(clip [, bool ''interlaced'', string ''matrix'',  <br>  
 
|ConvertToYV16(clip [, bool ''interlaced'', string ''matrix'',  <br>  
 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''ChromaInPlacement'',  <br>  
 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''ChromaInPlacement'',  <br>  
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''chromaresample''] )
+
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''chromaresample'', <br>
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''ChromaOutPlacement'' {{AvsPluscon}} ] )  
 
}} <br>
 
}} <br>
{{FuncDef
 
|ConvertToYUV422(clip, [ string ''matrix'', bool ''interlaced'',  <br>
 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''ChromaInPlacement'',  <br>
 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''chromaresample'' ] ) {{AvsPluscon}}
 
}}<br>
 
 
{{FuncDef
 
{{FuncDef
 
|ConvertToYUY2(clip [, bool ''interlaced'', string ''matrix'',  <br>  
 
|ConvertToYUY2(clip [, bool ''interlaced'', string ''matrix'',  <br>  
 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''ChromaInPlacement'',  <br>  
 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''ChromaInPlacement'',  <br>  
 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''chromaresample''] )
 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''chromaresample''] )
 +
}}<br>
 +
{{FuncDef
 +
|ConvertToYUV422(clip, [ string ''matrix'', bool ''interlaced'',  <br>
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''ChromaInPlacement'',  <br>
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''chromaresample'', <br>
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''ChromaOutPlacement''] )  {{AvsPluscon}}
 
}}
 
}}
  
Line 245: Line 238:
 
}}
 
}}
  
===== ''YUV420'' =====
+
===== ''YUV420'' ===== __NOEDITSECTION__
 
{{FuncDef
 
{{FuncDef
 
|ConvertToYV12(clip [, bool ''interlaced'', string ''matrix'',  <br>  
 
|ConvertToYV12(clip [, bool ''interlaced'', string ''matrix'',  <br>  
Line 259: Line 252:
 
}}
 
}}
  
===== ''YUV411'' =====
+
===== ''YUV411'' ===== __NOEDITSECTION__
 
{{FuncDef
 
{{FuncDef
 
|ConvertToYV411(clip [, bool ''interlaced'', string ''matrix'',  <br>  
 
|ConvertToYV411(clip [, bool ''interlaced'', string ''matrix'',  <br>  
 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''ChromaInPlacement'',  <br>  
 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''ChromaInPlacement'',  <br>  
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''chromaresample''] )
+
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''chromaresample''] )  
 
}}
 
}}
  
===== ''Y-only'' =====
+
===== ''Y-only'' ===== __NOEDITSECTION__
 
{{FuncDef
 
{{FuncDef
 
|ConvertToY8(clip [, string ''matrix''] )
 
|ConvertToY8(clip [, string ''matrix''] )
Line 272: Line 265:
 
{{FuncDef
 
{{FuncDef
 
|ConvertToY(clip, [ string ''matrix'' ] ) {{AvsPluscon}}  
 
|ConvertToY(clip, [ string ''matrix'' ] ) {{AvsPluscon}}  
}}  
+
}}
  
 
==== Parameter Details ====
 
==== Parameter Details ====
Line 278: Line 271:
 
{{Par2|matrix|string|"Rec601"}}
 
{{Par2|matrix|string|"Rec601"}}
 
:Controls the colour coefficients and scaling factors used in RGB&harr;YUV conversions.
 
:Controls the colour coefficients and scaling factors used in RGB&harr;YUV conversions.
:*"Rec601"&nbsp; : Uses Rec.601 coefficients; scale full range [0..255<sub>8</sub>] RGB &harr; TV range [16<sub>8</sub>..235<sub>8</sub>] YUV.
+
:*"Rec601"&nbsp; : Uses Rec.601 coefficients; scale full range [0{{D}}..255{{D}}] RGB &harr; TV range [16{{D}}..235{{D}}] YUV.
 
:*"Rec709"&nbsp; : Uses Rec.709 (HD) coefficients; scale full range RGB &harr; TV range YUV.
 
:*"Rec709"&nbsp; : Uses Rec.709 (HD) coefficients; scale full range RGB &harr; TV range YUV.
 
:*"Rec2020" : Uses Rec.2020 (UHD) coefficients; scale full range RGB &harr; TV range YUV. {{AvsPluscon}}
 
:*"Rec2020" : Uses Rec.2020 (UHD) coefficients; scale full range RGB &harr; TV range YUV. {{AvsPluscon}}
 +
:*"PC.2020" : Uses Rec.2020 (UHD) coefficients; keep range unchanged. {{AvsPluscon}}
 
:*"PC.601"&nbsp; : Uses Rec.601 coefficients; keep range unchanged.
 
:*"PC.601"&nbsp; : Uses Rec.601 coefficients; keep range unchanged.
 
:*"PC.709"&nbsp; : Uses Rec.709 (HD) coefficients; keep range unchanged.
 
:*"PC.709"&nbsp; : Uses Rec.709 (HD) coefficients; keep range unchanged.
 
:*"Average"&nbsp; : Uses averaged coefficients (the luma becomes the average of the RGB channels); keep range unchanged.
 
:*"Average"&nbsp; : Uses averaged coefficients (the luma becomes the average of the RGB channels); keep range unchanged.
 +
 +
{{AvsPluscon}}
 +
:New syntax: more matrix string constants with separate full/limited range markers
 +
:"matrixname:full_or_limited" where
 +
:"matrixname" can be (internal _Matrix integer constant in parenthesys)
 +
::* "rgb" (0 - AVS_MATRIX_RGB)
 +
::* "709" (1 - AVS_MATRIX_BT709)
 +
::* "unspec" (2 - AVS_MATRIX_UNSPECIFIED)
 +
::* "170m" (6 - AVS_MATRIX_ST170_M)
 +
::* "240m" (7 - AVS_MATRIX_ST240_M)
 +
::* "470bg" (5 - AVS_MATRIX_BT470_BG)
 +
::* "601" (5 - AVS_MATRIX_BT470_BG)
 +
::* "fcc" (4 - AVS_MATRIX_BT470_M)
 +
::* "bt470m" (4 - AVS_MATRIX_BT470_M)
 +
::* "ycgco" (8 - AVS_MATRIX_YCGCO      not supported)
 +
::* "2020ncl" (9 - AVS_MATRIX_BT2020_NCL)
 +
::* "2020" (9 - AVS_MATRIX_BT2020_NCL)
 +
::* "2020cl" (10 - AVS_MATRIX_BT2020_CL  same as 2020ncl)
 +
::* "chromacl" (13 - AVS_MATRIX_CHROMATICITY_DERIVED_CL  not supported)
 +
::* "chromancl" (12 - AVS_MATRIX_CHROMATICITY_DERIVED_NCL not supported)
 +
::* "ictcp" (14 - AVS_MATRIX_ICTCP      not supported)
 +
 +
:: The above "matrix" parameters can be followed by a "full" or "f" and "limited" or "l" or "auto" marker after a ":"<p>e.g. "709:f" means the same as the old "PC.709"</p>
 +
:: When there is no limited-ness marker, or is set to "auto" then value of _ColorRange frame property is used
 +
 +
: Note: old-style "matrix" parameters are kept, their name indicate the full/limited
 +
 +
: For memo and the similar new string
 +
:*  "rec601" same as        "470bg:l"
 +
:*  "rec709"                "709:l"
 +
:*  "pc.601" and "pc601"    "470bg:f"
 +
:*  "pc.709" and "pc709"    "709:f"
 +
:*  "average"                - kept for compatibility, really it has no standard _Matrix equivalent
 +
:*  "rec2020"                "2020cl:l"
 +
:*  "pc.2020" and "pc2020"  "2020cl:f"
 +
 +
  
 
{{HiddenH5|Interlaced}}
 
{{HiddenH5|Interlaced}}
Line 303: Line 334:
 
{{Par2|ChromaInPlacement|string|"MPEG2"}}
 
{{Par2|ChromaInPlacement|string|"MPEG2"}}
 
{{Par2|ChromaOutPlacement|string|"MPEG2"}}
 
{{Par2|ChromaOutPlacement|string|"MPEG2"}}
:{{FuncArg|ChromaInPlacement}} determines the chroma placement in the clip when converting ''from'' YV12.
+
:{{FuncArg|ChromaInPlacement}} determines the chroma placement in the clip when converting ''from'' YV12 (4:2:0) or YV16 (4:2:2) {{AvsPluscon}}.
:{{FuncArg|ChromaOutPlacement}} determines the chroma placement in the clip when converting ''to'' YV12.
+
:{{FuncArg|ChromaOutPlacement}} determines the chroma placement in the clip when converting ''to'' YV12 (4:2:0) or YV16 (4:2:2) {{AvsPluscon}}.
 
:The placement can be one of these strings:
 
:The placement can be one of these strings:
 
:{|class="wikitable" width="600"
 
:{|class="wikitable" width="600"
 
|-
 
|-
|"MPEG2"&nbsp;
+
|"MPEG2"&nbsp; ( {{AvsPluscon}} synonyms: "left")
 
|Subsampling used in MPEG-2 4:2:''x'' and most other formats. Chroma samples are located on the left pixel column of the group&nbsp;(default).  
 
|Subsampling used in MPEG-2 4:2:''x'' and most other formats. Chroma samples are located on the left pixel column of the group&nbsp;(default).  
 
|-
 
|-
|"MPEG1"
+
|"MPEG1" ( {{AvsPluscon}} synonyms: "jpeg", "center")
 
|Subsampling used in MPEG-1 4:2:0. Chroma samples are located on the center of each group of 4 pixels.
 
|Subsampling used in MPEG-1 4:2:0. Chroma samples are located on the center of each group of 4 pixels.
 
|-
 
|-
 
|"DV"
 
|"DV"
 
| Like MPEG-2, but U and V channels are “co-sited” vertically: V on the top row, and U on the bottom row. For 4:1:1, chroma is located on the leftmost column.
 
| Like MPEG-2, but U and V channels are “co-sited” vertically: V on the top row, and U on the bottom row. For 4:1:1, chroma is located on the leftmost column.
 +
|-
 +
|"top_left"&nbsp; {{AvsPluscon}}
 +
|Subsampling used in UHD 4:2:0. Chroma samples are located on the top left pixel column of the group&nbsp;.
 +
|-
 +
|"bottom_left"&nbsp; {{AvsPluscon}}
 +
|4:2:0 only
 +
|-
 +
|"bottom"&nbsp; {{AvsPluscon}}
 +
|4:2:0 only
 +
|-
 
|}
 
|}
  
Line 321: Line 362:
 
{{Par2|chromaresample|string|"bicubic"}}
 
{{Par2|chromaresample|string|"bicubic"}}
 
:Determines which chroma resampler is used in the conversion. Only used when the chroma resolutions of the source and target are different. All AviSynth [[Resize|resizers]] are allowed ("point", "bilinear", "bicubic", "lanczos", "lanczos4", "blackman", "spline16", "spline36", "spline64", "gauss" and "sinc"). Default is "bicubic".
 
:Determines which chroma resampler is used in the conversion. Only used when the chroma resolutions of the source and target are different. All AviSynth [[Resize|resizers]] are allowed ("point", "bilinear", "bicubic", "lanczos", "lanczos4", "blackman", "spline16", "spline36", "spline64", "gauss" and "sinc"). Default is "bicubic".
</div>
 
  
 
==== Notes ====
 
==== Notes ====
 
<div style="max-width:62em" >
 
<div style="max-width:62em" >
 +
===== Frame properties {{AvsPluscon}} =====
 +
 +
In Avisynth v3.7.1. frame property (_ChromaLocation) support appears in selected filters (e.g. ConvertToYUV422).
 +
Property can be read and/or set.
 +
A frame property can replace default behaviour of location parameters and is set (or deleted) upon finishing conversion.
 +
Since a format without subsampling such as 4:4:4 (YV24) does not have chroma location, the property is deleted automatically when converting to 4:4:4 or RGB.
 +
 +
: "ChromaInLocation" rules:
 +
::* if source has _ChromaLocation frame property it will be used else the default is "mpeg2" ("left")
 +
::* if parameter is "auto" or not given at all, ChromaInLocation will be set to the above mentioned default value
 +
::* if parameter is explicitely given, it will be used
 +
 +
: "ChromaOutLocation" rules:
 +
::* default is "mpeg2" ("left")
 +
::* if parameter is "auto" or not given at all, ChromaOutLocation will be set to the above mentioned default value
 +
::* if parameter is explicitely given, it will be used
 +
 +
: Accepted values for "ChromaInLocation" and "ChromaOutLocation" (when source/target is a chroma subsampled format)
 +
: (full list):
 +
::* "left" or "mpeg2"
 +
::* "center" or "jpeg" or "mpeg1"
 +
::* "top_left"
 +
::* "dv"
 +
::* "top"
 +
::* "bottom_left"
 +
::* "bottom"
 +
 +
: _ChromaLocation constants - as seen in propShow()
 +
 
 +
::* AVS_CHROMA_LEFT        = 0
 +
::* AVS_CHROMA_CENTER      = 1
 +
::* AVS_CHROMA_TOP_LEFT    = 2 (4:2:0 only)
 +
::* AVS_CHROMA_TOP        = 3 (4:2:0 only)
 +
::* AVS_CHROMA_BOTTOM_LEFT = 4 (4:2:0 only)
 +
::* AVS_CHROMA_BOTTOM      = 5 (4:2:0 only)
 +
::* AVS_CHROMA_DV          = 6  Special to Avisynth
 +
 
===== Conversion paths =====
 
===== Conversion paths =====
  
Line 347: Line 424:
 
:[[Color_conversions|'''[This page]''']] covers the color conversions in more detail.
 
:[[Color_conversions|'''[This page]''']] covers the color conversions in more detail.
 
</div>
 
</div>
 
  
 
==== Changelog ====
 
==== Changelog ====
 
<div style="max-width:62em" >
 
<div style="max-width:62em" >
 
{| border="1"
 
{| border="1"
 +
|-
 +
| v3.7.1
 +
| Added ChromaOutPlacement to 4:2:2 related functions<br>Added new matrix constants, optional new syntax<br>Added new chroma location constants<br>Added _ChromaLocation frame property
 
|-  
 
|-  
 
| v2.60
 
| v2.60

Latest revision as of 15:00, 9 December 2021

Convert between any of the color formats that AviSynth supports:

Color format  Image format  Bit depth  Sample ratio   Description
RGB24 interleaved 8 4:4:4 (full chroma)
RGB32 interleaved 8 4:4:4:4 (full chroma + alpha)
YV24 planar 8 4:4:4 (full chroma)
YV16 planar 8 4:2:2 (chroma shared between 2 pixels)
YUY2 interleaved 8 4:2:2 (chroma shared between 2 pixels)
YV12 planar 8 4:2:0 (chroma shared between 2x2 pixels) 
YV411 planar 8 4:1:1 (chroma shared between 4 pixels)
Y8 (both) 8 4:0:0 (no chroma)
  (♦ = not supported in AviSynth version 2.58 or below)

AVS+ supports all of the above, plus:

Color format  Image format  Bit depth  Sample ratio   Description
RGB48 interleaved 16 4:4:4 (full chroma)
RGB64 interleaved 16 4:4:4:4 (full chroma + alpha)
RGBPxx planar 8-16, 32 *  4:4:4 (full chroma)
RGBAPxx planar 8-16, 32 *  4:4:4:4 (full chroma + alpha)
YUV444Pxx planar 8-16, 32 *  4:4:4 (full chroma)
YUVA444Pxx planar 8-16, 32 *  4:4:4:4 (full chroma + alpha)
YUV422Pxx planar 8-16, 32 *  4:2:2 (chroma shared between 2 pixels)
YUVA422Pxx planar 8-16, 32 *  4:2:2:4 (chroma shared between 2 pixels + alpha)
YUV420Pxx planar 8-16, 32 *  4:2:0 (chroma shared between 2x2 pixels) 
YUVA420Pxx planar 8-16, 32 *  4:2:0:4 (chroma shared between 2x2 pixels + alpha) 
Y10..Y32 (both) 10-16, 32 *  4:0:0 (no chroma)
  * 8-16 = 8,10,12,14,16 bit integer;  32 = 32 bit float


When the target format is the same as the source format, the original clip will be returned unchanged, except for the case of ConvertToYV12 where the ChromaInPlacement and ChromaOutPlacement parameters are different.

There is no unique way of converting YUV to RGB or vice-versa. There are different conversion matrices in use; the two most common ones are available in AviSynth, namely Rec.601 and Rec.709, plus some others. The following should be correct in most cases (see here for more)
  • Rec.601 should be used when your source is standard definition (usually defined as smaller than 720p):
ConvertToRGB(clip) (using default "Rec601")
  • Rec.709 should be used when your source is DVD or HDTV:
ConvertToRGB(clip, matrix="Rec709")
  • The special-purpose matrices PC.601 and PC.709 keep the range unchanged,
instead of converting between 0d-255d RGB and 16d-235d YUV, as is the normal practice.
  • The special-purpose matrix AVERAGE is used for (rarely found) sources with unweighted luma,
where Y = (R + G + B) / 3.

Note ConvertToRGB always converts to RGB32 – unless your source is RGB24, in which case no conversion is done. If you need 24-bit RGB for some reason, use ConvertToRGB24 explicitly.

Use ConvertBackToYUY2 to convert back to YUY2 with minimal color-blurring when you have previously applied a YUY2→RGB conversion.

AVS+ See also ConvertBits to convert between bit depths and/or between full-limited range.

Contents


Syntax and Parameters

RGB interleaved

ConvertToRGB(clip [, string matrix, bool interlaced,
     string ChromaInPlacement,
     string chromaresample] )

ConvertToRGB24(clip [, string matrix, bool interlaced,
     string ChromaInPlacement,
     string chromaresample] )

ConvertToRGB32(clip [, string matrix, bool interlaced,
     string ChromaInPlacement,
     string chromaresample] )

ConvertToRGB48(clip, [ string matrix, bool interlaced,
     string ChromaInPlacement,
      string chromaresample ] ) AVS+

ConvertToRGB64(clip, [ string matrix, bool interlaced,
     string ChromaInPlacement,
     string chromaresample ] ) AVS+

RGB planar

ConvertToPlanarRGB(clip, [ string matrix, bool interlaced,
     string ChromaInPlacement,
     string chromaresample ] ) AVS+

ConvertToPlanarRGBA(clip, [ string matrix, bool interlaced,
     string ChromaInPlacement,
     string chromaresample ] ) AVS+

YUV444

ConvertToYV24(clip [, bool interlaced, string matrix,
     string ChromaInPlacement,
     string chromaresample] )

ConvertToYUV444(clip, [ string matrix, bool interlaced,
     string ChromaInPlacement,
     string chromaresample ] ) AVS+

YUV422

ConvertToYV16(clip [, bool interlaced, string matrix,
     string ChromaInPlacement,
     string chromaresample,
     string ChromaOutPlacement AVS+ ] )

ConvertToYUY2(clip [, bool interlaced, string matrix,
     string ChromaInPlacement,
     string chromaresample] )

ConvertToYUV422(clip, [ string matrix, bool interlaced,
     string ChromaInPlacement,
     string chromaresample,
     string ChromaOutPlacement] ) AVS+

ConvertBackToYUY2(clip [, string matrix ] )

YUV420

ConvertToYV12(clip [, bool interlaced, string matrix,
     string ChromaInPlacement,
     string chromaresample,
     string ChromaOutPlacement] )

ConvertToYUV420(clip, [ string matrix, bool interlaced,
     string ChromaInPlacement,
     string chromaresample,
     string ChromaOutPlacement ] ) AVS+

YUV411

ConvertToYV411(clip [, bool interlaced, string matrix,
     string ChromaInPlacement,
     string chromaresample] )

Y-only

ConvertToY8(clip [, string matrix] )
ConvertToY(clip, [ string matrix ] ) AVS+

Parameter Details

Matrix

string  matrix = "Rec601"

Controls the colour coefficients and scaling factors used in RGB↔YUV conversions.
  • "Rec601"  : Uses Rec.601 coefficients; scale full range [0d..255d] RGB ↔ TV range [16d..235d] YUV.
  • "Rec709"  : Uses Rec.709 (HD) coefficients; scale full range RGB ↔ TV range YUV.
  • "Rec2020" : Uses Rec.2020 (UHD) coefficients; scale full range RGB ↔ TV range YUV. AVS+
  • "PC.2020" : Uses Rec.2020 (UHD) coefficients; keep range unchanged. AVS+
  • "PC.601"  : Uses Rec.601 coefficients; keep range unchanged.
  • "PC.709"  : Uses Rec.709 (HD) coefficients; keep range unchanged.
  • "Average"  : Uses averaged coefficients (the luma becomes the average of the RGB channels); keep range unchanged.

AVS+

New syntax: more matrix string constants with separate full/limited range markers
"matrixname:full_or_limited" where
"matrixname" can be (internal _Matrix integer constant in parenthesys)
  • "rgb" (0 - AVS_MATRIX_RGB)
  • "709" (1 - AVS_MATRIX_BT709)
  • "unspec" (2 - AVS_MATRIX_UNSPECIFIED)
  • "170m" (6 - AVS_MATRIX_ST170_M)
  • "240m" (7 - AVS_MATRIX_ST240_M)
  • "470bg" (5 - AVS_MATRIX_BT470_BG)
  • "601" (5 - AVS_MATRIX_BT470_BG)
  • "fcc" (4 - AVS_MATRIX_BT470_M)
  • "bt470m" (4 - AVS_MATRIX_BT470_M)
  • "ycgco" (8 - AVS_MATRIX_YCGCO not supported)
  • "2020ncl" (9 - AVS_MATRIX_BT2020_NCL)
  • "2020" (9 - AVS_MATRIX_BT2020_NCL)
  • "2020cl" (10 - AVS_MATRIX_BT2020_CL same as 2020ncl)
  • "chromacl" (13 - AVS_MATRIX_CHROMATICITY_DERIVED_CL not supported)
  • "chromancl" (12 - AVS_MATRIX_CHROMATICITY_DERIVED_NCL not supported)
  • "ictcp" (14 - AVS_MATRIX_ICTCP not supported)
The above "matrix" parameters can be followed by a "full" or "f" and "limited" or "l" or "auto" marker after a ":"

e.g. "709:f" means the same as the old "PC.709"

When there is no limited-ness marker, or is set to "auto" then value of _ColorRange frame property is used
Note: old-style "matrix" parameters are kept, their name indicate the full/limited
For memo and the similar new string
  • "rec601" same as "470bg:l"
  • "rec709" "709:l"
  • "pc.601" and "pc601" "470bg:f"
  • "pc.709" and "pc709" "709:f"
  • "average" - kept for compatibility, really it has no standard _Matrix equivalent
  • "rec2020" "2020cl:l"
  • "pc.2020" and "pc2020" "2020cl:f"


Interlaced

bool  interlaced = false

If true, it is assumed that clip is interlaced; by default, it is assumed to be progressive.
This option is needed because for example, the following (assuming clip is interlaced YV12):
SeparateFields(clip)
ConvertToYUY2
Weave
...is upsampled incorrectly. Instead it is better to use:
ConvertToYUY2(clip, interlaced=true)
Note, interlaced=true has an effect only on YV12↔YUY2 or YV12↔RGB conversions. More about that can be found here.
Chroma placement

string  ChromaInPlacement = "MPEG2"
string  ChromaOutPlacement = "MPEG2"

ChromaInPlacement determines the chroma placement in the clip when converting from YV12 (4:2:0) or YV16 (4:2:2) AVS+.
ChromaOutPlacement determines the chroma placement in the clip when converting to YV12 (4:2:0) or YV16 (4:2:2) AVS+.
The placement can be one of these strings:
"MPEG2"  ( AVS+ synonyms: "left") Subsampling used in MPEG-2 4:2:x and most other formats. Chroma samples are located on the left pixel column of the group (default).
"MPEG1" ( AVS+ synonyms: "jpeg", "center") Subsampling used in MPEG-1 4:2:0. Chroma samples are located on the center of each group of 4 pixels.
"DV" Like MPEG-2, but U and V channels are “co-sited” vertically: V on the top row, and U on the bottom row. For 4:1:1, chroma is located on the leftmost column.
"top_left"  AVS+ Subsampling used in UHD 4:2:0. Chroma samples are located on the top left pixel column of the group .
"bottom_left"  AVS+ 4:2:0 only
"bottom"  AVS+ 4:2:0 only
Chroma resample

string  chromaresample = "bicubic"

Determines which chroma resampler is used in the conversion. Only used when the chroma resolutions of the source and target are different. All AviSynth resizers are allowed ("point", "bilinear", "bicubic", "lanczos", "lanczos4", "blackman", "spline16", "spline36", "spline64", "gauss" and "sinc"). Default is "bicubic".

Notes

Frame properties AVS+

In Avisynth v3.7.1. frame property (_ChromaLocation) support appears in selected filters (e.g. ConvertToYUV422). Property can be read and/or set. A frame property can replace default behaviour of location parameters and is set (or deleted) upon finishing conversion. Since a format without subsampling such as 4:4:4 (YV24) does not have chroma location, the property is deleted automatically when converting to 4:4:4 or RGB.

"ChromaInLocation" rules:
  • if source has _ChromaLocation frame property it will be used else the default is "mpeg2" ("left")
  • if parameter is "auto" or not given at all, ChromaInLocation will be set to the above mentioned default value
  • if parameter is explicitely given, it will be used
"ChromaOutLocation" rules:
  • default is "mpeg2" ("left")
  • if parameter is "auto" or not given at all, ChromaOutLocation will be set to the above mentioned default value
  • if parameter is explicitely given, it will be used
Accepted values for "ChromaInLocation" and "ChromaOutLocation" (when source/target is a chroma subsampled format)
(full list):
  • "left" or "mpeg2"
  • "center" or "jpeg" or "mpeg1"
  • "top_left"
  • "dv"
  • "top"
  • "bottom_left"
  • "bottom"
_ChromaLocation constants - as seen in propShow()
  • AVS_CHROMA_LEFT = 0
  • AVS_CHROMA_CENTER = 1
  • AVS_CHROMA_TOP_LEFT = 2 (4:2:0 only)
  • AVS_CHROMA_TOP = 3 (4:2:0 only)
  • AVS_CHROMA_BOTTOM_LEFT = 4 (4:2:0 only)
  • AVS_CHROMA_BOTTOM = 5 (4:2:0 only)
  • AVS_CHROMA_DV = 6 Special to Avisynth
Conversion paths
In v2.60 the following conversion paths occur:
  • YUV planar → RGB via YV24
  • YUV planar → YUY2 via YV16
(except for YV12 and chroma options listed above not explicitly set; in that case there is a direct conversion from YV12 to YUY2)
  • RGB → YUV planar via YV24
  • YUY2 → YUV planar via YV16
(except for YV12 and chroma options listed above not explicitly set; in that case there is a direct conversion from YUY2 to YV12)
The chroma options chromaresample, ChromaInPlacement and ChromaOutPlacement are only used in the 'planar conversion' part of the conversion path.
Suppose you have a YUY2 clip for example and you convert it to YV24. The YUY2 will be converted to YV16 first without applying the chroma options. Then YV16 will be converted to YV24 while applying chromaresample. Since YV12 is not involved, ChromaInPlacement and ChromaOutPlacement won't be used.
Sampling
[This page] covers the sampling methods and color formats in more detail.
Color conversions
[This page] covers the color conversions in more detail.

Changelog

v3.7.1 Added ChromaOutPlacement to 4:2:2 related functions
Added new matrix constants, optional new syntax
Added new chroma location constants
Added _ChromaLocation frame property
v2.60 Added ConvertToY8, ConvertToYV411, ConvertToYV16, ConvertToYV24, ChromaInPlacement, ChromaOutPlacement, chromaresample, matrix="AVERAGE".
v2.50 Added ConvertToYV12.
Personal tools