# Voxel geometry

The sampler behind the fabricator: continuous occupancy fields over the unit cube, turned into buildable cells in deposition order, with the buried ones dropped.

> For the complete index, see [llms.txt](https://robocn.dev/llms.txt). A Markdown version of any page is available by appending `.md` to its URL or by sending an `Accept: text/markdown` header.

## Install

```bash
bunx --bun shadcn@latest add https://robocn.dev/r/voxel-geometry.json
```

Registry item: `voxel-geometry` · [`https://robocn.dev/r/voxel-geometry.json`](https://robocn.dev/r/voxel-geometry.json)

## Notes

- Surface extraction, not every cell: an occupied cell is only returned when one of its six neighbours inside the laid prefix is empty. Interior cells are painted over anyway, and dropping them turns a cubic count into a quadratic one.
- The clamp on resolution belongs to the renderer, not the geometry. The field is continuous and the sampled volume converges on it as the grid gets finer, which is what the tests assert against the analytic volume of a sphere.
- Pure functions over plain objects. No React, no dependencies beyond clamp.

## Usage

```tsx
import { voxelSolid, voxelLaid, voxelBuild } from "@/lib/robocn/voxel"

const solid = voxelSolid({ shape: "gear", resolution: 8 })
const part = voxelBuild(solid, voxelLaid(solid, 0.4))
part.surface // the cells worth drawing, each flagged if its top is open
part.active  // the cell under the nozzle
```

## API

| name | type | default | description |
| --- | --- | --- | --- |
| `voxelOccupies` | `(shape, u, v, w) => boolean` | — | The field itself, over the unit cube with u, v, w in −1..1 and v up. Continuous, so it can be sampled at any resolution; anything outside the cube or not a number is empty. |
| `voxelSolid` | `({ shape?, resolution? }) => VoxelSolid` | — | Samples a shape into every occupied cell, ordered the way a head would lay them: layer by layer, serpentine across each so the head never flies home empty. |
| `voxelLaid` | `(solid, progress) => number` | — | How many cells a 0–1 build fraction has laid. Non-finite progress empties the plate. |
| `voxelBuild` | `(solid, laid) => VoxelBuild` | — | The visible state of a part-built solid: the laid cells with an open face, whether each has an open top, the layer being worked, and the cell under the nozzle. |
| `voxelResolution` | `(value?) => number` | — | Rounds and clamps a requested resolution into 2–14, the range the drawing budget allows. |
| `voxelCenter` | `(cell, resolution) => Vec3` | — | A cell's centre in normalised coordinates, −1 to 1 on each axis. |
| `VoxelShape` | `"sphere" | "block" | "pyramid" | "gear" | "vessel" | "lattice"` | — | Six fields chosen to stay legible at low resolutions and to stress the sampler differently: curvature, a chamfer, stepping, angular teeth with a bore, a hollow interior, and an open-cell frame. |

## Source

- `src/lib/robocn/voxel.ts`