# Metaballs ## What this builds A playground of metaballs: implicit surfaces from a sum of radial fields, shaded in real time. The person can drag balls, change the threshold, and switch the falloff. Tests sample the field at known points and compare a render of a fixture set to a golden. The look is original. Read `spekkr.inputs.json` first. `title` is in a corner. `threshold` is the iso-value. `field` is the falloff. `normals` and `grid` change the picture. ## Out of scope - A general SDF modeller (that is a later, different spec). - Network or a gallery in the checks. - A physically based material library in this version. ## Requirements Each requirement has an id. Checks name the id they cover. ### R1. The field - For `inverse-square`, a ball of radius r at the origin contributes ` (r*r) / (x*x+y*y+z*z + 1e-8) ` at a point, and the field is the sum. - For `gaussian`, the contribution is `exp(-|x|² / (2 r²))`. - Samples in `fixtures/metaball-samples.json` match within 1e-5, at threshold unused (these are raw field values). Accept when: every listed sample matches for both falloffs. ### R2. The surface and a fixture set - The surface is the iso-value `threshold`. A ray or a mesh extract may be used, but a field sample just inside and just outside a documented point on the surface must be above and below the threshold. - `fixtures/metaball-set.json` is a set of five balls. Its render, at threshold 1.0, inverse-square, lit, matches the `fixture-set` golden. - Two balls of radius 1, centres 1.2 apart, merge at threshold 1.0; centres 3.0 apart do not. The inside/outside samples in the file confirm this. Accept when: the inside/outside samples pass, and the fixture-set render matches the golden. ### R3. Frames and files - Goldens: two balls apart, two balls merged, the five-ball fixture, and a flat-colour (normals off) view of the fixture. - One command runs the samples, the merge checks, and writes the frames. No network. Accept when: the command passes for both falloffs (each has a sibling golden for the fixture, or a documented skip of the image check if only samples are required for gaussian). ### R4. Inputs - The build reads `spekkr.inputs.json`. Settings label the UI, options turn features on or off, and a swap must be one of its choices. - A value outside a stated range, or a swap that is not one of its choices, is refused before the app starts its checks, with a message that names the key. Accept when: the default inputs render, an illegal swap is refused by name, and changing a visible setting (for example the title) shows up in a later check. ## Verification Field samples at known points match a file within 1e-5 for both falloffs. A fixture set of balls renders to a golden. A documented merge and a documented apart case are confirmed by inside/outside samples. No network. ## Definition of done - Every acceptance check above runs from one command, and all pass at the person's inputs. - A README says how to drag a ball, how to change the falloff, and how to run the checks.