ColorYUV

From Avisynth wiki
(Difference between revisions)
Jump to: navigation, search
(arg units conversion function)
m (typo)
(33 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Template:FuncDef|ColorYUV(clip [, float ''gain_y''] [, float ''off_y''] [, float ''gamma_y''] [, float ''cont_y''] [, float ''gain_u''] [, float ''off_u''] [, float ''gamma_u''] [, float ''cont_u''] [, float ''gain_v''] [, float ''off_v''] [, float ''gamma_v''] [, float ''cont_v''] [, string ''levels''] [, string ''opt''] [, boolean ''showyuv''] [, boolean ''analyze''] [, boolean ''autowhite''] [, boolean ''autogain''] [, boolean ''conditional''])}}
+
<div style="max-width:62em" >
 +
'''ColorYUV''' has many different methods of changing the color and luminance of your images. Gain, offset, gamma and contrast can be set independently on each channel. Also included are two 'auto' modes, an analysis function and a color gamut generator.
  
== Description: ==
+
All settings for this filter are optional. All values are defaulting to "0" or false.
  
ColorYUV allows many different methods of changing the color and luminance of your images. It is present in AviSynth from version 2.5. All settings for this filter are optional. All values are defaulting to "0" or false. Gain, offset, gamma and contrast can be set independently on each channel.
+
[[RGBAdjust]] works in a similar manner for [[RGB]] clips.
  
'''gain''' is a multiplier for the value, and it stretches the signal up from the bottom. In order to confuse you, in the filter [[Tweak]] this setting is called ''contrast''. That means that if the gain is set to 0, it preserves the values as they are. When gain is 256 all values are multiplied by 2 (twice as bright). If the gain is 512 all values are multiplied by 3. Thus if gain = k*256 for some integer k then Y becomes (k+1)*Y (idem for the chroma). Although it is possible, it doesn't make sense to apply this setting to the chroma of the signal.
+
* In AviSynth 2.6, all [[YUV]] color formats are supported ([[Y8]], [[YV12]], [[YV16]], [[YV24]], [[YV411]] and [[YUY2]])
 +
* {{AvsPluscon}} all [[YUV]] and [[YUVA]] color formats are supported, including [[Float_(color_format)|Float]].
 +
* {{AvsPluscon}} all relevant parameters are [[Autoscale_parameter|autoscaling]] &ndash; they work without changes at all bit depths.
  
'''off''' (offset) adds a value to the luma or chroma values. An offset set to 16 will add 16 to the pixel values.  An offset of -32 will subtract 32 from all pixel values.
 
  
'''gamma''' adjusts gamma of the specified channel. A ''gamma'' value of 0 is the same as gamma 1.0.  When ''gamma'' is set to 256 it is the same as gamma 2.0. ''gamma'' is valid down to -256, where it is the same as gamma 0.0. Note: gamma for chroma is not implemented (gamma_u and gamma_v are dummy parameters).
 
  
'''cont''' (contrast) is also multiplier for the value, and for the chroma components it stretches the signal out from the center. That means that if the contrast is set to 0, it preserves the values as they are. When the contract is set to 256, the relevant chroma value is set to 128. When the contrast is 256 all values (taken from the center) are multiplied by 2 (twice as bright). If the contrast is 512 all values (taken from the center) are multiplied by 3. Thus if cont = (k-1)*256 for some integer k (and zero gain) then U becomes 128 + k*(U-128) (V likewise). Although it is possible, it doesn't make sense to apply this setting to the luma of the signal.
+
__TOC__
 +
</div>
  
'''levels''' can be set to either "TV->PC" or "PC->TV". This will perform a range conversion. Normally YUV values are not mapped from 0 to 255 (PC range), but a limited range(TV range). This performs conversion between the two formats. If no parameter is specified, no conversion will be made (default operation).
+
== Syntax and Parameters ==
 +
<div style="max-width:62em" >
 +
{{FuncDef
 +
|ColorYUV(clip [, <br>
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;float ''gain_y'', float ''off_y'', float ''gamma_y'', float ''cont_y'',<br>
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;float ''gain_u'', float ''off_u'', float ''gamma_u'', float ''cont_u'',<br>
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;float ''gain_v'', float ''off_v'', float ''gamma_v'', float ''cont_v'',<br>
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''levels'', string ''opt'', bool ''showyuv'', bool ''analyze'',<br>
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bool ''autowhite'', bool ''autogain'', bool ''conditional'' ] )}} <br>
 +
{{FuncDef
 +
|ColorYUV(clip [, <br>
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;float ''gain_y'', float ''off_y'', float ''gamma_y'', float ''cont_y'',<br>
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;float ''gain_u'', float ''off_u'', float ''gamma_u'', float ''cont_u'',<br>
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;float ''gain_v'', float ''off_v'', float ''gamma_v'', float ''cont_v'',<br>
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;string ''levels'', string ''opt'', bool ''showyuv'', bool ''analyze'',<br>
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bool ''autowhite'', bool ''autogain'', bool ''conditional'',<br>
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int ''bits'', bool ''showyuv_fullrange'', bool ''f2c'' ] )}} {{AvsPluscon}}
  
'''opt''' can be either "coring" or "" (nothing, default setting). Specifying "coring" will clip your YUV values to the valid TV-ranges. Otherwise "invalid results" will be accepted.
+
:{{Par2|gain_y|float|0}}
 +
:{{Par2|gain_u|float|0}}
 +
:{{Par2|gain_v|float|0}}
 +
::A multiplier for the ''Y'', ''U'' or ''V'' value.
 +
::If {{FuncArg|gain_y}} = {{Serif|''k''}}, then ''Y'' becomes ''Y'' '''·''' ({{Serif|''k''}} / 256 + 1) – for example:
 +
::('''TL;DR''' ''see [[#Parameter_Rescaling|Parameter Rescaling]] below'')
 +
::{|class="wikitable"
 +
!style="padding:0.3em;width:4em;text-align:left;"| {{FuncArg|gain_}}''x''
 +
!style="padding:0.3em;width:8em;text-align:center;"| &rarr;
 +
!style="padding:0.3em;"| multiplier
 +
|-
 +
|style="text-align:right;padding:0.3em;"| &nbsp;&nbsp;-256
 +
|style="text-align:right;padding:0.3em;"| (-256 / 256) + 1
 +
|style="text-align:left;padding:0.3em;"| 0.0 (no output)
 +
|-
 +
|style="text-align:right;padding:0.3em;"| -128
 +
|style="text-align:right;padding:0.3em;"| (-128 / 256) + 1
 +
|style="text-align:left;padding:0.3em;"| 0.5 (darker)
 +
|-
 +
|style="text-align:right;padding:0.3em;"| 0
 +
|style="text-align:right;padding:0.3em;"| (0 / 256) + 1
 +
|style="text-align:left;padding:0.3em;"| 1.0 (no change)
 +
|-
 +
|style="text-align:right;padding:0.3em;"| 256
 +
|style="text-align:right;padding:0.3em;"| (256 / 256) + 1
 +
|style="text-align:left;padding:0.3em;"| 2.0 (brighter)
 +
|-
 +
|style="text-align:right;padding:0.3em;"| 512
 +
|style="text-align:right;padding:0.3em;"| (512 / 256) + 1
 +
|style="text-align:left;padding:0.3em;"| 3.0
 +
|}
 +
::*{{FuncArg|gain_}}''x'' is valid down to -256, where a gain of 0.0 is applied.
 +
::*Although it is possible, it doesn't make sense to apply this setting to the chroma of the signal.
 +
::*In order to confuse you, in the filter [[Tweak]] this setting is called ''contrast''.  
  
'''showYUV''' can be true or false. This will overwrite your image with an image showing all chroma values along the two axes. This can be useful if you need to adjust the color of your image, but need to know how the colors are arrangedAt the topleft of the image, the chroma values are '16'. At the right side of the image, U is at maximum.  At the bottom of the screen V is at its maximum.  In the middle both chroma is 128 (or grey).
+
:{{Par2|off_y|float|0}}
 +
:{{Par2|off_u|float|0}}
 +
:{{Par2|off_v|float|0}}
 +
::Adds an ''offset'' to the luma or chroma values.  
 +
::*An {{FuncArg|off_}}''x'' of 16 will add 16{{D}} to all pixel values.   
 +
::*An {{FuncArg|off_}}''x'' of -32 will subtract 32{{D}} from all pixel values.
  
'''analyze''' can be true or false. This will print out color statistics on the screen. There are maximum and minimum values for all channels. There is an average for all channels. There is a "loose maximum" and "loose minimum". The "loose" values are made to filter out very bright or very dark noise creating an artificially low or high minimum / maximum.
+
:{{Par2|gamma_y|float|0}}
 +
:{{Par2|gamma_u|float|0}}
 +
:{{Par2|gamma_v|float|0}}
 +
::Adjusts [[Wikipedia:Gamma_correction|gamma]] of the specified channel,
 +
:: as ''X''{{Sup2|(1/{{Template:Serif|g}})}} where {{Serif|''g''}}=({{FuncArg|gamma_}}''x'' + 256) / 256 &ndash; for example:
 +
:: ('''TL;DR''' ''see [[#Parameter_Rescaling|Parameter Rescaling]] below'')
 +
::{|class="wikitable"
 +
!style="padding:0.3em;width:4em;text-align:left;"| {{FuncArg|gamma_}}''x''
 +
!style="padding:0.3em;width:8em;text-align:center;"| &rarr;
 +
!style="padding:0.3em;"| gamma
 +
|-
 +
|style="text-align:right;padding:0.3em;"| &nbsp;&nbsp;-256
 +
|style="text-align:right;padding:0.3em;"| (-256 / 256) + 1
 +
|style="text-align:left;padding:0.3em;"| 0.01
 +
|-
 +
|style="text-align:right;padding:0.3em;"| -128
 +
|style="text-align:right;padding:0.3em;"| (-128 / 256) + 1
 +
|style="text-align:left;padding:0.3em;"| 0.5 (darker)
 +
|-
 +
|style="text-align:right;padding:0.3em;"| 0
 +
|style="text-align:right;padding:0.3em;"| (0 / 256) + 1
 +
|style="text-align:left;padding:0.3em;"| 1.0 (no change)
 +
|-
 +
|style="text-align:right;padding:0.3em;"| 256
 +
|style="text-align:right;padding:0.3em;"| (256 / 256) + 1
 +
|style="text-align:left;padding:0.3em;"| 2.0 (lighter)
 +
|-
 +
|style="text-align:right;padding:0.3em;"| 512
 +
|style="text-align:right;padding:0.3em;"| (512 / 256) + 1
 +
|style="text-align:left;padding:0.3em;"| 3.0
 +
|}
 +
::*{{FuncArg|gamma_}}''x'' is valid down to -256, where a minimal gamma of 0.01 is applied (gamma cannot be zero)
 +
::*'''Note:''' gamma for chroma is not implemented (''gamma_u'' and ''gamma_v'' are dummy parameters).
 +
::*{{AvsPluscon}} will operate on TV range instead of the default PC range when the input clip is known to be in TV range:
 +
:::*{{FuncArg|levels}}="TV->PC", or {{FuncArg|levels}}="TV", 
 +
:::*or {{FuncArg|opt}}="coring" and {{FuncArg|levels}} is ''not'' "PC->TV" or "PC->TV.Y"
  
'''autowhite''' can be true or false. This setting will use the information from the analyzer, and attempt to center the color offsets. If you have recorded some material, where the colors are shifted toward one color, this filter may help. But be careful - it isn't very intelligent - if your material is a clear blue sky, autowhite will make it completely grey! If you add "off_u" or "off_v" parameters at the same time as autowhite, they will not be used!
+
:{{Par2|cont_y|float|0}}
 +
:{{Par2|cont_u|float|0}}
 +
:{{Par2|cont_v|float|0}}
 +
::Like {{FuncArg|gain_}}''X'', a multiplier for the value, but stretches or shrinks the signal from the center (128{{D}}).
 +
::This is most useful for the chroma components, where it translates to saturation.  
 +
::If {{FuncArg|cont_y}} = {{Serif|''k''}}, then ''Y'' becomes (''Y''-128) '''·''' {{Serif|''k''}} / 256 + 128 &ndash; for example:
 +
:: ('''TL;DR''' ''see [[#Parameter_Rescaling|Parameter Rescaling]] below'')
 +
::{|class="wikitable"
 +
!style="padding:0.3em;width:4em;text-align:left;"| {{FuncArg|cont_}}''x''
 +
!style="padding:0.3em;width:8em;text-align:center;"| &rarr;
 +
!style="padding:0.3em;"| contrast
 +
|-
 +
|style="text-align:right;padding:0.3em;"| &nbsp;&nbsp;-256
 +
|style="text-align:right;padding:0.3em;"| (-256 / 256) + 1
 +
|style="text-align:left;padding:0.3em;"| 0.0 (zero contrast)
 +
|-
 +
|style="text-align:right;padding:0.3em;"| -128
 +
|style="text-align:right;padding:0.3em;"| (-128 / 256) + 1
 +
|style="text-align:left;padding:0.3em;"| 0.5 (less contrast)
 +
|-
 +
|style="text-align:right;padding:0.3em;"| 0
 +
|style="text-align:right;padding:0.3em;"| (0 / 256) + 1
 +
|style="text-align:left;padding:0.3em;"| 1.0 (no change)
 +
|-
 +
|style="text-align:right;padding:0.3em;"| 256
 +
|style="text-align:right;padding:0.3em;"| (256 / 256) + 1
 +
|style="text-align:left;padding:0.3em;"| 2.0 (more contrast)
 +
|-
 +
|style="text-align:right;padding:0.3em;"| 512
 +
|style="text-align:right;padding:0.3em;"| (512 / 256) + 1
 +
|style="text-align:left;padding:0.3em;"| 3.0
 +
|}
 +
::*{{FuncArg|cont_}}''x'' is valid down to -256, where the signal is set to 128{{D}}.
 +
::*Although it is possible, it doesn't make sense to apply this setting to the luma of the signal.
  
'''autogain''' can be true or false. This setting will use the information from the analyzer, and attempt to create as good contrast as possible. That means, it will scale up the luma (y) values to match the minimum and maximum values. This will make it act much as an "autogain" setting on cameras, amplifying dark scenes very much, while leaving scenes with good contrast alone. Some places this is also refered to as "autolevels".
+
:{{Par2|levels|string|""}}
 +
::Can be "<tt>TV->PC</tt>", "<tt>PC->TV</tt>", "<tt>PC->TV.Y</tt>" or nothing (default)
 +
::*If {{FuncArg|levels}}="<tt>TV->PC</tt>", a 16{{D}}-235{{D}} &rarr; 0{{D}}-255{{D}} (contrast increasing) conversion is made
 +
::*If {{FuncArg|levels}}="<tt>PC->TV</tt>", a 0{{D}}-255{{D}} &rarr; 16{{D}}-235{{D}} (contrast decreasing) conversion is made
 +
::*If {{FuncArg|levels}}="<tt>PC->TV.Y</tt>", a 0{{D}}-255{{D}} &rarr; 16{{D}}-235{{D}} (contrast decreasing) conversion is made, on luma channel only
 +
::*By default, no conversion is made
 +
::{{AvsPluscon}} adds "<tt>TV</tt>", which does no conversion; it only tells the filter that {{FuncArg|gamma}}''_x'' will operate on a TV range clip.
  
'''conditional''' can be true or false (false by default). When set to false, it will make ColorYUV ignore any given conditional variables. See the "Conditional Variables" section for an overview of the conditional variables.
+
:{{Par2|opt|string|""}}
 +
::Can be either "coring" or "" (nothing, default setting).  
 +
::Specifying "coring" will clip your YUV values to the "TV" range (luma 16{{D}}-235{{D}}, chroma 16{{D}}-240{{D}}). Otherwise values outside that range will be accepted.
  
The quantities saturation, contrast and brightness (as in Tweak for example) are connected with quantities in this filter by the following equations:
+
:{{Par2|showyuv|bool|false}}
 +
::If ''true, ''this option will overwrite your image with a new 448x448 image showing all chroma values along the two axes. This can be useful if you need to adjust the color of your image, but need to know how the colors are arranged.  At the top left of the image, the chroma values are 16{{D}}. At the right side of the image, U is at maximum.  At the bottom of the screen V is at its maximum.  In the middle both chroma is 128{{D}} (or grey). See example image [[#Examples:|below]].
 +
::{{AvsPluscon}} Size changes depending on options selected &ndash; see {{FuncArg|showyuv_fullrange}} below
 +
::If {{FuncArg|bits}}=8, output colorspace is [[YV12]], else colorspace is [[Avisynthplus_color_formats|YUV422P16]].
  
<code>
+
:{{Par2|analyze|bool|false}}
cont_u = cont_v = (sat-1) * 256
+
::If true, '''ColorYUV''' will print color channel statistics on the screen (see [[#analyze|example below]])
gain_y = (cont-1) * 256
+
::*There is an '''Average''' for all channels.
off_y = bright
+
::*There are '''Minimum''' and '''Maximum''' values for all channels.
</code>
+
::*There is '''Loose Minimum''' and '''Loose Maximum''' which ignore the brightest and darkest 0.4% (1/256) pixels.
  
A saturation of 0.8 gives for example: cont_u = cont_v = - 0.2 * 256 = -51.2. Note that in [[Tweak]] your YUV values will always be clipped to valid TV-ranges, but here you have to specify opt="coring".
+
:{{Par2|autowhite|bool|false}}
 +
::If ''true, ''this option will use the information from the analyzer, and attempt to center the color offsets. If you have recorded some material, where the colors are shifted toward one color, this filter may help. But be careful - it isn't very intelligent - if your material is a clear blue sky, {{FuncArg|autowhite}} will make it completely grey! This option overrides {{FuncArg|off_u|}} and {{FuncArg|off_v}}.
  
You can add a simple [[User_defined_script_functions|user function]] to translate from familiar "Tweak-like" units to ColorYUV units:
+
:{{Par2|autogain|bool|false}}
ColorYUV(gain_y=256, cont_u=+51, cont_v=-51)
+
::If ''true, ''this option will use the information from the analyzer, and attempt to create as good contrast as possible. That means, it will scale up the ''Y ''(luma) values to match the minimum and maximum values. This will make it act like an "autogain" setting on cameras, amplifying dark scenes very much, while leaving scenes with good contrast alone. Some places this is also referred to as "autolevels".
+
 
## this statement is equivalent to the one above:
+
:{{Par2|conditional|bool|false}}
  ColorYUV(gain_y=f2c(2.0), cont_u=f2c(1.2), cont_v=f2c(0.8))  
+
::See the [[#Conditional_Variables|Conditional Variables]] section for an overview of the conditional variables and their use with '''ColorYUV'''. If ''false'' (the default), '''ColorYUV''' will ignore any conditional variables.
+
 
## scale ColorYUV arguments (1.0 = unity in/out)
+
:{{Par2|bits|int|8}}
 +
::{{AvsPluscon}} Sets the bit depth of {{FuncArg|showyuv}} output. Must be 8, 10, 12, 14 or 16.
 +
::Size changes depending on options selected &ndash; see next item.
 +
 
 +
:{{Par2|showyuv_fullrange|bool|false}}
 +
::{{AvsPluscon}} If ''true,'' {{FuncArg|showyuv}} output is full range instead of TV range.
 +
::At {{FuncArg|bits}}=8, size of the generated clip grows from 450x450 to 512x512.
 +
::At {{FuncArg|bits}}>8, size of the generated clip grows from 1800x1800 to 2048x2048.
 +
 
 +
:{{Par2|f2c|bool|false}}
 +
::{{AvsPluscon}} If ''true,'' perform [[#Parameter Rescaling|''parameter rescaling'']] as described below on all '''cont_'''''x'', '''gain_'''''x'' and '''gamma_'''''x'' arguments.
 +
::For example, with {{FuncArg|f2c}}=''true'', {{FuncArg|cont_u}}=1.2 results in a 20% increase in ''U'' channel "saturation".
 +
</div>
 +
 
 +
==Parameter Rescaling==
 +
<div style="max-width:62em" >
 +
The quantities ''saturation'', ''contrast'' and ''brightness'' (as in [[Tweak]] for example) are connected with quantities in this filter by the following equations:
 +
* {{FuncArg|cont_u}} = {{FuncArg|cont_v}} &#0061; ({{BoldColor|darkblue|100|sat}}-1) * 256
 +
* {{FuncArg|gain_y}} = ({{BoldColor|darkblue|100|cont}}-1) * 256
 +
* {{FuncArg|off_y}} = {{BoldColor|darkblue|100|bright}}
 +
A saturation of 0.8 gives for example: cont_u = cont_v = -0.2 * 256 = -51.2.
 +
 
 +
Note that in [[Tweak]] your YUV values will always be clipped to valid TV-ranges, but here you have to specify {{FuncArg|opt}}="coring".
 +
 
 +
You can add a simple [[User_defined_script_functions|user function]] to rescale or translate from familiar "Tweak-like" units to ColorYUV units:
 +
<div {{BoxWidthIndent|60|2}} >
 
  function f2c(float f) {
 
  function f2c(float f) {
     return Round((f - 1.0) * 256.0)
+
     return (f - 1.0) * 256.0
 
  }
 
  }
  
== Conditional Variables ==
+
## usage example:
 +
ColorYUV(gain_y=f2c({{BoldColor|blue|100|2.0}}), cont_u=f2c({{BoldColor|blue|100|1.2}}), cont_v=f2c({{BoldColor|blue|100|0.8}}))
 +
 +
## that is, gain is 200%, and contrast (saturation)
 +
## is +20% in the U channel, -20% in the V channel. 
 +
 +
## ...which specified normally, would look like this:
 +
ColorYUV(gain_y={{BoldColor|blue|100|256}}, cont_u={{BoldColor|blue|100|51.2}}, cont_v={{BoldColor|blue|100|-51.2}})
  
 +
## AVS+ users can rescale these arguments with the '''f2c''' option. 
 +
ColorYUV(gain_y={{BoldColor|blue|100|2.0}}, cont_u={{BoldColor|blue|100|1.2}}, cont_v={{BoldColor|blue|100|0.8}}, {{FuncArg|f2c}}=true)
 +
 +
</div>
 +
</div>
 +
 +
 +
== Conditional Variables ==
 +
<div style="max-width:62em" >
 
The global variables "coloryuv_xxx" with xxx = gain_y, gain_u, gain_v, bright_y, bright_u, bright_v, gamma_y, contrast_y, contrast_u or contrast_v are read each frame, and applied. It is possible to modify these variables using [[FrameEvaluate]] or [[ConditionalReader]].  
 
The global variables "coloryuv_xxx" with xxx = gain_y, gain_u, gain_v, bright_y, bright_u, bright_v, gamma_y, contrast_y, contrast_u or contrast_v are read each frame, and applied. It is possible to modify these variables using [[FrameEvaluate]] or [[ConditionalReader]].  
  
Line 55: Line 232:
  
 
coloryuvoffset.txt:
 
coloryuvoffset.txt:
 
+
<div {{BoxWidthIndent|56|2}} >
 
  Type float
 
  Type float
 
  Default 0.0
 
  Default 0.0
Line 62: Line 239:
 
  R 75 225 128.0
 
  R 75 225 128.0
 
  I 250 275 255.0 0.0
 
  I 250 275 255.0 0.0
 +
</div>
  
 
the script:
 
the script:
 
+
<div {{BoxWidthIndent|56|2}} >
 
  Colorbars(512,256).ConvertToYV12.Trim(0,299)
 
  Colorbars(512,256).ConvertToYV12.Trim(0,299)
 
  ColorYUV(cont_y=10, conditional=true)
 
  ColorYUV(cont_y=10, conditional=true)
 
  ConditionalReader("coloryuvoffset.txt", "coloryuv_gain_y", false)
 
  ConditionalReader("coloryuvoffset.txt", "coloryuv_gain_y", false)
 
  ShowFrameNumber()
 
  ShowFrameNumber()
 +
</div>
  
 
So up to frame 25 gain_y is equal to the default (which is 0.0), for frame 25 up to 50 the gain_y is increased from 0.0 to 255.0, etc ...
 
So up to frame 25 gain_y is equal to the default (which is 0.0), for frame 25 up to 50 the gain_y is increased from 0.0 to 255.0, etc ...
  
 
There are more examples of conditional modification at the [[ConditionalReader]] page.
 
There are more examples of conditional modification at the [[ConditionalReader]] page.
 +
</div>
  
== Examples: ==
 
  
<code>
+
== Examples ==
# This will adjust gamma for luma, while making luma smaller and chroma U greater:
+
<div style="max-width:62em" >
 +
* Adjust ''Y ''(luma) gamma and offset (brightness), while increasing chroma ''U ''(yellow-blue) offset (away from yellow and toward blue)
 +
<div {{BoxWidthIndent|56|2}} >
 
  ColorYUV(gamma_y=128, off_y=-16, off_u=5)
 
  ColorYUV(gamma_y=128, off_y=-16, off_u=5)
 +
</div>
  
  # Shows all colors. Frame 0 luma is 16, frame 1 luma is 17 and so on:
+
* {{FuncArg|autogain}} and {{FuncArg|autowhite}}: recovers visibility on "very bad" recordings:
 +
<div {{BoxWidthIndent|56|2}} >
 +
  ColorYUV(autogain=true, autowhite=true)
 +
</div>
 +
 
 +
* {{FuncArg|showyuv}}: show all colors in the [[YUV]] space. Requires a YUV clip as input.
 +
:Returns a [[YV12]], 448x448 clip with source frame rate, duration and audio.
 +
:'''Note''', not all colors are convertible to RGB - see [http://forum.doom9.org/showthread.php?t=154731 this discussion on doom9].
 +
:''U ''values run 16{{D}}-239{{D}}, left to right, and ''V'' values run from 16{{D}}-239{{D}}, top to bottom.
 +
:Frame 0 luma is 16{{D}}, frame 1 luma is 17{{D}} and so on.
 +
:{{AvsPluscon}} Size changes depending on options selected:
 +
:*By default size is 450x450.
 +
:*With {{FuncArg|showyuv_fullrange}}=true, size is 512x512.
 +
:*With {{FuncArg|bits}}=10, width and height are both multiplied by 4.
 +
<div {{BoxWidthIndent|56|2}} >
 
  ColorYUV(showyuv=true)
 
  ColorYUV(showyuv=true)
 +
</div>
 +
::[[File:ColorYUV(showyuv%3Dtrue)_fr175.png|224px]]
  
# Recovers visibility on "very bad" recordings:
 
ColorYUV(autogain=true, autowhite=true)
 
</code>
 
  
'''Changelog:'''
+
* Adjusting {{FuncArg|off_u}} and {{FuncArg|off_v}} to remove color cast (reduce yellow and magenta tints):
 +
<div {{BoxWidthIndent|56|2}} >
 +
[[ImageSource]]("[[:File:Lenna.png|Lenna.png]]")
 +
[[BicubicResize]](Width/2, Height/2)
 +
ColorYUV(off_u=+6, off_v=-23)
 +
[[Histogram#Levels_mode|Histogram]]("levels")
 +
</div>
 +
::[[File:Lenna-256x256-HistogramLevels-original.png]]
 +
::''(before)''
 +
::[[File:Lenna-256x256-HistogramLevels-ColorYUV-1.png]]
 +
::''(after; note the ''U '' and ''V'' range is moved towards the center)''
 +
 
 +
 
 +
*Demonstrating {{FuncArg|analyze}} output:
 +
<div id="analyze" style="display:inline;font-size:50%;height:0;line-height:0;overflow:hidden;"></div>
 +
<div {{BoxWidthIndent|24|2}} >
 +
[[FFmpegSource|FFmpegSource2]]("[http://www.sintel.org/ sintel].mp4")
 +
[[BicubicResize]](546, 272)
 +
ColorYUV(analyze=true)
 +
[[File:ColorYUV_analyze_Ex1.jpg]]
 +
</div>
 +
</div>
 +
 
 +
== Changelog ==
 
{| border="1"
 
{| border="1"
 
|-  
 
|-  

Revision as of 00:26, 6 March 2018

ColorYUV has many different methods of changing the color and luminance of your images. Gain, offset, gamma and contrast can be set independently on each channel. Also included are two 'auto' modes, an analysis function and a color gamut generator.

All settings for this filter are optional. All values are defaulting to "0" or false.

RGBAdjust works in a similar manner for RGB clips.


Contents

Syntax and Parameters

ColorYUV(clip [,
     float gain_y, float off_y, float gamma_y, float cont_y,
     float gain_u, float off_u, float gamma_u, float cont_u,
     float gain_v, float off_v, float gamma_v, float cont_v,
     string levels, string opt, bool showyuv, bool analyze,
     bool autowhite, bool autogain, bool conditional ] )

ColorYUV(clip [,
     float gain_y, float off_y, float gamma_y, float cont_y,
     float gain_u, float off_u, float gamma_u, float cont_u,
     float gain_v, float off_v, float gamma_v, float cont_v,
     string levels, string opt, bool showyuv, bool analyze,
     bool autowhite, bool autogain, bool conditional,
     int bits, bool showyuv_fullrange, bool f2c ] )
AVS+

float  gain_y = 0
float  gain_u = 0
float  gain_v = 0
A multiplier for the Y, U or V value.
If gain_y = k, then Y becomes Y · (k / 256 + 1) – for example:
(TL;DR see Parameter Rescaling below)
gain_x multiplier
  -256 (-256 / 256) + 1 0.0 (no output)
-128 (-128 / 256) + 1 0.5 (darker)
0 (0 / 256) + 1 1.0 (no change)
256 (256 / 256) + 1 2.0 (brighter)
512 (512 / 256) + 1 3.0
  • gain_x is valid down to -256, where a gain of 0.0 is applied.
  • Although it is possible, it doesn't make sense to apply this setting to the chroma of the signal.
  • In order to confuse you, in the filter Tweak this setting is called contrast.
float  off_y = 0
float  off_u = 0
float  off_v = 0
Adds an offset to the luma or chroma values.
  • An off_x of 16 will add 16d to all pixel values.
  • An off_x of -32 will subtract 32d from all pixel values.
float  gamma_y = 0
float  gamma_u = 0
float  gamma_v = 0
Adjusts gamma of the specified channel,
as X(1/g) where g=(gamma_x + 256) / 256 – for example:
(TL;DR see Parameter Rescaling below)
gamma_x gamma
  -256 (-256 / 256) + 1 0.01
-128 (-128 / 256) + 1 0.5 (darker)
0 (0 / 256) + 1 1.0 (no change)
256 (256 / 256) + 1 2.0 (lighter)
512 (512 / 256) + 1 3.0
  • gamma_x is valid down to -256, where a minimal gamma of 0.01 is applied (gamma cannot be zero)
  • Note: gamma for chroma is not implemented (gamma_u and gamma_v are dummy parameters).
  • AVS+ will operate on TV range instead of the default PC range when the input clip is known to be in TV range:
  • levels="TV->PC", or levels="TV",
  • or opt="coring" and levels is not "PC->TV" or "PC->TV.Y"
float  cont_y = 0
float  cont_u = 0
float  cont_v = 0
Like gain_X, a multiplier for the value, but stretches or shrinks the signal from the center (128d).
This is most useful for the chroma components, where it translates to saturation.
If cont_y = k, then Y becomes (Y-128) · k / 256 + 128 – for example:
(TL;DR see Parameter Rescaling below)
cont_x contrast
  -256 (-256 / 256) + 1 0.0 (zero contrast)
-128 (-128 / 256) + 1 0.5 (less contrast)
0 (0 / 256) + 1 1.0 (no change)
256 (256 / 256) + 1 2.0 (more contrast)
512 (512 / 256) + 1 3.0
  • cont_x is valid down to -256, where the signal is set to 128d.
  • Although it is possible, it doesn't make sense to apply this setting to the luma of the signal.
string  levels = ""
Can be "TV->PC", "PC->TV", "PC->TV.Y" or nothing (default)
  • If levels="TV->PC", a 16d-235d → 0d-255d (contrast increasing) conversion is made
  • If levels="PC->TV", a 0d-255d → 16d-235d (contrast decreasing) conversion is made
  • If levels="PC->TV.Y", a 0d-255d → 16d-235d (contrast decreasing) conversion is made, on luma channel only
  • By default, no conversion is made
AVS+ adds "TV", which does no conversion; it only tells the filter that gamma_x will operate on a TV range clip.
string  opt = ""
Can be either "coring" or "" (nothing, default setting).
Specifying "coring" will clip your YUV values to the "TV" range (luma 16d-235d, chroma 16d-240d). Otherwise values outside that range will be accepted.
bool  showyuv = false
If true, this option will overwrite your image with a new 448x448 image showing all chroma values along the two axes. This can be useful if you need to adjust the color of your image, but need to know how the colors are arranged. At the top left of the image, the chroma values are 16d. At the right side of the image, U is at maximum. At the bottom of the screen V is at its maximum. In the middle both chroma is 128d (or grey). See example image below.
AVS+ Size changes depending on options selected – see showyuv_fullrange below
If bits=8, output colorspace is YV12, else colorspace is YUV422P16.
bool  analyze = false
If true, ColorYUV will print color channel statistics on the screen (see example below)
  • There is an Average for all channels.
  • There are Minimum and Maximum values for all channels.
  • There is Loose Minimum and Loose Maximum which ignore the brightest and darkest 0.4% (1/256) pixels.
bool  autowhite = false
If true, this option will use the information from the analyzer, and attempt to center the color offsets. If you have recorded some material, where the colors are shifted toward one color, this filter may help. But be careful - it isn't very intelligent - if your material is a clear blue sky, autowhite will make it completely grey! This option overrides off_u and off_v.
bool  autogain = false
If true, this option will use the information from the analyzer, and attempt to create as good contrast as possible. That means, it will scale up the Y (luma) values to match the minimum and maximum values. This will make it act like an "autogain" setting on cameras, amplifying dark scenes very much, while leaving scenes with good contrast alone. Some places this is also referred to as "autolevels".
bool  conditional = false
See the Conditional Variables section for an overview of the conditional variables and their use with ColorYUV. If false (the default), ColorYUV will ignore any conditional variables.
int  bits = 8
AVS+ Sets the bit depth of showyuv output. Must be 8, 10, 12, 14 or 16.
Size changes depending on options selected – see next item.
bool  showyuv_fullrange = false
AVS+ If true, showyuv output is full range instead of TV range.
At bits=8, size of the generated clip grows from 450x450 to 512x512.
At bits>8, size of the generated clip grows from 1800x1800 to 2048x2048.
bool  f2c = false
AVS+ If true, perform parameter rescaling as described below on all cont_x, gain_x and gamma_x arguments.
For example, with f2c=true, cont_u=1.2 results in a 20% increase in U channel "saturation".

Parameter Rescaling

The quantities saturation, contrast and brightness (as in Tweak for example) are connected with quantities in this filter by the following equations:

  • cont_u = cont_v = (sat-1) * 256
  • gain_y = (cont-1) * 256
  • off_y = bright

A saturation of 0.8 gives for example: cont_u = cont_v = -0.2 * 256 = -51.2.

Note that in Tweak your YUV values will always be clipped to valid TV-ranges, but here you have to specify opt="coring".

You can add a simple user function to rescale or translate from familiar "Tweak-like" units to ColorYUV units:

function f2c(float f) {
    return (f - 1.0) * 256.0
}
## usage example: 
ColorYUV(gain_y=f2c(2.0), cont_u=f2c(1.2), cont_v=f2c(0.8)) 

## that is, gain is 200%, and contrast (saturation) 
## is +20% in the U channel, -20% in the V channel.  

## ...which specified normally, would look like this: 
ColorYUV(gain_y=256, cont_u=51.2, cont_v=-51.2)
## AVS+ users can rescale these arguments with the f2c option.  
ColorYUV(gain_y=2.0, cont_u=1.2, cont_v=0.8, f2c=true) 


Conditional Variables

The global variables "coloryuv_xxx" with xxx = gain_y, gain_u, gain_v, bright_y, bright_u, bright_v, gamma_y, contrast_y, contrast_u or contrast_v are read each frame, and applied. It is possible to modify these variables using FrameEvaluate or ConditionalReader.

For example:

coloryuvoffset.txt:

Type float
Default 0.0

I 25 50 0.0 255.0
R 75 225 128.0
I 250 275 255.0 0.0

the script:

Colorbars(512,256).ConvertToYV12.Trim(0,299)
ColorYUV(cont_y=10, conditional=true)
ConditionalReader("coloryuvoffset.txt", "coloryuv_gain_y", false)
ShowFrameNumber()

So up to frame 25 gain_y is equal to the default (which is 0.0), for frame 25 up to 50 the gain_y is increased from 0.0 to 255.0, etc ...

There are more examples of conditional modification at the ConditionalReader page.


Examples

  • Adjust Y (luma) gamma and offset (brightness), while increasing chroma U (yellow-blue) offset (away from yellow and toward blue)
ColorYUV(gamma_y=128, off_y=-16, off_u=5)
  • autogain and autowhite: recovers visibility on "very bad" recordings:
ColorYUV(autogain=true, autowhite=true)
  • showyuv: show all colors in the YUV space. Requires a YUV clip as input.
Returns a YV12, 448x448 clip with source frame rate, duration and audio.
Note, not all colors are convertible to RGB - see this discussion on doom9.
U values run 16d-239d, left to right, and V values run from 16d-239d, top to bottom.
Frame 0 luma is 16d, frame 1 luma is 17d and so on.
AVS+ Size changes depending on options selected:
  • By default size is 450x450.
  • With showyuv_fullrange=true, size is 512x512.
  • With bits=10, width and height are both multiplied by 4.
ColorYUV(showyuv=true)
ColorYUV(showyuv=true) fr175.png


  • Adjusting off_u and off_v to remove color cast (reduce yellow and magenta tints):
ImageSource("Lenna.png")
BicubicResize(Width/2, Height/2)
ColorYUV(off_u=+6, off_v=-23)
Histogram("levels")
Lenna-256x256-HistogramLevels-original.png
(before)
Lenna-256x256-HistogramLevels-ColorYUV-1.png
(after; note the U and V range is moved towards the center)


  • Demonstrating analyze output:
FFmpegSource2("sintel.mp4")
BicubicResize(546, 272)
ColorYUV(analyze=true)

ColorYUV analyze Ex1.jpg

Changelog

v2.6 Added conditional option
Personal tools