Convert csg.js from JavaScript to Go

Author: rene-post

LICENSE

@@ -1,7 +1,7 @@
 MIT License
 
+Copyright (c) 2021 René Post (https://github.com/reactivego)
 Copyright (c) 2011 Evan Wallace (http://madebyevan.com/)
-Copyright (c) 2021 René Post
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,3 +1,86 @@
 # csg
 
-Constructive solid geometry on meshes using BSP trees in Go
+    import "github.com/reactivego/csg"
+
+[![Go Reference](https://pkg.go.dev/badge/github.com/reactivego/csg.svg)](https://pkg.go.dev/github.com/reactivego/csg#section-documentation)
+
+![Example](../assets/example.svg)
+
+Constructive Solid Geometry (CSG) is a modeling technique that uses Boolean operations like union and intersection to combine 3D solids. This library implements CSG operations on meshes elegantly and concisely using BSP trees, and is meant to serve as an easily understandable implementation of the algorithm. All edge cases involving overlapping coplanar polygons in both solids are correctly handled.
+
+Example usage:
+``` go
+import "github.com/reactivego/csg"
+
+cube := csg.Cube()
+sphere := csg.Sphere(csg.Radius(1.3))
+polygons := cube.Subtract(sphere).Polygons
+```
+
+## Operations
+
+This library provides three CSG operations: union, subtract, and intersect.
+The operations are rendered below.
+
+| ![Cube](../assets/cube.svg) | ![Sphere](../assets/sphere.svg) |
+|:---:|:---:|
+| `a` | `b` |
+
+
+The solids `a` and `b` were generated with the following code:
+
+```go
+import . "github.com/reactivego/csg"
+
+a := Cube(Center(-0.25, -0.25, -0.25))
+b := Sphere(Center(0.25, 0.25, 0.25), Radius(1.3))
+```
+
+| ![Union](../assets/union.svg) | ![Subtract](../assets/subtract.svg) | ![Intersect](../assets/intersect.svg) |
+|:---:|:---:|:---:|
+| `a.Union(b)`| `a.Subtract(b)` | `a.Intersect(b)` |
+
+
+
+## Implementation Details
+
+All CSG operations are implemented in terms of two functions, `ClipTo()` and
+`Invert()`, which remove parts of a BSP tree inside another BSP tree and swap
+solid and empty space, respectively. Tob find the union of `a` and `b`, we
+want to remove everything in `a` inside `b` and everything in `b` inside `a`,
+then combine polygons from `a` and `b` into one solid:
+
+``` go
+a.ClipTo(b)
+b.ClipTo(a)
+a.AddPolygons(b.AllPolygons())
+```
+
+The only tricky part is handling overlapping coplanar polygons in both trees.
+The code above keeps both copies, but we need to keep them in one tree and
+remove them in the other tree. To remove them from `b` we can clip the
+inverse of `b` against `a`. The code for union now looks like this:
+
+``` go
+a.ClipTo(b)
+b.ClipTo(a)
+b.Invert()
+b.ClipTo(a)
+b.Invert()
+a.AddPolygons(b.AllPolygons())
+```
+
+Subtraction and intersection naturally follow from set operations. If
+union is `A | B`, subtraction is `A - B = ~(~A | B)` and intersection is
+`A & B = ~(~A | ~B)` where `~` is the complement operator.
+
+## Acknowledgments
+
+This package is a direct conversion of [cgs.js](http://evanw.github.io/csg.js/) to Go.
+The original JavaScript code was written by Evan Wallace and committed to git on November 30, 2011.
+As an odd coincidence, I am writing this a full 10 years later on Nov 30, 2021.
+
+## License
+
+This library is licensed under the terms of the MIT License.
+See [LICENSE](LICENSE) file for copyright notice and exact wording.

bsp.go

@@ -0,0 +1,124 @@
+package csg
+
+import (
+	"fmt"
+	"strings"
+)
+
+// BSP holds a node in a BSP tree. A BSP tree is built from a collection of
+// polygons by picking a polygon to split along. That polygon (and all other
+// coplanar polygons) are added directly to that node and the other polygons
+// are added to the front and/or back subtrees. This is not a leafy BSP tree
+// since there is no distinction between internal and leaf nodes.
+type BSP struct {
+	Plane    *Plane
+	Polygons Polygons
+	Front    *BSP
+	Back     *BSP
+}
+
+// Invert converts solid space to empty space and empty space to solid space.
+func (n *BSP) Invert() {
+	for i := range n.Polygons {
+		n.Polygons[i].Flip()
+	}
+	n.Plane.Flip()
+	if n.Front != nil {
+		n.Front.Invert()
+	}
+	if n.Back != nil {
+		n.Back.Invert()
+	}
+	n.Front, n.Back = n.Back, n.Front
+}
+
+// ClipPolygons recursively removes all polygons in `polygons` that are inside
+// this BSP tree.
+func (n BSP) ClipPolygons(polygons Polygons) Polygons {
+	if n.Plane == nil {
+		return append(Polygons(nil), polygons...)
+	}
+	var front, back Polygons
+	for _, p := range polygons {
+		n.Plane.SplitPolygon(p, &front, &back, &front, &back)
+	}
+	if n.Front != nil {
+		front = n.Front.ClipPolygons(front)
+	}
+	if n.Back != nil {
+		back = n.Back.ClipPolygons(back)
+	} else {
+		back = nil
+	}
+	return append(front, back...)
+}
+
+// ClipTo removes all polygons in this BSP tree that are inside the other BSP
+// tree `bsp`.
+func (n *BSP) ClipTo(bsp *BSP) {
+	n.Polygons = bsp.ClipPolygons(n.Polygons)
+	if n.Front != nil {
+		n.Front.ClipTo(bsp)
+	}
+	if n.Back != nil {
+		n.Back.ClipTo(bsp)
+	}
+}
+
+// AllPolygons returns a list of all polygons in this BSP tree.
+func (n BSP) AllPolygons() Polygons {
+	polygons := append(Polygons(nil), n.Polygons...)
+	if n.Front != nil {
+		polygons = append(polygons, n.Front.AllPolygons()...)
+	}
+	if n.Back != nil {
+		polygons = append(polygons, n.Back.AllPolygons()...)
+	}
+	return polygons
+}
+
+// AddPolygons builds a BSP tree out of `polygons`. When called on an existing
+// tree, the new polygons are filtered down to the bottom of the tree and become
+// new nodes there. Each set of polygons is partitioned using the first polygon
+// (no heuristic is used to pick a good split).
+func (n *BSP) AddPolygons(polygons Polygons) {
+	if len(polygons) == 0 {
+		return
+	}
+	if n.Plane == nil {
+		p := polygons[0].Plane
+		n.Plane = &p
+	}
+	var front, back Polygons
+	for _, p := range polygons {
+		n.Plane.SplitPolygon(p, &n.Polygons, &n.Polygons, &front, &back)
+	}
+	if len(front) > 0 {
+		if n.Front == nil {
+			n.Front = &BSP{}
+		}
+		n.Front.AddPolygons(front)
+	}
+	if len(back) > 0 {
+		if n.Back == nil {
+			n.Back = &BSP{}
+		}
+		n.Back.AddPolygons(back)
+	}
+}
+
+func (n *BSP) print(level int, sb *strings.Builder) {
+	sb.WriteString(fmt.Sprintf("%*s%s:%+v\n", level*2, "", "plane", n.Plane.Normal))
+	if n.Front != nil {
+		n.Front.print(level+1, sb)
+	}
+	if n.Back != nil {
+		n.Back.print(level+1, sb)
+	}
+}
+
+func (n *BSP) String() string {
+	var sb strings.Builder
+	n.print(0, &sb)
+	return sb.String()
+}

cube.go

@@ -0,0 +1,46 @@
+package csg
+
+// Cube constructs an axis-aligned solid cuboid. Optional parameters are
+// `Center` and `Size`, which default to `Center(0, 0, 0)` and
+// `Size(2, 2, 2)`. The Size is specified a list of three numbers, one for
+// each axis.
+//
+// Example code:
+//
+//     cube := csg.Cube(
+//       csg.Center(0, 0, 0),
+//       csg.Size(2, 2, 2))
+//
+func Cube(options ...Option) *Solid {
+	o := OptionsFrom(options)
+	faces := [][]int{
+		{0, 4, 6, 2},
+		{1, 3, 7, 5},
+		{0, 1, 5, 4},
+		{2, 6, 7, 3},
+		{0, 2, 3, 1},
+		{4, 5, 7, 6}}
+	normals := []Vector{
+		{X: -1, Y: 0, Z: 0},
+		{X: +1, Y: 0, Z: 0},
+		{X: 0, Y: -1, Z: 0},
+		{X: 0, Y: +1, Z: 0},
+		{X: 0, Y: 0, Z: -1},
+		{X: 0, Y: 0, Z: +1}}
+	polygons := []Polygon{}
+	c := o.Center
+	r := o.Size.DividedBy(2)
+	for i, corners := range faces {
+		vertices := make([]Vertex, 0, len(corners))
+		for _, corner := range corners {
+			pos := Vector{
+				X: c.X + r.X*normals[0+corner&1/1].X,
+				Y: c.Y + r.Y*normals[2+corner&2/2].Y,
+				Z: c.Z + r.Z*normals[4+corner&4/4].Z,
+			}
+			vertices = append(vertices, Vertex{Pos: pos, Normal: normals[i]})
+		}
+		polygons = append(polygons, PolygonFromVertices(vertices...))
+	}
+	return SolidFromPolygons(polygons)
+}

cylinder.go

@@ -0,0 +1,51 @@
+package csg
+
+import (
+	"math"
+)
+
+// Cylinder constructs a solid cylinder. Optional parameters are `Start`,
+// `End`, `Radius`, and `Slices`, which default to `Start(0, -1, 0)`,
+// `End(0, 1, 0)`, `Radius(1)`, and `Slices(16)`. The `Slices` parameter
+// controls the tessellation.
+//
+// Example usage:
+//
+//     cylinder := csg.Cylinder(
+//       Start(0, -1, 0),
+//       End(0, 1, 0),
+//       Radius(1),
+//       Slices(16))
+//
+func Cylinder(options ...Option) *Solid {
+	o := OptionsFrom(options)
+	s := o.Start
+	e := o.End
+	ray := e.Minus(s)
+	r := o.Radius
+	slices := float64(o.Slices)
+	axisZ := ray.Unit()
+	axisX := Vector{0, 1, 0}
+	if math.Abs(axisZ.Y) > 0.5 {
+		axisX = Vector{1, 0, 0}
+	}
+	axisX = axisX.Cross(axisZ).Unit()
+	axisY := axisX.Cross(axisZ).Unit()
+	start := Vertex{Pos: s, Normal: axisZ.Negated()}
+	end := Vertex{Pos: e, Normal: axisZ.Unit()}
+	point := func(stack, slice, normalBlend float64) Vertex {
+		angle := slice * math.Pi * 2
+		out := axisX.Times(math.Cos(angle)).Plus(axisY.Times(math.Sin(angle)))
+		pos := s.Plus(ray.Times(stack)).Plus(out.Times(r))
+		normal := out.Times(1 - math.Abs(normalBlend)).Plus(axisZ.Times(normalBlend))
+		return Vertex{Pos: pos, Normal: normal}
+	}
+	var polygons Polygons
+	for i := 0.0; i < slices; i++ {
+		t0, t1 := i/slices, (i+1)/slices
+		polygons = append(polygons, PolygonFromVertices(start, point(0, t0, -1), point(0, t1, -1)))
+		polygons = append(polygons, PolygonFromVertices(point(0, t1, 0), point(0, t0, 0), point(1, t0, 0), point(1, t1, 0)))
+		polygons = append(polygons, PolygonFromVertices(end, point(1, t1, 1), point(1, t0, 1)))
+	}
+	return SolidFromPolygons(polygons)
+}

go.mod

@@ -0,0 +1,3 @@
+module github.com/reactivego/csg
+
+go 1.17