Working on description of volumetric cloud code.

Author: wedesoft

src/volumetric_clouds/main.clj

@@ -189,22 +189,25 @@
 
 ;; ### Getting indices of Neighbours
 ;;
-;; The following function determines the neighbouring indices of a cell.recursing over each dimension.
+;; The following function determines the neighbouring indices of a cell recursing over each dimension.
 (defn neighbours
   [& args]
   (if (seq args)
     (mapcat (fn [v] (map (fn [delta] (into [(+ (first args) delta)] v)) [-1 0 1]))
             (apply neighbours (rest args)) )
     [[]]))
 
-
 (facts "Get neighbouring indices"
        (neighbours) => [[]]
        (neighbours 0) => [[-1] [0] [1]]
        (neighbours 3) => [[2] [3] [4]]
        (neighbours 1 10) => [[0 9] [1 9] [2 9] [0 10] [1 10] [2 10] [0 11] [1 11] [2 11]])
 
 
+;; ### Sampling Worley noise
+;; Using above functions one can now implement Worley noise.
+;; For each pixel the distance to the closest seed point is calculated.
+;; The distance to each random point in all neighbouring cells is calculated and the minimum is taken.
 (defn worley-noise
   [{:keys [size dimensions] :as params}]
   (let [random-points (random-points params)]
@@ -220,18 +223,28 @@
                                     (apply wrap-get random-points neighbour))))))
         :double))))
 
-
+;; Here a 256x256 Worley noise tensor is created.
 (def worley (worley-noise (make-noise-params 256 8 2)))
 
+;; The values are normalised to be between 0 and 255.
 (def worley-norm
   (dfn/* (/ 255 (- (dfn/reduce-max worley) (dfn/reduce-min worley)))
          (dfn/- (dfn/reduce-max worley) worley)))
 
+;; Finally one can display the noise.
 (bufimg/tensor->image worley-norm)
 
 ;; ## Perlin noise
-;; https://adrianb.io/2014/08/09/perlinnoise.html
+;;
+;; [Perlin noise](https://adrianb.io/2014/08/09/perlinnoise.html) is generated by choosing a random gradient vector at each cell corner.
+;; The noise tensor's intermediate values are interpolated with a continuous function, utilizing the gradient at the corner points.
 
+;; ### Random gradients
+;;
+;; The 2D or 3D gradients are generated by creating a vector where each component is set to a random number between -1 and 1.
+;; Random vectors are generated until the vector length is greater 0 and lower or equal to 1.
+;; The vector then is normalized and returned.
+;; Random vectors outside the unit circle or sphere are discarded in order to achieve a uniform distribution on the surface of the unit circle or sphere.
 (defn random-gradient
   [& args]
   (loop [args args]
@@ -241,13 +254,13 @@
             (div random-vector vector-length)
             (recur args)))))
 
-
+;; The function below serves as a Midje checker for a vector with an approximate expected value.
 (defn roughly-vec
   [expected error]
   (fn [actual]
       (<= (mag (sub actual expected)) error)))
 
-
+;; In the following tests, the random function is again replaced with a deterministic function.
 (facts "Create unit vector with random direction"
        (with-redefs [rand (constantly 0.5)]
          (random-gradient 0 0)
@@ -256,12 +269,12 @@
          (random-gradient 0 0)
          => (roughly-vec (vec2 (sqrt 0.5) (sqrt 0.5)) 1e-6)))
 
-
+;; The random gradient function is then used to generate a field of random gradients.
 (defn random-gradients
  [{:keys [divisions dimensions]}]
  (tensor/clone (tensor/compute-tensor (repeat dimensions divisions) random-gradient)))
 
-
+;; The function is tested that it generates 2D and 3D random gradient fields correctly.
 (facts "Random gradients"
        (with-redefs [rand (constantly 1.5)]
          (dtype/shape (random-gradients {:divisions 8 :dimensions 2}))
@@ -272,7 +285,7 @@
          ((random-gradients {:divisions 8 :dimensions 3}) 0 0 0)
          => (vec3 (/ 1 (sqrt 3)) (/ 1 (sqrt 3)) (/ 1 (sqrt 3)))))
 
-
+;; The gradient field can be plotted with Plotly as a scatter plot of disconnected lines/
 (let [gradients (tensor/reshape (random-gradients (make-noise-params 256 8 2))
                                 [(* 8 8)])
       points    (tensor/reshape (tensor/compute-tensor [8 8] (fn [y x] (vec2 x y)))