Merge pull request #20 from MrLixm/feat-obs-camera-colorspaces

Feat(obs): add camera colorspaces
MrLixm · Nov 25, 2023 · 075ff03 · 075ff03
2 parents d519684 + a4f3965
commit 075ff03
Show file tree

Hide file tree

Showing 25 changed files with 1,312 additions and 806 deletions.
diff --git a/dev/obs/obs_codegen/__init__.py b/dev/obs/obs_codegen/__init__.py
diff --git a/dev/obs/obs_codegen/__main__.py b/dev/obs/obs_codegen/__main__.py
diff --git a/dev/obs/obs_codegen/hlsl/__init__.py b/dev/obs/obs_codegen/hlsl/__init__.py
diff --git a/dev/obs/obs_codegen/lua/__init__.py b/dev/obs/obs_codegen/lua/__init__.py
diff --git a/obs/README.md b/obs/README.md
@@ -2,26 +2,31 @@
 
 Implementation of AgX for [OBS](https://obsproject.com/) as a script.
 
-![screenshot of OBS interface while in the Filters section](doc/img/obs-main.png)
+This is mainly intended to be applied on live camera feeds as this would not have
+many benefits applied on desktop capture.
 
-This is mainly intended to be applied on live camera feeds as this would have not much benefit
-to apply this on desktop captures.
+![screenshot of OBS interface while in the Filters section](doc/img/obs-main.png)
 
-![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)
-> bottom image has the AgX filter applied in OBS, top is default rendering -- standard C922 webcam
+| default rendering                                                                                                           | with AgX filter                                                                                                         |
+|-----------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
+| ![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
 
 # Requirements
 
-- This has been developed on OBS 28.1.2 for Windows but should work for lower version
-and other operating systems.
+- This has been developed on OBS `28.1.2` for Windows but should work for lower 
+versions, and other operating systems.
 
 - Nothing more than the content of this directory.
 
 # Installation
 
-Put the **whole** content of the [obs-script](obs-script) directory anywhere you want.
+[Download](https://github.com/MrLixm/AgXc/archive/refs/heads/main.zip) this whole
+GitHub repository.
+
+Put the **whole** content of the [obs/obs-script](obs-script) directory 
+anywhere you want on your system (you DON'T need the `src/` or the `doc/` directory).
 
 1. Open OBS
 2. In the top menu > Tools > Scripts
@@ -39,21 +44,22 @@ All done ! You can now configure it.
 
 ![screenshot of OBS interface while in the Filters section](doc/img/obs-filter-options.png)
 
-> **Note** Reminder that AgX being a display transform it should be placed at the
-> very end of the image processing chain. (so at the bottom in OBS)
+> ![NOTE]
+> 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 paramaters. There is no setup that work for all cases (but once
-configured for your camera/usual lighting, you will not need to touch it anymore)
+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
+## Recommended Options
 
 I recommend to always start by :
 
-- boosting the Grading Exposure by +1.0 stop.
+- boosting the `Grading Exposure` by +1.0 stop.
 - boosting `Highligh Gain` by 2.0
 
-## Available
+## Available Options
 
 ### Input Colorspace
 
@@ -65,20 +71,20 @@ Passthrough means no decoding is applied.
 
 Target colorspace encoding. Must correspond to your monitor calibration.
 
-> **Note** You can request adding new colorspace by opening an issue !
+> ![NOTE]
+> 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.
 
-None means you can use all the options like grading, input colorspace, ... but
-you will get a look similar to the usual broken imagery workflow.
+`None` will not apply AgX but still allow you to use the grading options. 
 
 
 ### Pre-Grading/...
 
-Adjust imagery look in a Linear space, before AgX is applied.
+Adjust imagery look in a linear space, before AgX is applied.
 
 ### Grading/Exposure
 
@@ -108,7 +114,7 @@ See above.
 Grading modifications applied after AgX on display encoded data. This will
 introduce skews, clipping and other artefacts.
 
-Recommended to change small values if used.
+Not recommended to use or with very small values.
 
 ### Debug/Use OCIO Log Transform
 
@@ -120,6 +126,7 @@ Does not create any change visually.
 
 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. 
 
 ### Debug/CAT Method
 

diff --git a/obs/doc/DEV.md b/obs/doc/DEV.md
@@ -4,37 +4,34 @@
 
 - `AgX.lua` : direct interface with OBS used for building the GUI
 - `AgX.hlsl` : GPU shader with the actual AgX code.
-- `colorspace.hlsl` : side-module imported in `AgX.hlsl`
+- `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`
 
-An important point is that part of the code in `colorspace.hlsl` is "procedurally"
-generated from python code.
-
-To keep scalability on such a pontentatilly big dataset and reduce human mistakes,
-a good part of the code is generated in python.
-
-This can be found in [{root}/dev/obs/obs_codegen](../../dev/obs/obs_codegen)
-package. More details below.
+The "procedurally" generated code can be found in the [../src/](../src) directory.
 
 # Add a new colorspace.
 
 ## Case 1 : gamut/whitepoint/cctf are already there.
 
 You will need :
 
-1. Modify the `/dev/obs/obs_codegen/__main__.py` by adding the new colorspace.
-This is done by adding a new instance of `AssemblyColorspace`.
-
-2. Generate the HLSL code by running `python -m obs_codegen hlsl`
-3. Copy the code generated in `colorspace.hlsl` (using the `//region` `//endregion` comment as marks)
-4. Generate the LUA code `python -m obs_codegen lua`
-5.  Copy the code generated in `AgX.lua` where it "seems" to belong. 
-(for now just adding entries to the properties dropdown)
+1. Modify the `../src/scripts/build-colorspace_core.hlsl.py` by adding the new colorspace.
+   1. This is done by adding a new instance of `AssemblyColorspace`.
+2. Run the script, this will automatically take care of the hlsl code.
+3. You will need to manually update the LUA code :
+   1. copy the lua code generated and print in the console to `AgX.lua` where it "seems" to belong. 
+   (for now just adding entries to the properties dropdown)
 
 ## Case 2 : whole new colorspace
 
 Similar to Case 1 but :
 
-- the step 1. is more complex : you also have to add a new Gamut/TransferFunction/Whitepoint
+- the step 1.1 is more complex : you also have to add a new Gamut/TransferFunction/Whitepoint
 instance if needed.
-- After step 3 you migth need to manually add the corresponding cctf function 
-(the name is generated automatically but you have to manually create it)
+- If you added a new `TransferFunction` you will need to manually write its 
+hlsl code in the `colorscience/cctf.hlsl` module. Note the name of the function
+can be found in `cctf-auto.hlsl` after running the build script.