docs(geom-sdf): update readme, add assets

thi-ng · Jun 23, 2022 · 8c5c802 · 8c5c802
1 parent 4ffbc86
commit 8c5c802
Show file tree

Hide file tree

Showing 29 changed files with 167 additions and 3 deletions.
diff --git a/assets/geom-sdf/combine-chamfer-diff.png b/assets/geom-sdf/combine-chamfer-diff.png
diff --git a/assets/geom-sdf/combine-chamfer-isec.png b/assets/geom-sdf/combine-chamfer-isec.png
diff --git a/assets/geom-sdf/combine-chamfer-union.png b/assets/geom-sdf/combine-chamfer-union.png
diff --git a/assets/geom-sdf/combine-none-diff.png b/assets/geom-sdf/combine-none-diff.png
diff --git a/assets/geom-sdf/combine-none-isec.png b/assets/geom-sdf/combine-none-isec.png
diff --git a/assets/geom-sdf/combine-none-union.png b/assets/geom-sdf/combine-none-union.png
diff --git a/assets/geom-sdf/combine-round-diff.png b/assets/geom-sdf/combine-round-diff.png
diff --git a/assets/geom-sdf/combine-round-isec.png b/assets/geom-sdf/combine-round-isec.png
diff --git a/assets/geom-sdf/combine-round-union.png b/assets/geom-sdf/combine-round-union.png
diff --git a/assets/geom-sdf/combine-smooth-diff.png b/assets/geom-sdf/combine-smooth-diff.png
diff --git a/assets/geom-sdf/combine-smooth-isec.png b/assets/geom-sdf/combine-smooth-isec.png
diff --git a/assets/geom-sdf/combine-smooth-union.png b/assets/geom-sdf/combine-smooth-union.png
diff --git a/assets/geom-sdf/combine-steps-diff.png b/assets/geom-sdf/combine-steps-diff.png
diff --git a/assets/geom-sdf/combine-steps-isec.png b/assets/geom-sdf/combine-steps-isec.png
diff --git a/assets/geom-sdf/combine-steps-union.png b/assets/geom-sdf/combine-steps-union.png
diff --git a/assets/geom-sdf/domain-grid-01.png b/assets/geom-sdf/domain-grid-01.png
diff --git a/assets/geom-sdf/domain-grid-02.png b/assets/geom-sdf/domain-grid-02.png
diff --git a/assets/geom-sdf/domain-grid-03.png b/assets/geom-sdf/domain-grid-03.png
diff --git a/assets/geom-sdf/domain-mirror-01.png b/assets/geom-sdf/domain-mirror-01.png
diff --git a/assets/geom-sdf/domain-mirror-02.png b/assets/geom-sdf/domain-mirror-02.png
diff --git a/assets/geom-sdf/domain-mirror-03.png b/assets/geom-sdf/domain-mirror-03.png
diff --git a/assets/geom-sdf/domain-polar-01.png b/assets/geom-sdf/domain-polar-01.png
diff --git a/assets/geom-sdf/domain-polar-02.png b/assets/geom-sdf/domain-polar-02.png
diff --git a/assets/geom-sdf/domain-polar-03.png b/assets/geom-sdf/domain-polar-03.png
diff --git a/assets/geom-sdf/domain-repeat-01.png b/assets/geom-sdf/domain-repeat-01.png
diff --git a/assets/geom-sdf/domain-repeat-02.png b/assets/geom-sdf/domain-repeat-02.png
diff --git a/assets/geom-sdf/domain-repeat-03.png b/assets/geom-sdf/domain-repeat-03.png
diff --git a/packages/geom-sdf/README.md b/packages/geom-sdf/README.md
@@ -10,7 +10,11 @@ This project is part of the
 [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo.
 
 - [About](#about)
+  - [SDF creation](#sdf-creation)
+  - [SDF combinators](#sdf-combinators)
+  - [SDF discretization, sampling & domain modifiers](#sdf-discretization-sampling--domain-modifiers)
   - [Status](#status)
+  - [Related packages](#related-packages)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
 - [API](#api)
@@ -21,12 +25,94 @@ This project is part of the
 
 2D Signed Distance Field creation from [@thi.ng/geom](https://github.com/thi-ng/umbrella/tree/develop/packages/geom) shapes, conversions, sampling, combinators.
 
+Includes several distance functions and SDF operators ported from GLSL
+implementations by:
+
+- Inigo Quilez ([Article](https://iquilezles.org/articles/distfunctions2d/))
+- Mercury demogroup ([HG_SDF](https://mercury.sexy/hg_sdf/))
+
+### SDF creation
+
+SDFs can be directly defined/composed via provided shape primitive functions and
+combinators OR via automatic conversion from @thi.ng/geom geometry
+types/hierarchies. In the latter case various
+[attributes](https://docs.thi.ng/umbrella/geom-sdf/interfaces/SDFAttribs.html)
+can be used to control the conversion process. Regardless of approach, the
+result will be a single distance function which accepts a world position and
+returns the signed distance to the encoded scene.
+
+```ts
+// via direct SDF composition
+import { circle2, union } from "@thi.ng/geom-sdf";
+
+const f = union([circle2([-50, 0], 100), circle2([50, 0], 100)]);
+
+// via conversion
+import { circle, group } from "@thi.ng/geom";
+import { asSDF } from "@thi.ng/geom-sdf";
+
+const f = asSDF(group({}, [circle([-50, 0], 100), circle([50, 0], 100)]));
+```
+
+### SDF combinators
+
+The following table illustrates various options how SDFs can be combined. When
+using the [`asSDF()`](https://docs.thi.ng/umbrella/geom-sdf/modules.html#asSDF)
+geometry converter, these operators can be specified and configured (most are
+parametric) via a shape `group()`'s
+[attributes](https://docs.thi.ng/umbrella/geom-sdf/interfaces/SDFAttribs.html),
+e.g.
+
+```ts
+group({ __sdf: { combine: "diff", chamfer: 50 }}, [
+    rectFromCentroid([-50,-50], 200),
+    rectFromCentroid([50,50], 200),
+])
+```
+
+| Operator | Union                                                                                                    | Difference                                                                                              | Intersection                                                                                            |
+|----------|----------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| default  | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-none-union.png)    | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-none-diff.png)    | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-none-isec.png)    |
+| chamfer  | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-chamfer-union.png) | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-chamfer-diff.png) | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-chamfer-isec.png) |
+| round    | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-round-union.png)   | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-round-diff.png)   | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-round-isec.png)   |
+| smooth   | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-smooth-union.png)  | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-smooth-diff.png)  | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-smooth-isec.png)  |
+| steps    | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-steps-union.png)   | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-steps-diff.png)   | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-steps-isec.png)   |
+
+### SDF discretization, sampling & domain modifiers
+
+The package provides the
+[`sample2d()`](https://docs.thi.ng/umbrella/geom-sdf/modules.html#sample2d) and
+[`asPolygons()`](https://docs.thi.ng/umbrella/geom-sdf/modules.html#asPolygons)
+functions to discretize an SDF and cache results in a buffer (image) and then
+extract contour polygons from it, i.e. convert the 2D back into geometry (see
+example further below). The SDF will be sampled in a user defined bounding
+rectangle (with customizable resolution) and the sampling positions can be
+modulated via several provided domain modifiers to create various axial/spatial
+repetions, symmetries etc. Modifiers are nestable/composable via standard
+functional composition (e.g. using
+[`compL()`](https://docs.thi.ng/umbrella/compose/modules.html#compL)) and also
+support custom modfifiers. The table below illustrates a few examples effects:
+
+| Modifier          |                                                                                                     |                                                                                                     |                                                                                                     |
+|-------------------|-----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
+| `repeat2()`       | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-repeat-01.png) | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-repeat-02.png) | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-repeat-03.png) |
+| `repeatGrid2()`   | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-grid-01.png)   | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-grid-02.png)   | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-grid-03.png)   |
+| `repeatMirror2()` | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-mirror-01.png) | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-mirror-02.png) | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-mirror-03.png) |
+| `repeatPolar2()`  | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-polar-01.png)  | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-polar-02.png)  | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-polar-03.png)  |
+
 ### Status
 
 **ALPHA** - bleeding edge / work-in-progress
 
 [Search or submit any issues for this package](https://github.com/thi-ng/umbrella/issues?q=%5Bgeom-sdf%5D+in%3Atitle)
 
+### Related packages
+
+- [@thi.ng/distance-transform](https://github.com/thi-ng/umbrella/tree/develop/packages/distance-transform) - Binary image to Distance Field transformation
+- [@thi.ng/geom-isoline](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-isoline) - Fast 2D contour line extraction / generation
+- [@thi.ng/pixel](https://github.com/thi-ng/umbrella/tree/develop/packages/pixel) - Typedarray integer & float pixel buffers w/ customizable formats, blitting, drawing, convolution
+- [@thi.ng/shader-ast-stdlib](https://github.com/thi-ng/umbrella/tree/develop/packages/shader-ast-stdlib) - Function collection for modular GPGPU / shader programming with [@thi.ng/shader-ast](https://github.com/thi-ng/umbrella/tree/develop/packages/shader-ast)
+
 ## Installation
 
 ```bash
@@ -50,7 +136,7 @@ node --experimental-repl-await
 > const geomSdf = await import("@thi.ng/geom-sdf");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 2.63 KB
+Package sizes (gzipped, pre-treeshake): ESM: 4.08 KB
 
 ## Dependencies
 
@@ -94,7 +180,8 @@ const scene = group({ stroke: "red", __sdf: { smooth: 20 } }, [
 ]);
 
 // compute bounding box + some extra margin
-// the margin is to ensure
+// the extra margin is to ensure the SDF can be fully sampled
+// at some distance from the original boundary (see further below)
 const sceneBounds = bounds(scene, 40);
 
 // convert to an SDF distance function

diff --git a/packages/geom-sdf/tpl.readme.md b/packages/geom-sdf/tpl.readme.md
@@ -13,6 +13,82 @@ This project is part of the
 
 ${pkg.description}
 
+Includes several distance functions and SDF operators ported from GLSL
+implementations by:
+
+- Inigo Quilez ([Article](https://iquilezles.org/articles/distfunctions2d/))
+- Mercury demogroup ([HG_SDF](https://mercury.sexy/hg_sdf/))
+
+### SDF creation
+
+SDFs can be directly defined/composed via provided shape primitive functions and
+combinators OR via automatic conversion from @thi.ng/geom geometry
+types/hierarchies. In the latter case various
+[attributes](https://docs.thi.ng/umbrella/geom-sdf/interfaces/SDFAttribs.html)
+can be used to control the conversion process. Regardless of approach, the
+result will be a single distance function which accepts a world position and
+returns the signed distance to the encoded scene.
+
+```ts
+// via direct SDF composition
+import { circle2, union } from "@thi.ng/geom-sdf";
+
+const f = union([circle2([-50, 0], 100), circle2([50, 0], 100)]);
+
+// via conversion
+import { circle, group } from "@thi.ng/geom";
+import { asSDF } from "@thi.ng/geom-sdf";
+
+const f = asSDF(group({}, [circle([-50, 0], 100), circle([50, 0], 100)]));
+```
+
+### SDF combinators
+
+The following table illustrates various options how SDFs can be combined. When
+using the [`asSDF()`](https://docs.thi.ng/umbrella/geom-sdf/modules.html#asSDF)
+geometry converter, these operators can be specified and configured (most are
+parametric) via a shape `group()`'s
+[attributes](https://docs.thi.ng/umbrella/geom-sdf/interfaces/SDFAttribs.html),
+e.g.
+
+```ts
+group({ __sdf: { combine: "diff", chamfer: 50 }}, [
+    rectFromCentroid([-50,-50], 200),
+    rectFromCentroid([50,50], 200),
+])
+```
+
+| Operator | Union                                                                                                    | Difference                                                                                              | Intersection                                                                                            |
+|----------|----------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| default  | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-none-union.png)    | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-none-diff.png)    | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-none-isec.png)    |
+| chamfer  | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-chamfer-union.png) | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-chamfer-diff.png) | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-chamfer-isec.png) |
+| round    | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-round-union.png)   | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-round-diff.png)   | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-round-isec.png)   |
+| smooth   | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-smooth-union.png)  | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-smooth-diff.png)  | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-smooth-isec.png)  |
+| steps    | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-steps-union.png)   | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-steps-diff.png)   | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/combine-steps-isec.png)   |
+
+
+### SDF discretization, sampling & domain modifiers
+
+The package provides the
+[`sample2d()`](https://docs.thi.ng/umbrella/geom-sdf/modules.html#sample2d) and
+[`asPolygons()`](https://docs.thi.ng/umbrella/geom-sdf/modules.html#asPolygons)
+functions to discretize an SDF and cache results in a buffer (image) and then
+extract contour polygons from it, i.e. convert the 2D back into geometry (see
+example further below). The SDF will be sampled in a user defined bounding
+rectangle (with customizable resolution) and the sampling positions can be
+modulated via several provided domain modifiers to create various axial/spatial
+repetions, symmetries etc. Modifiers are nestable/composable via standard
+functional composition (e.g. using
+[`compL()`](https://docs.thi.ng/umbrella/compose/modules.html#compL)) and also
+support custom modfifiers. The table below illustrates a few examples effects:
+
+| Modifier          |                                                                                                     |                                                                                                     |                                                                                                     |
+|-------------------|-----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
+| `repeat2()`       | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-repeat-01.png) | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-repeat-02.png) | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-repeat-03.png) |
+| `repeatGrid2()`   | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-grid-01.png)   | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-grid-02.png)   | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-grid-03.png)   |
+| `repeatMirror2()` | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-mirror-01.png) | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-mirror-02.png) | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-mirror-03.png) |
+| `repeatPolar2()`  | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-polar-01.png)  | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-polar-02.png)  | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-sdf/domain-polar-03.png)  |
+
 ${status}
 
 ${supportPackages}
@@ -62,7 +138,8 @@ const scene = group({ stroke: "red", __sdf: { smooth: 20 } }, [
 ]);
 
 // compute bounding box + some extra margin
-// the margin is to ensure
+// the extra margin is to ensure the SDF can be fully sampled
+// at some distance from the original boundary (see further below)
 const sceneBounds = bounds(scene, 40);
 
 // convert to an SDF distance function