WhiteBalance - Revision history

Reel.Deal: fix dead link

2018-11-24T06:40:24Z

fix dead link

Reel.Deal: category

2014-09-20T23:25:28Z

Reel.Deal: /* Links */

2014-09-20T22:18:00Z

‎Links

Reel.Deal: /* Syntax and Parameters */

2014-09-20T22:16:36Z

‎Syntax and Parameters

Reel.Deal: /* Why write another filter to do this when there are other methods? */

2014-09-20T22:06:10Z

‎Why write another filter to do this when there are other methods?

Reel.Deal: /* Examples */

2014-09-20T22:03:22Z

‎Examples

Reel.Deal: /* Examples */

2014-09-20T22:00:52Z

‎Examples

Reel.Deal: /* Color Space Considerations */

2014-09-20T21:57:12Z

‎Color Space Considerations

Reel.Deal: /* How does the White Balance filter work? */

2014-09-20T21:51:14Z

‎How does the White Balance filter work?

Reel.Deal: /* Why write another filter to do this when there are other methods? */

2014-09-20T21:49:01Z

‎Why write another filter to do this when there are other methods?

@@ Line 4: / Line 4: @@
 |SomeJoe
 |v1.0
-|[http://www.64k.it/andres/data/avisynth/WhiteBalance100.zip WhiteBalance100.zip]
+|[http://web.archive.org/web/20140308180916/http://www.64k.it/andres/data/avisynth/WhiteBalance100.zip WhiteBalance100.zip]
 |Levels and Chroma
 |Closed source

← Older revision		Revision as of 23:25, 20 September 2014
Line 1:		Line 1:
−	{{FilterCat4\|External_filters\|Plugins\|Adjustment_filters\|Levels and Chroma}}	+	{{FilterCat4\|External_filters\|Plugins\|Adjustment_filters\|Levels and Chroma filters}}

	{{Filter3		{{Filter3

@@ Line 151: / Line 151: @@
   v1.0         2006/01/22      - Initial release
 <br>
-== Links ==
+==External Links ==
 *[http://forum.doom9.org/showthread.php?t=106196 Doom9 Forum] - WhiteBalance discussion.
 *[http://web.archive.org/web/20140308180916/http://www.64k.it/andres/data/avisynth/WhiteBalance100.zip Archive.org] - Archived download.

@@ Line 59: / Line 59: @@
 :{{Template:FuncDef|WhiteBalance (''clip'', ''int'' "r1", ''int'' "g1", ''int'' "b1", ''int'' "y1", ''int'' "u1", ''int'' "v1", ''int'' "r2", ''int'' "g2", ''int'' "b2", ''int'' "y2", ''int'' "u2", ''int'' "v2", ''bool'' "interlaced", ''bool'' "split")}}
 <br>
-:::{{Par2|r1|int| }}
+::{{Par2| |clip| }}
-:::{{Par2|g1|int| }}
+:::Input clip.
-:::{{Par2|b1|int| }}
-::::These are the red, green, and blue values of a point on the camera's white axis.
-::::In other words, these are the red, green, and blue values of a white or near-white object in the original video.
-:::::Range: 0 to 255
 <br>
-:::{{Par2|y1|int| }}
+::{{Par2|r1|int| }}
-:::{{Par2|u1|int| }}
+::{{Par2|g1|int| }}
-:::{{Par2|v1|int| }}
+::{{Par2|b1|int| }}
-::::Optionally, if you don't want to specify red, green, and blue values of your white or near-white object, you can specify a YUV value of the white or near- white object.
+:::These are the red, green, and blue values of a point on the camera's white axis. In other words, these are the red, green, and blue values of a white or near-white object in the original video.
-:::::Range: 16 to 235 for {{Template:FuncDef|y1}}
-:::::Range: 16 to 240 for {{Template:FuncDef|u1}} and {{Template:FuncDef|v1}}
+:::Range: 0 to 255
 <br>
-:::*Either {{Template:FuncDef|r1, g1, b1}} OR {{Template:FuncDef|y1, u1, v1}} must be given.
+::{{Par2|y1|int| }}
-::::These values are telling the White Balance filter of one point on the camera's white axis line (the blue line in the  3D YUV graph).
+::{{Par2|u1|int| }}
-::::If both {{Template:FuncDef|r1, g1, b1}} AND {{Template:FuncDef|y1, u1, v1}} are given, the filter uses the {{Template:FuncDef|r1, g1, b1}} values, and {{Template:FuncDef|y1, u1, v1}} are not used.
+::{{Par2|v1|int| }}
 <br>
-:::{{Par2|r2|int| }}
+::*Either {{Template:FuncDef|r1, g1, b1}} OR {{Template:FuncDef|y1, u1, v1}} must be given. These values are telling the White Balance filter of one point on the camera's white axis line (the blue line in the  3D YUV graph).
-:::{{Par2|g2|int| }}
+::*If both {{Template:FuncDef|r1, g1, b1}} AND {{Template:FuncDef|y1, u1, v1}} are given, the filter uses the {{Template:FuncDef|r1, g1, b1}} values, and {{Template:FuncDef|y1, u1, v1}} are not used.
-:::{{Par2|b2|int| }}
-::::Optionally, these are the red, green, and blue values of another point on the camera's white axis.
-::::In other words, these are the red, green, and blue values of a black or near-black object in the original video.
-:::::Range: 0 to 255
 <br>
-:::{{Par2|y2|int| }}
+::{{Par2|r2|int| }}
-:::{{Par2|u2|int| }}
+::{{Par2|g2|int| }}
-:::{{Par2|v2|int| }}
+::{{Par2|b2|int| }}
-::::Optionally, if you don't want to specify red, green, and blue values of your black or near-black object, you can specify a YUV value of the black or near-black object.
+:::Optionally, these are the red, green, and blue values of another point on the camera's white axis. In other words, these are the red, green, and blue values of a black or near-black object in the original video.
-:::::Range: 16 to 235 for {{Template:FuncDef|y2}}
-:::::Range: 16 to 240 for {{Template:FuncDef|u2}} and {{Template:FuncDef|v2}}
+:::Range: 0 to 255
 <br>
-:::*Both {{Template:FuncDef|r2, g2, b2}} AND {{Template:FuncDef|y2, u2, v2}} are optional.
+::{{Par2|y2|int| }}
-::::If they are not specified, the White Balance filter assumes that black objects were filmed correctly by the camera
+::{{Par2|u2|int| }}
-::::(i.e. the blue white axis of the camera coincides with the true white axis at y=16, i.e. black luminance plane).
+::{{Par2|v2|int| }}
 <br>
-:::{{Par2|interlaced|bool|false}}
+::{{Par2|interlaced|bool|false}}
-::::This parameter is a boolean value (i.e. true or false), and tells the filter whether the input video is interlaced or not.
+:::This parameter is a boolean value (i.e. true or false), and tells the filter whether the input video is interlaced or not. This parameter is optional, and defaults to false. It doesn't need to be specified unless the input color space is YV12.
-::::This parameter is optional, and defaults to false. It doesn't need to be specified unless the input color space is YV12.
+:::(see YV12 color space explanation later in the document for details).
-::::(see YV12 color space explanation later in the document for details).
 <br>
-:::{{Par2|split|bool|false}}
+::{{Par2|split|bool|false}}
-::::This parameter is a boolean value (i.e. true or false), and is used for troubleshooting.
+:::This parameter is a boolean value (i.e. true or false), and is used for troubleshooting. This parameter is optional, default is false.
-::::If set to true, the White Balance filter will only white balance the right half of your video frame (the left half will not be processed).
+:::If set to true, the White Balance filter will only white balance the right half of your video frame (the left half will not be processed). This is so that you can look at a before/after split to see what the White Balance filter has done to the video.
-::::This is so that you can look at a before/after split to see what the White Balance filter has done to the video. This parameter is optional, default is false.
 <br>
 == Examples ==
 . Suppose I have a clip that has incorrect white balance. I export a frame from it that has a near-white object and a near-black object (i.e. I know that the objects are supposed to be nearly white and nearly black. The camera filmed both of the objects with an orange-ish tint.) I load that frame into the graphics application of my choice and look at the RGB values of each object. The near-white object has a coloration of RGB 176/153/132. The near-black object has a coloration of RGB 56/40/32.<br>

@@ Line 25: / Line 25: @@
 <br>
 == Why write another filter to do this when there are other methods? ==
-Not satisfied with other methods of adjusting white balance, because they come with other shortcomings that are not easily overcome.<br>
+Not satisfied with other methods of adjusting white balance, because they come with other shortcomings that are not easily overcome. Some other methods of white balancing video fall into one of two categories:<br>
 Some other methods of white balancing video fall into one of two categories:<br>
 <br>
-:1.)
+:'''1.)''' "Levels" adjustment filters, such as the Adobe Photoshop "Auto Levels" filter, or some implementations of AVISynth's [[RGBAdjust]]() filter. These filters work in [[RGB]] color space, and attempt to make white objects equal to 255/255/255, and black objects equal to 0/0/0. Given a reference to a white object and a black object, they then scale the red, green, and blue values throughout the image.<br>
-::"Levels" adjustment filters, such as the Adobe Photoshop "Auto Levels" filter, or some implementations of AVISynth's [[RGBAdjust]]() filter.
-::These filters work in [[RGB]] color space, and attempt to make white objects equal to 255/255/255, and black objects equal to 0/0/0. Given a reference to a white object and a black object, they then scale the red, green, and blue values throughout the image.<br>
-<br>
-::This method has the following problems:
-:::'''a.)''' You need a pure white and pure black object in your video so that you can tell the filter what RGB values are at the extreme. This may or may not be possible, as you may not have pure white and black objects available in the video.<br>
+:This method has the following problems:
-:::'''b.)''' Applying the levels algorithm like this will change the contrast and brightness settings overall. This may make the video too dark or too light.<br>
+::'''a.)''' You need a pure white and pure black object in your video so that you can tell the filter what RGB values are at the extreme. This may or may not be possible, as you may not have pure white and black objects available in the video.<br>
-:::'''c.)''' If there are colored objects that are brighter than your brightest white (for instance a candle flame), or colored objects darker than your darkest gray (for instance, a navy blue fabric), luminance clipping will occur which removes shadow and highlight detail.<br>
+::'''b.)''' Applying the levels algorithm like this will change the contrast and brightness settings overall. This may make the video too dark or too light.<br>
-:::'''d.)''' The Levels adjustment algorithm is only accurate at the white and black points. If the camera's red/green/blue intensity response was somewhat non-linear, midtones may not be white balanced properly even after the algorithm is applied.<br>
+::'''c.)''' If there are colored objects that are brighter than your brightest white (for instance a candle flame), or colored objects darker than your darkest gray (for instance, a navy blue fabric), luminance clipping will occur which removes shadow and highlight detail.<br>
 <br>
-:2.)
+:'''2.)''' YUV static-adjustment filters, such as using AVISynth's [[ColorYUV]]() filter. This  method works in YUV color space, and applies an offset to the U and V values throughout a clip.<br>
-::YUV static-adjustment filters, such as using AVISynth's [[ColorYUV]]() filter.<br>
-::This  method works in YUV color space, and applies an offset to the U and V values throughout a clip.<br>
+:This works a bit better than the Levels algorithm, but:<br>
-<br>
-::This works a bit better than the Levels algorithm, but:<br>
-:::'''a.)''' The camera's color response may not have been constant throughout the luminance range. In other words, the camera may have recorded blacks fairly accurately, but only shifted towards yellow on the whites. By applying a constant offset to all U and V values, whites are corrected from yellow to white, but at the same time, blacks are shifted from black to blue.<br>
+::'''a.)''' The camera's color response may not have been constant throughout the luminance range. In other words, the camera may have recorded blacks fairly accurately, but only shifted towards yellow on the whites. By applying a constant offset to all U and V values, whites are corrected from yellow to white, but at the same time, blacks are shifted from black to blue.<br>
-:::'''b.)''' Colors near the extremes of saturation will either lose some saturation due to the shift, or gradients near the edge of saturation will get clipped, possibly resulting in some visible banding.<br>
+::'''b.)''' Colors near the extremes of saturation will either lose some saturation due to the shift, or gradients near the edge of saturation will get clipped, possibly resulting in some visible banding.<br>
 <br>
 This White Balance filter takes these problems into account, and is able to adjust camera white to true white throughout the luminance range.<br>

@@ Line 112: / Line 112: @@
 <br>
 == Examples ==
-. Suppose I have a clip that has incorrect white balance. I export a frame from it that has a near-white object and a near-black object (i.e. I know that the objects are supposed to be nearly white and nearly black. The camera filmed both of the objects with an orange-ish tint.)<br>
+. Suppose I have a clip that has incorrect white balance. I export a frame from it that has a near-white object and a near-black object (i.e. I know that the objects are supposed to be nearly white and nearly black. The camera filmed both of the objects with an orange-ish tint.) I load that frame into the graphics application of my choice and look at the RGB values of each object. The near-white object has a coloration of RGB 176/153/132. The near-black object has a coloration of RGB 56/40/32.<br>
 I load that frame into the graphics application of my choice and look at the RGB values of each object. The near-white object has a coloration of RGB 176/153/132. The near-black object has a coloration of RGB 56/40/32.<br>
 I white balance this clip as follows:
   WhiteBalance(r1=176, g1=153, b1=132, r2=56, g2=40, b2=32)
 <br>
 . Supposed I have another clip with incorrect white balance. It looks like the camera was correct with black values, but white values are shifted towards blue because the scene was filmed outdoors under an overcast sky. I export a frame of the video, and my graphics application says that a near white object has a coloration of RGB 210/215/229. In addition, I want to see a before/after split of this video to look at the difference. Further, this is interlaced video, and I'm using YV12 color space.<br>

@@ Line 131: / Line 131: @@
 <br>
 == Color Space Considerations ==
-The White Balance filter works in these color spaces (RGB24, RGB32, YUY2, and YV12).<br>
+The White Balance filter works in these color spaces (RGB24, RGB32, YUY2, and YV12). Some notes for each color space:<br>
 Some notes for each color space:<br>
 <br>
 ==== [[RGB32]] and [[RGB24]] ====
-:Because the translation for each pixel to a corrected color involves the luminance value, the White Balance filter is most accurate in RGB24 and RGB32 color spaces,
+:Because the translation for each pixel to a corrected color involves the luminance value, the White Balance filter is most accurate in RGB24 and RGB32 color spaces, because the chrominance information is not downsampled. Each pixel's luminance value is individually used to translate the pixel's color to the corrected value. Because the translation matrix works in YUV color space internally, using RGB24 or RGB32 color space from your AVISynth script results in a substantial speed penalty. The filter's speed is about half of it's potential maximum when working in RGB24 or RGB32 color space.
-:because the chrominance information is not downsampled. Each pixel's luminance value is individually used to translate the pixel's color to the corrected value.
-:Because the translation matrix works in YUV color space internally, using RGB24 or RGB32 color space from your AVISynth script results in a substantial speed penalty.
+:WhiteBalance uses 32-bit integer implementations of [[RGB]]<->[[YUV]] conversions, so they run reasonably fast, and according to my spreadsheets are as accurate as the floating point implementations.
-:The filter's speed is about half of it's potential maximum when working in RGB24 or RGB32 color space.
-<br>
 :WhiteBalance uses 32-bit integer implementations of RGB<->YUV conversions, so they run reasonably fast, and according to my spreadsheets are as accurate as the
-:floating point implementations.
 <br>
 ==== [[YUY2]] ====
-:This color space is less accurate than RGB because chrominance information is downsampled by half resolution in the horizontal direction (4:2:2 downsampling).
+:This color space is less accurate than RGB because chrominance information is downsampled by half resolution in the horizontal direction (4:2:2 downsampling). For every two pixels, there is only one color. To translate that color, the filter uses  the average luminance of the two pixels to determine which luminance plane to use to apply the color correction.
-:For every two pixels, there is only one color. To translate that color, the filter uses  the average luminance of the two pixels to determine which luminance
-:plane to use to apply the color correction.
-<br>
 :YUY2 runs at near the filter's maximum theoretical speed.
 <br>
 ==== [[YV12]] ====
-:This color space is less accurate than both RGB and YUY2 color spaces because chrominance information is downsampled by half resolution in BOTH the horizontal
+:This color space is less accurate than both RGB and YUY2 color spaces because chrominance information is downsampled by half resolution in BOTH the horizontal and vertical directions (4:2:0 downsampling). For every 4 pixels, there is only one color. To translate that color, the filter uses the average luminance of the 4 pixels to determine which luminance plane to use to apply the color correction. The filter takes into account which lines to use for luminance averaging based on the interlaced parameter. With non-interlaced footage, the chrominance samples come from adjacent lines, so the filter uses adjacent line's luminance values when computing the 4-pixel average. With interlaced footage, the chrominance samples come from adjacent lines within a single field, so the filter needs to use adjacent line's luminance values from the same field to compute the 4-pixel average. With interlaced=true, the filter does this.
-:and vertical directions (4:2:0 downsampling). For every 4 pixels, there is only one color.
-:To translate that color, the filter uses the average luminance of the 4 pixels to determine which luminance plane to use to apply the color correction.
-:The filter takes into account which lines to use for luminance averaging based on the interlaced parameter.
-:With non-interlaced footage, the chrominance samples come from adjacent lines, so the filter uses adjacent line's luminance values when computing the 4-pixel average.
-:With interlaced footage, the chrominance samples come from adjacent lines within a single field, so the filter needs to use adjacent line's luminance values from the
-:same field to compute the 4-pixel average. With interlaced=true, the filter does this.
-<br>
 :YV12 runs at near the filter's maximum theoretical speed.
 <br>
@@ Line 170: / Line 156: @@
 :In all other conditions, you may omit the interlaced parameter.
 <br>
 == Changelog ==
   Version      Date            Changes<br>

@@ Line 56: / Line 56: @@
 == How does the White Balance filter work? ==
-White Balance filter works internally in YUV color space. Imagine the following 3D diagram of YUV color space:
+White Balance filter works internally in [[YUV]] color space. Imagine the following 3D diagram of YUV color space:
 :::[[Image:WhiteBalanceGraph.png]]
-In this hypothetical diagram, the camera's white balance was incorrect, resulting in true white objects shifted towards yellow (the blue dot in the red plane).<br>
+In this hypothetical diagram, the camera's white balance was incorrect, resulting in true white objects shifted towards yellow (the blue dot in the red plane). At the same time, black objects were shifted towards blue (blue dot in the green plane). Thus the "white axis" of the camera is diagonal within the YUV cylindrical color space, and never even intersects the black "true white" axis. The White Balance filter intelligently scales U and V values within each luminance plane, avoiding decreasing saturation where a color was fully saturated, and avoiding clipping saturated colors at the opposite extreme. Once the U and V values are scaled, the camera's white axis lines up with the true white axis, making all whites, grays, and blacks perfectly neutral throughout all luminance planes.<br>
-At the same time, black objects were shifted towards blue (blue dot in the green plane). Thus the "white axis" of the camera is diagonal within the YUV<br>
-cylindrical color space, and never even intersects the black "true white" axis. The White Balance filter intelligently scales U and V values within each luminance<br>
-plane, avoiding decreasing saturation where a color was fully saturated, and avoiding clipping saturated colors at the opposite extreme. Once the U and V values are<br>
 scaled, the camera's white axis lines up with the true white axis, making all whites, grays, and blacks perfectly neutral throughout all luminance planes.<br>
 <br>
 == [[Script variables|Syntax and Parameters]] ==
 :{{Template:FuncDef|WhiteBalance (''clip'', ''int'' "r1", ''int'' "g1", ''int'' "b1", ''int'' "y1", ''int'' "u1", ''int'' "v1", ''int'' "r2", ''int'' "g2", ''int'' "b2", ''int'' "y2", ''int'' "u2", ''int'' "v2", ''bool'' "interlaced", ''bool'' "split")}}