Documentazione

Due porte sulla stessa stanza: una libreria JavaScript che gira nel browser, e una specifica OpenAPI che descrive le stesse operazioni in forma leggibile da una macchina.

1. La libreria (browser)

Il motore e un solo file: geometry.js. Espone window.AICAD (alias window.GEOMETRY). Nessuna dipendenza, nessun build.

Solidi

Funzione	Firma	Restituisce
`sphere`	(cx, cy, cz, r, colore)	solido
`planeY`	(h, colore)	piano orizzontale y = h
`box`	(cx, cy, cz, hx, hy, hz, colore)	parallelepipedo
`scene`	([solidi])	scena con `.trace(o, d)`

Ogni solido espone intersect(o, d) (restituisce t o null) e normal(p) (il gradiente).

Camera

Metodo	Cosa fa
`camera(opts)`	theta, phi, dist, fov, target, near, far
`basis()`	restituisce eye, fwd, right, up
`orbit(dt, dp)`	orbita; blocco ai poli
`zoom(f)`	distanza x f (fov fisso = rapporto mantenuto)
`pan(dx, dy)`	sposta il bersaglio
`ray(sx, sy, aspect)`	raggio normalizzato per un pixel

2. L'API HTTP (specifica)

La specifica openapi.yaml descrive gli stessi servizi come endpoint. Un client puo implementarli con la libreria locale, oppure puntarli a un server che espone geometry.js. Ecco gli endpoint.

Metodo	Percorso	Cosa fa
GET	`/solidi`	tipi di solido disponibili
POST	`/solido`	definisce un solido da un descrittore JSON
POST	`/interseca`	dato un raggio, restituisce t, punto e normale
POST	`/superficie`	segno di f e normale in un punto (pieno/vuoto/superficie)
POST	`/camera`	definisce o modifica la camera
POST	`/render`	renderizza una scena, restituisce un PNG

Esempio: interseca

Richiesta: un raggio che parte da (0, 1.6, 8) e va verso -z, contro una sfera di raggio 1.6 centrata in (0, 1.6, 0).

POST /interseca
{
  "solido": { "tipo": "sfera", "centro": [0,1.6,0], "raggio": 1.6 },
  "origine": [0, 1.6, 8],
  "direzione": [0, 0, -1]
}

200 OK
{
  "colpito": true,
  "t": 6.4,
  "punto": [0, 1.6, 1.6],
  "normale": [0, 0, 1]
}

Il valore t = 6.4 non e approssimato: e la soluzione dell'equazione di secondo grado risolta in forma chiusa. Il raggio non cerca, la funzione dichiara.

Esempio: superficie

POST /superficie
{ "solido": {"tipo":"sfera","centro":[0,1.6,0],"raggio":1.6},
  "punto": [0, 3.2, 0] }

200 OK
{ "f": 0, "dentro": false, "sullaSuperficie": true,
  "normale": [0, 1, 0] }

Il punto (0, 3.2, 0) e esattamente la cima della sfera: f = 0, cioe sulla superficie.

3. Il principio

Il solido e una funzione f(x,y,z). Non una mesh, non un insieme di punti.
Il segno decide: f < 0 pieno, f > 0 vuoto, f = 0 superficie.
La superficie non si estrae: e il livello zero di f, si legge.
La normale non si stima: e il gradiente, in forma chiusa.
Il raggio non cerca: la funzione dichiara dove viene colpita.