nt3d

Getting started

Mon, 01 Jan 0001 00:00:00 +0000

Getting started#

Install#

nt3d is a Go module, nimbleterminal.dev/nt3d, and needs Go 1.26.8 or later:

go get nimbleterminal.dev/nt3d@latest

The packages#

You import only what you use. The core package reads no files; nt3dmesh reads the common formats, and the others register themselves when imported, so a program that reads no glTF carries no glTF.

Import	Package	What it is for
`nimbleterminal.dev/nt3d`	`nt3d`	Scenes, cameras, geometry, textures, picking, and rendering
`nimbleterminal.dev/nt3d/math`	`nt3dmath`	Float32 vectors, matrices, rays, and bounds
`nimbleterminal.dev/nt3d/widget`	`nt3dwidget`	The Bubble Tea widget, with Kitty graphics or colored glyphs
`nimbleterminal.dev/nt3d/mesh`	`nt3dmesh`	Reading and writing STL, OBJ, 3MF, and PLY
`nimbleterminal.dev/nt3d/mesh/gltf`	`nt3dgltf`	Reading glTF 2.0 (`.gltf` and `.glb`)
`nimbleterminal.dev/nt3d/mesh/formats`	`formats`	Imported for its side effects: every optional mesh format, and WebP textures

A first program#

This shows an orange ball in the terminal. Drag to orbit it, scroll to zoom, and press q to quit.

Scenes

Mon, 01 Jan 0001 00:00:00 +0000

Scenes#

A Scene is a tree of nodes. Each node has a name, a place in the tree, a transform relative to its parent, a visibility switch, and optionally some geometry to draw. Moving, hiding, or rotating a node does the same to everything under it.

scene := nt3d.NewScene()
group, err := scene.Add(nt3d.Root, "objects")
if err != nil { panic(err) }
node, err := scene.SetGeometry("marker", nt3d.Geometry{
 Points: []nt3d.Point{{
 Position: nt3dmath.Vec3{Z: .5},
 Radius: 5, Color: color.RGBA{R: 240, A: 255},
 }},
})
if err != nil { panic(err) }
if err := scene.Reparent(node, group); err != nil { panic(err) }
if err := scene.SetTransform(group, nt3dmath.RotationZ(.4)); err != nil { panic(err) }

Nodes#

Root is always there, and every other node descends from it.
Add(parent, name) makes an empty group. Names must be unique and not empty.
SetGeometry(name, g) creates a node with that geometry, or replaces the geometry of the node already called that. SetNodeGeometry(id, g) does the same by ID.
Reparent moves a node under a new parent, keeping its local transform. A node can’t become its own ancestor.
SetVisible hides or shows a node and everything under it.
Remove deletes a node and everything under it.
Node(id) returns a copy of a node’s details.

Node IDs are stable and never reused, so an ID you hold either still means the same node or means nothing.

Shapes and geometry

Mon, 01 Jan 0001 00:00:00 +0000

Shapes and geometry#

A Geometry is what a node draws: triangles (with colors, normals, and texture coordinates), points, boxes, lines, and arrows, plus a material. You can fill one in by hand, but usually you build one or read one from a file.

Building shapes#

BuildSphere, BuildCylinder, BuildTorus, and BuildCuboid each take a small spec struct and return a lit, UV-mapped mesh centered on the origin, with Z up. Leave the tessellation counts and color at zero for sensible defaults.

Materials and textures

Mon, 01 Jan 0001 00:00:00 +0000

Materials and textures#

A geometry’s Material says how its surface looks: its texture, whether light affects it, and whether it lets things show through. Without a material, a mesh is lit and colored by its vertex colors.

tex, err := nt3d.NewTexture(img) // any image.Image
mat := &nt3d.Material{Texture: tex, Repeat: true, Specular: .4}

Textures#

NewTexture takes a snapshot of any image.Image, up to 8192 pixels a side. Textures are sRGB, as images are, and both renderers filter them in linear light.

Repeat. With Material.Repeat, texture coordinates outside 0 to 1 wrap around, and filtering blends across the seams, so a texture made to tile shows none. Otherwise they clamp to the edge. The OBJ, PLY, and 3MF readers set it, since those formats tile by default.
Tint. Material.Tint multiplies the texture by the vertex colors.
Unlit. Material.Unlit shows colors as they are, ignoring the light.

Mipmaps#

A tiled floor running to the horizon packs many texels into each distant pixel, and without care it shimmers into moiré. nt3d keeps each texture with copies of itself halved down to one texel, averaged in linear light, and each pixel samples the copies that match how many texels it covers. Frame.Anisotropy (1 to 16; zero means 16) goes further: where a pixel covers a long, thin run of texels, as on a floor seen at a slant, it samples along the run, so the floor keeps its detail instead of blurring to gray. The GPU and software renderers do the same.

Normal maps

Mon, 01 Jan 0001 00:00:00 +0000

Normal maps add surface detail by changing the shading normal between vertices. GPU and software use them for diffuse light, specular highlights, and environment diffuse light. They leave silhouettes, bounds, picking, wireframe, and shadow-caster geometry unchanged. Shadow bias still uses the unperturbed surface normal.

Materials#

Decode a normal image with Go’s image packages, then create a linear-data texture:

normal, err := nt3d.NewNormalMap(img)
if err != nil {
 return err
}
mat := &nt3d.Material{
 NormalMap: normal,
 NormalStrength: 1,
 NormalRepeat: true,
 Specular: 0.4,
 Shininess: 48,
}

Assign the material to triangle geometry with one Geometry.UV per vertex. NormalStrength scales tangent-space X and Y. Set it to 1 for the authored strength; zero disables the normal perturbation. Negative strengths reverse the X/Y slopes. NormalRepeat controls wrapping independently of the base-color texture’s Repeat. Both slots use the same Geometry.UV coordinates.

Particles and sprites

Mon, 01 Jan 0001 00:00:00 +0000

Particles and sprites#

Try the particles demo with task particles: n cycles up to 100,000 particles, t switches between discs and animated atlas sprites, b changes blending, and a pauses. All three renderers use the same scene; wireframe shows dots.

Updating points#

Create a geometry with Points and PointStyle as usual. For subsequent frames, keep its count and style and call:

var bounds nt3dmath.AABB
bounds.Include(nt3dmath.Vec3{X: -3, Y: -3, Z: 0})
bounds.Include(nt3dmath.Vec3{X: 3, Y: 3, Z: 3})
err := scene.SetNodePoints(node, particles, bounds)
// Or replace only a range, starting at index 100:
err = scene.UpdateNodePoints(node, 100, particles[100:200], bounds)

These methods check and copy the supplied points, share all unrelated geometry, and use the supplied bounds without recomputing them. Existing frame snapshots remain immutable, so each update still allocates a point slice; this API does not expose mutable scene storage. Partial updates copy that slice too, but validate and upload only the changed range. If the GPU skipped updates or replays an older frame, it uploads the complete point buffer to restore the correct snapshot. Buffer allocations, other primitive uploads, and repeated point validation during rendering are avoided. Alpha sorting is refreshed when points move.

Clustering and LOD

Mon, 01 Jan 0001 00:00:00 +0000

Clustering and LOD#

Try the point cloud demo with task cloud: a galaxy of up to a million points, l switches clustering off to compare, n cycles the count, and - and = zoom. All three renderers draw the same selection.

A large set of similar, independently placed items (points, instances, labels) need not be drawn whole every frame. nimbleterminal.dev/nt3d/clod (nt3dclod) groups such a set into spatial clusters once and, each frame, selects the clusters inside the view and a level of detail for each: near clusters list all their items, far ones a spread fraction or none, leaving you to draw one representative. The output is a compact list of item indices that the existing point, instance, or label paths draw. The package knows nothing of what an item is beyond its position, and never draws.

Spatial index

Mon, 01 Jan 0001 00:00:00 +0000

Spatial index#

Try the AABB tree demo with task aabb: click a box to see its ancestors in the tree as nested wireframes, and set the boxes drifting to watch the tree update.

nimbleterminal.dev/nt3d/aabbtree (nt3daabbtree) is a dynamic AABB tree: a spatial index over a changing set of boxed objects that answers “which objects overlap this box?” and “which objects does this ray meet?” in logarithmic time. It is independent of scenes and renderers; you hand it bounds and a value of your own type, and it hands them back from queries. It is not a collision solver, and the static triangle hierarchy that picking uses stays as it is.

Fur

Mon, 01 Jan 0001 00:00:00 +0000

Fur#

nt3d grows fur on any mesh with shells: copies of the surface pushed out a little further each time, each a cutout showing the cross-section of every strand at that height. Stacked, they read as strands.

coat, err := nt3d.NewFur(nt3d.Fur{Length: .05, Shells: 16, Spacing: .011})
shells, err := coat.Shells(spot) // textured, so the fur takes Spot's colors
for k, g := range shells {
	id, _ := scene.SetGeometry(fmt.Sprintf("fur %d", k), g)
	scene.SetTransform(id, coat.Sway(k, wind)) // each frame, to animate
}

The coat#

FurCoat.Shells(base) returns an opaque skin plus one cutout layer per shell. Each strand has its own place, length, and taper.

Mesh files

Mon, 01 Jan 0001 00:00:00 +0000

Mesh files#

nt3dmesh reads and writes the common 3D file formats. Reading gives you a Model, a list of objects, which you can add to a scene as one node each:

model, err := nt3dmesh.ReadFile("part.obj", &nt3dmesh.Options{Color: grey})
group, err := model.AddTo(scene, nt3d.Root, "part") // one child node per object
fit, _, _ := model.Bounds().Normalization()
err = scene.SetTransform(group, fit) // scale it to fit the default camera

Formats#

Format	Read	Write
STL	binary and ASCII, with face colors	binary, with colors
OBJ	with materials, textures, and lines	triangles and lines
3MF	with colors, textures, painting, and parts	one object, with face colors
PLY	ASCII and binary, including raw scans	binary
glTF 2.0	`.gltf` and `.glb`	—
SOG	`.sog` bundles and `meta.json` folders	—

STL, OBJ, 3MF, and PLY are built in. glTF is in its own package, nt3d/mesh/gltf, SPZ Gaussian splats in nt3d/mesh/spz, and SOG Gaussian splats in nt3d/mesh/sog; each registers itself when imported, the way image formats do with image. To get every optional format, and WebP textures, import them all at once:

Animation and skinning

Mon, 01 Jan 0001 00:00:00 +0000

AnimationClip, Track, Skeleton, and Deformation are independent of file formats. Tracks target scene nodes; procedural code can supply the same data or update joint transforms and morph weights directly.

Playing and sampling#

clip := nt3d.AnimationClip{Name: "slide", Tracks: []nt3d.Track{{
 Node: node, Channel: nt3d.Translation, Width: 3,
 Times: []float32{0, 2},
 Values: []float32{0, 0, 0, 2, 0, 0},
}}}
player, err := nt3d.NewAnimation(scene, clip)
if err != nil { return err }
player.Mode = nt3d.PingPong // Once (clamped), Loop, or PingPong
if err := player.Step(elapsed.Seconds()); err != nil { return err }
player.Paused = true
if err := player.Sample(1.25); err != nil { return err } // works while paused

Time is in seconds. Speed defaults to one and may be negative. Time is the unwrapped playback clock; Sample folds it according to Mode. Once clamps at the endpoints. Translation and Scale use width three; Rotation uses normalized XYZW quaternions and width four. MorphWeights uses the target count. UserChannel invokes the player’s Apply(name, values) callback.

Environment and sky

Mon, 01 Jan 0001 00:00:00 +0000

An environment gives a scene a distant sky and diffuse image-based lighting. It is optional: scenes without one keep their solid background and existing lighting.

sky := nt3d.GradientEnvironment(
 color.RGBA{72, 130, 220, 255}, // zenith
 color.RGBA{218, 231, 245, 255}, // horizon
 color.RGBA{115, 100, 77, 255}, // ground
)
scene.SetEnvironment(sky)

The widget picks it up through the scene’s frames. Call view.Refresh() after changing it when the application is not already scheduling frames. Remove it with scene.SetEnvironment(nil). Environment objects are immutable and can be shared between scenes; frames retain the environment they were made with.

Labels and billboards

Mon, 01 Jan 0001 00:00:00 +0000

Labels and billboards#

Labels are scene geometry. They move with their parents and use the same textured triangles, clipping, depth, and picking as other meshes on WebGPU and software. Wireframe uses depth-tested terminal text.

id, err := scene.SetLabel("peak", nt3d.Label{
 Text: "Peak\nz = 0.60",
 Pixels: true, Height: 32,
 Color: color.RGBA{245, 248, 255, 255},
 Background: color.RGBA{24, 32, 48, 255},
 Padding: 2, Border: 1,
 BorderColor: color.RGBA{90, 160, 210, 255},
})
// Handle errors from each operation.
err = scene.Reparent(id, terrainNode)
err = scene.SetTransform(id, nt3dmath.Translation(nt3dmath.Vec3{Z: .8}))

Height is the whole label’s height. With Pixels, it stays the same size while zooming and supersampling; otherwise it is in world units. Zero height uses the texture’s native height in pixel mode, or one world unit. Labels are centered on the node origin. Camera-facing labels inherit parent translation; Fixed: true keeps the local XY plane and inherits parent rotation and scale. Fixed opaque labels are single-sided, following the mesh winding convention. Blended quads draw both sides, as other transparent meshes do. Scene bounds include only the anchor for pixel-sized labels, so camera fitting does not interpret pixels as world units.

Wave surfaces

Mon, 01 Jan 0001 00:00:00 +0000

Wave surfaces#

WaveSurface combines directional Gerstner waves on the XY plane, with Z up and mean height zero. It supplies positions, analytic normals, tangents, and material-point velocities. One evaluator can move a water mesh and answer surface queries for floating objects. The surface is immutable and safe to sample concurrently; its zero value is flat water.

surface, err := nt3d.NewWaveSurface([]nt3d.GerstnerWave{
 {Direction: nt3dmath.Vec3{X: 1, Y: .3}, Wavelength: 4.5, Amplitude: .2},
 {Direction: nt3dmath.Vec3{X: -.3, Y: 1}, Wavelength: 2.7, Amplitude: .09, Phase: 1.1},
}, 9.81)
if err != nil {
 return err
}

// Move a mesh vertex from its original, undisplaced XY coordinates.
sample, err := surface.Sample(restX, restY, seconds)
if err != nil {
 return err
}
vertex.Position = sample.Position
vertex.Normal = sample.Normal

// Find the water under an object at a world XY location.
water, err := surface.AtWorld(worldX, worldY, seconds)
if err != nil {
 return err
}
height := water.Position.Z

Directions are normalized on construction and must have zero Z. Wavelengths are positive, amplitudes nonnegative, and phases are radians. With gravity 9.81, lengths are meters and time is seconds. Other consistent units work too. Angular speed follows the deep-water relation sqrt(gravity * 2π / wavelength). The constructor rejects non-finite inputs and total steepness sum(2π * amplitude / wavelength) >= 1, so waves cannot fold over themselves.

Rendering

Mon, 01 Jan 0001 00:00:00 +0000

Rendering#

To draw a scene, take a Frame of it through a camera, then hand the frame to a renderer. The widget does all of this for you; this page is for when you want to know what it’s doing, or render without it.

camera := nt3d.DefaultCamera()
frame, err := scene.Frame(camera, 960, 640)
if err != nil { panic(err) }
gpu := nt3d.NewGPURenderer()
defer gpu.Close()
img, mode, err := nt3d.Snapshot(frame, nt3d.WebGPU, gpu)
// mode reports whether WebGPU drew it or software stood in.

Frames#

A frame is a snapshot: the geometry, world transforms, and visibility of the scene at the moment you took it. It never changes afterwards. To update the picture, change the scene and take a new frame; old frames stay valid, and can even be rendered again. This is what lets rendering run on another goroutine while you keep editing.

Picking

Mon, 01 Jan 0001 00:00:00 +0000

Picking#

Scene.Pick finds what lies under a point on the screen: the node, the kind and index of the primitive, your application’s datum ID, and the world position hit. In the widget, a click sends you a PickMsg with the same answer.

hit := scene.Pick(camera, frame, x, y, tolerance)
if hit != nil {
	fmt.Println(hit.Name, hit.Index, hit.Position)
}

Meshes are hit on their faces. Picking sees through a cutout’s holes to what’s behind them, and treats transparent surfaces as solid.
Hidden nodes, and nodes outside the view, are never hit.
Points, boxes, and lines are tested one by one.

Fast picking on big meshes#

Testing every triangle takes a few milliseconds even for a 1.5-million-triangle mesh, so a click is answered at once. The first pick of a mesh over 256 triangles also starts building an index (a bounding volume hierarchy) in the background, and after that picks, such as following the mouse for hover, take about a microsecond. The index lasts until the node’s geometry changes.

The widget

Mon, 01 Jan 0001 00:00:00 +0000

nt3dwidget puts a scene in a Bubble Tea program. It handles the camera and mouse, schedules renders so slow frames never pile up, falls back when the GPU can’t help, and shows the result as Kitty graphics or colored glyphs through ntpicture.

view := nt3dwidget.New(scene, 80, 24)
defer view.Close()

The widget draws only the 3D view. Headers, footers, and quitting belong to your program; Getting started shows a complete one.

Controls#

Input	Does
drag	orbit
shift-drag	pan
wheel, `+`, `-`	zoom
arrows, `h` `j` `k` `l`	orbit
`c`	fit the scene in view (`Fit()`)
`r`	turn automatic rotation on or off
`o`	switch between perspective and orthographic
`g`	switch between Kitty graphics and glyphs

A click sends your program a PickMsg saying what was hit; see Picking.

Demos

Mon, 01 Jan 0001 00:00:00 +0000

Demos#

The demos are complete programs in examples/demos, and the quickest way to see what nt3d does. Each runs in a terminal with task <name>, and in a browser from the gallery.

They all share the widget’s controls (drag to orbit, wheel to zoom, c to fit, r to rotate) and a few keys of their own: 1, 2, and 3 switch between GPU, software, and wireframe, and q quits. Each demo lists its other keys along the top of the screen.

Development

Mon, 01 Jan 0001 00:00:00 +0000

Development#

Setting up#

nt3d’s dependencies, ntcanvas, ntgpuimage, and ntpicture among them, all come through Go modules:

git clone https://github.com/NimbleTerminal/nt3d
cd nt3d
task ci

To change ntpicture alongside nt3d, clone it beside nt3d and run task workspace, which copies go.work.example to go.work (git ignores it) so the build uses your checkout instead of the published module.

The library is one module. The demos in examples/demos are a second module, so that go-booba and the Bubble Tea fork the browser needs never become requirements of the library.

nt3d

Getting started

Getting started#

Install#

The packages#

A first program#

Scenes

Scenes#

Nodes#

Shapes and geometry

Shapes and geometry#

Building shapes#

Materials and textures

Materials and textures#

Textures#

Mipmaps#

Normal maps

Materials#

Particles and sprites

Particles and sprites#

Updating points#

Clustering and LOD

Clustering and LOD#

Spatial index

Spatial index#

Fur

Fur#

The coat#

Mesh files

Mesh files#

Formats#

Animation and skinning

Playing and sampling#

Environment and sky

Labels and billboards

Labels and billboards#

Wave surfaces

Wave surfaces#

Rendering

Rendering#

Frames#

Picking

Picking#

Fast picking on big meshes#

The widget

The widget#

Controls#

Demos

Demos#

Development

Development#

Setting up#