Introduce new cli-tool

README.md

@@ -32,6 +32,100 @@ ToDo
 
 ToDo
 
+## Tools
+
+### glkernel-cli
+
+The glkernel-cli tool provides a convenient way to generate and manipulate kernels using the command line.  
+The usage is as follows:
+
+```
+glkernel-cli [--force] [--beautify] [--output <outputFileName>] [--format <outputFileFormat>] <inputFileName>
+
+Options:
+ -b, --beautify  Beautify the output (only applies to json output format)
+     --force     Override the output file, if it exists
+ -f, --format    File format for the generated / converted kernel (e.g., json, png, h)
+ -o, --output    File that the generated / converted kernel will be written to (defaults: <inputFileName>.json for generation, <inputFileName>.png for conversion)
+```
+
+- The default output format for kernel generation is JSON
+- The default output format for kernel conversion is PNG
+- If not output file name is given, the output file name will be deduced from the input file name (here, it would be `kernel.json`)
+- If no output format is given, the output format will be deduced from the output file name (explicitly given or deduced)
+
+#### Generating a kernel using JavaScript
+
+Kernels can be generated from JavaScript by simply passing a `.js` file as input to the command line tool.
+Examples:
+
+```
+$ glkernel-cli kernel.js
+
+$ glkernel-cli kernel.js -o random_noise_kernel.json --force --beautify
+
+$ glkernel-cli kernel.js -o sorted_kernel -f png
+```
+
+A JavaScript interface (`JSInterface.h`, `JSInterface.cpp`, `glkernel.js`) allows calling glkernel functionality from user scripts.
+It is included in the tool's sources (C++ files), and in the `data/` directory (JavaScript file).
+The interface is automatically generated from the existing glkernel API.
+
+__If you extend or change the glkernel API, please [re-generate the JavaScript interface](#generating-the-javascript-interface)!__
+
+##### Writing kernel generation instructions in JavaScript
+
+While the glkernel library uses free functions, the JavaScript API provides manipulation of kernels via object methods on kernel objects.
+The API method names are taken from the library.
+
+The following script shows the usage of the JavaScript API by example (it can be found in `scripts/kernel.js`):
+
+```javascript
+// create new Kernel2 object (i.e., a 3D kernel of dimensions 10x5x2, holding vec2's as values
+var kernel = new Kernel2(10, 5, 2);
+
+// translates to glkernel::sequence::uniform(kernel, 0.0, 1.0)
+kernel.sequence.uniform(0.0, 1.0);
+
+// examples for other kernel methods
+kernel.shuffle.random();
+kernel.scale.range(-1.0, 1.0);
+
+// glkernel::sort::distance for a Kernel2 requires a vec2 as parameter
+// vec parameters can be passed as JavaScript arrays
+kernel.sort.distance([0.0, 0.0]);
+```
+
+#### Converting an existing kernel
+
+After generating a kernel in JSON format, that kernel can be read by the tool to be converted into another representation (e.g., PNG).
+This is achieved by simply passing a `.json` file as input to the command line tool.
+Examples:
+
+```
+$ glkernel-cli kernel.json
+
+$ glkernel-cli kernel.json -o sorted_kernel -f png --force
+```
+
+If no output file or format is given, the default output format is PNG.
+
+#### Generating the JavaScript interface
+
+The JavaScript interface files can simply be re-generated using the CMake `generate` target, either from your IDE, or from the project's root folder using the following CMake command:
+
+```
+$ cmake --build ./build --target generate
+```
+
+This requires Python 2 or 3 to be installed on the system.
+Alternatively, the Python script can be executed manually (also from the root folder):
+
+__TODO__: update this if the destination of JS and C++ files are different
+```
+$ python scripts/generate.py -t scripts/templates -d source/tools/glkernel-cli
+```
+
 ##### glkernel-cmd
 
 Additionally to using glkernel as a library, there is a standalone command line tool to generate kernels from JSON descriptions.

data/glkernel.js

@@ -0,0 +1,192 @@
+
+// THIS IS A GENERATED FILE!
+// DO NOT EDIT
+
+GradientNoiseType = {
+    Perlin: 0,
+    Simplex: 1
+};
+
+HemisphereMapping = {
+    Uniform: 0,
+    Cosine: 1
+};
+
+OctaveType = {
+    Standard: 0,
+    Cloud: 1,
+    CloudAbs: 2,
+    Wood: 3,
+    Paper: 4
+};
+
+var _Kernel = function(x,y,z) {
+    this._initialize = function(x,y,z) {
+        var that = this;
+
+        this.kernel = this.generateKernel(x,y,z);
+
+        this.noise = {
+            uniform: function(range_min, range_max) {
+                _glkernel.noise_uniform(that.kernel, range_min, range_max);
+                return that;
+            },
+            normal: function(mean, stddev) {
+                _glkernel.noise_normal(that.kernel, mean, stddev);
+                return that;
+            },
+            gradient: function(noise_type, octave_type, startFrequency, octaves) {
+                // Defaults
+                noise_type = (typeof noise_type !== 'undefined') ? noise_type : GradientNoiseType.Perlin;
+                octave_type = (typeof octave_type !== 'undefined') ? octave_type : OctaveType.Standard;
+                startFrequency = (typeof startFrequency !== 'undefined') ? startFrequency : 3;
+                octaves = (typeof octaves !== 'undefined') ? octaves : 5;
+
+                _glkernel.noise_gradient(that.kernel, noise_type, octave_type, startFrequency, octaves);
+                return that;
+            }
+        };
+        this.sample = {
+            poisson_square: function(num_probes) {
+                // Defaults
+                num_probes = (typeof num_probes !== 'undefined') ? num_probes : 32;
+
+                _glkernel.sample_poisson_square(that.kernel, num_probes);
+                return that;
+            },
+            poisson_square: function(min_dist, num_probes) {
+                // Defaults
+                num_probes = (typeof num_probes !== 'undefined') ? num_probes : 32;
+
+                _glkernel.sample_poisson_square1(that.kernel, min_dist, num_probes);
+                return that;
+            },
+            stratified: function() {
+                _glkernel.sample_stratified(that.kernel);
+                return that;
+            },
+            hammersley: function() {
+                _glkernel.sample_hammersley(that.kernel);
+                return that;
+            },
+            halton: function(base1, base2) {
+                _glkernel.sample_halton(that.kernel, base1, base2);
+                return that;
+            },
+            hammersley_sphere: function(type) {
+                // Defaults
+                type = (typeof type !== 'undefined') ? type : HemisphereMapping.Uniform;
+
+                _glkernel.sample_hammersley_sphere(that.kernel, type);
+                return that;
+            },
+            halton_sphere: function(base1, base2, type) {
+                // Defaults
+                type = (typeof type !== 'undefined') ? type : HemisphereMapping.Uniform;
+
+                _glkernel.sample_halton_sphere(that.kernel, base1, base2, type);
+                return that;
+            },
+            best_candidate: function(num_candidates) {
+                // Defaults
+                num_candidates = (typeof num_candidates !== 'undefined') ? num_candidates : 32;
+
+                _glkernel.sample_best_candidate(that.kernel, num_candidates);
+                return that;
+            },
+            n_rooks: function() {
+                _glkernel.sample_n_rooks(that.kernel);
+                return that;
+            },
+            multi_jittered: function(correlated) {
+                // Defaults
+                correlated = (typeof correlated !== 'undefined') ? correlated : false;
+
+                _glkernel.sample_multi_jittered(that.kernel, correlated);
+                return that;
+            },
+            golden_point_set: function() {
+                _glkernel.sample_golden_point_set(that.kernel);
+                return that;
+            }
+        };
+        this.scale = {
+            range: function(rangeToLower, rangeToUpper, rangeFromLower, rangeFromUpper) {
+                // Defaults
+                rangeFromLower = (typeof rangeFromLower !== 'undefined') ? rangeFromLower : 0;
+                rangeFromUpper = (typeof rangeFromUpper !== 'undefined') ? rangeFromUpper : 1;
+
+                _glkernel.scale_range(that.kernel, rangeToLower, rangeToUpper, rangeFromLower, rangeFromUpper);
+                return that;
+            }
+        };
+        this.sequence = {
+            uniform: function(range_min, range_max) {
+                _glkernel.sequence_uniform(that.kernel, range_min, range_max);
+                return that;
+            }
+        };
+        this.shuffle = {
+            bucket_permutate: function(subkernel_width, subkernel_height, subkernel_depth, permutate_per_bucket) {
+                // Defaults
+                subkernel_width = (typeof subkernel_width !== 'undefined') ? subkernel_width : 1;
+                subkernel_height = (typeof subkernel_height !== 'undefined') ? subkernel_height : 1;
+                subkernel_depth = (typeof subkernel_depth !== 'undefined') ? subkernel_depth : 1;
+                permutate_per_bucket = (typeof permutate_per_bucket !== 'undefined') ? permutate_per_bucket : false;
+
+                _glkernel.shuffle_bucket_permutate(that.kernel, subkernel_width, subkernel_height, subkernel_depth, permutate_per_bucket);
+                return that;
+            },
+            bayer: function() {
+                _glkernel.shuffle_bayer(that.kernel);
+                return that;
+            },
+            random: function(start) {
+                // Defaults
+                start = (typeof start !== 'undefined') ? start : 1;
+
+                _glkernel.shuffle_random(that.kernel, start);
+                return that;
+            }
+        };
+        this.sort = {
+            distance: function(origin) {
+                _glkernel.sort_distance(that.kernel, origin);
+                return that;
+            }
+        };
+    };
+};
+
+var Kernel1 = function(x,y,z) {
+    this.generateKernel = function(x,y,z) {
+        return _glkernel.createKernel1(x,y,z);
+    }
+    this._initialize(x,y,z);
+};
+
+var Kernel2 = function(x,y,z) {
+    this.generateKernel = function(x,y,z) {
+        return _glkernel.createKernel2(x,y,z);
+    }
+    this._initialize(x,y,z);
+};
+
+var Kernel3 = function(x,y,z) {
+    this.generateKernel = function(x,y,z) {
+        return _glkernel.createKernel3(x,y,z);
+    }
+    this._initialize(x,y,z);
+};
+
+var Kernel4 = function(x,y,z) {
+    this.generateKernel = function(x,y,z) {
+        return _glkernel.createKernel4(x,y,z);
+    }
+    this._initialize(x,y,z);
+};
+
+Kernel1.prototype = new _Kernel;
+Kernel2.prototype = new _Kernel;
+Kernel3.prototype = new _Kernel;
+Kernel4.prototype = new _Kernel;