Docs · Go

Go API

The Go wrappers over the two libraries: cadaclysm_capi reads, meshes and writes; cadaclysm_blacksmith builds exact solids. Every type and call, with the signature as the wrapper declares it — read from its source when this page is built.

Install

Install and load

The packages github.com/rdeioris/cadaclysm-sdk/go/cadaclysm (the reader) and .../go/blacksmith (the kernel), over cgo — so a C compiler is needed at build time (MinGW-w64 on Windows). Go 1.24 or later.

Get the libraries with the SDK's fetch.py (or unpack a release archive's lib/ and include/); keep the wrapper files and the libraries from the same release. Details on the start page.

go get github.com/rdeioris/cadaclysm-sdk/go
# the loader must find the library at run time:
export LD_LIBRARY_PATH=$PWD/lib        # macOS: DYLD_LIBRARY_PATH; Windows: add lib to PATH

Where the library is found

cgo links against the SDK's lib/ at build time (set CGO_LDFLAGS=-L<dir> for another place); at run time the operating system's loader finds the library, so its directory goes on PATH (Windows), LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (macOS), or the library ships beside the executable.

The licence

Unlicensed, everything works and a notice is printed on every open and export. A licence file removes it: set CADACLYSM_LICENSE, or put cadaclysm.lic beside the executable or in the working directory, or load it from code — once per library:

if err := cadaclysm.License("cadaclysm.lic"); err != nil { log.Fatal(err) }
if err := blacksmith.License("cadaclysm.lic"); err != nil { log.Fatal(err) }

Quick start

Build a part, then read it back

The kernel builds a plate with a boss, bores it and rounds its corners, then writes STEP — the Examples page's first part:

package main

import (
	"log"
	"math"

	"github.com/rdeioris/cadaclysm-sdk/go/blacksmith"
)

func must[T any](v T, err error) T {
	if err != nil {
		log.Fatal(err)
	}
	return v
}

func main() {
	plate := must(blacksmith.XY().Extrude(must(blacksmith.Rect(120, 80)), 14).Solid())
	defer plate.Close()
	boss := must(blacksmith.FromSolid(plate).
		Faces(blacksmith.Max(blacksmith.AxisZ)).OnFace().
		Extrude(must(blacksmith.Circle(22)), 26).Solid())
	defer boss.Close()
	joined := must(plate.Join(boss, blacksmith.DefaultTolerance))
	defer joined.Close()

	bore := must(must(blacksmith.XY().Extrude(must(blacksmith.Circle(11)), 60).Solid()).Translate(0, 0, -10))
	defer bore.Close()
	bored := must(joined.Cut(bore, blacksmith.DefaultTolerance))
	defer bored.Close()

	// The plate's four vertical corners: the lines along Z between two planes
	// (the boss has vertical seams too, but those lie on its cylinder).
	var corners []int
	for _, e := range must(bored.Edges()) {
		d, ok := e.Direction()
		if !ok || math.Abs(d[2]) <= 0.99 {
			continue
		}
		planes := true
		for _, f := range e.Faces {
			planes = planes && must(bored.FaceKind(f)) == "plane"
		}
		if planes {
			corners = append(corners, e.Index)
		}
	}
	part := must(bored.Fillet(corners, 12, blacksmith.FilletTolerance))
	defer part.Close()
	if err := part.Step("plate.stp", "", "mm"); err != nil {
		log.Fatal(err)
	}
}

The reader opens that file, walks its tree, meshes what it draws and writes glTF:

package main

import (
	"fmt"
	"log"
	"strings"

	"github.com/rdeioris/cadaclysm-sdk/go/cadaclysm"
)

func main() {
	scene, err := cadaclysm.Open("plate.stp")
	if err != nil {
		log.Fatal(err)
	}
	defer scene.Close()
	fmt.Println(scene.Schema(), scene.MetresPerUnit(), "m per unit")

	// The tree: assemblies, parts and bodies, parents before children.
	for _, node := range scene.Walk() {
		fmt.Printf("%s%s [%s]\n", strings.Repeat("  ", int(node.Depth())), node.Label(), node.Kind())
	}

	// What to draw: every placement of every shape, meshed on first ask.
	for _, placement := range scene.Placements() {
		mesh, err := placement.Geometry().Mesh()
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(placement.Geometry().Label(), mesh.TriangleCount(), "triangles")
	}

	if err := scene.Save("plate.glb", "glb"); err != nil {
		log.Fatal(err)
	}
}

Reader · cadaclysm_capi

Reading, meshing, writing

Module functions

Loading the library, the licence, and opening a file — from disk or from bytes already in memory. Every other object on this page comes out of cadaclysm.Open() or cadaclysm.OpenMemory().

`cadaclysm.Open()`

func Open(path string, opts ...Option) (*Scene, error)

Open a CAD file and read its tree. The format comes from the extension (a .zip opens its first readable member — Scene.SourceName() says which). The tree is read now and the geometry is built lazily, node by node, when it is first asked for.

convention is the space to read into — a Convention, optionally with the file-units and world-UV flags — and the library converts everything it hands back into it. schema names an extra EXPRESS schema (.exp, or a directory of them); every schema the SDK ships is already built in, so it is needed only for one the library does not carry. colours asks for per-vertex colours on bodies the file painted in more than one colour.

Never returns an empty handle: on failure it returns a *CadaclysmError carrying the library's reason.

`cadaclysm.OpenMemory()`

func OpenMemory(data []byte, name string, opts ...Option) (*Scene, error)

Open a file already in bytes — a download, a database blob, an archive member. With no file name to take the format from, it is named as an extension would name it: step, ifc, igs, 3dm, brep, scad (a leading dot is fine). The bytes are copied; the buffer can be reused as soon as this returns. Otherwise as cadaclysm.Open().

`cadaclysm.Version()`

func Version() string

The version of the library actually loaded — the one worth reporting in a bug.

`cadaclysm.BuildDate()`

func BuildDate() string

When the loaded library was built, YYYY-MM-DD. A licence covers every build dated on or before its expiry.

`cadaclysm.License()`

func License(textOrPath string) error

Load a licence: the certificate text, or the path of a file holding it. Without this call the library looks in the CADACLYSM_LICENSE environment variable, then for cadaclysm.lic beside the executable and in the working directory. On a licence that does not verify it returns a *CadaclysmError with the reason, and the previous licence (if any) stays in use.

`cadaclysm.LicenseInfo()`

func LicenseInfo() string

One line about the licence in use — customer=… expiry=… entitlements=… — or unlicensed (unlicensed -- <reason> when a licence was found but did not verify). Never nil.

`cadaclysm.LicenseNoticeCount()`

func LicenseNoticeCount() uint64

How many unlicensed notices the library has printed to stderr in this process. An application with no console to watch (a GUI, a game) can poll this and show its own banner.

`cadaclysm.MeshFormats()`

func MeshFormats() []MeshFormat

Every mesh format Node.SaveMesh() writes, with its file extension: stl, stl-ascii, msh (Gmsh), glb, gltf and obj in this release. Build a save menu from this list rather than hard-coding it, and a format added to the library appears without a code change.

`cadaclysm.PickFile()`

func PickFile() (string, bool)

Ask the user for a file through the platform's own open dialog, filtered to what this build can read. nil when they cancel or no dialog is available (on Linux, neither an XDG portal nor zenity). Blocks until the user acts; on macOS call it from the main thread.

`cadaclysm.DeclaredSchema()`

func DeclaredSchema(path string) (string, error)

The schema a STEP or IFC file says it speaks (its FILE_SCHEMA line), read from the first few kilobytes — cheap even on a very large file. Empty when it names none.

`cadaclysm.ResolveSchema()`

func ResolveSchema(modelPath, schema string) (chosen string, fallbacks []string, err error)

Which .exp of a schema directory matches a model: the chosen file, or — when the file's declared name resembles none of them — the whole list as fallbacks to try in turn. cadaclysm.Open() does this itself when given a directory; this is for a caller that wants to report the choice.

`LibraryPath`

Where the shared library was found: CADACLYSM_LIBRARY (a file or a directory) first, then beside the wrapper, then a lib/ directory in any parent (the SDK's layout).

cgo links the library at build time; see Install.

`None`

The node index the C API uses for "no such node" (CADACLYSM_NONE, 0xFFFFFFFF). The wrappers turn it into nil where a node may be missing (Node.Parent(), Node.InstanceOf()), so it matters only when reading raw indices.

Missing nodes are nil.

`Open options` Go only

func WithFormat(format string) Option
func WithConvention(c Convention) Option
func WithSchema(schema string) Option
func WithColours() Option
func WithSourceMetresPerUnit(v float64) Option

cadaclysm.Open() and cadaclysm.OpenMemory() take Python's keyword arguments as functional options: cadaclysm.Open(path, cadaclysm.WithConvention(cadaclysm.YUp)). WithFormat names the format for cadaclysm.OpenMemory() when the name's extension does not.

Scene

type Scene struct

An open document. Close it when done — Scene.Close(), or let the language's scope do it (with, using, defer, try-with-resources). Everything it hands back borrows from it: node handles, meshes, polylines. See Lifetimes for what survives a close.

`Scene.Close()`

func (s *Scene) Close() error

Give the document back. Idempotent. Every mesh and polyline view still held reads freed memory afterwards (the wrappers that can tell refuse to read them).

`Scene.Closed()`

func (s *Scene) Closed() bool

Whether Scene.Close() has run.

`Scene.Path()`

func (s *Scene) Path() string

The file it was read from, or the name given to cadaclysm.OpenMemory().

`Scene.SchemaPath()`

func (s *Scene) SchemaPath() string

The .exp actually used, or nil — worth reporting when a directory was passed.

`Scene.Convention()`

func (s *Scene) Convention() Convention

The convention it was opened with. Nothing the library hands back says what space it is in, and every array out of this scene is in this one.

`Scene.Version()`

func (s *Scene) Version() string

The version of the library that read it.

`Scene.Schema()`

func (s *Scene) Schema() string

The schema the file named, or empty for a format that names none.

`Scene.SchemaRead()`

func (s *Scene) SchemaRead() string

The schema that actually read it. A file declaring a release candidate reads under the finished schema of the same version where that is what is built in; a file whose schema is unknown reads under the one that defines its entity types.

`Scene.Substituted()`

func (s *Scene) Substituted() bool

Whether something other than the file's own schema read it — Scene.Schema() and Scene.SchemaRead() differ.

`Scene.MetresPerUnit()`

func (s *Scene) MetresPerUnit() float64

What one length unit in the file is worth in metres; 1 where the file did not say.

`Scene.Bounds()`

func (s *Scene) Bounds() Bounds

Everything the model covers, in world coordinates — the one figure not in a node's own frame. This meshes the whole model, being the only way to know how far it reaches; to frame a view quickly, use the bounds of the nodes already built.

`Scene.Diagnostics()`

func (s *Scene) Diagnostics() []string

What the file held that the reader could not build, one line each.

`Scene.SourceName()`

func (s *Scene) SourceName() string

The archive member this was read from, or nil for a plain file.

`Scene.Nodes()`

func (s *Scene) Nodes() []*Node

Every node, in index order: assemblies, shapes, layers, storeys — structure as well as geometry. To draw, iterate Scene.Placements() instead.

`Scene.Roots()`

func (s *Scene) Roots() []*Node

The nodes nothing else contains: where a tree view starts.

`Scene.Walk()`

func (s *Scene) Walk() []*Node

Every node reachable from the roots, parents before children.

`Scene.Query()`

func (s *Scene) Query(filter string) ([]*Node, error)

The indices of the nodes a filter matches, in document order. The filter is one boolean expression in the query language — class == ON_Brep and within(name == Walls). A filter that does not parse returns a *CadaclysmError with the parser's message and position; one that matches nothing is an empty result, not an error.

Returns the matching nodes.

`Scene.Placements()`

func (s *Scene) Placements() []*Placement

What the document draws, and where. Not the nodes: a block or an instanced part is one node of geometry drawn at several places, and a node walk draws it once at its definition's frame. Iterate this to draw, and the nodes to build a tree. See Placement.

`Scene.RealizeAll()`

func (s *Scene) RealizeAll() uint32

Build every mesh now, across all cores, and return how many were built. Reading is lazy so a tree can be on screen while the shapes are still coming; asking node by node meshes on one core, this uses them all. Watch it from another thread with Scene.Realized() and Scene.RealizeTotal(); stop it with Scene.Cancel().

`Scene.Realized()`

func (s *Scene) Realized() uint32

How many nodes Scene.RealizeAll() has finished. Safe to read from another thread.

`Scene.RealizeTotal()`

func (s *Scene) RealizeTotal() uint32

How many it will build in all; zero until it starts.

`Scene.Cancel()`

func (s *Scene) Cancel()

Ask a running Scene.RealizeAll() to stop. One-way for the life of the scene: later calls return at once, and meshes are still built one node at a time on request.

`Scene.Save()`

func (s *Scene) Save(path, format string) error

Write the whole scene: glb (binary glTF), gltf (text glTF, one file) or obj (every placement baked to its own named object, with a .mtl beside it when anything has a colour). Every placement of every shape, named and placed as the tree is, one material per colour; in the scene's convention (use Y-up metres for the space glTF specifies). A format outside these three, or a failed write, returns a *CadaclysmError.

`Scene.SurfaceMatrix()`

func (s *Scene) SurfaceMatrix() [16]float64

The 4×4 that puts Node.Surfaces() into the space everything else is already in. Meshes and polylines arrive in the scene's convention; surfaces arrive in the file's own frame, because converting a surface means converting its parameter space too. Identity for a document opened in its native convention and units.

`Scene.Show`

Draw every visible placement — each block instance where the file puts it — with the viewer in use. Keywords: view= (front, back, left, right, top, bottom, iso), az=, el=, zoom=, up= (default from the convention the scene was opened with), edges= (the B-rep edges over the shapes; free curves are drawn either way), width=, height=, hint=. No tolerance=: a document is drawn at the tolerance it was read with.

Comes with the viewers follow-up.

`Scene.View`

Orbit the model with the viewer in use; returns (azimuth, elevation, zoom) where it was left.

Comes with the viewers follow-up.

Node

type Node struct

One node of the document — an assembly, a part, a body, a layer, a placement. A handle, not a snapshot: each property asks the scene when read, so nothing goes stale and nothing is built that is never looked at. Names and attributes are cheap; Node.Bounds() and Node.Mesh() build the geometry.

`Node.Scene`

The scene it belongs to.

Not exposed: keep the *Scene you opened.

`Node.Index()`

func (n *Node) Index() uint32

Its index in the scene, stable while the scene is open: a key for a map of what has been uploaded.

`Node.Name()`

func (n *Node) Name() string

The name the file gave it, or empty.

`Node.ID()`

func (n *Node) ID() string

What the file calls it: a STEP #N, an IFC GlobalId, a Rhino object id.

`Node.Kind()`

func (n *Node) Kind() string

Its type in the file: an IFC class, an openNURBS class, a STEP shape kind.

`Node.Label()`

func (n *Node) Label() string

Something to put in a tree row: the name, else the kind, else #index.

`Node.Depth()`

func (n *Node) Depth() uint32

How far down the tree it sits; a root is zero.

`Node.Generator()`

func (n *Node) Generator() string

What its geometry was before it was triangles — brep, mesh, csg — or empty for a node that draws nothing.

`Node.Visible()`

func (n *Node) Visible() bool

Whether the file says to show it when opened. The node's own switch, not inherited; true where the format has no such switch.

`Node.VisibleNow()`

func (n *Node) VisibleNow() bool

Node.Visible() with every ancestor consulted: a layer switched off hides what hangs under it.

`Node.Locked()`

func (n *Node) Locked() bool

Whether the file says it cannot be selected or edited (Rhino's lock, own or by layer). A locked node is still drawn.

`Node.Parent()`

func (n *Node) Parent() *Node

The node containing this one, or nil for a root.

`Node.Children()`

func (n *Node) Children() []*Node

The nodes directly under this one.

`Node.InstanceOf()`

func (n *Node) InstanceOf() *Node

The node whose geometry this one places, or nil. A part placed seventy times is one mesh and seventy transforms; this is how a caller knows to upload it once.

`Node.SelectAs()`

func (n *Node) SelectAs() *Node

What a click on this node's geometry should select — usually itself. Formats that hang geometry under the object it belongs to (an IFC representation under its product) point back at the object.

`Node.Attributes()`

func (n *Node) Attributes() []Attribute

Everything the file said about the node, as Attribute values.

`Node.CanMesh()`

func (n *Node) CanMesh() bool

Whether the node has geometry of its own to draw. Builds nothing; most nodes are structure and answer false.

`Node.Colour()`

func (n *Node) Colour() ([4]float32, bool)

The colour the file gave it as RGBA in 0–1, or nil — most STEP files carry none, and the caller's default is the right answer.

`Node.Transform()`

func (n *Node) Transform() [16]float64

Where the node's geometry sits: a 4×4 in double precision, composed through every frame above it. Meshes stay single precision in their own frame under a double transform, so a model at survey coordinates keeps its millimetres.

`Node.RawTransform()`

func (n *Node) RawTransform() [16]float64

The same matrix as 16 numbers in the C API's column-major order, ready for a GPU uniform.

`Node.Bounds()`

func (n *Node) Bounds() Bounds

The extent of the node's geometry in that geometry's own frame. Builds the geometry if needed; carry it through Node.Transform() for world coordinates.

`Node.Mesh()`

func (n *Node) Mesh() (*Mesh, error)

Its triangles in their own frame, built now if they have not been. A node that instances another hands back the instanced node's arrays — the same memory for every placement. The arrays are views into the scene; see Lifetimes.

`Node.Surfaces()`

func (n *Node) Surfaces() (*Surfaces, error)

Its faces as exact surfaces plus the trim loops that cut them, each in the surface's own (u, v). Nothing is meshed to produce it, and reading it costs Node.Mesh() nothing. Empty where the reader has no parametric description (a tessellated body, a mesh format). In the file's frame — see Scene.SurfaceMatrix().

`Node.Edges()`

func (n *Node) Edges() *Polylines

Its feature edges as polylines, for an outline overlay. Builds the geometry if needed.

`Node.Brep()`

func (n *Node) Brep() (*Brep, error)

Its exact B-rep, as a Brep, for the kernel's blacksmith.FromNode() to operate on — or nil where it has none (a mesh, a curve, a CSG body, a JT or OpenSCAD part). Shared with the scene, not copied.

`Node.Curves()`

func (n *Node) Curves() *Polylines

Its free curves as polylines; a 2D drawing is all of these.

`Node.Isocurves()`

func (n *Node) Isocurves() *Polylines

Lines ruled across its surfaces, so a curved face reads as curved in a wireframe. A flat face yields its outline, so these can overlap Node.Edges().

`Node.SaveMesh()`

func (n *Node) SaveMesh(path, format string) error

Write this node's own mesh — where it is defined, without its placement — in one of cadaclysm.MeshFormats(). A node that draws nothing, or an unknown format, returns a *CadaclysmError; ask Node.CanMesh() first to grey out a menu entry. To write the whole model, see Scene.Save().

`Node.Walk()`

func (n *Node) Walk() []*Node

This node and every node under it, parents before children.

`Node.Show`

Draw what this node and everything under it places with the viewer in use. Keywords as Scene.Show.

Comes with the viewers follow-up.

`Node.View`

Orbit this node and everything under it; returns (azimuth, elevation, zoom) where it was left.

Comes with the viewers follow-up.

Brep

type Brep struct

A body's exact B-rep — the trimmed surfaces its mesh is cut from — shared with the scene rather than copied, and held by this object until it is released. It is what Node.Brep() hands the kernel's blacksmith.FromNode(), which operates on it without a copy, and it can say whether it is a Manifold. It outlives the scene it came from for as long as anything holds it. In the node's own frame and the file's own units and axes; the kernel library must come from the same release as the reader.

`Brep.Pointer()`

func (b *Brep) Pointer() unsafe.Pointer

The brep's C pointer, which the kernel's wrapper hands across. returns a *CadaclysmError once released.

`cadaclysm.BrepLayoutID()`

func BrepLayoutID() string

How this library lays a brep out in memory: its compiler, target and source. The kernel shares a brep only with a reader whose id equals its own.

`Brep.Manifold()`

func (b *Brep) Manifold() (Manifold, error)

Whether its faces make a manifold — every edge bordered by one face or two, the faces round every vertex one fan — and whether it is closed, as a Manifold. Read off the topology the file wrote, not a mesh. returns a *CadaclysmError once released.

`Brep.Close()`

func (b *Brep) Close() error

Give the reference back now. Leaving a with block, or the garbage collector, does it otherwise.

Placement

type Placement struct

One drawing of one node's geometry at one place: what Scene.Placements() lists. Two drawings of the same shape name the same geometry node, and so the same arrays — upload once, draw twice.

`Placement.Scene`

The scene it belongs to.

Not exposed: keep the *Scene you opened.

`Placement.Index()`

func (p *Placement) Index() uint32

Its index in Scene.Placements().

`Placement.Geometry()`

func (p *Placement) Geometry() *Node

The node whose mesh, edges and curves this draws.

`Placement.Select()`

func (p *Placement) Select() *Node

What a click on this drawing selects: the placement's own node rather than the shared shape, which would light up every copy.

`Placement.Transform()`

func (p *Placement) Transform() [16]float64

Where to draw it: a 4×4, already composed through every frame from the root.

`Placement.RawTransform()`

func (p *Placement) RawTransform() [16]float64

The same matrix as 16 numbers, column-major.

Mesh

type Mesh struct

A node's triangles, in the node's own frame: what Node.Mesh() returns. The arrays are read-only views into the scene's memory, not copies — a large assembly is tens of millions of triangles, and most of them go straight to a GPU. Mesh.Copy() makes arrays of your own.

`Mesh.Positions`

Positions []float32

Three floats a vertex.

`Mesh.Normals`

Normals []float32

Three floats a vertex, or nil for a mesh that carries none.

`Mesh.Uvs`

Uvs []float32

Two floats a vertex, or nil: only readers asked for world-scale UVs fill them. One unit of u or v is one world unit, so faces overlap in UV space — a tiling material, not a lightmap.

`Mesh.Colours`

Colours []float32

Four floats (RGBA) a vertex, or nil — the common case. Only a body painted in several colours, opened with colours on, carries them.

`Mesh.Indices`

Indices []uint32

Three vertex indices a triangle, unsigned 32-bit.

`Mesh.VertexCount`

How many vertices.

len(Positions) / 3.

`Mesh.IndexCount`

How many indices: three a triangle.

len(Indices).

`Mesh.TriangleCount()`

func (m *Mesh) TriangleCount() int

How many triangles.

`Mesh.Copy()`

func (m *Mesh) Copy() MeshData

The same arrays in memory of your own, safe to keep after Scene.Close(). Deliberately visible: on a large model this is where the gigabytes go.

Polylines

type Polylines struct

Edges or curves already flattened to points, in the node's own frame: what Node.Edges(), Node.Curves() and Node.Isocurves() return. Views into the scene, like Mesh.

`Polylines.Positions`

Positions []float32

Three floats a point, the runs end to end.

`Polylines.Counts`

Counts []uint32

How many points each run has, in order.

`Polylines.PolylineCount()`

func (p *Polylines) PolylineCount() int

How many runs.

`Polylines.VertexCount()`

func (p *Polylines) VertexCount() int

How many points in all.

`Polylines.SegmentIndices()`

func (p *Polylines) SegmentIndices() []int

Index pairs into the positions, two per line segment — what GL_LINES and every pair-taking API want. Indices rather than points, so a caller can transform the points once and expand afterwards.

`Polylines.Segments()`

func (p *Polylines) Segments() []float32

The segment endpoints themselves, two points per segment.

Surfaces and Face

type Surfaces struct{ Faces []Face }

A node's faces as exact surfaces and trims: what Node.Surfaces() returns. Iterate it for Face values. In the file's own frame; Scene.SurfaceMatrix() brings it into the scene's.

`Surfaces.Faces`

Faces []Face

The faces, one per trimmed face of the body.

`Face`

type Face struct
Kind uint32
Origin [3]float32
Domain [4]float32
Scalars [4]float32
Loops [][]float32
Nurbs []float32

One trimmed face. kind is the surface: 0 plane, 1 cylinder, 2 cone, 3 sphere, 4 torus, 5 revolution, 6 extrusion, 7 NURBS, 8 sum. origin, ax, ay, az are its frame, scalars its kind-dependent sizes (radius, angle…) and domain its (u min, v min, u max, v max). loops holds the trim loops as (u, v) points, each closing implicitly; profile, profile2 and nurbs carry what a swept or NURBS surface needs. reversed flips the normal; transposed swaps u and v. The C header's CadaclysmFace is the full description.

Bounds

type Bounds struct{ Min, Max [3]float64 }

An axis-aligned box: what Node.Bounds() and Scene.Bounds() return. All zeros means "nothing here".

`Bounds.Min`

Min [3]float64

The low corner.

`Bounds.Max`

Max [3]float64

The high corner.

`Bounds.IsEmpty()`

func (b Bounds) IsEmpty() bool

Whether this is the all-zero box that stands for nothing.

`Bounds.Size()`

func (b Bounds) Size() [3]float64

The extent along each axis.

`Bounds.Centre()`

func (b Bounds) Centre() [3]float64

The midpoint.

Attribute

type Attribute struct

One thing the file said about a node: what Node.Attributes() lists.

`Attribute.Name`

Name string

What the file called it.

`Attribute.Kind`

Kind ValueKind

Which kind of value it holds — a ValueKind. Lets a caller tell a reference from prose, or total the numbers.

`Attribute.Value`

Value string

The value, in the language's own type where it has one for the kind.

A string in this wrapper; Kind says how to read it.

`Attribute.Text()`

func (a Attribute) Text() string

The value rendered for display, identically in every wrapper: true/false, reals in their shortest exact form, lists as [a, b, c].

Convention

type Convention uint32

The coordinate space to open a file into. The library converts on the way out, so a caller names the space it draws in and reads geometry already in it — nothing to rotate or scale afterwards.

`Convention`

type Convention uint32
Native = Convention(C.CADACLYSM_NATIVE)
Unreal = Convention(C.CADACLYSM_UNREAL)
Unity = Convention(C.CADACLYSM_UNITY)
YUp = Convention(C.CADACLYSM_Y_UP)
Blender = Convention(C.CADACLYSM_BLENDER)

The presets: NATIVE keeps the file's own axes and units; UNREAL is Z up, left-handed, centimetres; UNITY Y up, left-handed, metres; Y_UP Y up, right-handed, metres (glTF, three.js, most real-time engines); BLENDER Z up, right-handed, metres.

`cadaclysm.FileUnits`

FileUnits = Convention(0x100)

Combine with a preset to keep its axes but the file's own units.

`cadaclysm.UVWorld`

UVWorld = Convention(0x200)

Combine with a preset to ask for world-scale texture coordinates in Mesh.Uvs. Off by default: eight bytes a vertex nobody asked for.

`cadaclysm.ParseConvention()`

func ParseConvention(text string) (Convention, error)

A convention from a name a user typed: unreal, or unreal+file-units. An unknown name returns a *CadaclysmError listing the accepted ones, rather than silently reading as native.

ValueKind

type ValueKind int32

Which kind of value an Attribute holds.

`ValueKind`

type ValueKind int32
ValueKindNone ValueKind = iota
ValueKindText
ValueKindInteger
ValueKindReal
ValueKindBoolean
ValueKindList
ValueKindReference

TEXT, INTEGER, REAL, BOOLEAN; LIST (the elements rendered as [a, b, c]); REFERENCE (another entity, by the id the file gave it, so it can be followed rather than shown as prose); NONE for an attribute that had no value.

Manifold

type Manifold struct

Whether a body's faces make a manifold — every edge bordered by one face or two, the faces round every vertex one fan — told from its topology rather than a mesh: what a brep's manifold and the kernel's Solid.Manifold() return. Orientation is not asked. The topology is the file's: faces that name no shared edge (IGES, each surface its own sheet; an IFC face written as one polygon) read as open however well they meet in space.

`Manifold.Faces`

Faces int

How many faces.

`Manifold.Edges`

Edges int

How many distinct edges: one shared by two faces counts once.

`Manifold.Vertices`

Vertices int

How many distinct vertices.

`Manifold.BoundaryEdges`

BoundaryEdges int

Edges only one face borders: a sheet's rim, a hole in a shell.

`Manifold.NonManifoldEdges`

NonManifoldEdges int

Edges three or more faces border: a fin, or two solids meeting along a line.

`Manifold.NonManifoldVertices`

NonManifoldVertices int

Vertices whose faces make more than one fan: two solids touching at a corner.

`Manifold.IsManifold`

IsManifold bool

No non-manifold edge or vertex: a manifold, possibly with a boundary.

`Manifold.IsClosed`

IsClosed bool

A manifold with no boundary edge either: it encloses a solid.

Errors

type CadaclysmError struct{ Message string }

A call into the library failed; the message is the library's own reason. One type for every reader failure.

Kernel · cadaclysm_blacksmith

Building solids

Frames and axes

A frame is twelve numbers: an origin, then the x, y and z axes, each three numbers (0,0,0, 1,0,0, 0,1,0, 0,0,1 is the world). A profile is drawn in its frame's x/y and extruded along its z. An axis is six numbers: a point and a direction, which need not be unit. blacksmith.XY() and friends start on the three world planes; Solid.FaceFrame() gives the frame on a face. A Frame builds one for you — blacksmith.FrameXY() at any origin, blacksmith.FrameAt() from a point and a normal — and checks that its axes are square and right-handed, which a bare twelve numbers are not.

Frames are blacksmith.Frame ([12]float64), axes [6]float64; FrameXY, FrameAt and NewFrame build a checked one.

Module functions

The kernel's own library, licence and STEP writer. It is a separate shared library (cadaclysm_blacksmith) from the reader, with its own licence call; one licence file serves both.

`blacksmith.WriteStep()`

func WriteStep(path string, solids []*Solid, schema, unit string) error

Write several solids as one STEP file, each its own body. unit is mm, m or in. schema is left out for AP203 (built in — no file needed), the name of another built-in schema such as AP242's AP242_MANAGED_MODEL_BASED_3D_ENGINEERING_MIM_LF (AP214's AUTOMOTIVE_DESIGN cannot carry the writer's mechanical_context), or a custom EXPRESS schema: a path to its .exp or its text.

`blacksmith.WriteStepText()`

func WriteStepText(solids []*Solid, schema, unit string) (string, error)

The same STEP file as text, for a caller that stores or sends it rather than writing a file.

`blacksmith.DefaultSchema()`

func DefaultSchema() (string, error)

Where an ap203.exp file is found (CADACLYSM_SCHEMAS, else schemas/ in a parent). No longer needed to write STEP: the kernel's AP203 is built in.

`blacksmith.Version()`

func Version() string

The version of the kernel library actually loaded.

`blacksmith.BuildDate()`

func BuildDate() string

When the loaded kernel was built, YYYY-MM-DD.

`blacksmith.License()`

func License(textOrPath string) error

Load a licence into the kernel — the text, or a file's path. The reader has its own call; the same file works for both.

`blacksmith.LicenseInfo()`

func LicenseInfo() string

One line about the kernel's licence, or unlicensed. Never nil.

`blacksmith.LicenseNoticeCount()`

func LicenseNoticeCount() uint64

How many unlicensed notices the kernel has printed to stderr in this process.

`blacksmith.BrepLayoutID()`

func BrepLayoutID() string

How the loaded kernel lays a brep out in memory: its compiler, target and source. blacksmith.FromNode() works only where this equals the reader's cadaclysm.BrepLayoutID() — the two libraries from the same release.

`LibraryPath`

Where the kernel library was found: CADACLYSM_BLACKSMITH_LIBRARY first, then as the reader's.

cgo links the library at build time; see Install.

Profile

type Profile struct{ handle *C.CadaclysmBlacksmithProfile }

A closed outline with holes, in its own x/y — what gets extruded, revolved, lofted or swept. Immutable: every method returns a new one.

Its loops must be simple: an outline that crosses or touches itself (a figure-eight, a vertex landing on another side), a hole that runs into the boundary, or two holes that overlap are refused by every call that builds a face or a closed solid, naming the loops — extrude: hole 0 crosses the boundary. The open calls (extrude_open, revolve_open, sweep_open, loft_open) build sheets, and take such a profile as it is.

`blacksmith.Rect()`

func Rect(w, h float64) (*Profile, error)

A w × h rectangle centred on the origin.

`blacksmith.Circle()`

func Circle(r float64) (*Profile, error)

A circle of radius r about the origin.

`blacksmith.Slot()`

func Slot(centre [2]float64, length, r float64) (*Profile, error)

A slot (stadium) length long overall, with end radius r, centred on centre and running along x. length must exceed 2 * r.

`blacksmith.Polygon()`

func Polygon(points [][2]float64) (*Profile, error)

A closed polygon through the points, in order, its side back to the first point a segment of its own. At least three points.

`blacksmith.RegularPolygon()`

func RegularPolygon(centre [2]float64, radius float64, sides int, angle float64) (*Profile, error)

A regular polygon of sides sides (at least 3) on the circle of radius about centre, its first corner at angle radians from the sketch's x axis (0 by default), the rest counter-clockwise.

`blacksmith.Spline()`

func Spline(points [][2]float64, degree int, weights []float64, closed bool) (*Profile, error)

A spline of degree (3 by default) through the control polygon points, weights one per point or nil. Open, it starts on the first point and ends on the last: an open chain, for blacksmith.ExtrudeOpen() or blacksmith.Chain(). Closed, it is periodic — smooth through its own start, no corner there — and a closed profile. The degree is lowered to fit the points; a degree of zero, too few points (two open, three closed) or a weight not positive returns a *BuildError.

`blacksmith.NewPath()`

func NewPath(x, y float64) *Path

Start drawing an outline segment by segment at start; see Path.

`blacksmith.Chain()`

func Chain(pieces []*Profile, tolerance float64) (*Profile, error)

Open profiles — paths ended open — joined end to end into one: the forge's merge. They may come in any order and either way round: each next piece is the first of the rest with an end within tolerance (1e-6 by default) of either end of the chain so far, reversed where that makes it meet. Every segment is kept exactly — a line a line, an arc an arc, a spline the same spline. Closed where the chain's two ends meet, otherwise an open chain. A piece that is empty, has holes, is closed on its own or meets none of the others returns a *BuildError naming it by its index.

`blacksmith.FromLoops()`

func FromLoops(loops []*Profile) (*Profile, error)

Closed loops, in any order, as one profile: the loop enclosing the most area is the boundary and every other a hole in it, in the order given — a sketch's rectangle and the circles drawn inside it. Each loop is a closed profile with no holes of its own, wound either way; one that closes within rounding is closed exactly. A loop that is open, empty or encloses no area, loops that cross or touch, a hole outside the boundary, or one inside another hole (an island) returns a *BuildError, naming the loops by their index.

`Profile.CloseLoop()`

func (p *Profile) CloseLoop() (*Profile, error)

This profile closed — the forge's sketch "close": where its last segment stops short of its start (a path ended open), a straight segment back to it; where it already comes back within 1e-9 of its extent, its last segment made to land on the start exactly. A closed profile comes back as it is, and holes are closed the same way.

`Profile.WithHole()`

func (p *Profile) WithHole(hole *Profile) (*Profile, error)

This outline with hole cut out of it.

`Profile.Translate()`

func (p *Profile) Translate(dx, dy float64) (*Profile, error)

This outline moved by (dx, dy).

`Profile.Round()`

func (p *Profile) Round(radius float64, corners []int, open bool) (*Profile, error)

This outline with its corners rounded by radius: where two straight segments meet, both are cut back and an exact arc tangent to both goes between them; a corner next to an arc or a spline is left as it is. With no corners every such corner is rounded, the holes' too; a list picks corners of the outline — corner k is where segment k ends. open reads the profile as an open chain whose two ends stay square. A radius that does not fit returns a *BuildError naming the corner.

`Profile.Polylines`

The outline, then each hole, as polylines at z = 0 within tolerance of its arcs and splines — what a viewer draws it with. A closed loop repeats its first point at the end; an open chain (a profile ended open) stays open. Views, like Solid.Mesh().

Declared; the method comes with the viewers.

`Profile.Show`

Draw the outline and holes with the viewer in use, from the top by default. Keywords as Solid.Show; edges= is ignored, the lines being the whole picture.

Comes with the viewers follow-up.

`Profile.View`

Orbit the outline with the viewer in use; returns (azimuth, elevation, zoom) where it was left.

Comes with the viewers follow-up.

Path

type Path struct

An outline drawn a segment at a time — lines, arcs, Béziers, NURBS — then closed into a Profile. Ending it consumes the builder.

`Path.LineTo()`

func (p *Path) LineTo(x, y float64) *Path

A straight segment to (x, y).

`Path.ArcTo()`

func (p *Path) ArcTo(x, y float64, centre [2]float64, ccw bool) *Path

A circular arc to (x, y) about centre, counter-clockwise unless ccw is false.

`Path.BezierTo()`

func (p *Path) BezierTo(c1, c2, to [2]float64) *Path

A cubic Bézier through control points c1, c2 to to.

`Path.NurbsTo()`

func (p *Path) NurbsTo(control [][2]float64, knots []float64, degree int, weights []float64) *Path

A NURBS segment: control is every control point after the current one, the endpoint last; knots the full knot vector; weights one per control point including the current one, or nil for a non-rational curve.

`Path.End()`

func (p *Path) End() (*Profile, error)

Close the outline back to its start and return the Profile.

`Path.EndOpen()`

func (p *Path) EndOpen() (*Profile, error)

The path as it stands, not closed: an open chain for blacksmith.ExtrudeOpen(), blacksmith.SweepOpen() or blacksmith.LoftOpen().

SweepPath

type SweepPath struct

The 3D path a profile is carried along by blacksmith.Sweep(): lines and circular arcs. Sweeping only borrows it, so one path can be swept many times; close it when done.

`blacksmith.NewSweepPath()`

func NewSweepPath(x, y, z float64) *SweepPath

Start a path at a 3D point.

`blacksmith.SweepPathAlong()`

func SweepPathAlong(curve *Profile, frame Frame, tolerance float64, open bool) *SweepPath

The path a 2D chain (usually from Path.EndOpen()) draws on frame: a line a straight piece, an arc a circular one, a Bézier or spline fitted with biarcs — arcs tangent to each other and to the curve — within tolerance, so the path is tangent throughout and the sweep exact along it. open false closes the path back to its start.

`SweepPath.LineTo()`

func (p *SweepPath) LineTo(point [3]float64) *SweepPath

A straight piece to a 3D point.

`SweepPath.Arc()`

func (p *SweepPath) Arc(centre, axis [3]float64, angle float64) *SweepPath

Turn angle radians (in (0, 2π]) about the axis through centre along axis.

`SweepPath.Close()`

func (p *SweepPath) Close() error

Free the path.

Slant

type Slant struct

A plane a blacksmith.ExtrudeBetween() starts or ends on, read as a height over the sketch plane at each point: at + grad · (x, y). Flat for an ordinary cap; sloped for a mitre.

`Slant.At`

At float64

The height at the sketch origin.

`Slant.Grad`

Grad [2]float64

The slope in x and y.

`blacksmith.Flat()`

func Flat(at float64) Slant

A flat plane at height at.

`blacksmith.OfPlane()`

func OfPlane(frame Frame, point, normal [3]float64) (Slant, error)

The plane through point square to normal, as heights over frame. A plane that contains the extrusion direction has no height and returns a *BuildError.

Frame

type Frame [12]float64

A frame built for you instead of twelve numbers typed out: an origin and three unit axes, square to each other and right-handed (z = x × y). It goes wherever a frame does. Immutable. The constructor takes the origin and the three axes, normalises them, and returns a *BuildError when they are not square or not right-handed.

`blacksmith.FrameXY()`

func FrameXY(origin [3]float64) Frame

The world XY plane through origin: z up, as blacksmith.XY().

`blacksmith.FrameXZ()`

func FrameXZ(origin [3]float64) Frame

The world XZ plane through origin: x along X, y along Z, so z is -Y, as blacksmith.XZ().

`blacksmith.FrameYZ()`

func FrameYZ(origin [3]float64) Frame

The world YZ plane through origin: x along Y, y along Z, so z is +X, as blacksmith.YZ().

`blacksmith.FrameAt()`

func FrameAt(origin, normal [3]float64) (Frame, error)
func FrameAtX(origin, normal, x [3]float64) (Frame, error)

The plane through origin square to normal, which becomes the frame's z (it need not be unit). Its x axis is x laid onto that plane; with none, world X laid onto it, or world Y when the normal is within about 25° of X — the axes Solid.FaceFrame() gives a face facing normal. So a normal along +Z, -Y or +X gives exactly blacksmith.FrameXY(), blacksmith.FrameXZ() or blacksmith.FrameYZ(). A zero normal, or an x along the normal, returns a *BuildError.

`blacksmith.FrameOf()`

func FrameOf(f Frame) (Frame, error)

Twelve numbers — what Solid.FaceFrame() and Workplane.Frame() hand back — as a checked frame, to read its axes or move it.

`blacksmith.FrameMidplane()`

func FrameMidplane(a, b Frame) (Frame, error)

The plane midway between the planes of frames a and b — Fusion's midplane: for parallel planes the one halfway between, on a's axes; for planes that meet, the plane bisecting them through the line they meet on, its x along that line.

`blacksmith.FrameThrough()`

func FrameThrough(p, q, r [3]float64) (Frame, error)

The plane through the points p, q and r: its origin p, its x towards q, its z the normal the three turn about counter-clockwise. Three points on one line returns a *BuildError.

`Frame.Origin()`

func (f Frame) Origin() [3]float64
func (f Frame) X() [3]float64
func (f Frame) Y() [3]float64
func (f Frame) Z() [3]float64

The origin and the three axes, each three numbers.

`Frame.Translate()`

func (f Frame) Translate(dx, dy, dz float64) Frame

This frame moved by (dx, dy, dz) in world coordinates.

`Frame.Offset()`

func (f Frame) Offset(distance float64) Frame

This frame moved distance along its own z: Frame.xy().offset(5) is the XY plane at z = 5.

`NewFrame` Go only

func NewFrame(origin, x, y, z [3]float64) (Frame, error)

Python's Frame(origin, x, y, z): the frame with these axes, normalised, or a *BuildError. A Frame literal is taken as written, unchecked; blacksmith.FrameOf() checks one.

Workplane

type Workplane struct

The fluent chain: a frame, the solid built so far, and the face last picked. A build step replaces the solid rather than adding to it — combine solids explicitly with Solid.Join(). Every step returns a *BuildError at once rather than holding the error for later.

`blacksmith.XY()`

func XY() *Workplane

Start on the XY plane at the origin (Z up). blacksmith.XZ() and blacksmith.YZ() start on the other two.

`blacksmith.XZ()`

func XZ() *Workplane

Start on the XZ plane.

`blacksmith.YZ()`

func YZ() *Workplane

Start on the YZ plane.

`blacksmith.On()`

func On(frame Frame) *Workplane

Start on any frame (see Frames).

`blacksmith.FromSolid()`

func FromSolid(solid *Solid) *Workplane

Start from an existing solid, on the XY plane — the usual way to pick one of its faces and build on it.

`Workplane.Frame()`

func (w *Workplane) Frame() Frame

The current frame, 12 numbers.

`Workplane.Cuboid()`

func (w *Workplane) Cuboid(x, y, z float64) *Workplane

A box on the current frame; replaces the solid.

`Workplane.Cylinder()`

func (w *Workplane) Cylinder(r, h float64) *Workplane

A cylinder of radius r and height h standing on the current frame; replaces the solid.

`Workplane.Face()`

func (w *Workplane) Face(profile *Profile) *Workplane

The planar sheet the profile bounds on this frame — see blacksmith.Face(); replaces the solid.

`Workplane.Extrude()`

func (w *Workplane) Extrude(profile *Profile, height float64) *Workplane

The profile extruded height along the frame's z; replaces the solid.

`Workplane.Revolve()`

func (w *Workplane) Revolve(profile *Profile, angle float64) *Workplane

The profile revolved angle radians about the frame's y axis; replaces the solid.

`Workplane.Translate()`

func (w *Workplane) Translate(dx, dy, dz float64) *Workplane

Slide the current solid. Keeps the face selection — a rigid move keeps every face's index.

`Workplane.Faces()`

func (w *Workplane) Faces(selector Selector) *Workplane

Pick a face of the current solid with a Selector.

`Workplane.OnFace()`

func (w *Workplane) OnFace() *Workplane

Move the frame onto the face last picked (outward normal as z), so the next step builds on it.

`Workplane.Solid()`

func (w *Workplane) Solid() (*Solid, error)

The solid built so far. On an empty chain it returns a *BuildError.

Selector and Axis

type Selector struct

Which face to pick: the one furthest along an axis, furthest against it, the one facing a direction, or by index. Used by Workplane.Faces() and Solid.SelectFace().

`blacksmith.Max()`

func Max(axis Axis) Selector

The face furthest along axis.

`blacksmith.Min()`

func Min(axis Axis) Selector

The face furthest against axis.

`blacksmith.Normal()`

func Normal(direction [3]float64) Selector

The face whose outward normal is nearest direction (need not be unit).

`blacksmith.Index()`

func Index(i int) Selector

The face with this index.

`Axis`

type Axis int
AxisX Axis = iota
AxisY
AxisZ

X, Y, Z: the axes blacksmith.Max() and blacksmith.Min() take.

Solid

type Solid struct

An exact B-rep solid (or an open sheet): planes, cylinders, cones, spheres, tori and NURBS, trimmed and joined, never approximated by triangles. Immutable — every operation returns a new one. Close it when done, or let the language's scope do it; see Lifetimes.

Primitives

`blacksmith.Cuboid()`

func Cuboid(x, y, z float64) (*Solid, error)

A box x × y × z, centred on the origin.

`blacksmith.Cylinder()`

func Cylinder(r, h float64) (*Solid, error)

A cylinder of radius r, from z = 0 to h.

`blacksmith.Cone()`

func Cone(r, h float64) (*Solid, error)

A cone of base radius r and height h, apex up.

`blacksmith.Sphere()`

func Sphere(r float64) (*Solid, error)

A sphere of radius r about the origin.

`blacksmith.Torus()`

func Torus(major, minor float64) (*Solid, error)

A torus about the z axis: major to the tube's centre, minor the tube's radius.

`blacksmith.Wedge()`

func Wedge(x, y, z, topX float64) (*Solid, error)

A box whose top face is top_x long instead of x: a ramp.

From a profile

`blacksmith.Extrude()`

func Extrude(profile *Profile, frame Frame, height float64) (*Solid, error)

The profile on frame, extruded height along the frame's z.

`blacksmith.ExtrudeOpen()`

func ExtrudeOpen(profile *Profile, frame Frame, height float64) (*Solid, error)

The walls only, no caps: an open sheet. Takes an open Path.EndOpen() chain as well as a closed profile.

`blacksmith.ExtrudeTapered()`

func ExtrudeTapered(profile *Profile, frame Frame, height, taper float64) (*Solid, error)

Extrude with a draft: the walls lean out by taper radians as they rise (in, when negative). Every wall stays exact — a plane off a line, a cone off an arc.

`blacksmith.ExtrudeOpenTapered()`

func ExtrudeOpenTapered(profile *Profile, frame Frame, height, taper float64) (*Solid, error)

The tapered walls without caps.

`blacksmith.ExtrudeBetween()`

func ExtrudeBetween(profile *Profile, frame Frame, bottom, top Slant) (*Solid, error)

Extrude between two planes rather than two heights: bottom and top are each a Slant (a bare number is a flat one). With both flat this is blacksmith.Extrude(); with a slope it is the mitred end of a frame member. A top that comes down to or through the bottom returns a *BuildError.

`blacksmith.ExtrudeOpenBetween()`

func ExtrudeOpenBetween(profile *Profile, frame Frame, bottom, top Slant) (*Solid, error)

blacksmith.ExtrudeBetween() without the caps.

`blacksmith.Revolve()`

func Revolve(profile *Profile, axis [6]float64, angle float64) (*Solid, error)

The profile swung angle radians about axis (a point and a direction — see Frames). The profile's x is read as the radius and its y as the height along the axis, so it must lie to one side of it.

`blacksmith.RevolveOpen()`

func RevolveOpen(profile *Profile, axis [6]float64, angle float64) (*Solid, error)

The revolved surface of an open profile: a sheet.

`blacksmith.RevolveInPlane()`

func RevolveInPlane(profile *Profile, frame Frame, a, b [2]float64, angle float64) (*Solid, error)

The profile on frame swung angle radians about the axis through the sketch points a and b (each (x, y) on the frame) — the profile and its axis drawn together, as a sketch draws them, where blacksmith.Revolve() reads the profile as (radius, height). The profile may lie on either side of the axis and touch it (a half-disc with its diameter on the axis turns into a ball), but not cross it. The sweep starts where the profile is drawn and turns right-handed about b - a, so a partial turn leaves one end of the solid over the profile itself.

`blacksmith.RevolveOpenInPlane()`

func RevolveOpenInPlane(profile *Profile, frame Frame, a, b [2]float64, angle float64) (*Solid, error)

blacksmith.RevolveInPlane() for a curve: its segments swung into a sheet, no caps.

`blacksmith.Coil()`

func Coil(profile *Profile, axis [6]float64, pitch, turns float64) (*Solid, error)

The profile coiled about axis (a point and a direction): read as blacksmith.Revolve() reads it — x the distance from the axis, y along it — and turned turns times while climbing pitch along the axis each turn: a spring, a thread, Fusion's Coil. The walls follow the helix to a few millionths of the radius (a helix is not a NURBS curve, so they are a close fit, exact at both ends); the two ends are the profile itself, flat. A profile reaching the axis, one with holes, or — from a full turn up — a pitch no taller than the profile returns a *BuildError.

`blacksmith.Loft()`

func Loft(a *Profile, frameA Frame, b *Profile, frameB Frame) (*Solid, error)

The solid between profile a on one frame and b on another: ruled walls between matching sides (both profiles need the same number of sides, and no holes), capped by the two.

`blacksmith.LoftOpen()`

func LoftOpen(a *Profile, frameA Frame, b *Profile, frameB Frame) (*Solid, error)

The ruled walls without the caps.

`blacksmith.LoftThrough()`

func LoftThrough(profiles []*Profile, frames []Frame) (*Solid, error)

The solid smooth through every section — a profile on its frame, in order: each wall interpolates its side across all the profiles (cubic through four or more, quadratic through three, blacksmith.Loft() through two), capped by the first and the last. Every section of the result is its profile exactly, arcs and all. The profiles must have the same number of sides and no holes; otherwise returns a *BuildError.

`blacksmith.LoftThroughOpen()`

func LoftThroughOpen(profiles []*Profile, frames []Frame) (*Solid, error)

The walls through the curves without the caps: an open sheet.

`blacksmith.Sweep()`

func Sweep(profile *Profile, frame Frame, path *SweepPath) (*Solid, error)

The profile on frame, carried along a SweepPath. A straight piece is an extrusion and an arc a revolution about the arc's axis, so nothing is approximated — a circle along an arc is an exact torus wall.

`blacksmith.SweepOpen()`

func SweepOpen(profile *Profile, frame Frame, path *SweepPath) (*Solid, error)

The swept walls without caps: an open sheet.

`blacksmith.Pipe()`

func Pipe(path *SweepPath, radius, thickness float64) (*Solid, error)

A circle of radius carried along a SweepPath, square to where it starts — Fusion's Pipe: a solid rod, or with a positive thickness a tube whose walls are that thick. The path is only borrowed, as by blacksmith.Sweep(), and refused the same way.

`Solid.ExtrudeFaces()`

func (s *Solid) ExtrudeFaces(height float64) (*Solid, error)

Every face of a sheet pushed height along its own normal, walled and closed: the sheet as a solid of that thickness.

`blacksmith.Face()`

func Face(profile *Profile, frame Frame) (*Solid, error)

The flat sheet a profile bounds on frame: one planar face, each hole a hole through it, its normal the frame's z however the profile winds, every edge the exact line, arc or spline its segment is. An open sheet — raise it with Solid.ExtrudeFaces(), cut it with Solid.Trim().

Placing

`Solid.Place()`

func (s *Solid) Place(frame Frame) (*Solid, error)

A solid built about the origin moved onto frame: its origin to the frame's origin, its axes to the frame's (see Frames).

`Solid.Translate()`

func (s *Solid) Translate(dx, dy, dz float64) (*Solid, error)

Moved by (dx, dy, dz).

`Solid.Rotate()`

func (s *Solid) Rotate(axis [6]float64, radians float64) (*Solid, error)

Turned radians about axis (a point and a direction).

`Solid.Mirror()`

func (s *Solid) Mirror(plane Frame) (*Solid, error)

Reflected across plane: a frame whose z is the mirror plane's normal.

Booleans

`Solid.Join()`

func (s *Solid) Join(other *Solid, tolerance float64, merge ...bool) (*Solid, error)

The union with other, as an exact B-rep. merge (off by default, so face and edge numbers stay as they were) merges the flush faces the join leaves, as Solid.MergeFlush() does — Go takes it as a trailing true, Java as an overload; Solid.Cut() and Solid.Common() take it too. tolerance (0.05 by default) is the mesh tolerance the boolean decides at: both solids are meshed at it, so a tighter one is as correct and slower. progress, where the wrapper takes one, is called with a phase name and a done/total count.

`Solid.Cut()`

func (s *Solid) Cut(other *Solid, tolerance float64, merge ...bool) (*Solid, error)

This solid with other removed.

`Solid.Common()`

func (s *Solid) Common(other *Solid, tolerance float64, merge ...bool) (*Solid, error)

What this solid and other share.

`Solid.SplitSheet()`

func (s *Solid) SplitSheet(tool *Solid, tolerance float64) (*Solid, error)

This solid or sheet cut along tool's boundary with nothing removed: each face comes back as its pieces outside tool and then its pieces inside, in the original face order — the start of a surface trim. tool must be a closed solid. Keep the pieces you want with Solid.DropFaces(), or split and drop in one call with Solid.Trim().

Faces and sheets

`Solid.FaceSheet()`

func (s *Solid) FaceSheet(face int) (*Solid, error)

One face alone, as an open sheet: its surface, its loops and the exact curves on its edges, the rest of the solid left behind — raised by Solid.ExtrudeFaces() it is the prism over that face. Keeps the face's colour.

`Solid.DropFaces()`

func (s *Solid) DropFaces(faces []int) (*Solid, error)

This solid without the faces listed: the rest keep their surfaces, curves and colours in their order, so an index into the result is this one's with the dropped ones closed up. Dropping every face returns a *BuildError.

`Solid.Trim()`

func (s *Solid) Trim(tool *Solid, keep string, tolerance float64) (*Solid, error)

This sheet (or solid) cut along the closed tool's boundary and the pieces on one side thrown away: keep "outside" (the default) keeps what lies outside the tool — a hole punched through — and "inside" what lies within it. Nothing on the kept side returns a *BuildError. tolerance and progress as for Solid.Join().

`Solid.PushPull()`

func (s *Solid) PushPull(face int, distance, tolerance float64) (*Solid, error)
func (s *Solid) PushPullFaces(faces []int, distance, tolerance float64) (*Solid, error)

Face face pushed out by distance along its outward normal — pulled in, negative — the way Fusion and Rhino extrude a face: the prism over it joined on (cut out) at tolerance, and the flush faces merged, so a box's top raised is one taller box of six faces rather than a box and a prism with every side wall split at the seam. A face on a cylinder, a cone, a sphere or a torus moves out along its normal instead, as Fusion's press-pull does: the surface a step out — a boss fatter, a bore or a countersink narrower, a dome fuller — with the flat faces beside it carried along in their own planes. Any other curved face is refused, as is a curved face with anything but a plane it can follow beside it, reaching a cone's apex, pushed to its axis or centre, off a plane beside it or run into another edge. A flat face keeps its own colour where it now lies.

Several faces push together, as Fusion's press-pull on a selection: each by its own rule, one after another in the order given, each found again after the pushes before it renumbered the faces — a box's top and a side pushed 5 is the box 5 taller and 5 wider, a boss's top and wall the boss taller and fatter. A face on the same curved surface as one before it, and joined to it, moved with that one and is not pushed twice. No faces, or a face an earlier push took away, returns a *BuildError.

`Solid.Refillet()`

func (s *Solid) Refillet(face int, radius, tolerance float64) (*Solid, error)

The round face belongs to — a fillet's bands, balls and rim bands joined to that face — made again at radius, as Fusion's press-pull on a fillet face: taken back to the sharp edges it replaced, and those rounded again, so the round is the one Solid.Fillet() makes at that radius. Rounds of straight edges between planes (their ends square corners, mitres, balls, or a cylinder, cone or sphere the edge runs into — a D-cut shaft's top edge, a rib's into a boss) and of circular rims between a plane and a cylinder or cone (a boss's foot, a bore's mouth, a counterbore's step); a face that is not one, or a radius that does not fit, returns a *BuildError.

`Solid.Unfillet()`

func (s *Solid) Unfillet(face int) (*Solid, error)

The round face belongs to taken off, the faces beside it made sharp again, meeting on the edges the round replaced — Fusion's delete of a fillet face. The same rounds as Solid.Refillet().

`Solid.Rechamfer()`

func (s *Solid) Rechamfer(face int, distance, tolerance float64) (*Solid, error)

The chamfer face belongs to — its bevels (flat between two planes, cones round rims) and the corner triangles joined to that face — cut again at distance, as Fusion's press-pull on a chamfer face: taken back to the sharp edges it cut, and those bevelled again, so the chamfer is the one Solid.Chamfer() cuts at that distance. A flat bevel's ends may run into a cylinder, cone or sphere, as a round's may. A face that is not a chamfer's bevel, or a distance that does not fit, returns a *BuildError.

`Solid.Unchamfer()`

func (s *Solid) Unchamfer(face int) (*Solid, error)

The chamfer face belongs to taken off, the faces beside it made sharp again — Fusion's delete of a chamfer face. The same chamfers as Solid.Rechamfer().

`Solid.MergeFlush()`

func (s *Solid) MergeFlush() (*Solid, error)

This solid with its flush faces merged: flat faces on one plane, facing one way and meeting along their edges — the seams Solid.Join() leaves where two parts are flush — made one face, and the vertices left mid-way along a straight edge taken out.

`Solid.Split()`

func (s *Solid) Split(tool *Solid, tolerance float64) ([]*Solid, error)

This solid split by tool into bodies — Fusion's Split Body — returned as a list: a closed tool gives the parts outside it, then the parts inside; a flat sheet (a blacksmith.Face()) splits by the whole plane it lies on. Each connected part is a body of its own, so a U cut across both arms is three. The new faces are pieces of the tool's, the colours carried over. A tool that does not cross the solid, or a curved sheet, returns a *BuildError. tolerance and progress as for Solid.Join().

`Solid.SplitByPlane()`

func (s *Solid) SplitByPlane(plane Frame, tolerance float64) ([]*Solid, error)

This solid split by the plane through plane's origin, square to its z (a frame): the bodies in front of it first, then those behind.

`Solid.Lumps()`

func (s *Solid) Lumps() ([]*Solid, error)

This solid's connected bodies, each a solid of its own — faces sharing an edge are one body — in the order of their first faces. One body comes back as itself; a boolean that leaves two parts gives two.

Finishing

`Solid.Edges()`

func (s *Solid) Edges() ([]Edge, error)

The solid's edges as Edge values — what Solid.Fillet() and Solid.Chamfer() take. Copied; safe to keep.

`Solid.Fillet()`

func (s *Solid) Fillet(edges []int, radius, tolerance float64) (*Solid, error)

Round the given edges (Edge values or their indices) with radius. Exact: the blend faces are cylinders, tori and NURBS, and the neighbours are trimmed back onto them.

`Solid.Chamfer()`

func (s *Solid) Chamfer(edges []int, distance, tolerance float64) (*Solid, error)

A flat bevel instead of a round: each edge cut back distance along both its faces.

`Solid.Shell()`

func (s *Solid) Shell(thickness float64, open []int, tolerance float64) (*Solid, error)

Hollow the solid to walls thickness thick — inward for a positive thickness, outward (the solid becoming the cavity) for a negative one. The faces listed in open are removed so the hollow is reachable.

`Solid.Thicken()`

func (s *Solid) Thicken(thickness, tolerance float64) (*Solid, error)

A sheet made a solid thickness thick — Fusion's Thicken: its faces, their twins moved thickness along the faces' normals (against them for a negative thickness), and a wall round every open edge. Two faces of a folded sheet meet on their offsets' mitre; a closed sheet thickens to a hollow. Free-form (NURBS) faces offset by a fit held to tolerance. A thickness a face cannot take — a radius used up, a free-form offset folding over — returns a *BuildError.

Asking

`Solid.Faces()`

func (s *Solid) Faces() (int, error)

How many faces.

`Solid.FaceKind()`

func (s *Solid) FaceKind(face int) (string, error)

A face's surface: plane, cylinder, cone, sphere, torus, nurbs, revolution, extrusion or other.

`Solid.SelectFace()`

func (s *Solid) SelectFace(selector Selector) (int, error)

The index of the face a Selector picks.

`Solid.FaceFrame()`

func (s *Solid) FaceFrame(face int) (Frame, error)

The frame on a face: origin at its centre, z its outward normal, x world X laid onto the face (world Y on a face facing close to X) — blacksmith.FrameAt()'s rule, so the top of a box gets the XY plane's axes. What Workplane.OnFace() moves onto.

`Solid.Bounds()`

func (s *Solid) Bounds() (cadaclysm.Bounds, error)

The axis-aligned bounds, over the tessellation at 0.05.

`Solid.BoundsAt()`

func (s *Solid) BoundsAt(tolerance float64) (cadaclysm.Bounds, error)

The bounds over the tessellation at tolerance — the same cache Solid.Mesh() fills, so asking both costs one mesh.

`Solid.LeakedEdges()`

func (s *Solid) LeakedEdges(tolerance float64) (int, error)

How many mesh edges at tolerance are bound by anything other than two triangles: zero for a closed solid. A seam two solids share along a line does not count; a hole or a fold does.

`Solid.UnpairedEdges()`

func (s *Solid) UnpairedEdges(tolerance float64) (int, error)

How many mesh edges have triangle uses that do not cancel out: zero for a closed, consistently oriented solid. Unlike Solid.LeakedEdges() this catches a fold — two triangles running the same way.

`Solid.IsWatertight()`

func (s *Solid) IsWatertight(tolerance float64) (bool, error)

Whether Solid.LeakedEdges() is zero.

`Solid.Manifold()`

func (s *Solid) Manifold() (cadaclysm.Manifold, error)

Whether the faces make a manifold — every edge bordered by one face or two, the faces round every vertex one fan — and whether it is closed, as a Manifold. Read off the solid's topology, not a mesh, so it takes no tolerance; whether the faces all face out is Solid.UnpairedEdges()'s question.

Colour

`Solid.Coloured()`

func (s *Solid) Coloured(r, g, b float64) (*Solid, error)

A new solid coloured (r, g, b), each 0..1 — Python and Node.js also take "#rgb" or "#rrggbb" — or, given a face (Go: ColouredFace), just that face, whose colour then wins over the solid's. What is made from a coloured solid inherits: a move keeps every colour; a boolean, fillet, chamfer or shell gives each face the colour of the input face it lies on (a cut's bore takes the tool's), and a new face — a round, a shell's inner wall — the solid's. STEP output carries no colour.

`Solid.Colour()`

func (s *Solid) Colour() ([3]float64, bool, error)

The solid's own colour as (r, g, b), or none.

`Solid.FaceColour()`

func (s *Solid) FaceColour(face int) ([3]float64, bool, error)

A face's colour as drawn: its own, else the solid's, else none.

From files

`blacksmith.Open()`

func Open(path string) (*Solid, error)

The body a CAD file holds, as a solid: STEP (AP203/214/242), ACIS .sat, Rhino .3dm, OCCT .brep, IGES or IFC, read where it draws, in the file's own units and axes. A file drawing several bodies needs body (0-based, in drawing order) or blacksmith.OpenAll(). What such a solid can do is what its geometry allows: fillet and chamfer want line and circle edges; booleans take any surface, but new edges traced on a free-form face are not always writable back to STEP; and every verb meshes its operands first, so its cost grows with the body's face count. Reads through the reader library, which must be from the same release.

`blacksmith.OpenAll()`

func OpenAll(path string) ([]*Solid, error)

Every body a CAD file draws, as solids placed where it draws them: one per placement, so a part placed twice is two solids.

`blacksmith.FromNode()`

func FromNode(scene *cadaclysm.Scene, node *cadaclysm.Node, placed bool) (*Solid, error)

The body a reader Node draws, as a solid — sharing the reader's brep (Node.Brep()), not copying it; the scene can be closed first. placed (the default) puts it where the node's transform does, where its mesh draws; otherwise it keeps the node's own frame. The two libraries' layouts (blacksmith.BrepLayoutID()) must agree, or it returns a *CadaclysmError.

Output

`Solid.Mesh()`

func (s *Solid) Mesh(tolerance float64) (*Mesh, error)

Triangles at tolerance: positions, normals (three floats a vertex) and indices. Views into the solid's own cache — valid until the solid is closed or meshed again at a different tolerance; copy what must outlive either.

`Solid.FaceTriangles`

How many triangles each face meshed to at tolerance, one count per face in face order: the triangles of Solid.Mesh() at the same tolerance run face by face, so face f's are the counts[f] after the first counts[:f].sum(), and the counts sum to the mesh's triangle count. What a viewer colours a face by. A view, like Solid.Mesh().

Declared; the method comes with the viewers.

`Solid.EdgePolylines()`

func (s *Solid) EdgePolylines(tolerance float64) (*Polylines, error)

The feature edges as polylines at tolerance, one run of points per edge. Views, like Solid.Mesh().

`Solid.Show`

Draw the solid with the viewer in use — in a terminal, the picture is left in the scrollback. Each face keeps its own colour (Solid.FaceColour(): a colour of its own, else the solid's). Keywords: view= (front, back, left, right, top, bottom, iso), az=, el=, zoom=, up=, edges=, width=, height=, hint=, tolerance=.

Comes with the viewers follow-up.

`Solid.View`

Orbit the solid with the viewer in use until it is closed; returns (azimuth, elevation, zoom) where it was left. Keywords as Solid.Show.

Comes with the viewers follow-up.

`Solid.Step()`

func (s *Solid) Step(path, schema, unit string) error

Write this solid as an AP203 STEP file; see blacksmith.WriteStep() for schema and unit.

`Solid.StepText()`

func (s *Solid) StepText(schema, unit string) (string, error)

The same STEP file as text.

`Solid.ToScene()`

func (s *Solid) ToScene(schema string) (*cadaclysm.Scene, error)

This solid as a reader Scene, through STEP in memory: the door from the kernel to everything the reader does — its tree, meshes, glTF/OBJ/STL export. Needs the reader library as well.

`Solid.Close()`

func (s *Solid) Close() error

Free the solid now. The garbage collector, or the language's scope, does it otherwise.

`DefaultTolerance` Go only

const DefaultTolerance = 0.05

Go has no default arguments: pass blacksmith.DefaultTolerance (0.05) wherever Python's tolerance would default — booleans, meshing, bounds.

Edge

type Edge struct

One edge of a solid as plain data, copied out of it: what Solid.Edges() lists and Solid.Fillet() takes.

`Edge.Index`

Index int

Its index — what Solid.Fillet() and Solid.Chamfer() take.

`Edge.Kind`

Kind string

The curve: line, circle, ellipse, nurbs or other.

`Edge.Faces`

Faces []int

The faces meeting on it, as face indices.

`Edge.Segments`

Segments [][2][3]float64

The two ends of each piece of the edge.

`Edge.IsLine()`

func (e Edge) IsLine() bool

Whether the edge is straight.

`Edge.Direction()`

func (e Edge) Direction() ([3]float64, bool)

The unit direction of a straight edge, or nil for a curved one. Picking the vertical edges of a plate is a filter on this.

Manifold

What Solid.Manifold() returns: whether the solid's faces make a manifold, and whether it is closed, told from its topology rather than a mesh.