This is DeepDrill 3.2

dirkwhoffmann · Aug 24, 2023 · f2aaa0b · f2aaa0b
1 parent 233e6db
commit f2aaa0b
Show file tree

Hide file tree

Showing 7 changed files with 66 additions and 9 deletions.
diff --git a/DeepDrill.xcodeproj/project.pbxproj b/DeepDrill.xcodeproj/project.pbxproj
@@ -734,9 +734,9 @@
 		50BEC7562694873C00CCDFA8 /* palettes */ = {
 			isa = PBXGroup;
 			children = (
-				5029516D2A5E906300484F24 /* transparent.png */,
 				5072FD582A2718BD003DE341 /* white.png */,
 				5047B4FC29FD537D00AC38DC /* prism.png */,
+				5029516D2A5E906300484F24 /* transparent.png */,
 				5047B4E729F9623500AC38DC /* candy.png */,
 				5047B4EA29F9625600AC38DC /* default.png */,
 				5047B4E829F9624100AC38DC /* dolomiti.png */,

diff --git a/docs/References/Colorizers.md b/docs/References/Colorizers.md
@@ -0,0 +1,47 @@
+# Colorizing Algorithms
+
+DeepDrill offers multiple algorithms for colorizing images. 
+
+## Classic Escape-time Coloring 
+
+The classic escape-time coloring algorithm computes an iteration count for each pixel and uses this value as an index into a color table. To select the classic algorithm in DeepDrill, set the `palette.mode` key to `classic`:
+
+```shell
+./deepdrill top.ini -o top.jpg palette.mode=classic
+```
+![Classic escape-time coloring](images/classic.jpg "Classic escape-time coloring")
+
+The image shows the typical color bands that can be seen in many Mandelbrot images, especially older ones. They stem from the fact that the iteration count is an integer value that can only increase in discrete steps.
+
+## Continuous Escape-time Coloring
+
+Color bands can be eliminated by using fractional iteration counts. Please refer to the theory section to learn how the iteration count can be made continuous. To use this coloring method in DeepDrill, set the `palette.mode` key to `smooth`:
+```shell
+./deepdrill top.ini -o top.jpg palette.mode=smooth
+```
+![Continuous escape-time coloring](images/smooth.jpg "Continuous escape-time coloring")
+
+## Distance Coloring
+
+Distance coloring is based on the estimated distance of a pixel from the Mandelbrot set. This colorizing technique is often applied for computing black-and-white images because it can lead to very crisp illustrations of the Mandelbrot set. 
+
+To create such images, DeepDrill offers a special GPU shader called `distance.glsl`. It can be activated as follows: 
+```shell
+./deepdrill seahorse2.ini -o seahorse2.map -o seahorse2.jpg palette.image=white.png gpu.colorizer=distance.glsl distance.threshold=0.2
+```
+![Distance Coloring](images/distance1.jpg "Distance Coloring")
+
+By using different color options, it is possible to create partially transparent images. E.g., to create the image shown
+above with a transparent background, run DeepDrill with the `transparent` palette:
+```shell
+./deepdrill seahorse2.map -o seahorse2b.png palette.image=transparent.png gpu.colorizer=distance.glsl distance.threshold=0.2
+```
+![Distance Coloring](images/distance2.png "Distance Coloring (transparent background)")
+
+When adding transparency, make sure to export to a png image since the jpg format and bmp format ignore any alpha channel information.
+
+Alternatively, you may choose to use a transparent color for the Mandelbrot set:
+```shell
+./deepdrill seahorse2.map -o seahorse2c.png palette.image=white.png palette.bgcolor=transparent gpu.colorizer=distance.glsl distance.threshold=0.2
+```
+![Distance Coloring](images/distance3.png "Distance Coloring (transparent foreground)")
diff --git a/docs/References/Options.md b/docs/References/Options.md
@@ -36,7 +36,9 @@ Each option is briefly explained below:
 |-----|---------|-------------|
 | `width`  | 1920 | The horizontal resolution of the drill map. If this key is not specified, the width of the drill map is automatically chosen to match the image width.
 | `height`  | 1080 | The vertical resolution of the drill map. If this key is not specified, the width of the drill map is automatically chosen to match the image height.
-| `depth`  | 1 | Possible values are 0 and 1. If set to 1, a normal map will be written to the `.map` file.
+
+### Section `[mapfile]`
+
 | `compress`  | yes | Indicates whether map files should be saved in compressed format.
 
 
@@ -65,9 +67,17 @@ Each option is briefly explained below:
 | <div style="width:120px">Key</div> | <div style="width:100px">Default value</div> | Description |
 |-----|---------|-------------|
 | `image`  | - | Path to an image file storing the color palette. DeepDrill will derive the color palette from the uppermost horizontal line of the image.
+| `bgcolor`  | black | Background color. This color is used for colorizing pixels belonging to the Mandelbrot set.
+| `mode`  | smooth | Coloring mode. Options are `classic` and `smooth`. 
 | `scale`  | 1.0 | An optional scaling factor that can be used to stretch or shrink the color palette.  
-| `offset`  | 0.0 | An optional offset that can be used to rotate the color palette.  
+| `offset`  | -0.15 | An optional offset that can be used to rotate the color palette.  
+
+### Section `[distance]`
 
+| <div style="width:120px">Key</div> | <div style="width:100px">Default value</div> | Description |
+|-----|---------|-------------|
+| `threshold`  | 0.0 | This value is used by the distance-estimation filter. A pixel is considered to be part of the Mandelbrot 
+set if its distance estimate is below the threshold value. Smaller numbers lead to more fine-grained images. 
 
 ### Section `[texture]`
 | <div style="width:120px">Key</div> | <div style="width:100px">Default value</div> | Description |

diff --git a/docs/conf.py b/docs/conf.py
@@ -9,7 +9,7 @@
 project = 'DeepDrill'
 copyright = '2023, Dirk W. Hoffmann'
 author = 'Dirk W. Hoffmann'
-release = '3.1'
+release = '3.2'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -40,4 +40,4 @@
 }
 html_static_path = ['_static']
 html_logo = "images/icon.png"
-html_title = "DeepDrill 3.1"
+html_title = "DeepDrill 3.2"
diff --git a/docs/index.rst b/docs/index.rst
@@ -54,6 +54,7 @@ Table of Contents
    :maxdepth: 1
    :caption: References
 
+   References/Colorizers
    References/Options
    References/Examples
    References/Links
diff --git a/src/config.h b/src/config.h
@@ -21,13 +21,13 @@
 #define VER_MINOR       2
 #define VER_SUBMINOR    0
 
-#define VER_BETA        1
+#define VER_BETA        0
 
 // Mapfile format
 #define MAP_FORMAT      320
 
 // Uncomment this setting in a release build
-// #define RELEASEBUILD
+#define RELEASEBUILD
 
 
 //

diff --git a/src/shared/Options.cpp b/src/shared/Options.cpp
@@ -84,8 +84,7 @@ std::map<string,string> Options::defaults = [](){
     defaults["palette.offset"] = "-0.15";
 
     // Distance estimation keys
-    // defaults["distance.enable"] = "no";
-    defaults["distance.threshold"] = "0.2";
+    defaults["distance.threshold"] = "0.0";
 
     // Texture keys
     defaults["texture.image"] = "";