Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-3d

Source of release 0.9.5

0.9.5 / docs / API.md

# 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. |
| `Camera(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(target,up=(0,1,0))` (the view's up as near `up` as it can be), `set_aspect`, `set_projection`, `fov()`. FOV is vertical degrees. `set_orthographic(half_height)` sees orthographically, `half_height` world units above and below the view's center (0: perspective again; `orthographic()` reads it). Every renderer, picker and overlay below follows it. `projection(aspect)` gives the view as a `Projection`: its axes and lens, and `screen(point,width,height)` (pixels and depth), `ray_origin`/`ray_direction(x,y,width,height)` (a view ray: from the eye in perspective, from the film along the view in orthographic), `eye_for(point)`, `pixel(depth,height)` (the world length of a pixel), `clip(point,bias=0)` and `depth(point)`. |
| `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,band_low=0,band_high=0)`: 0 mean, 1 Gaussian, 2 k1, 3 k2, 4 largest |k|; range 0 is the 98th percentile; smallest radii under `band_low` draw magenta, over `band_high` grey, 0 off), 7 draft against `axis` as the pull direction (`set_draft(angle)` the degrees asked for: green past it, yellow within it, red past it facing away). `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). `select_box(mesh,camera,current,x0,y0,x1,y1,width,height,operation,visible_only=true)` changes a geocore point, edge or face `Selection` by what a screen box touches (operation 0 replace, 1 add, 2 remove); visible only reads the same id pass, and view rays 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. |
| `BoxSelect` | A marquee in Base: `BoxSelect.select(mesh,camera,current,x0,y0,x1,y1,width,height,operation,visible_only=true)` takes the points inside the box and the edges and faces it touches (visible only by view rays; `Renderer.select_box` uses the GPU id pass), `touches(mesh,camera,x0,y0,x1,y1,width,height)` whether any face (or, without faces, any point) of a world-space mesh meets it, through the depth. |
| `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. |
| `GroundGrid` | `GroundGrid.draw(camera,target,height,step,minor,major,axis,fade,width=1,facing=1)`: Blender's overlay grid on the plane facing world axis `facing` (0 X, 1 Y, 2 Z) at `height` along it, lines every `step` and every fifth level of it, finer levels fading in as the camera nears; faded out `fade` from the eye, across the whole film in orthographic. |
| `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`, `0 <= half_height < 1e12`. 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).