Merge pull request #21 from MrLixm/feat-obs-improvements

Feat(obs): add white-balance; code clean

Author: MrLixm

obs/README.md

@@ -11,12 +11,12 @@ many benefits applied on desktop capture.
 |-----------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
 | ![screenshot of obs interface while camera is pointing at various colored objects like legos](doc/img/obs-c922-default.jpg) | ![screenshot of obs interface while camera is pointing at various colored objects like legos](doc/img/obs-c922-agx.jpg) |
 
-> video device is a "standard" Logitech C922 webcam
+> video device is a "standard" Logitech C922 webcam for the above comparison
 
 # Requirements
 
 - This has been developed on OBS `28.1.2` for Windows but should work for lower 
-versions, and other operating systems.
+and upper versions, and other operating systems.
 
 - Nothing more than the content of this directory.
 
@@ -36,50 +36,54 @@ The script is now active. A new filter has been created :
 
 1. Go to your Scene/Source where you want to add the AgX filter and select it (the source)
 2. Click on the `Filters` button that should be a bit above the source.
-3. In the **Effect Filters** section, click the `+` button and choose AgX
+3. In the **Effect Filters** section, click the `+` button and choose `AgX`
 
 All done ! You can now configure it.
 
 # Configuration
 
 ![screenshot of OBS interface while in the Filters section](doc/img/obs-filter-options.png)
 
-> ![NOTE]
+> [!IMPORTANT]
 > Reminder that AgX being a display transform it should be placed at
 > **the very end** of the image processing chain (= at the bottom in OBS).
 
 The camera/video-source and your lighting setup will affect how much you need
 to tweak the parameters. There is no setup that work for all cases, but once
 configured for your camera/usual lighting, you should not need to touch it anymore.
 
-## Recommended Options
+## Guidelines
 
-I recommend to always start by :
-
-- boosting the `Grading Exposure` by +1.0 stop.
-- boosting `Highligh Gain` by 2.0
+I recommend to :
+- `Pre-Grading`
+  - boosting the `Grading Exposure` by +1.0 stop if you are in a dim environment.
+  - boosting `Highligh Gain` by 2.0 (always better)
+  - `White Balance`: `intensity` at 1.0 and use `tint` ~10.0 if your camera tend to
+  have to produce pinkish tones (noticable on skin).
 
 ## Available Options
 
 ### Input Colorspace
 
 Pick in which colorspace your source is encoded. 
 
-Passthrough means no decoding is applied.
+`Passthrough` means no decoding is applied.
 
 ### Output Colorspace
 
 Target colorspace encoding. Must correspond to your monitor calibration.
 
-> ![NOTE]
+> [!TIP]
 > You can request adding new colorspace by opening an issue on GitHub !
 
 ### DRT
 
 Pick the DRT to use. Technically here we could include other DRT than AgX.
-But for now only None and AgX are available.
+But for now only None and AgX (with 2 variants) are available.
 
-`None` will not apply AgX but still allow you to use the grading options. 
+- `None` will not apply AgX but still allow you to use the grading options.
+- `AgX w/Outset` is AgX but with an additional transform to restore chroma. This
+can reintroduce shift and skews but might be acceptable.
 
 
 ### Pre-Grading/...
@@ -96,7 +100,7 @@ Power function. 1.0 = neutral.
 
 ### Grading/Saturation
 
-Saturation based on BT.709 coeff. 1.0 = neutral.
+Saturation with coefficient based on the working color-space. 1.0 = neutral.
 
 ### Grading/Highlight Gain
 
@@ -109,32 +113,38 @@ via `Highlight Gain Threshold`.
 
 See above.
 
-### Post-Grading/...
+### Grading/White-Balance
 
-Grading modifications applied after AgX on display encoded data. This will
-introduce skews, clipping and other artefacts.
+Shift white tones, applied before all operations.
+
+- `Temperature`: in Kelvin. Lower=warmer, higher=colder.
+- `Tint`: shift the temperature: >0=greener, <0=pinker
+- `Intensity`: global multiplier for the effect. 0=disabled.
 
-Not recommended to use or with very small values.
+The most "neutral values" when `Intensity` is 1.0 are `Temperature`=`~5600` and
+`Tint`=`~-15.5` which try to match the Illuminant E (those neutral values are not 
+ideal and perhaps the white-balance implementation could be improved)
 
-### Debug/Use OCIO Log Transform
+![Close up diagram of the CIE 1960 UCS with the planckian locus iso lines visble](https://upload.wikimedia.org/wikipedia/commons/d/d7/Planckian-locus.png)
 
-Switch to use the HLSL transform being an exact match to the OCIO `log2Transform`.
 
-Does not create any change visually.
+### Post-Grading/...
 
-### Debug/Apply Outset
+Grading modifications applied after AgX on display encoded data. This will
+introduce skews, clipping and other artefacts.
 
-Not originally included in the first AgX version but should be in the future.
-Restore chroma and avoid having to use Punchy saturation.
-Might bring back some hue skews so better left off. 
+Not recommended to use or with very small values, but can help achieve a stronger
+artistic look.
+
+All parameters are described the same as for the Pre-Grading section.
 
 ### Debug/CAT Method
 
-Chromatic Adaptation Transform method to chose for whitepoint conversion.
+Chromatic Adaptation Transform method to chose for whitepoint conversion (when
+there is a whitepoint conversion between input and output colorspace.)
 
 Default is Bradford and doesn't need to be changed.
 
-
 # Developer
 
 Developer documentation can be found in [doc/DEV.md](doc/DEV.md).

obs/doc/DEV.md

@@ -3,13 +3,13 @@
 # Introduction.
 
 - `AgX.lua` : direct interface with OBS used for building the GUI
-- `AgX.hlsl` : GPU shader with the actual AgX code.
-- `colorspace.hlsl` : side-library imported in `AgX.hlsl`
-  - this is actually the public interface of the `colorscience/` "package".
-- `colorscience/` library of hlsl modules for color manipulation. some of the modules
-are code-generated and not intended to be edited directly. Directly editable modules are :
-  - `math.hlsl`
-  - `cctf.hlsl`
+- `AgX.hlsl` : top-level GPU shader used in the lua script.
+
+With that you will find additional hlsl modules that are all imported in `AgX.hlsl` :
+
+- `lib_colorscience.hlsl`: library of hlsl modules for color manipulation
+  - `_lib_colorscience/`: some of the modules are procedurally-generated and not 
+   intended to be edited directly (see header comment).
 
 The "procedurally" generated code can be found in the [../src/](../src) directory.
 

obs/doc/img/obs-filter-options.png

@@ -1,5 +1,9 @@
 /*
-HLSL implementation of AgX (by Troy Sobotka) for OBS.
+HLSL implementation of AgX for OBS.
+
+AgX is a Display Rendering Transform designed by Troy Sobotka.
+
+The code is not AgX-specific and actually very flexible to integrate any other DRT.
 
 author = "Liam Collod"
 repository = "https://github.com/MrLixm/AgXc"
@@ -12,7 +16,6 @@ References:
 - [4] https://github.com/Unity-Technologies/Graphics/blob/master/com.unity.postprocessing/PostProcessing/Shaders/Colors.hlsl#L574
 - [5] https://github.com/colour-science/colour/blob/develop/colour/models/rgb/transfer_functions/srgb.py#L99
 */
-#include "colorspace.hlsl"
 
 // OBS-specific syntax adaptation to HLSL standard to avoid errors reported by the code editor
 #define SamplerState sampler_state
@@ -34,16 +37,21 @@ colorspaceid_DCIP3_Display_2_6 = 5;
 colorspaceid_Apple_Display_P3 = 6;
 */
 uniform int DRT = 1;
-uniform float INPUT_EXPOSURE = 0.75;
+uniform float INPUT_EXPOSURE = 0.5;
 uniform float INPUT_GAMMA = 1.0;
 uniform float INPUT_SATURATION = 1.0;
-uniform float INPUT_HIGHLIGHT_GAIN = 0.0;
+uniform float INPUT_HIGHLIGHT_GAIN = 1.5;
 uniform float INPUT_HIGHLIGHT_GAIN_GAMMA = 1.0;
+// temperature/tint values try to emulate whitepoint E for neutral result
+uniform float INPUT_WHITE_BALANCE_TEMPERATURE = 5400;
+uniform float INPUT_WHITE_BALANCE_TINT = -15.5;
+uniform float INPUT_WHITE_BALANCE_INTENSITY = 1.0;
 uniform float PUNCH_EXPOSURE = 0.0;
 uniform float PUNCH_SATURATION = 1.0;
-uniform float PUNCH_GAMMA = 1.3;
-uniform bool USE_OCIO_LOG = false;
-uniform bool APPLY_OUTSET = true;
+uniform float PUNCH_GAMMA = 1.0;
+uniform float PUNCH_WHITE_BALANCE_TEMPERATURE = 5400;
+uniform float PUNCH_WHITE_BALANCE_TINT = -15.5;
+uniform float PUNCH_WHITE_BALANCE_INTENSITY = 1.0;
 
 // LUT AgX-default_contrast.lut.png
 uniform texture2d AgXLUT;
@@ -56,6 +64,7 @@ uniform texture2d AgXLUT;
 
 uniform int drt_id_none = 0;
 uniform int drt_id_agx = 1;
+uniform int drt_id_agx_outset = 2;
 
 /*=================
     OBS BOILERPLATE
@@ -87,6 +96,11 @@ struct PixelData
     float2 uv  : TEXCOORD0; // UV coordinates in the source picture
 };
 
+// order matters + need the constants defined above
+#include "lib_math.hlsl"
+#include "lib_colorscience.hlsl"
+#include "lib_grading.hlsl"
+#include "lib_agx.hlsl"
 
 /*=================
     Main processes
@@ -101,97 +115,27 @@ float3 applyInputTransform(float3 Image)
     return convertColorspaceToColorspace(Image, INPUT_COLORSPACE, colorspaceid_working_space);
 }
 
-float3 applyGrading(float3 Image)
+float3 applyOpenGrading(float3 Image)
 /*
-    Apply creative grading operations (pre-display-transform).
-*/
-{
-
-    float ImageLuma = powsafe(get_luminance(Image), INPUT_HIGHLIGHT_GAIN_GAMMA);
-    Image += Image * ImageLuma.xxx * INPUT_HIGHLIGHT_GAIN;
-
-    Image = saturation(Image, INPUT_SATURATION);
-    Image = powsafe(Image, INPUT_GAMMA);
-    Image *= powsafe(2.0, INPUT_EXPOSURE);
-    return Image;
-}
+    Apply creative grading on open-domain image state.
 
-float3 applyAgXLog(float3 Image)
-/*
-    Prepare the data for display encoding. Converted to log domain.
+    :param Image: expected to be in a open-domain state.
 */
 {
-
-    float3x3 agx_compressed_matrix = {
-        0.84247906, 0.0784336, 0.07922375,
-        0.04232824, 0.87846864, 0.07916613,
-        0.04237565, 0.0784336, 0.87914297
-    };
-
-    Image = max(0.0, Image); // clamp negatives
-    // why this doesn't work ??
-    // Image = mul(agx_compressed_matrix, Image);
-	Image = apply_matrix(Image, agx_compressed_matrix);
-
-    if (USE_OCIO_LOG)
-        Image = cctf_log2_ocio_transform(Image);
-    else
-        Image = cctf_log2_normalized_from_open_domain(Image, -10.0, 6.5);
-
-    Image = clamp(Image, 0.0, 1.0);
-    return Image;
-}
-
-float3 applyAgXLUT(float3 Image)
-/*
-    Apply the AgX 1D curve on log encoded data.
-
-    The output is similar to AgX Base which is considered
-    sRGB - Display, but here we linearize it.
-
-    -- ref[3] for LUT implementation
-*/
-{
-
-    float3 lut3D = Image * (AgXLUT_BLOCK_SIZE-1);
-
-    float2 lut2D[2];
-    // Front
-    lut2D[0].x = floor(lut3D.z) * AgXLUT_BLOCK_SIZE+lut3D.x;
-    lut2D[0].y = lut3D.y;
-    // Back
-    lut2D[1].x = ceil(lut3D.z) * AgXLUT_BLOCK_SIZE+lut3D.x;
-    lut2D[1].y = lut3D.y;
-
-    // Convert from texel to texture coords
-    lut2D[0] = (lut2D[0]+0.5) * AgXLUT_PIXEL_SIZE;
-    lut2D[1] = (lut2D[1]+0.5) * AgXLUT_PIXEL_SIZE;
-
-    // Bicubic LUT interpolation
-    Image = lerp(
-        AgXLUT.Sample(LUTSampler, lut2D[0]).rgb, // Front Z
-        AgXLUT.Sample(LUTSampler, lut2D[1]).rgb, // Back Z
-        frac(lut3D.z)
+    Image = white_balance(
+        Image,
+        INPUT_WHITE_BALANCE_TEMPERATURE,
+        INPUT_WHITE_BALANCE_TINT,
+        INPUT_WHITE_BALANCE_INTENSITY
     );
-    // LUT apply the transfer function so we remove it to keep working on linear data.
-    Image = cctf_decoding_Power_2_2(Image);
-    return Image;
-}
 
-float3 applyOutset(float3 Image)
-/*
-    Outset is the inverse of the inset applied during `applyAgXLog`
-    and restore chroma.
-*/
-{
-
-    float3x3 agx_compressed_matrix_inverse = {
-        1.1968790, -0.09802088, -0.09902975,
-        -0.05289685, 1.15190313, -0.09896118,
-        -0.05297163, -0.09804345, 1.15107368
-    };
-	Image = apply_matrix(Image, agx_compressed_matrix_inverse);
+    float ImageLuma = get_luminance(Image, colorspaceid_working_space);
+    ImageLuma = grade_gamma(ImageLuma, INPUT_HIGHLIGHT_GAIN_GAMMA);
+    Image += Image * ImageLuma.xxx * INPUT_HIGHLIGHT_GAIN;
 
+    Image = grade_saturation(Image, INPUT_SATURATION, colorspaceid_working_space);
+    Image = grade_gamma(Image, INPUT_GAMMA);
+    Image = grade_exposure(Image, INPUT_EXPOSURE);
     return Image;
 }
 
@@ -201,10 +145,10 @@ float3 applyDRT(float3 Image)
 */
 {
     if (DRT == drt_id_agx){
-        Image = applyAgXLog(Image);
-        Image = applyAgXLUT(Image);
-        if (APPLY_OUTSET)
-            Image = applyOutset(Image);
+        Image = applyAgX(Image);
+    }
+    if (DRT == drt_id_agx_outset){
+        Image = applyAgXOutset(Image);
     }
     return Image;
 
@@ -222,16 +166,23 @@ float3 applyODT(float3 Image)
 }
 
 
-float3 applyLookPunchy(float3 Image)
+float3 applyDisplayGrading(float3 Image)
 /*
-    Applies the post "Punchy" look to display-encoded data.
+    Apply creative grading on display-domain image state.
 
-    Input is expected to be in a display-state.
+    :param Image: expected to be in a display-state.
 */
 {
-    Image = powsafe(Image, PUNCH_GAMMA);
-    Image = saturation(Image, PUNCH_SATURATION);
-    Image *= powsafe(2.0, PUNCH_EXPOSURE);  // not part of initial cdl
+    Image = white_balance(
+        Image,
+        PUNCH_WHITE_BALANCE_TEMPERATURE,
+        PUNCH_WHITE_BALANCE_TINT,
+        PUNCH_WHITE_BALANCE_INTENSITY
+    );
+
+    Image = grade_gamma(Image, PUNCH_GAMMA);
+    Image = grade_saturation(Image, PUNCH_SATURATION, OUTPUT_COLORSPACE);
+    Image = grade_exposure(Image, PUNCH_EXPOSURE);  // not part of initial cdl
     return Image;
 
 }
@@ -250,10 +201,10 @@ float4 PIXELSHADER_AgX(PixelData pixel) : TARGET
     float4 OriginalImage = image.Sample(linear_clamp, pixel.uv);
     float3 Image = OriginalImage.rgb;
     Image = applyInputTransform(Image);
-    Image = applyGrading(Image);
+    Image = applyOpenGrading(Image);
     Image = applyDRT(Image);
     Image = applyODT(Image);
-    Image = applyLookPunchy(Image);
+    Image = applyDisplayGrading(Image);
 
     Image = convertColorspaceToColorspace(Image, 1, 4);