gsdf is a CAD 3D design library for Go that uses SDFs for shape definition. Rendering can be done on GPU or CPU
for visualization or 3D printing file outputs. Quick jump to usage: bolt example.
All images and shapes in readme were generated using this library.
- Go 1.25 or newer.
- Optional, for GPU usage: GPU evaluation and the UI use WebGPU which runs on Metal (macOS), Vulkan (Linux, Windows), D3D12 (Windows) and in the browser (WASM).
- Native builds require cgo and a GPU driver. On Debian/Ubuntu install
libegl1-mesa-dev mesa-vulkan-drivers libxcursor-dev libxi-dev libxinerama-dev libxrandr-dev libxxf86vm-dev libxkbcommon-dev libwayland-dev. - The first cgo build of a program importing
gpusdf(orgsdfaux) downloads prebuilt wgpu-native static libraries for all operating systems (several hundred MB). CPU-only users ofgsdf,glevalandglrenderdo not download them. - Builds without cgo and TinyGo builds compile and run on CPU; GPU functions return an error.
- Native builds require cgo and a GPU driver. On Debian/Ubuntu install
-
High test coverage. GPU tests run when a GPU is available, including software GPUs (lavapipe) in CI.
-
NEW!: GPU evaluation via WebGPU. Runs on macOS, Linux, Windows and in the browser. See
gpusdfand the WASM viewer example. -
Reusable WGSL code between shaders. See
gpusdf/glbuild/wgsllib -
Extremely coherent API design.
-
UI for visualizing parts, rendered directly from shaders. See UI example by running
go run ./examples/ui-mandala. Same UI runs in the browser. -
Generate visualization for your parts as WGSL shaders that can be pasted into compute.toys.
-
GPU and CPU implementations for all shapes and operations. CPU implementations are actually faster for simple parts.
-
Include arbitrary buffers into GPU calculation. See
Shaderinterface. -
Heapless algorithms for everything. No usage of GC in happy path.
-
Heapless Octree triangle renderer. Is stupid fast.
- Design your part using one API, switch between CPU and GPU after design.
-
TinyGo supported for CPU evaluation :)
gsdf: Top level package defines exact SDFs primitives and operations for use on CPU or GPU workloads. Consumesglbuildinterfaces and logic to build shaders.gpusdf/glbuild: Shape interfaces and automatic WGSL shader generation. Does not depend on WebGPU, importing it does not importgpusdf.gleval: SDF evaluation interfaces and CPU evaluation facilities.gpusdf: GPU evaluation of SDFs and the interactive UI using WebGPU. Compiles on all targets; functions return an error where no GPU support is available.glrender: Triangle rendering logic which consumes gleval. STL generation.forge: Engineering applications. Composed of subpackages.textsdfpackage for text generation.threadspackage for generating screw threads.
gsdfaux: High level helper functions to get users started up withgsdf. See examples.
Find examples under examples directory. Run on GPU with: -gpu flag.
Most 3D examples output two files:
example-name.wgsl: Visualization shader that can be copy pasted into compute.toys to visualize the part.example-name.stl: Triangle model file used in 3D printing software such as Cura. Can be visualized online in sites such as View STL.
CPU output and timings on 12th Gen Intel i5-12400F (12) @ 4.400GHz. GPU timings on AMD ATI Radeon RX 6800 (Vulkan). Timings vary with system load.
The WASM viewer example runs the same program natively or in the browser, see its index.html for instructions:
GOOS=js GOARCH=wasm go build -o examples/wasm-viewer/main.wasm ./examples/wasm-viewer
cp "$(go env GOROOT)/lib/wasm/wasm_exec.js" examples/wasm-viewer/
python3 -m http.server -d examples/wasm-viewer 8080gsdf previously used OpenGL 4.3 compute shaders. GPU evaluation now uses WebGPU:
glbuildmoved togithub.com/soypat/gsdf/gpusdf/glbuild(andglsllibtogpusdf/glbuild/wgsllib). Update imports, the package name is unchanged.- Shaders are generated in WGSL.
Shader.AppendShaderBodywas renamed toAppendWGSLBodyso customglbuild.Shaderimplementations fail to compile until ported from GLSL to WGSL. gleval.NewComputeGPUSDF3/2,gleval.Init1x1GLFW,PolygonGPU,Lines2DGPU,DisplaceMulti2DandBatchermoved togpusdf(gpusdf.SDF3,gpusdf.Device,gpusdf.Polygon, ...).gsdfaux.MakeGPUSDF2receives a*gpusdf.Device.runtime.LockOSThreadis no longer required for GPU evaluation. It is still required for the UI on macOS.
The simplesdf package provides a extremely simplified API for use by makers who want a more Python-like API. This is particularily useful for short one-off scripts. Note this API uses panics to help track down errors and also is not thread-safe. See examples/simple-knurled-cylinder.
package main
import (
"math"
. "github.com/soypat/gsdf/gsdfaux/simplesdf"
)
func main() {
// main body
f := Cylinder(1, 5, 0.1)
// knurling
x := Box(1, 1, 4, 0).RotateZ(math.Pi / 4)
x = x.Translate(1.6, 0, 0) // radial placement (fogleman circular_array offset)
x = x.CircArray(24, 24) // 24 instances evenly around the circle
x = x.Twist(0.75).Union(x.Twist(-0.75)) // diamond pattern via mirrored twist
f = f.Diff(x.K(0.1))
// central hole
f = f.Diff(Cylinder(0.5, 7, 0).K(0.1))
// vent holes
c := Cylinder(0.25, 3, 0).RotateY(math.Pi / 2) // orient along X
f = f.Diff(c.Translate(0, 0, -2.5).K(0.1))
f = f.Diff(c.Translate(0, 0, 2.5).K(0.1))
f.Save("knurling.stl", STLConfig{ResolutionDivisions: 200})
}This was converted from the original sdf library example.
go run ./examples/npt-flange -resdiv 400 -gpu
[-] using GPU ᵍᵒᵗᵗᵃ ᵍᵒ ᶠᵃˢᵗ
[126ms] init GPU radv AMD Radeon RX 6800 (RADV NAVI21) (vulkan, discrete-gpu) with compute invocation size 64
[9.91ms] GPU shader generated and compiled
[136ms] instantiating evaluation SDF took
[104.2µs] wrote nptflange.wgsl
[1.85s] evaluated SDF 45912059 times and rendered 423852 triangles with 95.72 percent evaluations omitted in octree pruning step with resolution 0.21679485
[327ms] wrote nptflange.stl
[2.32s] render done
finished npt-flange examplego run ./examples/npt-flange -resdiv 400
[-] using CPU
[13.2µs] instantiating evaluation SDF took
[-] CPU parallel evaluation on 11 goroutines
[153.4µs] wrote nptflange.wgsl
[322ms] evaluated SDF 6711686 times and rendered 423852 triangles with resolution 0.21679485
[136ms] wrote nptflange.stl
[459ms] render done
finished npt-flange exampleNote that the amount of triangles is very similar to the NPT flange example, but this part is more computationally complex.
go run ./examples/fibonacci-showerhead -resdiv 350 -gpu
[-] using GPU ᵍᵒᵗᵗᵃ ᵍᵒ ᶠᵃˢᵗ
[106ms] init GPU radv AMD Radeon RX 6800 (RADV NAVI21) (vulkan, discrete-gpu) with compute invocation size 64
[30.08ms] GPU shader generated and compiled
[136ms] instantiating evaluation SDF took
[1.84ms] wrote showerhead.wgsl
[739ms] evaluated SDF 14656720 times and rendered 309872 triangles with 89.08 percent evaluations omitted in octree pruning step with resolution 0.2979682
[230ms] wrote showerhead.stl
[1.11s] render done
showerhead example donego run ./examples/fibonacci-showerhead -resdiv 350
[-] using CPU
[23.6µs] instantiating evaluation SDF took
[-] CPU parallel evaluation on 11 goroutines
[612.9µs] wrote showerhead.wgsl
[1.01s] evaluated SDF 1512025 times and rendered 309872 triangles with resolution 0.2979682
[182ms] wrote showerhead.stl
[1.19s] render done
showerhead example done