dymokomi/luce-3d
Source of release 0.9.4
# API
The package exports `three`. It has no UI dependency: an application's view hands
the renderer a render target (luced-3d's `SceneView` is a `luce-ui` example).
Public objects use `init` and methods in Base, and existing `Type(args)`
construction in Luce. Mutating or allocating operations can fail; Luce callers
handle or propagate those errors.
Polygon meshes, their builders and modeling kernels live in
[luce-geocore](https://github.com/dymokomi/luce-geocore) (export `geocore`); `three`
re-exports its `Vector3`, `Matrix4`, `Vertex`, `Bounds` and `Geometry`. A
scene draws a geocore `Mesh` through `Mesh.of`, from GPU arrays (a geocore
mesh is not a per-vertex `Geometry`; `MeshGeometry` wraps it for that path).
| Type | Responsibility and principal methods |
| --- | --- |
| `Vector3(x=0,y=0,z=0)` | Immutable operations `add`, `subtract`, `multiply_scalar`, `dot`, `cross`, `length`, `normalized`, `rotated`; public coordinates are values. |
| `Matrix4` | Affine column vectors and translation, implicit final row `(0,0,0,1)`; `compose`, `multiply`, `transform_point`, `transform_direction`, `transform_normal`. |
| `Vertex(position,normal,u=0,v=0,color=Vector3(1,1,1))` | Position, nonzero normal, UV coordinates and multiplicative RGB tint. |
| `Bounds(minimum,maximum)` | Axis-aligned local-space bounds. |
| `Geometry` | Open interface: `vertex_count`, `index_count`, `vertex`, `index`, `bounds`. |
| `BufferGeometry(vertices,indices)` | Copies and validates indexed triangle data; subsequent caller mutations do not change it. |
| `SphereGeometry(radius=1,width_segments=32,height_segments=16)` | Shared immutable UV sphere; duplicates the seam, omits degenerate polar triangles. |
| `BoxGeometry(width=1,height=1,depth=1)` | Origin-centred box: 24 hard-normal, face-local UV vertices and 12 outward-wound triangles. Dimensions must be finite and in `(0,1e6]`. |
| `Material` | Open interface: linear RGB `color()` and `is_lit()`. |
| `MeshBasicMaterial(color=white)` | Unlit linear color, mutable with `set_color`. |
| `MeshLambertMaterial(color=white)` | Ambient plus directional Lambert lighting, mutable with `set_color`. |
| `Object3D` | Open interface: stable `node`, optional retained `geometry`/`material`, and `light`. |
| `ObjectNode` | Transform, visibility and child membership shared through composition; `position`, `rotation`, `scale`, corresponding setters, `matrix`, `set_visible`, `add`, `remove`, `clear`, `child_count`. |
| `Scene`, `Group` | Own a node and child objects; expose `node`, transform methods, `add`, `remove`, `clear`. |
| `Mesh(geometry,material)` | Owns shared geometry/material interfaces and its own node. |
| `Mesh.of(mesh,material)` | A scene object for a geocore `Mesh`, drawn from GPU arrays retained by the mesh's change ids (per-vertex fallback on deviceless frames). |
| `MeshGeometry(mesh)` | The per-vertex `Geometry` of a geocore `Mesh`: its corners as vertices. `Mesh.of` uses it without a device. |
| `AmbientLight(color=white,intensity=1)` | Scene light; `set_intensity` updates its contribution. |
| `DirectionalLight(color=white,intensity=1,direction=(1,1,1))` | Direction points toward the light and is transformed with its scene node. |
| `PerspectiveCamera(fov=50,aspect=1,near=0.1,far=1000)` | World-space camera initially at `(0,0,5)` looking at the origin; `set_position`, `look_at`, `set_aspect`, `set_projection`. FOV is vertical degrees. |
| `Renderer(static_scene=false)` | `static_scene` keeps prepared objects between frames (scene changes still invalidate them; `invalidate()` after custom geometry or material edits). `render(scene,camera,target,fit_aspect=false)` appends checked triangles to a standard GPU target. `set_wire_overlay(width=0)` reserves slope-aware depth for a coplanar logical-pixel wire overlay; zero restores ordinary depth. It changes draw state, not cached geometry. `set_shading(mode,stripes=20,duty=0.5,axis=(0,1,0),planar=false,stripes_only=false)` shades polygon meshes: 0 lit, 1 flat, 2 zebra, 3 isophotes, 4 normals, 5 unlit, 6 curvature (`set_curvature(kind,range=0)`: 0 mean, 1 Gaussian, 2 k1, 3 k2, 4 largest |k|; range 0 is the 98th percentile). `set_edges(width,color,surfaces=true)` draws their edges from the same arrays (`surfaces=false`: wires only). `set_face_selection(mesh,faces,color,weight)`, `set_selected_faces(mesh,selection,color,weight)` (a geocore face `Selection`, keyed by its bits) and `clear_face_selection()` tint selected faces in the surface pass from one bit per face (it follows the mesh's Moves). A mesh with subdivision settings draws its limit surface (`subdivided_display`) with the cage's wires over it, the tint mapped onto the display faces. `set_flat(on)` switches to face normals. `pick_face(mesh,camera,x,y,width,height)` returns the face under a view point from a GPU id pass, reused until the mesh or view changes (fails `unavailable` before a device frame). `uploads()` and `uploaded_bytes()` count GPU array uploads; a local Move patches only its neighbourhood of the previous buffers. None of the draw state re-uploads geometry. |
| `EditOverlay` | Edit-mode overlays for one mesh, kept in Base (mode 0 points, 1 edges, 2 faces, 3 corners): `show(mesh,mode,selection,hovered)` from a geocore `Selection` (or `update` with ids), `draw(camera,target,wire,accent,point,wires=true,hidden=none)` (`hidden`: the selection through surfaces first, dimmed), `pick(camera,x,y,width,height,face=-2)` (points and edges on a known face, else a ray; the nearest point on screen for a point cloud), `center(mesh,mode,ids)`, `set_fill(false)` to leave face fills to the renderer's tint, and `set_soft(radius,falloff=3,symmetry=0)`: points a soft selection reaches are drawn in a falloff ramp by their weight (computed in Base with geocore's `selection_weights`), in every mode. |
| `Knife`, `KnifePlane` | A knife stroke on screen: `Knife.plane(camera,x0,y0,x1,y1,width,height)` is the plane through the eye holding the stroke (a point and a unit normal, for Clip's custom plane), `faces_under(mesh,camera,...)` the faces the line passes over, `snapped(x0,y0,x1,y1)` the end at the nearest 15 degrees. |
| `WireRenderer` | `lines(points,camera,target,color,width=1,bias=0.000001,depth=true)` draws independent world endpoint pairs at constant logical-pixel width; near clipped and depth tested (`depth=false`: over everything). `triangles(points,camera,target,color)` draws depth-tested selection fills. Uses the existing target depth buffer; current GPU API also writes depth. |
| `WireBatch` | Retained endpoint pairs drawn at constant pixel width (`draw(camera,target,color,width)`); `count()` segments and `bounds()` for framing. |
| `FogVolume`, `FogLook`, `FogScene` | A fog drawing of a luce-geocore set, ray-marched on the GPU as smoke (see below): `FogVolume.of(geometry,index,matrix=identity,light=(3,5,2))` the `index`th fog drawing of the set's own volume (luce-geocore's `fog_show`: its fog grids but those lending their values as fields), placed by `matrix`, its self-shadowing swept toward `light`, drawn with its grid's look; `FogVolume.count(geometry)` how many there are; `FogVolume.key(geometry,index,matrix,light)` what its texels are made from (grid contents, emission and emission color fields, placement, light), equal for a changed look; `FogVolume.look_of(geometry,index)` a drawing's look and `restyle(geometry,index)` takes it; `set_look(look)` sets `FogLook` (`density` scale, smoke `color`, `shadow` scale, `emission` scale and `emission_color`, `step` in voxels 0.25..8), uploading no texels; `bounds()` (the world box, for framing), `peak()`, `texels(axis)`, `upload_count()` (one, on the first draw) and `strip_upload_count()` for tests. A `FogScene` draws them: `draw(volumes,camera,target,key=(0.85,0.85,0.85),ambient=0.35)` marches every volume over what the target holds, ending at its depth; `table_count()`, `pass_count()` (the last draw's passes) and `stack_count()` (stacked atlases kept for groups) for tests. Base callers: `fog_volume_of(set,index,matrix,light)` makes a heap volume (on a worker; adopt it with `fog_volume_type`), `fog_volume_key`, `fog_look`, `fog_look_of`, `restyle_fog`, `fog_grid_count(set)`, and `release_fog_pipelines()` frees the shared shaders. |
| `GaussianSplats`, `SplatLook`, `SplatMode`, `SplatTimes` | A luce-geocore point cloud drawn as Gaussian splats, or as dots when it has no `orient`, `scale` and `opacity` (see below): `GaussianSplats.of(geometry,matrix=identity)` packs the set's cloud placed by `matrix`; `GaussianSplats.count(geometry)` its points (0 without a cloud); `GaussianSplats.key(geometry,matrix)` what it packs from (column ids, color space, placement). `draw(camera,target)` draws it alone over what the target holds, depth tested; `set_look(look)` sets `SplatLook` (`mode` splats or centers, `sh_degree` 0..3, `alpha_cull`, `scale`, `max_size` in pixels, `dot_size` in points, `lod_pixels` and `lod_from` for level of detail), uploading nothing; `set_marks(selection)` tints the points a luce-geocore `Selection` of the cloud's points selects (none clears); `occlude(occluders)` adds its splats as placed to a luce-geocore `SplatOccluders`, behind which Edit GSplats' Visible only hides an edited cloud's splats (columns shared, nothing copied); `bounds()`, `size()`, `is_splats()`, `has_lod()`, `sh_items()`, `upload_count()` (one, on the first draw), `sort_count()` (views sorted alone) and `timings()` (the last such view's GPU milliseconds per step) for tests and reports. Base callers: `gaussian_splats_of(set,matrix)` packs a heap one (on a worker; adopt it with `gaussian_splats_type`), `splat_key`, `splat_count`, and `release_splat_pipelines()` frees the shared shader. `RadixSort` and `radix_arguments` are the GPU sort it orders depths with. |
| `SplatScene` | Several clouds drawn as one: `draw(clouds,camera,target)` sorts every cloud given in one combined pass, so splats of clouds that interleave (overlapping captures, instances) blend in depth order across clouds; `set_look(look)` applies to all of them; `sort_count()` and `timings()` as above. A viewport keeps one. |
| `CurveLines` | The curves of a luce-geocore `GeometrySet` as wire batches: `batch(geometry)` draws every evaluated curve (instances placed), `batch(geometry, true)` the control hulls (control polygons of smooth curves, Bezier handle arms, a cross per control point); `count(geometry)` segments. Base code appends the same endpoint pairs with `append_curve_segments(set, matrix, lines, hulls)`, extracted in parallel from the evaluated-curve cache. |
| `SurfaceHits` | Where a view ray meets the scene: `cast(root,origin,direction)` returns the nearest face of any visible polygon object under `root` (each placed by its parents, hit through its BVH) as a `SurfaceHit` (`found`, world `point`, unit `normal`, `distance`); `plane(origin,direction,point,normal)` meets a construction plane. |
Rotations are intrinsic XYZ radians, applied as Z, Y, X to column vectors. A world
matrix is `parent * local`; normals use the inverse transpose, including
nonuniform scale. Negative scale is permitted, zero or near-zero scale is rejected.
The initial GPU pipeline draws both triangle faces.
Node transform components are finite and bounded to magnitude 1e6; scale
magnitudes must be at least 1e-6. BufferGeometry retains its separate small-buffer
limits; the renderer supports luce-geocore's larger mesh budgets.
Sphere segments are 3–256 by 2–128, with radius in `(0,1e6]`. The renderer
accepts up to 1024 objects and 64 levels per frame. Standard GPU command and vertex
budgets apply to the whole frame as well. Invalid custom interface results fail
before indexing or copying their data. Device frames retain GPU batches (split
below 128 MiB); standalone CPU recordings still use the dynamic frame budget.
Camera aspect is positive and bounded to `[1e-6,1e6]`; `0 < near < far <= 1e9`,
`0 < fov < 179`. Camera position and target must be finite and distinct. The initial
camera is independent of scene parenting. `SceneView` fits projection to its
allocated viewport without mutating the shared camera's configured aspect.
Base consumers use explicit `interop.Reference`, `interop.Interface` and
`interop.Outcome` carriers. Descriptor constants such as `mesh_type`,
`sphere_geometry_type` and `renderer_type` are available from `three`. Reference/interface return values
transfer one retained edge. Outcome values own their results or error messages;
release the carrier after use. The Luce compiler supplies the matching ARC and
error conversion automatically. See `tests/geometry/main.lucb` and `tests/pixels/readback.lucb` for
compiled direct Base consumers, and `tests/custom/main.luc` for application-defined
geometry and materials.
## Fog volumes
A fog grid has no surface, so it is drawn by ray marching (Houdini's viewport
smoke), split between the CPU, once per grid, and the GPU, per frame:
- **Texels** (`renderers/fog_texels.lucb`). The grid's leaves span a box of
voxels; the box, padded by a texel of background, becomes a dense texel box
whose z slices sit side by side in one `rgba16_float` atlas texture (red the
density, green the optical depth toward the key light, blue toward the sky,
alpha the look's emission field, sampled from that grid at texel centers,
never below zero; with an emission color field, a second block of tiles
below holds that field in red, negative values kept for the ramp's range).
luce-gpu has no 3D textures, and a 2D atlas of slices filters bilinearly in
hardware on every backend: the shader adds the linear step between two
slices. Leaves wider than 256³ texels (or an atlas past 16384 texels a side)
are averaged down by a whole factor. The optical depths, ∫ density along the
world length toward the light, are swept plane by plane on the CPU (in
parallel per plane), so lighting costs two reads per step and a new density
scale needs no new sweep.
- **The march** (`renderers/fog_scene.lucb`, `shaders/fog.frag`). A
`FogScene` draws every fog drawing of a view. Each pass covers the convex
outline of its boxes on screen and marches each pixel's eye ray, front to
back, from its box entry to its exit or the scene's depth, whichever is
nearer: the pipeline reads the frame's depth (luce-gpu's `scene_depth`), so
the march ends exactly at a mesh inside the fog, its last step cut to a
fraction, and a mesh cuts the fog smoothly at every depth. Steps are the
look's step in voxels along the view axis; the first after each box entry
is a fraction of a step from a 64×64 tile of blue noise
(`renderers/fog_noise.lucb`, void and cluster), so step boundaries never
line up from pixel to pixel; two steps a turn send their texture reads
together. Each step: Beer–Lambert absorption, single scattering of the key
light (`exp(-depth_light × density × shadow)`) and of the sky, and emission
(`max(field, 0) × emission` per world unit, colored by the strip at the
emission color field's value, else the emission field's). It emits
premultiplied color over the scene.
- **Overlap** (`renderers/fog_groups.lucb`). Drawings whose boxes overlap
past their padding, directly or through others, march in one pass, up to
four (the shader's GROUP variant). A pass binds one atlas image, so a
group's atlases are stacked into one texture on the GPU when the group
first draws, and kept while it stays the same. Each step sums every drawing
holding its sample: extinction, scattered light in proportion, emission,
and the optical depths toward the key light and the sky. A drawing's depth
at a point runs through its own grid toward the light, so every grid
covering a sample shadows it, and two crossing smokes mix and shadow each
other the same from either side. A grid that does not cover the sample
still casts no shadow on it. More than four overlapping drawings (or a
stack past 16384 texels) fall back to passes of up to four consecutive
drawings by distance, farther first: where those passes overlap, the nearer
veils the farther whole. Other drawings take passes of their own, farther
first.
The look is the grid's (luce-geocore's `VolumeLook`, which Volume
Visualization sets per grid). A `FogScene` keeps a table texture
(`rgba32_float`, 256 wide): the noise tile, then per drawing its numbers
(world-to-box rows, counts, step, smoke, scales, the strip's fit) and its
emission strip (`renderers/fog_ramp.lucb`). A new look sends only the table.
Each volume's atlas uploads on its first draw and the CPU copy is freed; later
draws (camera moves, a new look) upload no texels. The shaders and pipelines
are shared by every scene. `tests/fog_pixels` checks a fog ball's pixels, a
quad leaning through the fog (no bands), two and three crossing smokes from in
front and behind, two overlapping grids shadowing each other, five falling
back to two passes, the emission color field, and reports a 128³ ball's GPU
time at 2800×1800 (about 5.2 ms on an M4 Max) and that of one, two and three
overlapping balls.
## Gaussian splats
A point cloud with luce-geocore's splat conventions (`orient`, `scale`,
`opacity`, linear `Cd`, the `sh` array, optional `restorient`; see its
`splats` module) is drawn as 3D Gaussian Splatting draws it (Kerbl et al.
2023), with a global depth sort and hardware-blended quads:
- **Pack** (`renderers/splat_data.lucb`), once per cloud on the CPU, in
parallel: per splat its placed center (f32, relative to the cloud's placed
origin) and opacity, its placed covariance L Σ Lᵀ (f32 × 6), its DC color in
the cloud's encoding (`encode(Cd)`, f16), its SH frame
`orient · restorient⁻¹` (f16, only with a `restorient`) and its SH items
(f16). About 140 bytes per degree-3 splat. Uploaded on the first draw; the
CPU copy is freed.
- **Level of detail** (`renderers/splat_lod.lucb`), packed with clouds of 2^20
splats or more: the splats go in Morton order of their centers (16 bits over
the box's longest side, so a flat capture's thin axis takes few bits), and
one merged splat per run of 4, 16, 64 and 256 consecutive splats is appended.
A merged splat matches its members' moments (weights opacity × (det Σ)^⅓;
mean center; covariance the weighted Σᵢ plus the centers' spread; linear
mean color) and keeps their summed opacity, so its drawn opacity is the
members' coverage widened by the 0.3 px² low-pass, as they would draw. About
16 bytes more per splat.
- **Project** (`shaders/splat_project.comp`), each new view, once per cloud:
with level of detail on, the coarsest merged splat of a splat's runs whose
footprint (3σ) is under `lod_pixels` stands in for its run (it takes the
run's first slot; the others stay empty); then the EWA 2D covariance (x/z
and y/z clamped to 1.3 tan(fov/2), a 0.3 px² low-pass), its eigenvectors,
the quad's half axes k·√λ where the Gaussian falls to the alpha cull (k at
most 3, the longest capped by `max_size`), frustum and opacity culling, and
the color: the SH bands toward the eye, turned into the splat's SH frame,
added to the DC color, clamped at 0 and decoded from sRGB, which is
luce-geocore's `display_color`; a marked (selected) splat is tinted toward
the highlight. A capture trained antialiased (Mip-Splatting's 2D filter;
detail `gsplat_antialiased`, which luce-spz reads from an SPZ) has its
opacity scaled by √(det Σ′ / det(Σ′ + 0.3 I)), so the low-pass keeps a
small splat's integral instead of fattening it. Each visible splat writes a 48-byte quad record (clip center,
clip half axes, linear color and opacity; an opacity of 2 marks a dot) at its
slot, and a 24-bit depth key (the view depth's float bits, reversed: far
first). Every cloud of a view takes a run of slots in one combined index
space (`renderers/splat_view.lucb`), padded to whole workgroups.
- **Gather** (`splat_offsets.comp`, `splat_compact.comp`), once over all
slots: a workgroup's visible count, one scan of those counts, and a stable
rank inside each workgroup put the visible keys and slots in slot order, so
equal keys never trade places between frames. The same kernel writes the
draw's indirect arguments and the sort's workgroup count.
- **Sort** (`renderers/radix_sort.lucb`, `radix_*.comp`), once over all
clouds: an LSD radix sort, 4 bits a pass (six passes for 24-bit keys), each
pass a count per tile of 2048 keys, one scan, and a stable scatter that
sorts each tile in shared memory first, so every digit's run is written out
whole (coalesced writes made the sort 2× faster on an NVIDIA GPU and 6× on a
Radeon 890M). Reduce-then-scan needs no forward progress between
workgroups, which Metal does not promise.
- **Draw**: luce-gpu's `shade_quads`, the records through the sorted slots,
the count from the GPU. `shaders/splat.frag` gives
α = min(0.99, o·exp(-½ k² ρ²)), drops α under the cull, and writes
premultiplied color with `Blend.over`, back to front. The pipeline is depth
tested without writing depth: meshes in front hide splats, splats veil
meshes behind them.
The compute pass runs only when the clouds, their placements and marks, the
view or the look changed; at rest a frame is the draw alone. A `SplatScene`
sorts all its clouds together, so interleaved clouds composite exactly; a
cloud drawn alone (`GaussianSplats.draw`) sorts by itself. Level of detail
engages when the clouds drawn together number at least `lod_from` (10M by
default) at `lod_pixels` (2 by default). Centers mode, and every cloud without
the splat attributes, draws round opaque dots of the DC color (`Cd` for plain
clouds) through the same pass. `tests/splat_pixels` checks pixels against
these formulas and reports times per step (docs/VALIDATION.md).