Merge pull request #5 from bean-mhm/documentation

0.4.3-alpha + updated documentation

README.md

@@ -1,3 +1,4 @@
+
 <!-- Improved compatibility of back to top link: See: https://github.com/othneildrew/Best-README-Template/pull/73 -->
 <a name="readme-top"></a>
 <!--
@@ -28,10 +29,6 @@
 
 
 
-### NOTE: This page is outdated and demands rewriting. I'm currently working on it.
-
-
-
 <!-- TABLE OF CONTENTS -->
 <details>
   <summary>Table of Contents</summary>
@@ -53,30 +50,31 @@
 <!-- INTRODUCTION -->
 ## Introduction
 
-RealBloom lets you simulate physically accurate bloom effect for your 3D renders, or any HDR image.
+RealBloom is a physically accurate bloom simulation software for adding more realism to 3D renders and HDR images in general.
 
-![RealBloom Screenshot](images/screenshot3.png)
+![RealBloom Screenshot](images/1-main.png)
 
-![RealBloom Screenshot](images/screenshot4.png)
+![RealBloom Screenshot](images/2-main-conv.png)
 
-RealBloom was started as a hobby project in late August 2022. This project was inspired by [AngeTheGreat's video](https://www.youtube.com/watch?v=QWqb5Gewbx8) on bloom and how to simulate it. **I highly recommend watching this video** in order to have a basic understanding of how RealBloom works. Make sure to check out their [GitHub page](https://github.com/ange-yaghi) and their other projcets as well!
+RealBloom was started as a hobby project in late August 2022, inspired by [AngeTheGreat's video](https://www.youtube.com/watch?v=QWqb5Gewbx8) on bloom and how to simulate it. **I highly recommend watching this video** in order to have a basic understanding of how RealBloom works. Make sure to check out their [GitHub page](https://github.com/ange-yaghi) and their other projcets as well!
 
-The ultimate goal of writing this project was to achieve more realism in 3D renders that contain bright spots on dark backgrounds. For example, the sun in a blue sky, a car headlight at night, bright lights at a concert, or a flashlight pointing directly at the camera. You can learn about some other lens effects such as [Lens Flare](https://en.wikipedia.org/wiki/Lens_flare) and [Bokeh](https://en.wikipedia.org/wiki/Bokeh). If you're a [Blender](https://blender.org/) user like myself, you might want to watch [this video](https://www.youtube.com/watch?v=UDvuhuU9tFg) on applying a custom bokeh effect in Blender. The custom bokeh effect can be used alongside convolutional bloom to achieve a more life-like render.
+The ultimate goal is to achieve more realism in 3D renders that contain bright spots on dark backgrounds. For example, the sun in a blue sky, a car headlight at night, bright lights at a concert, a flashlight pointing directly at the camera, you name it.
 
 ### How It's Made
 
-RealBloom is written in C++ using Visual Studio 2022. The target platform is Windows. However, considering the fact that all the libraries used and most of the code for RealBloom are platform-independent, it should be fairly easy to port it to another platform. I personally don't plan on doing that.
+RealBloom is written in C++ using Visual Studio 2022. The target platform is Windows. However, considering the fact that all the libraries used and most of the code for RealBloom are platform-independent, it should be fairly easy to port it to another platform.
 
 RealBloom uses the following libraries:
 | Library | Used for |
 |--|--|
-| [FFTW](https://www.fftw.org/) | Generating diffraction patterns |
 | [GLEW](https://glew.sourceforge.net/) | OpenGL extensions |
 | [GLFW](https://www.glfw.org/) | Window and context creation for use in ImGui |
 | [Dear ImGui](https://github.com/ocornut/imgui) | Graphical user interface |
-| [LibTIFF](https://libtiff.gitlab.io/libtiff/) | Reading and writing TIFF image files |
-| [LodePNG](https://lodev.org/lodepng/) | Reading and writing PNG image files |
+| [OpenColorIO](https://opencolorio.org/) | Color management |
+| [OpenImageIO](https://sites.google.com/site/openimageio/) | Reading and writing images |
+| [PocketFFT](https://github.com/mreineck/pocketfft) | 2D Fast Fourier Transforms |
 | [NFD](https://github.com/mlabbe/nativefiledialog) | Native file dialogs |
+| [Rapidcsv](https://github.com/d99kris/rapidcsv) | Parsing CSV files |
 | [inih](https://github.com/jtilly/inih) | Parsing config files |
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
@@ -86,13 +84,7 @@ RealBloom uses the following libraries:
 <!-- RUNNING -->
 ## Running RealBloom
 
-To run RealBloom, [Visual C++ Runtime](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170) needs to be installed. Chances are you already have it installed, but regardless, a 64-bit version of the installer is included with every release build, in the `prerequisites` folder.
-
-You can get the latest release [here](https://github.com/bean-mhm/realbloom/releases).
-
-### Recommended Specs
-
- To perform convolutional bloom, you need powerful hardware. My recommendation would be a Windows 10/11 PC with a high-end GPU. If you have a dedicated GPU, always use that for convolution, instead of the CPU. RealBloom doesn't use a lot of RAM.
+[Microsoft Visual C++ Runtime](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170) is required to run RealBloom. Chances are you already have it installed, though. To get RealBloom, you can [download the latest release here](https://github.com/bean-mhm/realbloom/releases).
 
 ### Minimum Requirements
 
@@ -102,16 +94,14 @@ You can get the latest release [here](https://github.com/bean-mhm/realbloom/rele
 
  - GPU with OpenGL 3.2 support
 
-My Specs: As the developer, RealBloom runs quite well on my laptop with a Ryzen 7 3750H, a GTX 1650, and 16 GB of RAM.
-
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 
 
 <!-- USAGE -->
 ## Using RealBloom
 
-Check out [this page](USAGE.md) for a detailed step-by-step tutorial on getting started with RealBloom.
+Check out [this page](USAGE.md) for a step-by-step tutorial on getting started with RealBloom. This tutorial will cover most of what you need to know.
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
@@ -132,25 +122,28 @@ The project was made for Windows and built with MSVC, so you're going to need a
 
 2. Open the solution `RealBloomCPP.sln` in Visual Studio.
 
-3. `RealBloomCPP` is the main project, while `RealBloomGPUConv` is a helper program that gets used by the main program.*
+3. `RealBloomCPP` is the main project, while `RealBloomGPUConv` is a GPU helper program that gets used by the main program.
 
 4. Build the solution and run `RealBloom.exe`. Feel free to explore and play with the code!
 
->*`RealBloomGPUConv.exe` takes an input file containing buffers and parameters required for GPU convolution, performs convolution, then writes the result to an output file which gets read by `RealBloom.exe`.
-
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 
 
 <!-- ROADMAP -->
 ## Roadmap
 
-- [ ] Color Management System
-- [ ] OpenEXR support
+- [x] Color Management System
+- [x] OpenEXR support
+- [x] Command Line Interface
+- [ ] GPU FFT Convolution
+- [ ] GPU Dispersion
+- [ ] GPU Diffraction Pattern
+- [ ] GPU Image Transforms
 - [ ] Node-based workflow
-- [ ] Support for animated apertures, kernels and input images
+- [ ] ~~Support for animated apertures, kernels and input images~~ 
 
-See the [open issues](https://github.com/bean-mhm/realbloom/issues) for a full list of proposed features (and known issues).
+See [open issues](https://github.com/bean-mhm/realbloom/issues) for a full list of proposed features (and known issues).
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
@@ -160,13 +153,13 @@ See the [open issues](https://github.com/bean-mhm/realbloom/issues) for a full l
 
 I have in mind to make RealBloom's interface more generic and robust by making it node-based. Here's the concept represented using Blender's node system:
 
-![Node-based approach](images/node-based.png)
+![Node-based approach](images/3-nodes.png)
 
-Unfortunately, I can't afford the time to work on this as of now, because of school and other things in life. However, I do plan on doing it after I get into a university. If you do have the time and some knowledge on node-based applications, feel free to fork the repo and work on it, which would be really appreciated!
+Unfortunately, I can't afford the time to work on this as of now, but I do plan on doing it whenever possible. If you do have the time and some knowledge on node-based applications, feel free to fork the repo and work on it, which would be really appreciated!
 
-For some initial ideas, there could be a specific XML format for representing nodes, a core program that runs a node-tree, and a GUI program that displays the nodes and allows for creating, importing, and exporting node trees, as well as using the core program to run them and show the status.
+For some initial ideas, there could be a specific text format - based on XML, JSON, or anything else - for representing nodes, a core library that runs a node-tree, and a GUI for creating, managing, and displaying nodes.
 
-Nodes should have unique IDs, cached buffers - *with their own unique IDs* - that only get reprocessed when the node's input parameters change, status and progress indicators, etc. You can see some example nodes in the image above.
+Nodes could have unique IDs, cached buffers that only get reprocessed when the node's input parameters change, status and progress indicators, etc. You can see some example nodes in the image above.
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
@@ -202,7 +195,9 @@ Distributed under the [AGPL-3.0 license](https://github.com/bean-mhm/realbloom/b
 <!-- CONTACT -->
 ## Contact
 
-Harry Bean - [[email protected]](mailto:[email protected])
+Harry Bean (Developer)
+ - Email: [[email protected]](mailto:[email protected])
+ - Discord: `!bean#0446`
 
 Project Link: [https://github.com/bean-mhm/realbloom](https://github.com/bean-mhm/realbloom)
 
@@ -214,3 +209,4 @@ Project Link: [https://github.com/bean-mhm/realbloom](https://github.com/bean-mh
 <!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->
 [product-screenshot]: images/screenshot.png
 
+

RealBloomCPP/RealBloomCPP.vcxproj

@@ -210,6 +210,7 @@ XCOPY "$(ProjectDir)cmf\" "$(OutDir)cmf\" /S /Y</Command>
     <ClCompile Include="src\Utils\CliStackTimer.cpp" />
     <ClCompile Include="src\Utils\ConsoleColors.cpp" />
     <ClCompile Include="src\Utils\CliParser.cpp" />
+    <ClCompile Include="src\Utils\FileDialogs.cpp" />
     <ClCompile Include="src\Utils\GlTexture.cpp" />
     <ClCompile Include="include\oiio\detail\pugixml\pugixml.cpp" />
     <ClCompile Include="src\ColorManagement\OcioShader.cpp" />
@@ -250,6 +251,7 @@ XCOPY "$(ProjectDir)cmf\" "$(OutDir)cmf\" /S /Y</Command>
     <ClInclude Include="src\Utils\CliStackTimer.h" />
     <ClInclude Include="src\Utils\ConsoleColors.h" />
     <ClInclude Include="src\Utils\CliParser.h" />
+    <ClInclude Include="src\Utils\FileDialogs.h" />
     <ClInclude Include="src\Utils\GlTexture.h" />
     <ClInclude Include="include\inih\INIReader.h" />
     <ClInclude Include="include\ocio\OpenColorABI.h" />

RealBloomCPP/RealBloomCPP.vcxproj.filters

@@ -123,6 +123,9 @@
     <ClCompile Include="src\Utils\CliStackTimer.cpp">
       <Filter>Source Files</Filter>
     </ClCompile>
+    <ClCompile Include="src\Utils\FileDialogs.cpp">
+      <Filter>Source Files</Filter>
+    </ClCompile>
   </ItemGroup>
   <ItemGroup>
     <ClInclude Include="src\RealBloom\DiffractionPattern.h">
@@ -473,6 +476,9 @@
     <ClInclude Include="src\Utils\CliStackTimer.h">
       <Filter>Header Files</Filter>
     </ClInclude>
+    <ClInclude Include="src\Utils\FileDialogs.h">
+      <Filter>Header Files</Filter>
+    </ClInclude>
   </ItemGroup>
   <ItemGroup>
     <None Include="libs\glfw3\glfw3.dll" />

RealBloomCPP/demo/Scripts/anim_conv.py

@@ -0,0 +1,70 @@
+# This is a script for using RealBloom's CLI to apply convolutional bloom on a sequence of frames.
+# https://github.com/bean-mhm/realbloom
+
+import subprocess
+import time
+
+# Paths
+rb_path = "path to RealBloom.exe"
+frames_dir = "path to the folder containing the frames, must end with a (back)slash"
+kernel_path = "path to the kernel"
+output_dir = "path to the folder containing the output frames, must end with a (back)slash"
+
+# Frames
+frame_start = 1
+frame_end = 50
+
+# Example: frame0001.exr
+frame_prefix = "frame"
+frame_length = 4
+frame_suffix = ".exr"
+
+# Color Spaces (w = working space)
+frames_cs = "w"
+kernel_cs = "w"
+output_cs = "w"
+
+# Additional Arguments
+arguments = "--kernel-contrast 0.05 --kernel-crop 0.8 --autoexp --mix 0.15"
+
+"""
+Arguments:
+  --input, -i             * Input filename
+  --input-space, -a       * Input color space
+  --kernel, -k            * Kernel filename
+  --kernel-space, -b      * Kernel color space
+  --output, -o            * Output filename
+  --output-space, -c      * Output color space
+  --kernel-exposure, -e   Kernel exposure [def: 0]
+  --kernel-contrast, -f   Kernel contrast [def: 0]
+  --kernel-rotation, -r   Kernel rotation [def: 0]
+  --kernel-scale, -s      Kernel scale [def: 1]
+  --kernel-crop, -q       Kernel crop [def: 1]
+  --kernel-center, -u     Kernel center [def: 0.5,0.5]
+  --threshold, -t         Threshold [def: 0]
+  --knee, -w              Threshold knee [def: 0]
+  --autoexp, -n           Auto-Exposure
+  --input-mix, -x         Input mix (additive blending)
+  --conv-mix, -y          Output mix (additive blending)
+  --mix, -m               Blend between input and output (normal blending) [def: 1]
+  --conv-exposure, -z     Conv. output exposure [def: 0]
+  --verbose, -v           Enable verbose logging
+"""
+
+for i in range(frame_start, frame_end + 1):
+    filename = frame_prefix + str(i).zfill(frame_length) + frame_suffix
+    command = "\"{}\" conv -i \"{}\" -a \"{}\" -k \"{}\" -b \"{}\" -o \"{}\" -c \"{}\" {}"
+    command = command.format(
+        rb_path,
+        frames_dir + filename,
+        frames_cs,
+        kernel_path,
+        kernel_cs,
+        output_dir + filename,
+        output_cs,
+        arguments
+    )
+    start = time.time()
+    subprocess.call(command)
+    end = time.time()
+    print(filename + " done in {:.1f} ms".format((end - start) * 1000.0))

RealBloomCPP/imgui.ini

@@ -4,10 +4,10 @@ Size=1440,810
 Collapsed=0
 
 [Window][Misc]
-Pos=0,552
-Size=283,258
+Pos=0,561
+Size=283,249
 Collapsed=0
-DockId=0x00000004,0
+DockId=0x00000006,0
 
 [Window][Debug##Default]
 Pos=60,60
@@ -16,44 +16,44 @@ Collapsed=0
 
 [Window][Image List]
 Pos=0,0
-Size=283,269
+Size=283,305
 Collapsed=0
-DockId=0x00000005,0
+DockId=0x00000003,0
 
 [Window][Image Viewer]
 Pos=285,0
-Size=829,810
+Size=822,810
 Collapsed=0
 DockId=0x00000002,0
 
 [Window][Diffraction Pattern]
-Pos=1116,0
-Size=324,384
+Pos=1109,0
+Size=331,417
 Collapsed=0
 DockId=0x00000009,0
 
 [Window][Convolution]
-Pos=1116,386
-Size=324,424
+Pos=1109,419
+Size=331,391
 Collapsed=0
 DockId=0x0000000A,0
 
 [Window][Color Management]
-Pos=0,271
-Size=283,279
+Pos=0,307
+Size=283,252
 Collapsed=0
-DockId=0x00000006,0
+DockId=0x00000004,0
 
 [Docking][Data]
 DockSpace         ID=0x8B93E3BD Window=0xA787BDB4 Pos=0,0 Size=1440,810 Split=X
-  DockNode        ID=0x00000007 Parent=0x8B93E3BD SizeRef=1594,1009 Split=X
+  DockNode        ID=0x00000007 Parent=0x8B93E3BD SizeRef=1587,1009 Split=X
     DockNode      ID=0x00000001 Parent=0x00000007 SizeRef=283,1009 Split=Y Selected=0x3232ABD5
-      DockNode    ID=0x00000003 Parent=0x00000001 SizeRef=335,685 Split=Y Selected=0x775F88F2
-        DockNode  ID=0x00000005 Parent=0x00000003 SizeRef=335,335 Selected=0x41D61AAD
-        DockNode  ID=0x00000006 Parent=0x00000003 SizeRef=335,348 Selected=0x775F88F2
-      DockNode    ID=0x00000004 Parent=0x00000001 SizeRef=335,322 Selected=0x3232ABD5
-    DockNode      ID=0x00000002 Parent=0x00000007 SizeRef=1309,1009 CentralNode=1 Selected=0x7316D680
-  DockNode        ID=0x00000008 Parent=0x8B93E3BD SizeRef=324,1009 Split=Y Selected=0x5A7F401A
-    DockNode      ID=0x00000009 Parent=0x00000008 SizeRef=271,478 Selected=0x5A7F401A
-    DockNode      ID=0x0000000A Parent=0x00000008 SizeRef=271,529 Selected=0x1AABE1E7
+      DockNode    ID=0x00000005 Parent=0x00000001 SizeRef=335,559 Split=Y Selected=0x41D61AAD
+        DockNode  ID=0x00000003 Parent=0x00000005 SizeRef=283,305 Selected=0x41D61AAD
+        DockNode  ID=0x00000004 Parent=0x00000005 SizeRef=283,252 Selected=0x775F88F2
+      DockNode    ID=0x00000006 Parent=0x00000001 SizeRef=335,249 Selected=0x3232ABD5
+    DockNode      ID=0x00000002 Parent=0x00000007 SizeRef=1302,1009 CentralNode=1 Selected=0x7316D680
+  DockNode        ID=0x00000008 Parent=0x8B93E3BD SizeRef=331,1009 Split=Y Selected=0x5A7F401A
+    DockNode      ID=0x00000009 Parent=0x00000008 SizeRef=331,520 Selected=0x5A7F401A
+    DockNode      ID=0x0000000A Parent=0x00000008 SizeRef=331,487 Selected=0x1AABE1E7
 

RealBloomCPP/src/Async.cpp

@@ -1,29 +1,29 @@
 #include "Async.h"
 
-std::unordered_map<std::string, void*> Async::s_shared;
-std::mutex Async::s_sharedMutex;
+std::unordered_map<std::string, void*> Async::S_SHARED;
+std::mutex Async::S_SHARED_MUTEX;
 
-std::deque<std::packaged_task<void()>> Async::s_tasks;
-std::mutex Async::s_tasksMutex;
+std::deque<std::packaged_task<void()>> Async::S_TASKS;
+std::mutex Async::S_TASKS_MUTEX;
 
 void Async::schedule(std::function<void()> job)
 {
     std::packaged_task<void()> task(job);
     {
-        std::lock_guard<std::mutex> lock(s_tasksMutex);
-        s_tasks.push_back(std::move(task));
+        std::lock_guard<std::mutex> lock(S_TASKS_MUTEX);
+        S_TASKS.push_back(std::move(task));
     }
 }
 
 void Async::putShared(std::string key, void* value)
 {
-    std::lock_guard<std::mutex> lock(s_sharedMutex);
-    s_shared[key] = value;
+    std::lock_guard<std::mutex> lock(S_SHARED_MUTEX);
+    S_SHARED[key] = value;
 }
 
 void* Async::getShared(std::string key)
 {
-    if (s_shared.contains(key))
-        return s_shared[key];
+    if (S_SHARED.contains(key))
+        return S_SHARED[key];
     return nullptr;
 }