README
¶
⚠️ ARCHIVED ⚠️
Development has moved to https://github.com/soypat/gsdf.
This project has been archived in favor of developing a more advanced solution. gsdf redesigns APIs to be vectorised speeding things up considerably and enabling usage of GPU which enables real-time visualization of shapes with infinite detail (no triangle rendering step required).
Most functionality in sdf has already been reimplemented at the time of archiving. Feel free to ask questions in the issue tracker!
sdf (originally sdfx)
A rewrite of the original Signed Distance Function CAD package sdfx for generating 2D and 3D geometry using Go.
Highlights
- GUI with real-time rendering using sdf3ui (or SDF Viewer).
- 3d and 2d objects modelled with signed distance functions (SDFs).
- Minimal and idiomatic API.
- Render objects as triangles or save to STL, 3MF(experimental) file format.
- End-to-end testing using image comparison.
mustandformpackages provide panicking and normal error handling basic shape generation APIs for different scenarios.- Dead-simple, single method
Rendererinterface. - Import mesh files: Edit STL and 3MF files as if they were native SDFs using
sdfexp.ImportModel - Tetrahedron mesher: Measure volume or create physics models of your shapes using
sdfexp.UniformTetrahedronMesh. Experimental feature. Example result image.
Examples
For real-world examples with images see examples directory README.
See images of rendered shapes in render/testdata.
Here is a rendered bolt from one of the unit tests under form3_test.go
Roadmap
- Clean up thread API mess
- Add a 2D renderer and it's respective
Renderer2interface. - Make 3D renderer multicore
Comparison
deadsy/sdfx
Advantages of deadsy/sdfx:
- Widely used
- More helper functions
- Working 2D renderer
Advantages of soypat/sdf:
- Very fast rendering
deadsy/sdfxis over 2 times slower and has ~5 times more allocations.
- Minimal and idiomatic API
Rendererinterface is dead-simple, idiomatic Go and not limited to SDFs- deadsy/sdfx
Renderer3interface has filledrenderpackage with technical debt.
- deadsy/sdfx
- Has
SDFUnionandSDFDiffinterfaces for blending shapes easilyMinPolyredesign to allow for n-degree polynomials. Also returns a sensible "undefined output"MinFuncbefore dividing by zero.
- No
nilvalued SDFs- deadsy/sdfx internally makes use of
nilSDFs as "empty" objects. This can later cause panics during rendering well after the point of failure causing hard to debug issues.
- deadsy/sdfx internally makes use of
- Well defined package organization.
- deadsy/sdfx dumps helper and utility functions in
sdf
- deadsy/sdfx dumps helper and utility functions in
- End-to-end tested.
- Ensures functioning renderer and SDF functions using image comparison preventing accidental changes.
- Error-free API under
must3andmust2packages for makers.- For simple projects these packages allow for streamlined error handling process using
panicinstead of returned errors. - deadsy/sdfx only allows for Go-style error handling like the
form3andform2packages.
- For simple projects these packages allow for streamlined error handling process using
- Sound use of
mathpackage for best precision and overflow prevention.math.Hypotused for all length calculations.deadsy/sdfxdoes not usemath.Hypot.
- Uses gonum's
spatialpackagesdfxhas own vector types with methods which hurt code legibilityspatialtypes from gonum library with correct Triangle degeneracy calculation.deadsy/sdfx's Degenerate calculation is incorrect.
- Idiomatic
threadpackage. Define arbitrary threads with ease usingThreaderinterface.deadsy/sdfxdefines threads with strings i.e."M16x2".sdfDefines threads with types corresponding to standards. i.e:thread.ISO{D:16, P:2}, which defines an M16x2 ISO thread.
Contributing
See CONTRIBUTING.
Why was sdfx rewritten?
The original sdfx package is amazing. I thank deadsy for putting all that great work into making an amazing tool I use daily. That said, there are some things that were not compatible with my needs:
Rendering speed
Here is a benchmark rendering a threaded bolt:
$ go test -benchmem -run=^$ -bench ^(BenchmarkSDFXBolt|BenchmarkBolt)$ ./render
goos: linux
goarch: amd64
pkg: github.com/soypat/sdf/render
cpu: AMD Ryzen 5 3400G with Radeon Vega Graphics
BenchmarkSDFXBolt-8 6 196941244 ns/op 14700786 B/op 98261 allocs/op
BenchmarkBolt-8 13 87547265 ns/op 18136785 B/op 20754 allocs/op
PASS
ok github.com/soypat/sdf/render 4.390s
BenchmarkBolt-8 is this implementation of Octree. BenchmarkSDFXBolt-8 is the sdfx implementation of said algorithm.
Unwieldy API design
- https://github.com/deadsy/sdfx/issues/48 Vector API redesign
- https://github.com/deadsy/sdfx/issues/35 Better STL save functions.
- https://github.com/deadsy/sdfx/issues/50 Removing returned errors from shape generation functions
The vector math functions are methods which yield hard to follow operations. i.e:
return bb.Min.Add(bb.Size().Mul(i.ToV3().DivScalar(float64(node.meshSize)).
Div(node.cellCounts.ToV3().DivScalar(float64(node.meshSize))))) // actual code from original sdfx.
A more pressing issue was the Renderer3 interface definition method, Render
type Renderer3 interface {
// ...
Render(s sdf.SDF3, meshCells int, output chan<- *Triangle3)
}
This presented a few problems:
-
Raises many questions about usage of the function Render- who closes the channel? Does this function block? Do I have to call it as a goroutine?
-
To implement a renderer one needs to bake in concurrency which is a hard thing to get right from the start. This also means all rendering code besides having the responsibility of computing geometry, it also has to handle concurrency features of the language. This leads to rendering functions with dual responsibility- compute geometry and also handle the multi-core aspect of the computation making code harder to maintain in the long run
-
Using a channel to send individual triangles is probably a bottleneck.
-
I would liken
meshCellsto an implementation detail of the renderer used. This can be passed as an argument when instantiating the renderer used. -
Who's to say we have to limit ourselves to signed distance functions? With the new proposed
Rendererinterface this is no longer the case.
sdf and sdfx consolidation
None planned.
Logo work
Gopher rendition by Juliette Whittingslow.
Gopher design authored by Renée French
is licensed by the Creative Commons Attribution 3.0 licensed.
Documentation
¶
Index ¶
- func MirrorX() m33
- func MirrorXY() m44
- func MirrorXZ() m44
- func MirrorXeqY() m44
- func MirrorY() m33
- func MirrorYZ() m44
- func NormalExtrude(p r3.Vec) r2.Vec
- func R2FromI(a V2i) r2.Vecdeprecated
- func R3FromI(a V3i) r3.Vecdeprecated
- func Rotate(a float64) m22
- func Rotate2D(a float64) m33
- func Rotate3D(v r3.Vec, a float64) m44
- func RotateX(a float64) m44
- func RotateY(a float64) m44
- func RotateZ(a float64) m44
- func Scale2D(v r2.Vec) m33
- func Scale3D(v r3.Vec) m44
- func Translate2D(v r2.Vec) m33
- func Translate3D(v r3.Vec) m44
- type CutSDF2
- type ExtrudeFunc
- type MaxFunc
- type MinFunc
- type SDF2
- func Center2D(s SDF2) SDF2
- func CenterAndScale2D(s SDF2, k float64) SDF2
- func Cut2D(sdf SDF2, a, v r2.Vec) SDF2
- func Elongate2D(sdf SDF2, h r2.Vec) SDF2
- func LineOf2D(s SDF2, p0, p1 r2.Vec, pattern string) SDF2
- func Multi2D(s SDF2, positions d2.Set) SDF2
- func Offset2D(sdf SDF2, offset float64) SDF2
- func RotateCopy2D(sdf SDF2, n int) SDF2
- func RotateUnion2D(sdf SDF2, num int, step m33) SDF2
- func ScaleUniform2D(sdf SDF2, k float64) SDF2
- func Slice2D(sdf SDF3, a, n r3.Vec) SDF2
- func Transform2D(sdf SDF2, m m33) SDF2
- type SDF2Diff
- type SDF2Union
- type SDF3
- func Cut3D(sdf SDF3, a, n r3.Vec) SDF3
- func Elongate3D(sdf SDF3, h r3.Vec) SDF3
- func Extrude3D(sdf SDF2, height float64) SDF3
- func ExtrudeRounded3D(sdf SDF2, height, round float64) SDF3
- func LineOf3D(s SDF3, p0, p1 r3.Vec, pattern string) SDF3
- func Loft3D(sdf0, sdf1 SDF2, height, round float64) SDF3
- func Multi3D(s SDF3, positions d3.Set) SDF3
- func Offset3D(sdf SDF3, offset float64) SDF3
- func Orient3D(s SDF3, base r3.Vec, directions d3.Set) SDF3
- func Revolve3D(sdf SDF2, theta float64) SDF3
- func RotateCopy3D(sdf SDF3, num int) SDF3
- func ScaleExtrude3D(sdf SDF2, height float64, scale r2.Vec) SDF3
- func ScaleTwistExtrude3D(sdf SDF2, height, twist float64, scale r2.Vec) SDF3
- func ScaleUniform3D(sdf SDF3, k float64) SDF3
- func Shell3D(sdf SDF3, thickness float64) SDF3
- func Transform3D(sdf SDF3, matrix m44) SDF3
- func TwistExtrude3D(sdf SDF2, height, twist float64) SDF3
- type SDF3Diff
- type SDF3Union
- type ScaleUniformSDF2
- type TransformSDF2
- type V2i
- func R2ToI(a r2.Vec) V2ideprecated
- type V3i
- func R3ToI(a r3.Vec) V3ideprecated
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func MirrorXY ¶
func MirrorXY() m44
MirrorXY returns a 4x4 matrix with mirroring across the XY plane.
func MirrorXZ ¶
func MirrorXZ() m44
MirrorXZ returns a 4x4 matrix with mirroring across the XZ plane.
func MirrorXeqY ¶
func MirrorXeqY() m44
MirrorXeqY returns a 4x4 matrix with mirroring across the X == Y plane.
func MirrorYZ ¶
func MirrorYZ() m44
MirrorYZ returns a 4x4 matrix with mirroring across the YZ plane.
func NormalExtrude ¶
NormalExtrude returns an extrusion function.
func Rotate ¶
func Rotate(a float64) m22
Rotate returns an orthographic 2x2 rotation matrix (right hand rule).
func Rotate2D ¶
func Rotate2D(a float64) m33
Rotate2D returns an orthographic 3x3 rotation matrix (right hand rule).
func RotateX ¶
func RotateX(a float64) m44
RotateX returns a 4x4 matrix with rotation about the X axis.
func RotateY ¶
func RotateY(a float64) m44
RotateY returns a 4x4 matrix with rotation about the Y axis.
func RotateZ ¶
func RotateZ(a float64) m44
RotateZ returns a 4x4 matrix with rotation about the Z axis.
func Scale2D ¶
Scale2D returns a 3x3 scaling matrix. Scaling does not preserve distance. See: ScaleUniform2D().
Types ¶
type CutSDF2 ¶
type CutSDF2 struct {
// contains filtered or unexported fields
}
CutSDF2 is an SDF2 made by cutting across an existing SDF2.
type ExtrudeFunc ¶
ExtrudeFunc maps r3.Vec to V2 - the point used to evaluate the SDF2.
func ScaleExtrude ¶
func ScaleExtrude(height float64, scale r2.Vec) ExtrudeFunc
ScaleExtrude returns an extrusion functions that scales with z.
func ScaleTwistExtrude ¶
func ScaleTwistExtrude(height, twist float64, scale r2.Vec) ExtrudeFunc
ScaleTwistExtrude returns an extrusion function that scales and twists with z.
func TwistExtrude ¶
func TwistExtrude(height, twist float64) ExtrudeFunc
TwistExtrude returns an extrusion function that twists with z.
type MinFunc ¶
MinFunc is a minimum functions for SDF blending.
func MinPoly ¶
MinPoly creates a n-degree polynomial MinFunc with parameter k that controls radius of the smoothing function.
- n<0 or k<=0 undefined output
- n=0 returns a chamfer-like MinFunc
- n=1 returns math.Min
type SDF2 ¶
type SDF2 interface {
// Evaluate takes a point in 2D space as input and returns
// the minimum distance of the SDF2 to the point. The distance
// is negative if the point is contained within the SDF3.
Evaluate(p r2.Vec) float64
// Bounds returns the bounding box that completely contains the SDF2.
Bounds() r2.Box
}
SDF2 is the interface to a 2d signed distance function object.
func CenterAndScale2D ¶
CenterAndScale2D centers the origin of an SDF2 on it's bounding box, and then scales it. Distance is correct with scaling.
func Cut2D ¶
Cut2D cuts the SDF2 along a line from a in direction v. The SDF2 to the right of the line remains.
func Elongate2D ¶
Elongate2D returns the elongation of an SDF2.
func RotateCopy2D ¶
RotateCopy2D rotates and copies an SDF2 n times in a full circle.
func RotateUnion2D ¶
RotateUnion2D returns a union of rotated SDF2s.
func ScaleUniform2D ¶
ScaleUniform2D scales an SDF2 by k on each axis. Distance is correct with scaling.
func Slice2D ¶
Slice2D returns an SDF2 created from a planar slice through an SDF3. a is point on slicing plane, n is normal to slicing plane
func Transform2D ¶
Transform2D applies a transformation matrix to an SDF2. Distance is *not* preserved with scaling.
type SDF2Diff ¶
func Difference2D ¶
Difference2D returns the difference of two SDF2 objects, s0 - s1.
func Intersect2D ¶
Intersect2D returns the intersection of two SDF2s.
type SDF3 ¶
type SDF3 interface {
// Evaluate takes a point in 3D space as input and returns
// the minimum distance of the SDF3 to the point. The distance
// is negative if the point is contained within the SDF3.
Evaluate(p r3.Vec) float64
// Bounds returns the bounding box that completely contains
// the SDF3.
Bounds() r3.Box
}
SDF3 is the interface to a 3d signed distance function object.
func Cut3D ¶
Cut3D cuts an SDF3 along a plane passing through a with normal n. The SDF3 on the same side as the normal remains.
func Elongate3D ¶
Elongate3D returns the elongation of an SDF3.
func ExtrudeRounded3D ¶
ExtrudeRounded3D extrudes an SDF2 to an SDF3 with rounded edges.
func Revolve3D ¶
Revolve3D returns an SDF3 for a solid of revolution. theta is in radians. For a full revolution call
Revolve3D(s0, 2*math.Pi)
func RotateCopy3D ¶
RotateCopy3D rotates and creates N copies of an SDF3 about the z-axis. num is the number of copies.
func ScaleExtrude3D ¶
ScaleExtrude3D extrudes an SDF2 and scales it over the height of the extrusion.
func ScaleTwistExtrude3D ¶
ScaleTwistExtrude3D extrudes an SDF2 and scales and twists it over the height of the extrusion.
func ScaleUniform3D ¶
ScaleUniform3D uniformly scales an SDF3 on all axes.
func Transform3D ¶
Transform3D applies a transformation matrix to an SDF3.
func TwistExtrude3D ¶
TwistExtrude3D extrudes an SDF2 while rotating by twist radians over the height of the extrusion.
type SDF3Diff ¶
func Difference3D ¶
Difference3D returns the difference of two SDF3s, s0 - s1. Difference3D will panic if one any of the arguments is nil.
func Intersect3D ¶
Intersect3D returns the intersection of two SDF3s. Intersect3D will panic if any of the arguments are nil.
type SDF3Union ¶
func RotateUnion3D ¶
RotateUnion3D creates a union of SDF3s rotated about the z-axis. num is the number of copies.
type ScaleUniformSDF2 ¶
type ScaleUniformSDF2 struct {
// contains filtered or unexported fields
}
ScaleUniformSDF2 scales another SDF2 on each axis.
func (*ScaleUniformSDF2) Bounds ¶
func (s *ScaleUniformSDF2) Bounds() r2.Box
BoundingBox returns the bounding box of an SDF2 with uniform scaling.
type TransformSDF2 ¶
type TransformSDF2 struct {
// contains filtered or unexported fields
}
TransformSDF2 transorms an SDF2 with rotation, translation and scaling.
func (*TransformSDF2) Bounds ¶
func (s *TransformSDF2) Bounds() r2.Box
BoundingBox returns the bounding box of a transformed SDF2.
type V2i ¶
type V2i [2]int
V2i is a 2D integer vector.
Source Files
Directories
