add docs

docs/lib2x-nz_perlin3.md

@@ -0,0 +1,34 @@
+# nz_perlin3
+
+Returns the 3D [Perlin noise](https://en.wikipedia.org/wiki/Perlin_noise) value at the (x, y, z) coordinate.
+
+**Since:** 2.3
+
+## Parameters
+
+- `x` : The x coordinate.
+- `y` : The y coordinate.
+- `z` : The z coordinate.
+- `seed` : The random seed.
+
+## Examples
+
+    use <util/rand.scad>;
+    use <noise/nz_perlin3.scad>;
+
+    seed = rand(0, 255);
+    noised = [
+        for(z = [0:.2:5])
+            for(y = [0:.2:5])
+                for(x = [0:.2:5])
+                    [x, y, z, nz_perlin3(x, y, z, seed)]
+    ];    
+
+    for(nz = noised) {
+        if(nz[3] > 0.2) {
+            translate([nz[0], nz[1], nz[2]])
+                cube(.2);
+        }
+    }
+
+![nz_perlin3](images/lib2x-nz_perlin3-1.JPG)

docs/lib2x-nz_perlin3s.md

@@ -0,0 +1,61 @@
+# nz_perlin3s
+
+Returns 3D [Perlin noise](https://en.wikipedia.org/wiki/Perlin_noise) values at (x, y, z) coordinates.
+
+**Since:** 2.3
+
+## Parameters
+
+- `points` : A list of `[x, y, z]` coordinates.
+- `seed` : The random seed. If it's ignored, a randomized value will be used.
+
+## Examples
+
+    use <util/rand.scad>;
+    use <noise/nz_perlin2s.scad>;
+    use <noise/nz_perlin3s.scad>;
+
+    points = [
+        for(y = [0:.2:10])
+            [
+                for(x = [0:.2:10])
+                [x, y]
+            ]
+    ];
+
+    seed = rand(0, 256);
+
+    points_with_h = [
+            for(ri = [0:len(points) - 1])
+                let(ns = nz_perlin2s(points[ri], seed))
+                    [
+                        for(ci = [0:len(ns) - 1])
+                            [points[ri][ci][0], points[ri][ci][1], ns[ci] + 1]
+                    ]
+        ];
+
+    h_scale = 1.5;
+    for(row = points_with_h) {        
+        for(i = [0:len(row) - 1]) {
+            p = row[i];
+            pts = [
+                for(z = [0:.2:p[2] * h_scale]) [p[0], p[1], z]
+            ];
+            noise = nz_perlin3s(pts, seed);
+            for(j = [0:len(pts) - 1]) {
+                if(noise[j] > 0) {
+                    color(
+                        pts[j][2] < 1 ? "green" : 
+                        pts[j][2] < 1.5 ? "Olive" : "white")
+                    translate(pts[j])
+                        cube(.2);
+                }           
+            }
+        }
+    }
+
+    color("LimeGreen")
+    linear_extrude(.2)
+        square(10);
+
+![nz_perlin3s](images/lib2x-nz_perlin3s-1.JPG)