# API di scripting Lua di pxstud.io — Colore

> Parte del riferimento di scripting Lua di pxstud.io, la cui panoramica (https://pxstud.io/it/docs/scripting.md) ne spiega le convenzioni. I gruppi di opzioni e i tipi a cui rimanda sono in https://pxstud.io/it/docs/scripting/option-groups.md e https://pxstud.io/it/docs/scripting/types.md. Tutto in un unico file (in inglese): https://pxstud.io/llms-full.txt. L'indice dell'intero sito (in inglese): https://pxstud.io/llms.txt.

### Colore
Calcoli sui colori senza dover analizzare a mano l'esadecimale né mescolare l'RGB. I colori in ingresso sono stringhe "#rrggbb" / "#rrggbbaa" o tabelle { r, g, b, a } (0-255, a facoltativo); i colori in uscita sono tabelle { r, g, b, a }, a meno che il nome non indichi hex. Miscelazione e regolazione usano OKLab come predefinito, uno spazio percettivo in cui passi uguali appaiono uguali; `space` può essere "oklab", "oklch", "rgb" o "hsl". I risultati vengono limitati a sRGB riducendo la chroma, così tonalità e luminosità restano invariate. Le liste (ramp, shades) si costruiscono con una sola chiamata.

#### `app.color.adjust(c, opts?)` — pura
Cambia luminosità, chroma, tonalità, saturazione o alfa di un colore, in modo assoluto o relativo. Il risultato è limitato alla gamma sRGB riducendo la chroma (luminosità e tonalità restano), non troncando i canali.

- `c` (color) — Un colore: "#rrggbb", "#rrggbbaa" o { r, g, b, a }.
- `opts` (table, facoltativo) — Le chiavi assolute impostano un valore; quelle con prefisso d lo incrementano (prima si applica il valore impostato, poi il delta). Le chiavi omesse mantengono il valore del colore.
  - `lightness` (number) — Imposta la luminosità: la L di OKLab/OKLCH (0 nero - 1 bianco), oppure la luminosità HSL con space = "hsl".
  - `chroma` (number ≥ 0) — Imposta la chroma OKLCH (intensità del colore, 0 = grigio; sRGB arriva al massimo intorno a 0.32). Non disponibile con space = "hsl".
  - `hue` (number) — Imposta l'angolo della tonalità in gradi (si riavvolge a 360).
  - `saturation` (number 0–1) — Imposta la saturazione 0-1: saturazione HSL con space = "hsl"; altrimenti la chroma come frazione della massima chroma consentita da sRGB a quella luminosità e tonalità.
  - `alpha` (number 0–255) — Imposta l'alfa, 0-255.
  - `dLightness` (number) — Somma alla luminosità (un valore negativo scurisce).
  - `dChroma` (number) — Somma alla chroma.
  - `dHue` (number) — Ruota la tonalità di questi gradi.
  - `dSaturation` (number) — Somma alla saturazione (scala 0-1).
  - `dAlpha` (number) — Somma all'alfa (scala 0-255).
  - `space` (string; predefinito "oklab") — "oklab" | "oklch" (qui sono equivalenti) | "hsl". "rgb" non ha un asse di luminosità o tonalità e viene rifiutato.

Restituisce (table): { r, g, b, a }, ciascuno 0-255.

#### `app.color.contrast(a, b)` — pura
Rapporto di contrasto WCAG tra due colori (alfa ignorato), da 1 (identici) a 21 (nero su bianco). 4.5 è il minimo abituale per un testo leggibile.

- `a` (color) — Un colore: "#rrggbb", "#rrggbbaa" o { r, g, b, a }.
- `b` (color) — Un colore: "#rrggbb", "#rrggbbaa" o { r, g, b, a }.

Restituisce (number): Il rapporto, 1-21.

#### `app.color.darken(c, amount, space?)` — pura
Scorciatoia per app.color.adjust(c, { dLightness = -amount }).

- `c` (color) — Un colore: "#rrggbb", "#rrggbbaa" o { r, g, b, a }.
- `amount` (number) — Sottratto dalla luminosità (unità della L di OKLab, 0-1).
- `space` (string, facoltativo) — Lo spazio in cui si misura la luminosità: "oklab" (predefinito), "oklch" o "hsl".

Restituisce (table): { r, g, b, a }, ciascuno 0-255.

#### `app.color.distance(a, b)` — pura
Distanza euclidea tra due colori in OKLab (alfa ignorato). 0 = identici; da nero a bianco è 1; circa 0.02 è appena percettibile.

- `a` (color) — Un colore: "#rrggbb", "#rrggbbaa" o { r, g, b, a }.
- `b` (color) — Un colore: "#rrggbb", "#rrggbbaa" o { r, g, b, a }.

Restituisce (number): La distanza, 0 o più.

#### `app.color.hex(c, withAlpha?)` — pura
Un colore come stringa esadecimale in minuscolo.

- `c` (color) — Un colore: "#rrggbb", "#rrggbbaa" o { r, g, b, a }.
- `withAlpha` (boolean, facoltativo) — true per "#rrggbbaa"; predefinito "#rrggbb".

Restituisce (string): "#rrggbb", oppure "#rrggbbaa" con withAlpha.

#### `app.color.lighten(c, amount, space?)` — pura
Scorciatoia per app.color.adjust(c, { dLightness = amount }).

- `c` (color) — Un colore: "#rrggbb", "#rrggbbaa" o { r, g, b, a }.
- `amount` (number) — Sommato alla luminosità (unità della L di OKLab, 0-1).
- `space` (string, facoltativo) — Lo spazio in cui si misura la luminosità: "oklab" (predefinito), "oklch" o "hsl".

Restituisce (table): { r, g, b, a }, ciascuno 0-255.

#### `app.color.mix(a, b, t, space?)` — pura
Fonde due colori (anche l'alfa) in uno spazio percettivo; per impostazione predefinita OKLab, che evita i punti medi sporchi della miscela in RGB.

- `a` (color) — Un colore: "#rrggbb", "#rrggbbaa" o { r, g, b, a }.
- `b` (color) — Un colore: "#rrggbb", "#rrggbbaa" o { r, g, b, a }.
- `t` (number) — 0 = a, 1 = b; limitato a 0-1.
- `space` (string, facoltativo) — Spazio di interpolazione: "oklab" (predefinito), "oklch" (la tonalità segue il percorso più breve), "rgb" o "hsl".

Restituisce (table): { r, g, b, a }, ciascuno 0-255.

#### `app.color.nearest(c, palette)` — pura
La voce della palette più vicina a c per distanza OKLab (alfa ignorato). In caso di parità vince la voce precedente.

- `c` (color) — Un colore: "#rrggbb", "#rrggbbaa" o { r, g, b, a }.
- `palette` (table) — Una lista non vuota di colori.

Restituisce (number): L'indice in palette, a partire da 1.

#### `app.color.parse(c)` — pura
Normalizza qualsiasi colore accettato in { r, g, b, a } (a = 255 quando l'input non ne ha).

- `c` (color) — Un colore: "#rrggbb", "#rrggbbaa" o { r, g, b, a }.

Restituisce (table): { r, g, b, a }, ciascuno 0-255.

#### `app.color.ramp(stops, n, space?)` — pura
Un gradiente campionato in una lista di n colori, dal primo all'ultimo punto, con entrambi gli estremi inclusi. Una sola chiamata a prescindere da n.

- `stops` (table) — Una lista di colori, o di { color =, pos = } con pos 0-1 (i punti senza pos sono distribuiti in modo uniforme). Ne serve almeno uno.
- `n` (number) — Quanti colori restituire, 1-4096. Con 1 restituisce il primo punto.
- `space` (string, facoltativo) — Spazio di interpolazione: "oklab" (predefinito), "oklch" (la tonalità segue il percorso più breve), "rgb" o "hsl".

Restituisce (table): Una lista di n colori { r, g, b, a }.

#### `app.color.shades(base, n, opts?)` — pura
Una lista di n colori dall'ombra alla luce attorno a base, per l'ombreggiatura. La base si trova all'indice floor(n / 2) + 1 (al centro per n dispari) e viene restituita esattamente. Con f che va da -1 (il più scuro) passando per 0 (la base) fino a +1 (il più chiaro), la sfumatura i ha luminosità OKLab L + f * spread / 2 (limitata a 0-1), tonalità H + f * hueShift e chroma C * (1 - 0.4 * f^2), così gli estremi restano dentro sRGB (ciò che resta fuori perde chroma, mai luminosità). L'alfa viene mantenuto. La luminosità è monotona lungo la lista.

- `base` (color) — Un colore: "#rrggbb", "#rrggbbaa" o { r, g, b, a }.
- `n` (number) — Quanti colori restituire, 1-4096.
- `opts` (table, facoltativo)
  - `spread` (number; predefinito 0.5) — Intervallo totale di luminosità OKLab, dall'ombra alla luce (la base è al centro: metà dell'intervallo verso il basso, metà verso l'alto). Limitato a 0-1.
  - `hueShift` (number; predefinito 8) — Gradi di cui ruota la tonalità agli estremi: le ombre di -hueShift, le luci di +hueShift, con scala lineare fino a 0 alla base.

Restituisce (table): Una lista di n colori { r, g, b, a }, dal più scuro.