Da zero a una mano che ti imita

Il primo programma: variabili e tipi

Cosa succede davvero quando un programma «gira», come si tiene da parte un valore, e perché TypeScript ti sgrida prima di eseguire il codice invece che dopo.

• Dove si lavora: TypeScript Playground, niente da installare
• Concetti nuovi: istruzione, console.log, let e const, i tipi string number boolean, annotazione e inferenza, stringhe con `${}`
• Alla fine lo studente sa: scrivere ed eseguire un programma di dieci righe, leggere un messaggio d'errore del compilatore e capire di quale riga parla

Teoria

Un programma è un elenco di istruzioni che il computer esegue una dopo l'altra, dall'alto verso il basso. L'istruzione più utile all'inizio è quella che scrive un messaggio:

console.log("ciao");
console.log("mondo");

Due righe, due messaggi, in quest'ordine. Non c'è magia: se inverti le righe, si inverte il risultato.

Una variabile è un nome dato a un valore, per poterlo riusare. In TypeScript se ne dichiarano di due tipi:

let punteggio = 0;        // potrà cambiare
const nome = "Giulia";    // non cambierà mai

punteggio = punteggio + 10;   // ok
nome = "Marco";               // ERRORE: const non si può riassegnare

Ogni valore ha un tipo. I tre che servono oggi: string (testo, fra virgolette), number (numeri, interi o con la virgola — che in programmazione è un punto) e boolean (solo true o false).

const nome: string = "Giulia";
const eta: number = 17;
const maggiorenne: boolean = false;

Quel : string è l'annotazione di tipo: è la parte che in JavaScript non esiste ed è il motivo per cui questo linguaggio si chiama TypeScript. Spesso si può omettere, perché il compilatore capisce il tipo da solo guardando il valore (si dice che lo inferisce):

const nome = "Giulia";   // TypeScript sa già che è una string
nome.toUpperCase();      // infatti qui ti suggerisce i metodi del testo

E a cosa serve tutto questo? A far comparire gli errori mentre scrivi, non mentre il programma gira davanti agli utenti:

let eta = 17;
eta = "diciassette";
// Errore: Type 'string' is not assignable to type 'number'.
// Tradotto: "avevi detto che qui ci va un numero, e questo è testo".

Ultimo pezzo: unire testo e valori. Con gli apici inclinati ` (backtick) si scrivono stringhe in cui si possono infilare valori con ${…}:

const dita = 5;
console.log(`la mano ha ${dita} dita`);
console.log(`e ${dita * 4} falangi... circa`);

Demo del docente (15')

1. Apri la mano finita e muovi la mano davanti alla webcam. Dì: «fra dieci lezioni lo scrivete voi».
2. Apri il Playground e scrivi tre righe con console.log.
3. Dichiara const punta = 8; e spiega che quel numero, nel progetto finale, sarà la punta dell'indice.
4. Sbaglia apposta un tipo e leggi l'errore insieme alla classe.

Laboratorio (60')

console.log("Giulia");
console.log(17);

const nome = "Giulia";
const eta = 17;
const amaLaPizza = true;

console.log(`${nome} ha ${eta} anni e la pizza le piace: ${amaLaPizza}`);

const larghezza: number = 640;
const altezza: number = 480;
const fotogrammiAlSecondo: number = 30;

console.log(`un fotogramma ha ${larghezza * altezza} pixel`);
console.log(`in un minuto arrivano ${fotogrammiAlSecondo * 60} fotogrammi`);
console.log(`il disegno gira ${fotogrammiAlSecondo} volte al secondo`);

const x = 0.5;
const y = 0.25;
const larghezza = 640;
const altezza = 480;

console.log(`pixel x: ${x * larghezza}`);   // 320
console.log(`pixel y: ${y * altezza}`);     // 120

Errori tipici in aula

• Virgolette sbagliate: il correttore del sistema operativo trasforma " in “ ”. Nel Playground non succede, ma succede se qualcuno scrive il codice in un documento di testo e lo incolla.
• Backtick introvabile: su tastiera italiana è Alt Gr + '. Vale la pena mostrarlo alla lavagna: senza, l'esercizio 1.2 si blocca.
• Virgola al posto del punto nei decimali: 0,5 non è un numero, 0.5 sì.
• «Non vedo niente»: il pannello dei messaggi del Playground è sulla destra, scheda Logs. Da mostrare una volta per tutte all'inizio.

Verifica veloce (5 domande)

Compito per casa (20-30 minuti)

Scrivi un programma che descriva la tua mano: quante dita, il nome del dito più lungo, se sei mancino. Deve usare almeno un const, un let, i tre tipi visti e una frase con i backtick. Poi condividi il link del Playground con il docente (pulsante Share: il codice viaggia dentro l'indirizzo, non serve un account).

Decidere e ripetere: if, cicli, array

Finora il programma andava dritto dall'alto in basso. Oggi impara a scegliere una strada invece di un'altra e a ripetere lo stesso lavoro su molti valori. Serve perché la mano non è un numero: sono ventuno punti, e vanno guardati tutti.

• Dove si lavora: TypeScript Playground, sempre senza account
• Concetti nuovi: operatori di confronto, && || !, if/else if/else, for, for…of, while, array tipizzati, length, tipi unione
• Alla fine lo studente sa: scorrere un elenco di numeri, contare quante volte si verifica una condizione, e scrivere un tipo che ammette solo certi valori

Teoria

A cosa serve. Un programma che fa sempre le stesse cose nello stesso ordine non è molto utile. La mano davanti alla webcam a volte c'è e a volte no, le dita a volte sono alzate e a volte chiuse: il programma deve decidere. E siccome i punti della mano sono ventuno, scrivere ventuno volte la stessa riga non è una strada percorribile: il programma deve ripetere.

Si comincia dal confronto. Confrontare due valori produce sempre un boolean, cioè true o false: è lo stesso tipo visto la volta scorsa, ma questa volta non lo scriviamo a mano, lo calcola il computer.

const dita = 5;

console.log(dita === 5);    // true   "è uguale a"
console.log(dita !== 5);    // false  "è diverso da"
console.log(dita > 3);      // true   "maggiore di"
console.log(dita < 3);      // false  "minore di"
console.log(dita >= 5);     // true   "maggiore o uguale"
console.log(dita <= 4);     // false  "minore o uguale"

I confronti si combinano con gli operatori logici. Sono tre e si leggono ad alta voce come in italiano:

const x = 0.4;

console.log(x >= 0 && x <= 1);   // true   "e"   → devono essere vere entrambe
console.log(x < 0 || x > 1);     // false  "o"   → basta che ne sia vera una
console.log(!(x < 0));           // true   "non" → capovolge il risultato

Con un valore boolean in mano si può finalmente scegliere. L'istruzione if esegue un blocco di codice solo se la condizione è vera:

const dita = 5;

if (dita === 5) {
  console.log("mano aperta");
}

Le parentesi graffe racchiudono il blocco, cioè le righe che appartengono a quel if. Con else si dice cosa fare quando la condizione è falsa, e con else if si mettono in fila più domande. Il computer le prova dall'alto in basso e si ferma alla prima vera:

const dita = 2;

if (dita === 0) {
  console.log("pugno");
} else if (dita === 5) {
  console.log("mano aperta");
} else if (dita === 2) {
  console.log("vittoria");
} else {
  console.log("gesto non riconosciuto");
}

// stampa: vittoria

Passiamo al ripetere. Il modo più classico è il ciclo for. Scritto tutto insieme fa paura, quindi si legge un pezzo alla volta:

for (let i = 0; i < 5; i++) {
  console.log(i);
}

// stampa: 0 1 2 3 4

Dentro le tonde ci sono tre cose separate da punto e virgola, e ognuna ha un compito:

1. let i = 0 — il punto di partenza. Si crea una variabile, di solito chiamata i (da indice), che vale zero.
2. i < 5 — la condizione per continuare. Prima di ogni giro il computer la controlla: se è vera fa il giro, se è falsa esce dal ciclo.
3. i++ — cosa fare alla fine di ogni giro. i++ è la scrittura breve di i = i + 1.

Quindi il computer esegue: i vale 0, 0 è minore di 5, stampa, i diventa 1… finché i vale 5, che non è minore di 5, e il ciclo finisce. Il corpo è stato eseguito cinque volte, con i che valeva 0, 1, 2, 3, 4.

Adesso serve qualcosa su cui ripetere. Un array è un elenco ordinato di valori, tutti dello stesso tipo. Si scrive fra parentesi quadre, e il suo tipo è il tipo degli elementi seguito da []:

const numeri: number[] = [10, 20, 30, 40];
const nomi: string[] = ["pollice", "indice", "medio"];

console.log(numeri.length);   // 4   → quanti elementi ci sono
console.log(numeri[0]);       // 10  → il PRIMO elemento
console.log(numeri[3]);       // 40  → l'ultimo
console.log(numeri[4]);       // undefined → non esiste

Due cose vanno imparate subito, perché sono la fonte di metà degli errori dei principianti. Primo: gli indici partono da zero. Un array di quattro elementi ha gli indici 0, 1, 2, 3. Secondo: di conseguenza l'ultimo indice è length - 1, mai length.

Mettendo insieme ciclo e array si ottiene la riga più usata di tutto il corso:

const numeri: number[] = [10, 20, 30, 40];

for (let i = 0; i < numeri.length; i++) {
  console.log(`l'elemento numero ${i} vale ${numeri[i]}`);
}

Si scrive i < numeri.length e non i < 4: così il codice continua a funzionare se domani l'array cambia lunghezza. E nel progetto finale cambia eccome, perché un array di punti può contenerne 21 (una mano) o 33 (un corpo intero).

Quando l'indice non ti serve, e ti interessa solo il valore, esiste una forma più corta e più leggibile, for…of:

const numeri: number[] = [10, 20, 30, 40];

for (const valore of numeri) {
  console.log(valore);
}

Si legge letteralmente: «per ogni valore di numeri». Si usa const perché a ogni giro nasce una variabile nuova. Quando usare quale: se ti basta il valore, for…of; se ti serve anche sapere in che posizione sei — e per trovare il dito più alto serve — allora il for classico con l'indice.

Esiste un terzo modo, while, che ripete finché una condizione resta vera senza contatore automatico. Si usa quando non sai in partenza quanti giri serviranno:

let rimaste = 3;

while (rimaste > 0) {
  console.log(`mancano ${rimaste} prove`);
  rimaste = rimaste - 1;
}

Nel progetto della mano non compare mai: quando si lavora su elenchi di punti si sa sempre quanti sono. È utile conoscerlo, non è utile usarlo oggi.

Ultimo concetto, ed è quello che fa di TypeScript qualcosa di più di JavaScript: i tipi unione. A cosa servono: spesso una variabile non può contenere qualunque testo, ma solo due o tre parole precise. Dirlo al compilatore evita una intera famiglia di errori.

type Stato = "spenta" | "accesa";

let camera: Stato = "spenta";
camera = "accesa";    // ok
camera = "acesa";     // ERRORE: Type '"acesa"' is not assignable to type 'Stato'.

La barra verticale | si legge «oppure». Senza il tipo unione avresti scritto let camera: string, e quel "acesa" con una c sola sarebbe passato liscio: il programma avrebbe controllato camera === "accesa", avrebbe trovato false e non avrebbe acceso niente, senza un solo messaggio d'errore. Un pomeriggio buttato via, per una lettera.

Chiudiamo con una trappola che merita i suoi trenta secondi. const su un array non rende l'array immutabile: impedisce solo di sostituirlo con un altro array.

const numeri: number[] = [1, 2, 3];

numeri.push(4);           // PERMESSO: l'array ora è [1, 2, 3, 4]
console.log(numeri);

numeri = [9, 9, 9];       // ERRORE: Cannot assign to 'numeri' because it is a constant.

Il motivo: const protegge il nome, non il contenuto. La variabile numeri continuerà a indicare quell'elenco lì; cosa ci sia dentro l'elenco è un altro discorso. push aggiunge un elemento in fondo ed è il modo normale di costruire un array poco per volta.

Demo del docente (15')

1. Scrivi un array di cinque numeri e stampalo con un for classico, leggendo ad alta voce i tre pezzi delle tonde.
2. Riscrivi lo stesso ciclo con for…of e chiedi alla classe cosa si è guadagnato e cosa si è perso (si è persa la posizione).
3. Togli i++ e mostra la scheda che si blocca. Poi rimettilo. Serve a togliere la paura: è successo, si chiude, si riapre.
4. Dichiara un array di 21 numeri fra 0 e 1 — «sono le posizioni orizzontali dei ventuno punti della mano» — e conta con un if dentro il ciclo quanti stanno sotto 0.5.
5. Scrivi type Gesto = "pugno" | "mano aperta", sbaglia una lettera e mostra l'errore. È il momento in cui i tipi unione si capiscono.

Laboratorio (60')

const numeri: number[] = [12, 7, 30, 4, 22];

let somma = 0;
// scrivi qui il ciclo che aggiunge ogni numero a `somma`

console.log(`somma: ${somma}`);

const numeri: number[] = [12, 7, 30, 4, 22];

let somma = 0;
for (const valore of numeri) {
  somma = somma + valore;
}

const media = somma / numeri.length;

console.log(`somma: ${somma}`);    // 75
console.log(`media: ${media}`);    // 15

const x = 0.42;

if (x >= 0 && x <= 1) {
  console.log("punto dentro l'immagine");
} else {
  console.log("punto fuori dall'immagine");
}

const alzate: boolean[] = [false, true, true, false, false];

const alzate: boolean[] = [false, true, true, false, false];

let quante = 0;
for (const dito of alzate) {
  if (dito === true) {
    quante = quante + 1;
  }
}

console.log(`dita alzate: ${quante}`);   // 2

if (quante === 0) {
  console.log("pugno");
} else if (quante === 5) {
  console.log("mano aperta");
} else {
  console.log("altro");
}

const numeri: number[] = [12, 7, 30, 4, 22];

const numeri: number[] = [12, 7, 30, 4, 22];

let massimo = numeri[0];
let indiceDelMassimo = 0;

for (let i = 1; i < numeri.length; i++) {
  if (numeri[i] > massimo) {
    massimo = numeri[i];
    indiceDelMassimo = i;
  }
}

console.log(`il massimo è ${massimo}, alla posizione ${indiceDelMassimo}`);
// il massimo è 30, alla posizione 2

const x: number[] = [
  0.50, 0.42, 0.36, 0.33, 0.30,
  0.44, 0.42, 0.41, 0.40,
  0.51, 0.51, 0.51, 0.51,
  0.57, 0.58, 0.59, 0.60,
  0.63, 0.66, 0.68, 0.70,
];

const x: number[] = [
  0.50, 0.42, 0.36, 0.33, 0.30,
  0.44, 0.42, 0.41, 0.40,
  0.51, 0.51, 0.51, 0.51,
  0.57, 0.58, 0.59, 0.60,
  0.63, 0.66, 0.68, 0.70,
];

let sinistra = 0;
let destra = 0;

for (const valore of x) {
  if (valore < 0.5) {
    sinistra = sinistra + 1;
  } else {
    destra = destra + 1;
  }
}

console.log(`punti totali: ${x.length}`);              // 21
console.log(`a sinistra: ${sinistra}`);                // 8
console.log(`a destra: ${destra}`);                    // 13
console.log(`controllo: ${sinistra + destra}`);        // 21

if (sinistra > destra) {
  console.log("la mano sta più a sinistra");
} else if (destra > sinistra) {
  console.log("la mano sta più a destra");
} else {
  console.log("la mano sta al centro");
}

Errori tipici in aula

• Confondere = e ===: if (dita = 5) non confronta, assegna. Il compilatore in questo caso aiuta e segnala l'errore, ma il messaggio non è intuitivo: vale la pena mostrarlo prima che lo incontrino da soli.
• Indice che parte da 1: for (let i = 1; i <= numeri.length; i++) salta il primo elemento e legge uno che non esiste. Doppio danno in una riga sola.
• La variabile dichiarata dentro il ciclo: let somma = 0 scritto dentro le graffe si azzera a ogni giro, e alla fine stampa solo l'ultimo valore.
• Graffe dimenticate: if (x > 0) console.log("a"); console.log("b"); stampa sempre "b". Regola del corso: le graffe si mettono sempre, anche per una riga sola.
• NaN stampato a schermo: quasi sempre è un numeri[i] letto oltre la fine dell'array, oppure una divisione per un length che vale zero.
• Ciclo infinito: la scheda si blocca. Si chiude, si riapre il Playground, il codice è nell'indirizzo. Nessun dramma.

Verifica veloce (5 domande)

Compito per casa (30 minuti)

Scrivi un programma che, partendo dall'array x dell'esercizio 2.5, stampi il punto più a destra (valore e posizione) e il punto più a sinistra, e dica se la mano è larga o stretta: chiama «larga» una mano in cui la differenza fra il massimo e il minimo supera 0.35, «stretta» altrimenti. Dichiara la risposta in una variabile con il tipo type Larghezza = "larga" | "stretta". Condividi il link del Playground con il docente.

Funzioni: dare un nome a un pezzo di lavoro

Nella lezione scorsa hai scritto tre volte quasi lo stesso ciclo. Oggi impari a scriverlo una volta sola, dargli un nome e richiamarlo quando serve. È il passo che trasforma un elenco di istruzioni in un programma che si può leggere.

• Dove si lavora: TypeScript Playground
• Concetti nuovi: function, parametri tipizzati, tipo di ritorno, return, void, funzioni freccia, valori predefiniti, parametri opzionali ?, map e filter
• Alla fine lo studente sa: scrivere una funzione con parametri e valore di ritorno, riusarla dentro un'altra funzione, e capire quando una funzione restituisce qualcosa e quando invece «fa» e basta

Teoria

A cosa serve. Due motivi, in ordine di importanza. Il primo è che dare un nome a un pezzo di lavoro lo rende comprensibile: distanza(a, b) si capisce al volo, quattro righe di radici quadrate no. Il secondo è che una cosa scritta in un punto solo si corregge in un punto solo. Se la stessa formula è copiata in cinque punti, prima o poi quattro sono aggiornati e uno no.

Una funzione è un blocco di codice con un nome, che riceve dei valori in ingresso e ne restituisce uno in uscita. Si dichiara così:

function raddoppia(numero: number): number {
  return numero * 2;
}

console.log(raddoppia(5));    // 10
console.log(raddoppia(21));   // 42

Pezzo per pezzo, perché ogni parte ha un nome che poi il docente userà:

• function — la parola che annuncia «sto per dichiarare una funzione».
• raddoppia — il nome. Si sceglie un verbo, perché una funzione fa qualcosa.
• numero: number — il parametro, con il suo tipo. È una variabile che esiste solo dentro la funzione.
• : number dopo le tonde — il tipo di ritorno: cosa esce.
• return — l'istruzione che consegna il risultato e termina subito la funzione.

raddoppia(5) è la chiamata: il 5 entra, prende il posto di numero, e la funzione restituisce 10. Il valore restituito si può stampare, mettere in una variabile, o darlo in pasto a un'altra funzione.

I parametri possono essere più di uno, separati da virgola, ognuno con il proprio tipo:

function area(larghezza: number, altezza: number): number {
  return larghezza * altezza;
}

console.log(area(640, 480));   // 307200

L'ordine conta. area(640, 480) e area(480, 640) qui danno lo stesso risultato per caso, ma in generale no: il primo valore finisce nel primo parametro, punto.

Alcune funzioni non restituiscono niente: stampano, disegnano, accendono. Il loro tipo di ritorno si scrive void, che significa «vuoto»:

function saluta(nome: string): void {
  console.log(`ciao ${nome}`);
}

saluta("Giulia");   // stampa: ciao Giulia

const risultato = saluta("Marco");
console.log(risultato);   // undefined: non c'era niente da restituire

Esiste una seconda scrittura, più breve, chiamata funzione freccia. Fa esattamente la stessa cosa:

const raddoppia = (numero: number): number => {
  return numero * 2;
};

// e quando il corpo è una sola espressione, si può togliere anche return e graffe:
const triplica = (numero: number): number => numero * 3;

console.log(raddoppia(5));    // 10
console.log(triplica(5));     // 15

La funzione viene messa in una const come fosse un valore qualsiasi — perché lo è. Questa forma serve soprattutto quando una funzione va passata a qualcun altro, che è il prossimo argomento.

I parametri possono avere un valore predefinito, usato quando chi chiama non lo passa:

function aPixel(valore: number, dimensione: number = 640): number {
  return valore * dimensione;
}

console.log(aPixel(0.5));        // 320  → usa 640
console.log(aPixel(0.5, 480));   // 240  → usa quello che gli passi

Oppure possono essere opzionali, con un punto interrogativo. In quel caso, se non vengono passati, valgono undefined, e la funzione deve prevederlo:

function etichetta(nome: string, gesto?: string): string {
  if (gesto === undefined) {
    return nome;
  }
  return `${nome}: ${gesto}`;
}

console.log(etichetta("Destra"));               // Destra
console.log(etichetta("Destra", "pugno"));      // Destra: pugno

Le funzioni possono chiamarne altre, e questo è il modo normale di costruire programmi: si parte da pezzi piccoli e sicuri e si compongono.

function distanza(x1: number, y1: number, x2: number, y2: number): number {
  const dx = x2 - x1;
  const dy = y2 - y1;
  return Math.sqrt(dx * dx + dy * dy);
}

function dimensioneMano(xPolso: number, yPolso: number, xNocca: number, yNocca: number): number {
  return distanza(xPolso, yPolso, xNocca, yNocca);
}

console.log(dimensioneMano(0.50, 0.88, 0.51, 0.58));   // circa 0.3002

Math è un insieme di strumenti matematici già pronti che il linguaggio mette a disposizione: Math.sqrt è la radice quadrata, Math.abs il valore assoluto, Math.round l'arrotondamento, Math.min e Math.max il più piccolo e il più grande fra due numeri.

Ultimo pezzo di oggi: map e filter. Sono due strumenti degli array che prendono una funzione come argomento. Sembra strano la prima volta, quindi conviene leggerli come frasi in italiano:

const numeri: number[] = [1, 2, 3, 4];

// map: "fammi un array NUOVO, applicando questa funzione a ogni elemento"
const doppi = numeri.map((n) => n * 2);          // [2, 4, 6, 8]

// filter: "fammi un array NUOVO con i soli elementi per cui questa funzione dice true"
const grandi = numeri.filter((n) => n > 2);      // [3, 4]

console.log(doppi);
console.log(grandi);
console.log(numeri);   // [1, 2, 3, 4] — l'originale non è stato toccato

Entrambi non modificano l'array di partenza: ne restituiscono uno nuovo. Sono la scrittura breve di un ciclo for che costruisce un array con push, e nel codice vero si usano quasi sempre al posto di quel ciclo perché dicono in una riga quale sia l'intenzione.

Chiudiamo con un'idea, non con una sintassi. Una funzione si dice pura quando, dati gli stessi ingressi, restituisce sempre la stessa uscita e non tocca niente fuori da sé. distanza è pura: con quei quattro numeri risponderà sempre uguale, oggi e fra un mese. saluta non lo è, perché stampa — cambia qualcosa nel mondo esterno. Le funzioni pure sono più facili da provare e non riservano sorprese: quando puoi scriverne una, scrivila.

Demo del docente (15')

1. Prendi il codice dell'esercizio 2.1 (somma e media) e trasformalo in una funzione mediaDi. Chiamala due volte su due array diversi: è il momento in cui si vede il guadagno.
2. Scrivi distanza dal vivo, con Math.sqrt, spiegando che è il teorema di Pitagora e nient'altro.
3. Mostra Math.hypot(dx, dy), che fa lo stesso in una riga, e di' che nel progetto vero si usa quella.
4. Calcola la distanza fra polso (0.50, 0.88) e nocca del medio (0.51, 0.58): «questo numero, nell'applicazione vera, decide quanto sono grosse le dita disegnate sullo schermo». Mostra la demo della mano e avvicina la mano alla camera.
5. Dimentica apposta il return e fai vedere che la funzione stampa undefined.

Laboratorio (60')

function distanza(x1: number, y1: number, x2: number, y2: number): number {
  const dx = x2 - x1;
  const dy = y2 - y1;
  return Math.sqrt(dx * dx + dy * dy);
}

function distanzaBreve(x1: number, y1: number, x2: number, y2: number): number {
  return Math.hypot(x2 - x1, y2 - y1);
}

console.log(distanza(0, 0, 3, 4));        // 5
console.log(distanzaBreve(0, 0, 3, 4));   // 5

function aPixel(valore: number, dimensione: number = 640): number {
  return valore * dimensione;
}

console.log(aPixel(0.5, 640));   // 320
console.log(aPixel(0, 640));     // 0
console.log(aPixel(1, 480));     // 480
console.log(aPixel(0.25));       // 160 — usa il predefinito

function mediaDi(numeri: number[]): number {
  if (numeri.length === 0) {
    return 0;
  }

  let somma = 0;
  for (const valore of numeri) {
    somma = somma + valore;
  }
  return somma / numeri.length;
}

console.log(mediaDi([12, 7, 30, 4, 22]));   // 15
console.log(mediaDi([0.4, 0.6]));           // 0.5
console.log(mediaDi([]));                   // 0

const x: number[] = [0.50, 0.42, 0.36, 0.44, 0.63, 0.70];

function aPixel(valore: number, dimensione: number): number {
  return valore * dimensione;
}

const x: number[] = [0.50, 0.42, 0.36, 0.44, 0.63, 0.70];

const inPixel = x.map((valore) => aPixel(valore, 640));
console.log(inPixel);   // [320, 268.8, 230.4, 281.6, 403.2, 448] — circa

const aSinistra = inPixel.filter((p) => p < 320);
console.log(`a sinistra ce ne sono ${aSinistra.length}`);   // 3

type Gesto = "pugno" | "mano aperta" | "altro";

function ditaAlzate(stati: boolean[]): number {
  let quante = 0;
  for (const dito of stati) {
    if (dito) {
      quante = quante + 1;
    }
  }
  return quante;
}

function nomeGesto(stati: boolean[]): Gesto {
  const quante = ditaAlzate(stati);
  if (quante === 0) {
    return "pugno";
  }
  if (quante === 5) {
    return "mano aperta";
  }
  return "altro";
}

console.log(nomeGesto([false, false, false, false, false]));   // pugno
console.log(nomeGesto([true, true, true, true, true]));        // mano aperta
console.log(nomeGesto([false, true, true, false, false]));     // altro

Errori tipici in aula

• return dimenticato: la funzione stampa ma non restituisce, e chi la chiama riceve undefined. Se TypeScript conosce il tipo di ritorno lo segnala subito — ottimo motivo per scriverlo sempre.
• Dichiarare e non chiamare: scrivere function distanza(…) e aspettarsi che succeda qualcosa. Dichiarare è come scrivere una ricetta; chiamare è cucinare.
• Chiamare senza le tonde: console.log(mediaDi) stampa il testo della funzione, non il risultato. Serve mediaDi(numeri).
• Parametri invertiti: aPixel(640, 0.5) dà 320 come aPixel(0.5, 640) — la moltiplicazione perdona — ma con distanza l'ordine sbagliato produce risultati insensati. Meglio abituarsi subito a leggere la firma.
• Usare una variabile dichiarata dentro un'altra funzione: i parametri e le const dichiarate dentro una funzione esistono solo lì dentro. Il messaggio è Cannot find name.
• Il punto e virgola dopo la freccia: const f = () => { … }; vuole il punto e virgola finale perché è una dichiarazione di variabile; function f() { … } no. Nessuno lo ricorda, e va benissimo così: il formattatore lo sistema.

Verifica veloce (5 domande)

Compito per casa (30 minuti)

Scrivi tre funzioni e provale: massimoDi(numeri: number[]): number, minimoDi(numeri: number[]): number e larghezzaDi(numeri: number[]): number, che restituisce la differenza fra massimo e minimo riusando le prime due. Provale sull'array delle ventuno posizioni orizzontali dell'esercizio 2.5. Nessuna delle tre deve contenere un console.log: devono restituire, non stampare — la stampa la fai fuori.

Oggetti e interfacce: il tipo Punto

Fin qui una coordinata erano due variabili separate, x e y, che bisognava ricordarsi di tenere insieme. Oggi diventano una cosa sola con un nome e un tipo. È il dato su cui gira tutto il progetto finale: dalla prossima lezione non scriveremo quasi più altro.

• Dove si lavora: TypeScript Playground, ultima lezione qui
• Concetti nuovi: oggetti letterali, accesso con il punto, interface, array di oggetti, proprietà opzionali e readonly, undefined e null, ?. e ??, restringimento del tipo
• Alla fine lo studente sa: definire un tipo con interface, scrivere funzioni che ricevono e restituiscono oggetti, e gestire senza paura un valore che potrebbe non esserci

Teoria

A cosa serve. Prova a immaginare di scrivere il progetto finale con quello che sai adesso: ventuno valori orizzontali in un array, ventuno verticali in un altro, e la promessa di non sbagliare mai l'accoppiamento. Basta un ordinamento su un array solo e la mano si smonta. Un oggetto tiene insieme i valori che descrivono la stessa cosa, e li tiene insieme per costruzione.

const polso = { x: 0.50, y: 0.88 };

console.log(polso.x);   // 0.5
console.log(polso.y);   // 0.88
console.log(polso);     // { x: 0.5, y: 0.88 }

Fra graffe si elencano le proprietà: un nome, due punti, un valore, separate da virgola. Si leggono con il punto: polso.x. È tutto qui. Se la variabile è let, o se la proprietà non è protetta, si possono anche modificare:

const polso = { x: 0.50, y: 0.88 };

polso.x = 0.55;         // PERMESSO, anche con const (vale la stessa regola degli array)
console.log(polso.x);   // 0.55

polso.z = 0.1;          // ERRORE: Property 'z' does not exist on type '{ x: number; y: number; }'.

Quell'ultimo errore è già TypeScript che lavora: ha dedotto da solo la forma dell'oggetto e non accetta proprietà inventate. Però quella forma è scritta in un punto solo, e se domani ci servisse in dieci funzioni diverse dovremmo ricopiarla dieci volte. Per questo esiste l'interface: dà un nome a una forma.

interface Punto {
  x: number;
  y: number;
  z?: number;     // il punto interrogativo: facoltativa
}

const polso: Punto = { x: 0.50, y: 0.88 };
const puntaIndice: Punto = { x: 0.40, y: 0.37, z: -0.02 };

console.log(polso.x, puntaIndice.z);

Dentro l'interfaccia le proprietà si separano con punto e virgola (o a capo) e non con la virgola come negli oggetti: è la confusione numero uno della lezione. Da qui in poi Punto è un tipo a tutti gli effetti, e si usa come number o string: come tipo di una variabile, di un parametro, di un valore di ritorno, e dentro un array.

const punti: Punto[] = [
  { x: 0.50, y: 0.88 },
  { x: 0.40, y: 0.37 },
  { x: 0.51, y: 0.58 },
];

console.log(punti.length);   // 3
console.log(punti[1].x);     // 0.4  → l'elemento 1, e di quello la x

for (const p of punti) {
  console.log(`(${p.x}, ${p.y})`);
}

punti[1].x si legge da sinistra a destra: prendi l'elemento di indice 1, e di quell'oggetto prendi la proprietà x. Questa riga, con punti[8].x, comparirà nel progetto vero decine di volte: 8 è la punta dell'indice.

interface Punto {
  x: number;
  y: number;
  z?: number;
}

const mano: Punto[] = [
  { x: 0.50, y: 0.88 },   // 0  polso
  { x: 0.42, y: 0.84 },   // 1  base del pollice
  { x: 0.30, y: 0.64 },   // 2  punta del pollice   (nel modello vero è il punto 4)
  { x: 0.44, y: 0.60 },   // 3  nocca dell'indice   (nel modello vero è il 5)
  { x: 0.40, y: 0.37 },   // 4  punta dell'indice   (nel modello vero è l'8)
  { x: 0.51, y: 0.58 },   // 5  nocca del medio     (nel modello vero è il 9)
  { x: 0.51, y: 0.33 },   // 6  punta del medio     (nel modello vero è il 12)
  { x: 0.63, y: 0.63 },   // 7  nocca del mignolo   (nel modello vero è il 17)
  { x: 0.70, y: 0.45 },   // 8  punta del mignolo   (nel modello vero è il 20)
];

Una proprietà può essere dichiarata readonly: si legge, non si riscrive. Serve a dire «questo dato, una volta creato, non si tocca».

interface PuntoFisso {
  readonly x: number;
  readonly y: number;
}

const origine: PuntoFisso = { x: 0, y: 0 };
origine.x = 5;   // ERRORE: Cannot assign to 'x' because it is a read-only property.

Adesso il pezzo più importante della lezione, e quello che separa chi scriverà programmi solidi da chi passerà le serate a cercare bug: i valori che potrebbero non esserci. Ce ne sono due, e significano cose leggermente diverse:

• undefined — «qui non è mai stato messo niente». È quello che ottieni da una proprietà facoltativa non valorizzata, da un parametro opzionale non passato, o da un elemento oltre la fine di un array.
• null — «qui, di proposito, non c'è niente». Lo scrive un programmatore per dire «questo posto è vuoto, e lo so».

Nel progetto finale entrambi compaiono: let stream: MediaStream | null = null significa «la webcam adesso è spenta, e non è una dimenticanza». Il problema è che leggere una proprietà di un valore che non c'è fa esplodere il programma:

interface Punto { x: number; y: number }

let punta: Punto | undefined = undefined;

console.log(punta.x);   // ERRORE del compilatore: 'punta' is possibly 'undefined'.
                        // e se lo eseguissi davvero: TypeError, il programma si ferma

Ci sono tre modi di gestirlo, in ordine di eleganza. Il primo è l'accesso sicuro ?.: prova a leggere, e se davanti non c'è niente restituisce undefined invece di esplodere.

let punta: Punto | undefined = undefined;

console.log(punta?.x);   // undefined — nessun errore

Il secondo è il valore di riserva ??, che si legge «altrimenti»: se quello che sta a sinistra è undefined o null, prende quello a destra. I due si usano quasi sempre insieme:

let punta: Punto | undefined = undefined;

const x = punta?.x ?? 0;
console.log(x);   // 0

punta = { x: 0.40, y: 0.37 };
console.log(punta?.x ?? 0);   // 0.4

Il terzo modo è il restringimento del tipo: un if che controlla, e dentro il quale il compilatore sa che il valore c'è. È il più chiaro quando devi usare il valore più di una volta:

function stampaPunto(punto: Punto | undefined): void {
  if (punto === undefined) {
    console.log("nessun punto");
    return;
  }

  // da qui in poi TypeScript sa che `punto` esiste: niente ?. e niente errori
  console.log(`x vale ${punto.x} e y vale ${punto.y}`);
}

stampaPunto(undefined);              // nessun punto
stampaPunto({ x: 0.4, y: 0.37 });    // x vale 0.4 e y vale 0.37

Il compilatore segue il ragionamento: dopo quel return, l'unico modo per essere ancora lì è che punto non sia undefined. Non è magia, è la stessa cosa che avresti pensato tu leggendo il codice — solo che la controlla lui.

Demo del docente (15')

1. Scrivi interface Punto alla lavagna e poi nel Playground. Crea polso e punta dell'indice con i valori realistici visti sopra.
2. Metti il z e togli il z, mostrando che con z? entrambe le versioni sono valide.
3. Scrivi centro(punti: Punto[]): Punto dal vivo, riusando l'idea della media della lezione 3. Falla restituire un oggetto: è la prima funzione del corso che restituisce qualcosa di composto.
4. Apri la demo della mano, mostra i puntini bianchi sull'anteprima e di': «ognuno di quei puntini è un oggetto come quello che abbiamo appena scritto; sono ventuno, e arrivano trenta volte al secondo».
5. Scrivi punti[99].x e fai vedere l'esplosione in esecuzione. Poi sistemala con punti[99]?.x ?? 0.

Laboratorio (60')

interface Punto {
  x: number;
  y: number;
  z?: number;
}

const polso: Punto = { x: 0.50, y: 0.88 };
const puntaIndice: Punto = { x: 0.40, y: 0.37, z: -0.02 };

console.log(`il polso sta in (${polso.x}, ${polso.y})`);
console.log(`la punta dell'indice sta in (${puntaIndice.x}, ${puntaIndice.y})`);
console.log(`profondità della punta: ${puntaIndice.z ?? 0}`);

function centro(punti: Punto[]): Punto {
  if (punti.length === 0) {
    return { x: 0, y: 0 };
  }

  let sommaX = 0;
  let sommaY = 0;
  for (const p of punti) {
    sommaX = sommaX + p.x;
    sommaY = sommaY + p.y;
  }

  return { x: sommaX / punti.length, y: sommaY / punti.length };
}

const c = centro(mano);
console.log(`il centro della mano sta in (${c.x}, ${c.y})`);
// il centro della mano sta in (0.49, 0.5911111111111111)

function piuAlto(punti: Punto[]): Punto {
  let migliore = punti[0];

  for (const p of punti) {
    if (p.y < migliore.y) {   // y PIÙ PICCOLA = più in alto nell'immagine
      migliore = p;
    }
  }

  return migliore;
}

const alto = piuAlto(mano);
console.log(`il punto più in alto è (${alto.x}, ${alto.y})`);
// il punto più in alto è (0.51, 0.33)  → la punta del medio

function puntoOppureNiente(punti: Punto[], indice: number): Punto | undefined {
  if (indice < 0 || indice >= punti.length) {
    return undefined;
  }
  return punti[indice];
}

function descrivi(punto: Punto | undefined): string {
  if (punto === undefined) {
    return "punto assente";
  }
  return `x: ${punto.x}`;
}

console.log(descrivi(puntoOppureNiente(mano, 4)));    // x: 0.4
console.log(descrivi(puntoOppureNiente(mano, 99)));   // punto assente

// la versione corta, quando serve solo un numero:
const x = puntoOppureNiente(mano, 99)?.x ?? 0;
console.log(x);   // 0

interface Mano {
  lato: "destra" | "sinistra";
  punti: Punto[];
  gesto?: string;
}

mano destra · 9 punti · centro (0.490, 0.591) · gesto: nessuno

interface Mano {
  lato: "destra" | "sinistra";
  punti: Punto[];
  gesto?: string;
}

function riassumi(m: Mano): string {
  const c = centro(m.punti);
  const nomeGesto = m.gesto ?? "nessuno";
  return `mano ${m.lato} · ${m.punti.length} punti · centro (${c.x.toFixed(3)}, ${c.y.toFixed(3)}) · gesto: ${nomeGesto}`;
}

const destra: Mano = { lato: "destra", punti: mano };

const sinistra: Mano = {
  lato: "sinistra",
  punti: [
    { x: 0.20, y: 0.70 },
    { x: 0.24, y: 0.62 },
  ],
  gesto: "pugno",
};

console.log(riassumi(destra));
// mano destra · 9 punti · centro (0.490, 0.591) · gesto: nessuno

console.log(riassumi(sinistra));
// mano sinistra · 2 punti · centro (0.220, 0.660) · gesto: pugno

Errori tipici in aula

• Virgola dentro l'interface: si scrive x: number; con il punto e virgola (o solo a capo). Con la virgola il compilatore protesta e il messaggio non è chiarissimo.
• Due punti al posto dell'uguale: const polso = { x: 0.5 } dentro l'oggetto vuole i due punti, ma la variabile si crea con l'uguale. Confondere le due cose è normalissimo il primo giorno.
• Parentesi graffe nel return: return { x: 1, y: 2 }; restituisce un oggetto. Le graffe qui non sono un blocco di codice, sono l'oggetto: capita di cercare un errore inesistente per questo motivo.
• Cercare il massimo per trovare il punto più in alto: nelle immagini la y cresce in giù. Se la mano disegnata risulta capovolta, il problema è quasi sempre qui.
• Usare || invece di ??: funziona finché non arriva uno zero legittimo, e allora si rompe in modo difficilissimo da rintracciare.
• Confrontare oggetti con ===: { x: 1 } === { x: 1 } è false. Il confronto guarda se sono lo stesso oggetto, non se hanno lo stesso contenuto. Per confrontare il contenuto si confrontano le proprietà una per una.

Verifica veloce (5 domande)

Compito per casa (30-40 minuti)

Scrivi dimensioneMano(punti: Punto[]): number, che restituisce la distanza fra il primo punto dell'array (il polso) e quello di indice 5 (la nocca del medio, nel nostro array ridotto), riusando la funzione distanza della lezione 3 — adattala però perché riceva due Punto invece di quattro numeri. Poi scrivi aperta(punti: Punto[]): boolean, che risponde true se la punta del medio sta più in alto della nocca del medio di almeno un quarto della dimensione della mano. Provala sull'array mano e su una versione modificata in cui hai abbassato la punta del medio a y: 0.56.

La pagina e il canvas: disegnare una mano finta

Fin qui il programma parlava solo attraverso console.log. Oggi si passa a una pagina vera e a una tela su cui disegnare, e alla fine delle due ore sullo schermo comparirà una mano. Finta, ferma, disegnata da te: ma è la stessa mano che fra quattro lezioni si muoverà seguendo la tua.

• Dove si lavora: vite.new/vanilla-ts su StackBlitz, senza account (in alternativa JSFiddle per le prove rapide)
• Concetti nuovi: la pagina HTML minima, document.getElementById, HTMLElement | null, as, getContext("2d"), beginPath, arc, moveTo/lineTo/stroke, fillStyle, lineWidth, clearRect, addEventListener
• Alla fine lo studente sa: prendere un elemento dalla pagina, ottenere il contesto di disegno, disegnare cerchi e linee alle coordinate giuste, e rispondere al clic su un pulsante

Teoria

A cosa serve. Un programma che stampa numeri in una console non lo guarda nessuno. Il progetto finale è una pagina web: c'è un pulsante, c'è un riquadro con la webcam e c'è una tela su cui compare la mano. Oggi impariamo i due meccanismi che tengono insieme il codice e quello che si vede: prendere un elemento della pagina e disegnare dentro di esso.

Cominciamo dalla pagina. Una pagina HTML è fatta di tag, che si aprono e si chiudono e contengono altri tag. Questa è la più piccola che ci serva:

<!doctype html>
<html lang="it">
  <head>
    <meta charset="UTF-8" />
    <title>La mia mano</title>
  </head>
  <body>
    <canvas id="tela" width="480" height="640"></canvas>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

<head> contiene le informazioni sulla pagina, <body> quello che si vede. Il <canvas> è la tela: un rettangolo vuoto, qui largo 480 pixel e alto 640, dentro cui il codice può disegnare. L'id è il nome con cui il codice lo cercherà: deve essere unico nella pagina. L'ultima riga carica il nostro programma.

Adesso il codice deve mettere le mani su quel <canvas>. Lo si chiede alla pagina per nome:

const tela = document.getElementById("tela");

document è la pagina, vista dal codice. getElementById cerca l'elemento con quell'id. Se però provi a usarlo, TypeScript si mette di traverso:

const tela = document.getElementById("tela");
console.log(tela.width);
// ERRORE: 'tela' is possibly 'null'.
// ERRORE: Property 'width' does not exist on type 'HTMLElement'.

Due proteste, e hanno tutte e due ragione:

1. Potrebbe non esserci. Il tipo di ritorno è HTMLElement | null: quel tipo unione dice «un elemento, oppure niente». Se hai scritto male l'id, o se il codice parte prima che la pagina sia pronta, la risposta è null. È lo stesso null della lezione 4.
2. Non sa che tipo di elemento è. Sa che è un elemento della pagina, HTMLElement, e basta. Ma un titolo non ha una larghezza di disegno, un canvas sì: finché il compilatore non sa che è un canvas, non ti fa usare le cose da canvas.

Il secondo problema si risolve con as, che si legge «trattalo come»: è una promessa che fai tu al compilatore.

const tela = document.getElementById("tela") as HTMLCanvasElement | null;

if (!tela) {
  throw new Error("canvas non trovato: controlla l'id nell'HTML");
}

console.log(tela.width);   // 480 — adesso va

if (!tela) si legge «se tela NON c'è»: è il punto esclamativo della lezione 2, quello che capovolge. Dopo quel blocco il compilatore sa che tela esiste — è lo stesso restringimento della lezione 4.

Sulla tela non si disegna direttamente: si chiede il contesto, cioè l'oggetto che possiede tutti gli attrezzi da disegno. Ne esistono di diversi; a noi serve quello bidimensionale.

const ctx = tela.getContext("2d");

if (!ctx) {
  throw new Error("contesto 2d non disponibile");
}

Anche questo può restituire null (per esempio se alla stessa tela fosse già stato chiesto un contesto di tipo diverso), quindi si controlla come prima. Da qui in poi ctx è l'oggetto con cui si disegna tutto.

Le coordinate. Prima di disegnare bisogna sapere dove finiranno le cose. Il canvas ha l'origine in alto a sinistra: la x cresce verso destra, la y cresce verso il basso. È la stessa convenzione delle immagini vista nella lezione 4 — e per una volta questo è un vantaggio: le coordinate del riconoscitore, moltiplicate per la dimensione della tela, finiscono al posto giusto senza rovesciare niente.

// su una tela 480 × 640:
// (0, 0)     angolo in alto a sinistra
// (480, 0)   angolo in alto a destra
// (0, 640)   angolo in basso a sinistra
// (240, 320) centro esatto

function aPixel(valore: number, dimensione: number): number {
  return valore * dimensione;
}

console.log(aPixel(0.5, 480));   // 240 → metà della larghezza

Disegnare un cerchio. Serve per le articolazioni della mano. Sono tre righe, sempre le stesse:

ctx.beginPath();                              // 1. inizia un disegno nuovo
ctx.arc(240, 320, 8, 0, Math.PI * 2);         // 2. descrivi un cerchio
ctx.fillStyle = "#38bdf8";                    // 3. scegli il colore di riempimento
ctx.fill();                                   // 4. riempilo

Gli argomenti di arc, in ordine: centro x, centro y, raggio, angolo di partenza, angolo di arrivo. 0 e Math.PI * 2 sono l'inizio e la fine del giro completo: è la ricetta per «cerchio intero», e si copia così com'è.

Disegnare una linea. Serve per le ossa. Stesso schema:

ctx.beginPath();
ctx.moveTo(100, 100);            // porta la penna qui, senza disegnare
ctx.lineTo(300, 400);            // traccia fino a qui
ctx.strokeStyle = "#f472b6";     // colore della linea
ctx.lineWidth = 4;               // spessore in pixel
ctx.stroke();                    // disegna davvero

La differenza fra fill e stroke è la stessa fra riempire e contornare: fillStyle/fill per il dentro, strokeStyle/stroke per il bordo. I colori si scrivono in esadecimale ("#38bdf8") o per nome ("white"). E niente viene disegnato davvero finché non chiami fill o stroke: le istruzioni prima si limitano a descrivere la forma.

Cancellare. Quando la mano si muove non si disegna sopra alla precedente: si pulisce tutto e si ridisegna da capo, trenta volte al secondo.

ctx.clearRect(0, 0, tela.width, tela.height);   // svuota tutta la tela

Rispondere a un clic. Ultimo attrezzo di oggi. Si prende il pulsante come si è preso il canvas, e gli si dice cosa fare quando viene premuto:

const pulsante = document.getElementById("cambia") as HTMLButtonElement | null;

if (pulsante) {
  pulsante.addEventListener("click", () => {
    console.log("premuto!");
  });
}

addEventListener vuole due cose: il nome dell'evento ("click") e una funzione da eseguire quando succede. Quella funzione è una funzione freccia senza parametri, della lezione 3. Nessuno la chiama esplicitamente: la chiama il browser, quando e se l'utente preme. Nel progetto finale è esattamente così che parte la webcam, dal clic sul pulsante «Accendi la camera».

Demo del docente (15')

1. Apri vite.new/vanilla-ts davanti alla classe: far vedere che in dieci secondi c'è un progetto funzionante toglie l'ansia dell'installazione.
2. Svuota src/main.ts e il <body> di index.html, metti il <canvas>, salva: la pagina resta bianca. «La tela c'è, è vuota.»
3. Scrivi getElementById senza as e mostra i due errori rossi. Aggiungi as e il controllo, e commentali: sono i due problemi che il compilatore ha appena evitato.
4. Disegna un cerchio. È il momento «funziona!» della lezione: aspetta due secondi prima di continuare.
5. Disegna tre cerchi dimenticando beginPath e fai vedere la ragnatela. Poi aggiungilo.
6. Collega un pulsante che cambia il colore del cerchio e ridisegna.

Laboratorio (60')

<body>
  <canvas id="tela" width="480" height="640"></canvas>
  <script type="module" src="/src/main.ts"></script>
</body>

const tela = document.getElementById("tela") as HTMLCanvasElement | null;
if (!tela) {
  throw new Error("canvas non trovato");
}

const ctx = tela.getContext("2d");
if (!ctx) {
  throw new Error("contesto 2d non disponibile");
}

// il cerchio azzurro al centro
ctx.beginPath();
ctx.arc(240, 320, 20, 0, Math.PI * 2);
ctx.fillStyle = "#38bdf8";
ctx.fill();

// la linea rosa dall'angolo al centro
ctx.beginPath();
ctx.moveTo(0, 0);
ctx.lineTo(240, 320);
ctx.strokeStyle = "#f472b6";
ctx.lineWidth = 4;
ctx.stroke();

interface Punto {
  x: number;
  y: number;
}

const MANO_APERTA: Punto[] = [
  { x: 0.50, y: 0.88 },   //  0 polso
  { x: 0.42, y: 0.84 },   //  1 pollice, base
  { x: 0.36, y: 0.77 },   //  2 pollice
  { x: 0.33, y: 0.70 },   //  3 pollice
  { x: 0.30, y: 0.64 },   //  4 pollice, PUNTA
  { x: 0.44, y: 0.60 },   //  5 indice, nocca
  { x: 0.42, y: 0.50 },   //  6 indice
  { x: 0.41, y: 0.43 },   //  7 indice
  { x: 0.40, y: 0.37 },   //  8 indice, PUNTA
  { x: 0.51, y: 0.58 },   //  9 medio, nocca
  { x: 0.51, y: 0.47 },   // 10 medio
  { x: 0.51, y: 0.40 },   // 11 medio
  { x: 0.51, y: 0.33 },   // 12 medio, PUNTA
  { x: 0.57, y: 0.60 },   // 13 anulare, nocca
  { x: 0.58, y: 0.49 },   // 14 anulare
  { x: 0.59, y: 0.43 },   // 15 anulare
  { x: 0.60, y: 0.37 },   // 16 anulare, PUNTA
  { x: 0.63, y: 0.63 },   // 17 mignolo, nocca
  { x: 0.66, y: 0.55 },   // 18 mignolo
  { x: 0.68, y: 0.50 },   // 19 mignolo
  { x: 0.70, y: 0.45 },   // 20 mignolo, PUNTA
];

function aPixel(valore: number, dimensione: number): number {
  return valore * dimensione;
}

ctx.clearRect(0, 0, tela.width, tela.height);

for (const p of MANO_APERTA) {
  const px = aPixel(p.x, tela.width);
  const py = aPixel(p.y, tela.height);

  ctx.beginPath();
  ctx.arc(px, py, 6, 0, Math.PI * 2);
  ctx.fillStyle = "#38bdf8";
  ctx.fill();
}

const CONNESSIONI: number[][] = [
  [0, 1], [1, 2], [2, 3], [3, 4],           // pollice
  [0, 5], [5, 6], [6, 7], [7, 8],           // indice
  [5, 9], [9, 10], [10, 11], [11, 12],      // medio
  [9, 13], [13, 14], [14, 15], [15, 16],    // anulare
  [13, 17], [17, 18], [18, 19], [19, 20],   // mignolo
  [0, 17],                                  // il lato del palmo
];

ctx.clearRect(0, 0, tela.width, tela.height);

// 1) le ossa, sotto
ctx.strokeStyle = "#38bdf8";
ctx.lineWidth = 4;

for (const osso of CONNESSIONI) {
  const a = MANO_APERTA[osso[0]];
  const b = MANO_APERTA[osso[1]];

  ctx.beginPath();
  ctx.moveTo(aPixel(a.x, tela.width), aPixel(a.y, tela.height));
  ctx.lineTo(aPixel(b.x, tela.width), aPixel(b.y, tela.height));
  ctx.stroke();
}

// 2) le articolazioni, sopra
for (const p of MANO_APERTA) {
  ctx.beginPath();
  ctx.arc(aPixel(p.x, tela.width), aPixel(p.y, tela.height), 6, 0, Math.PI * 2);
  ctx.fillStyle = "#38bdf8";
  ctx.fill();
}

const PUNTE: number[] = [4, 8, 12, 16, 20];

for (let i = 0; i < MANO_APERTA.length; i++) {
  const p = MANO_APERTA[i];
  const punta = PUNTE.includes(i);

  ctx.beginPath();
  ctx.arc(aPixel(p.x, tela.width), aPixel(p.y, tela.height), punta ? 9 : 6, 0, Math.PI * 2);
  ctx.fillStyle = punta ? "#ffffff" : "#38bdf8";
  ctx.fill();
}

<body>
  <button id="cambia">Cambia posa</button>
  <canvas id="tela" width="480" height="640"></canvas>
  <script type="module" src="/src/main.ts"></script>
</body>

const PUGNO: Punto[] = [
  { x: 0.50, y: 0.88 }, { x: 0.42, y: 0.84 }, { x: 0.37, y: 0.78 },
  { x: 0.36, y: 0.72 }, { x: 0.40, y: 0.68 },
  { x: 0.44, y: 0.62 }, { x: 0.43, y: 0.54 }, { x: 0.46, y: 0.56 },
  { x: 0.48, y: 0.60 },
  { x: 0.51, y: 0.60 }, { x: 0.51, y: 0.52 }, { x: 0.53, y: 0.55 },
  { x: 0.54, y: 0.60 },
  { x: 0.57, y: 0.61 }, { x: 0.58, y: 0.53 }, { x: 0.59, y: 0.57 },
  { x: 0.59, y: 0.62 },
  { x: 0.63, y: 0.64 }, { x: 0.65, y: 0.58 }, { x: 0.65, y: 0.62 },
  { x: 0.64, y: 0.66 },
];

function disegna(punti: Punto[]): void {
  ctx.clearRect(0, 0, tela.width, tela.height);

  ctx.strokeStyle = "#38bdf8";
  ctx.lineWidth = 4;
  for (const osso of CONNESSIONI) {
    const a = punti[osso[0]];
    const b = punti[osso[1]];
    ctx.beginPath();
    ctx.moveTo(aPixel(a.x, tela.width), aPixel(a.y, tela.height));
    ctx.lineTo(aPixel(b.x, tela.width), aPixel(b.y, tela.height));
    ctx.stroke();
  }

  for (let i = 0; i < punti.length; i++) {
    const p = punti[i];
    const punta = PUNTE.includes(i);
    ctx.beginPath();
    ctx.arc(aPixel(p.x, tela.width), aPixel(p.y, tela.height), punta ? 9 : 6, 0, Math.PI * 2);
    ctx.fillStyle = punta ? "#ffffff" : "#38bdf8";
    ctx.fill();
  }
}

let aperta = true;
disegna(MANO_APERTA);

const pulsante = document.getElementById("cambia") as HTMLButtonElement | null;

if (pulsante) {
  pulsante.addEventListener("click", () => {
    aperta = !aperta;
    disegna(aperta ? MANO_APERTA : PUGNO);
  });
}

Errori tipici in aula

• Pagina bianca e nessun errore: quasi sempre l'id nell'HTML e quello nel codice non coincidono, oppure manca la riga <script type="module" src="/src/main.ts">. Primo posto dove guardare: la console del browser.
• La ragnatela: beginPath dimenticato dentro il ciclo. Tutti i cerchi risultano uniti da linee.
• Niente si vede ma nessun errore: fill o stroke dimenticati. Il disegno è stato descritto ma non eseguito.
• La mano capovolta: qualcuno ha «corretto» la y pensando che 0 fosse in basso. Nel canvas la y cresce verso il basso, come nell'immagine: va lasciata com'è.
• Il canvas dimensionato con il CSS: mettere larghezza e altezza fuori dagli attributi width e height stira il disegno invece di ingrandirlo. Per oggi: solo attributi nell'HTML.
• Mano minuscola in un angolo: si è usato aPixel(p.x, 1) o ci si è dimenticati di moltiplicare. Le coordinate 0…1 senza moltiplicazione stanno tutte nel primo pixel.
• Il pulsante non risponde: l'ascoltatore è stato registrato su un elemento null dentro un if mai vero, oppure l'id è sbagliato.

Verifica veloce (5 domande)

Compito per casa (40 minuti)

Parti dalla soluzione dell'esercizio 5.5 e aggiungi una terza posa a tua scelta — il gesto della vittoria, il pollice in su, la mano che saluta — inventando tu le ventuno coordinate. Il pulsante deve ruotare fra le tre pose invece di alternarne due: tieni un let posa = 0, portalo avanti a ogni clic e riportalo a zero quando arriva a tre. Mettendo le tre pose in un array di array — const POSE: Punto[][] = [MANO_APERTA, PUGNO, LA_TUA] — il codice diventa di tre righe. Porta il link di StackBlitz alla prossima lezione: è l'ultima volta che si lavora nel browser, perché la sesta lezione si apre installando gli strumenti veri sul proprio computer.

Sul proprio computer: Node, Vite, moduli

Fino a ieri il codice girava dentro una pagina web altrui. Da oggi il progetto è tuo: sta in una cartella sul tuo computer, si avvia con un comando e si divide in più file. È il passaggio che rende possibile tutto il resto del corso.

• Dove si lavora: sul proprio computer, con VS Code e Node.js — piano B nel riquadro blu più sotto
• Concetti nuovi: Node.js, npm, Vite, la cartella di un progetto, package.json, tsconfig.json, strict, export e import, la compilazione
• Alla fine lo studente sa: creare un progetto TypeScript, avviarlo, dividere il proprio codice in due o tre file e capire cosa succede fra quello che scrive e quello che il browser esegue

Teoria

Nelle prime cinque lezioni hai scritto codice dentro una pagina che qualcun altro teneva aperta per te. Ha funzionato benissimo per imparare, ma adesso c'è un ostacolo preciso: la webcam non si accende dentro l'anteprima degli ambienti online. Il riquadro che mostra il risultato è una pagina incorniciata dentro un'altra, che arriva da un sito diverso, e i browser negano camera e microfono a quei riquadri. Non è un difetto dell'ambiente: è una regola pensata per impedire che un sito qualunque accenda la tua telecamera nascondendosi dentro una cornice.

Dalla prossima lezione ti serve la webcam. Quindi oggi ti serve un progetto vero.

Node.js: JavaScript fuori dal browser

Node.js è un programma che esegue JavaScript sul tuo computer, senza browser. A te non serve per far girare la mano — quella girerà nel browser come sempre — ma serve agli strumenti: il compilatore di TypeScript, il server di sviluppo, il programma che mette insieme i file. Sono tutti scritti in JavaScript e girano su Node.

Insieme a Node si installa npm (node package manager), che fa due cose:

• scarica librerie scritte da altri — alla lezione 8 scaricherai con un comando il riconoscitore di mani di Google;
• esegue i comandi del progetto, quelli scritti in package.json: npm run dev, npm run build.

Vite: il progetto già pronto

Creare a mano la cartella giusta, il file di configurazione giusto e il server giusto è noioso e non insegna niente. Vite lo fa per te con un comando:

npm create vite@latest mano-corso

Ti fa due domande. Alla prima (Select a framework) scegli Vanilla, che vuol dire «niente framework, solo la pagina e il codice». Alla seconda (Select a variant) scegli TypeScript. In breve si dice «il modello vanilla-ts», e lo puoi anche chiedere direttamente:

npm create vite@latest mano-corso -- --template vanilla-ts

Dentro la cartella appena creata trovi questo:

mano-corso/
├── index.html          ← la pagina: il titolo, i pulsanti, il canvas
├── package.json        ← il "documento d'identità" del progetto
├── tsconfig.json       ← le regole del compilatore TypeScript
├── public/             ← file serviti così come sono (immagini, icone)
└── src/
    ├── main.ts         ← il codice che parte all'apertura della pagina
    └── style.css       ← l'aspetto

In fondo a index.html c'è una riga sola che collega la pagina al codice:

<script type="module" src="/src/main.ts"></script>

Poi due comandi, sempre gli stessi, per tutto il resto del corso:

cd mano-corso     # entra nella cartella
npm install       # scarica gli strumenti: crea node_modules/ (pesante, non si tocca)
npm run dev       # avvia il server di sviluppo

npm run dev stampa un indirizzo, di solito http://localhost:5173. Lo apri nel browser e vedi la tua pagina. Il server resta acceso: lascia quella finestra del terminale aperta e scrivi il codice nell'altra finestra. Ogni volta che salvi, la pagina si aggiorna da sola in una frazione di secondo. Per fermarlo: Ctrl + C.

localhost vuol dire «questo computer». Nessuno, da fuori, vede quella pagina. Ed è anche un indirizzo di cui il browser si fida: come vedrai la prossima lezione, la webcam si accende solo su https://… o su localhost, e questo è il motivo per cui il progetto locale funziona subito.

I due file di configurazione

package.json è un file di testo che descrive il progetto: il nome, le librerie che usa e i comandi disponibili.

{
  "name": "mano-corso",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview"
  },
  "devDependencies": {
    "typescript": "~5.9.0",
    "vite": "^7.0.0"
  }
}

Quello che sta in scripts sono scorciatoie: npm run dev esegue quello che c'è scritto accanto a "dev". Quello che sta in devDependencies sono gli strumenti scaricati da npm install. Il numero accanto al nome è la versione, e conta: alla lezione 8 vedrai cosa succede quando una libreria cambia sotto i piedi di un progetto.

tsconfig.json dice al compilatore quanto essere severo. La riga che ci interessa oggi è una:

{
  "compilerOptions": {
    "target": "ES2022",
    "strict": true
  },
  "include": ["src"]
}

Con "strict": true TypeScript smette di lasciar correre. I due controlli che noterai subito:

• niente any per caso: un parametro senza tipo diventa un errore, perché «non lo so» non è una risposta accettabile;
• niente null di nascosto: se una cosa può non esistere — come document.getElementById("tela"), che restituisce l'elemento oppure null — devi dirlo tu cosa fare in quel caso.

// con strict acceso
const tela = document.getElementById("tela");
tela.textContent = "ciao";
// Errore: 'tela' is possibly 'null'.

// due modi onesti per risolverlo
const tela = document.getElementById("tela") as HTMLCanvasElement;   // "fidati, esiste"
// oppure, meglio:
const tela = document.getElementById("tela");
if (!tela) throw new Error("manca l'elemento #tela nella pagina");

Dividere il codice in file: export e import

Il progetto vero della mano — quello che vedi online — è diviso in cinque file, ognuno con un compito: accendere la camera, riconoscere la mano, smorzare il tremolio, disegnare, mettere tutto in fila. Non è pignoleria: è l'unico modo per ritrovare le cose.

Un file diventa un modulo nel momento in cui exporta qualcosa. Quello che non è esportato resta privato di quel file.

// src/disegna.ts
export interface Punto {
  x: number;
  y: number;
  z: number;
}

const COLORE_OSSA = "#38bdf8";   // niente export: la usa solo questo file

export function disegnaPunti(ctx: CanvasRenderingContext2D, punti: Punto[]): void {
  for (const p of punti) {
    ctx.beginPath();
    ctx.arc(p.x, p.y, 4, 0, Math.PI * 2);
    ctx.fill();
  }
}

// src/main.ts
import { disegnaPunti, type Punto } from "./disegna";

const punti: Punto[] = [{ x: 100, y: 50, z: 0 }];
// disegnaPunti(ctx, punti);

Tre cose da notare, e sono sempre le stesse tre:

1. fra graffe si scrivono gli stessi nomi usati nell'export: se lì è disegnaPunti, qui non può essere DisegnaPunti;
2. il percorso comincia con ./ (stessa cartella) o ../ (cartella sopra), e l'estensione .ts non si scrive;
3. per importare un tipo si scrive type davanti al nome: dice al compilatore «questo serve solo a te, non finirà nel codice eseguito».

Cosa fa il compilatore, davvero

Il browser non sa cos'è TypeScript. Non ha mai saputo cosa sono i tipi e non li imparerà. Quello che succede è più semplice di quanto sembri: i tipi vengono cancellati.

// quello che scrivi tu (TypeScript)
function distanza(a: Punto, b: Punto): number {
  const dx: number = a.x - b.x;
  const dy: number = a.y - b.y;
  return Math.sqrt(dx * dx + dy * dy);
}

// quello che arriva al browser (JavaScript)
function distanza(a, b) {
  const dx = a.x - b.x;
  const dy = a.y - b.y;
  return Math.sqrt(dx * dx + dy * dy);
}

Identico, meno le annotazioni. Da qui discendono due conseguenze che vale la pena fissare adesso:

• i tipi non costano niente a chi esegue il programma: a mezzogiorno sono già spariti;
• i tipi non proteggono mentre il programma gira. Se alla lezione 8 il riconoscitore restituisce zero mani, nessun tipo te lo impedisce: dovrai controllarlo tu con un if.

In sviluppo questa trasformazione la fa Vite, al volo, a ogni salvataggio. Il controllo dei tipi invece lo fa tsc, che gira quando lanci npm run build e in continuazione dentro VS Code, che è il motivo per cui le sottolineature rosse compaiono mentre scrivi.

Demo del docente (15')

1. Terminale vuoto: node -v e npm -v, per mostrare che ci sono.
2. npm create vite@latest demo-aula -- --template vanilla-ts, poi npm install e npm run dev: dal niente alla pagina aperta, in meno di due minuti.
3. Cambia una riga in src/main.ts, salva e fai vedere la pagina che si aggiorna da sola mentre nessuno la ricarica.
4. Crea src/saluta.ts con dentro export function saluta(nome: string) { … } e importala in main.ts. Poi sbaglia apposta: togli l'export e leggi l'errore insieme alla classe.
5. Apri tsconfig.json, metti "strict": true e mostra la riga che diventa rossa.

Laboratorio (60')

node -v
npm -v

v22.20.0     # un numero pari ≥ 20, il tuo può essere diverso
10.9.3       # qualunque numero ≥ 9

npm create vite@latest mano-corso -- --template vanilla-ts
cd mano-corso
npm install
npm run dev

<!doctype html>
<html lang="it">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>La mia mano</title>
  </head>
  <body>
    <h1>La mia mano</h1>
    <button id="disegna">Disegna</button>
    <canvas id="tela" width="640" height="480"></canvas>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

// src/main.ts
import "./style.css";

console.log("il progetto è vivo");

// src/disegna.ts
export interface Punto {
  x: number;
  y: number;
  z: number;
}

/** Le 21 ossa della mano: ogni coppia dice quali due punti collegare. */
export const OSSA: number[][] = [
  [0, 1], [1, 2], [2, 3], [3, 4],
  [0, 5], [5, 6], [6, 7], [7, 8],
  [5, 9], [9, 10], [10, 11], [11, 12],
  [9, 13], [13, 14], [14, 15], [15, 16],
  [13, 17], [17, 18], [18, 19], [19, 20],
  [0, 17],
];

export function disegnaPunti(ctx: CanvasRenderingContext2D, punti: Punto[]): void {
  ctx.fillStyle = "#ffffff";
  for (const p of punti) {
    ctx.beginPath();
    ctx.arc(p.x, p.y, 4, 0, Math.PI * 2);
    ctx.fill();
  }
}

export function disegnaOssa(ctx: CanvasRenderingContext2D, punti: Punto[]): void {
  ctx.strokeStyle = "#38bdf8";
  ctx.lineWidth = 3;
  for (const osso of OSSA) {
    const a = punti[osso[0]];
    const b = punti[osso[1]];
    ctx.beginPath();
    ctx.moveTo(a.x, a.y);
    ctx.lineTo(b.x, b.y);
    ctx.stroke();
  }
}

// src/main.ts
import "./style.css";
import { disegnaOssa, disegnaPunti, type Punto } from "./disegna";
import { MANO_FINTA } from "./punti";

const tela = document.getElementById("tela") as HTMLCanvasElement;
const ctx = tela.getContext("2d") as CanvasRenderingContext2D;

const punti: Punto[] = MANO_FINTA;
ctx.clearRect(0, 0, tela.width, tela.height);
disegnaOssa(ctx, punti);
disegnaPunti(ctx, punti);

// src/punti.ts
import type { Punto } from "./disegna";

/** Una mano aperta inventata: coordinate fra 0 e 1, come quelle vere. */
export const MANO_FINTA: Punto[] = [
  { x: 0.50, y: 0.90, z: 0 },   // 0  polso
  { x: 0.40, y: 0.84, z: 0 },   // 1  pollice
  { x: 0.33, y: 0.76, z: 0 },   // 2
  { x: 0.28, y: 0.68, z: 0 },   // 3
  { x: 0.24, y: 0.61, z: 0 },   // 4  punta del pollice
  { x: 0.44, y: 0.62, z: 0 },   // 5  indice
  { x: 0.43, y: 0.50, z: 0 },   // 6
  { x: 0.42, y: 0.42, z: 0 },   // 7
  { x: 0.42, y: 0.35, z: 0 },   // 8  punta dell'indice
  { x: 0.52, y: 0.60, z: 0 },   // 9  medio
  { x: 0.52, y: 0.47, z: 0 },   // 10
  { x: 0.52, y: 0.38, z: 0 },   // 11
  { x: 0.52, y: 0.31, z: 0 },   // 12 punta del medio
  { x: 0.59, y: 0.62, z: 0 },   // 13 anulare
  { x: 0.60, y: 0.50, z: 0 },   // 14
  { x: 0.61, y: 0.42, z: 0 },   // 15
  { x: 0.61, y: 0.35, z: 0 },   // 16 punta dell'anulare
  { x: 0.65, y: 0.67, z: 0 },   // 17 mignolo
  { x: 0.68, y: 0.58, z: 0 },   // 18
  { x: 0.70, y: 0.52, z: 0 },   // 19
  { x: 0.72, y: 0.46, z: 0 },   // 20 punta del mignolo
];

/** Da coordinate 0…1 a pixel di una tela larga `larghezza` e alta `altezza`. */
export function aPixel(p: Punto, larghezza: number, altezza: number): Punto {
  return { x: p.x * larghezza, y: p.y * altezza, z: p.z };
}

// src/main.ts — la parte che cambia
import { MANO_FINTA, aPixel } from "./punti";

const punti = MANO_FINTA.map((p) => aPixel(p, tela.width, tela.height));
disegnaOssa(ctx, punti);
disegnaPunti(ctx, punti);

// 1) 'const ctx' is possibly 'null'
//    getContext("2d") restituisce null se il canvas non supporta il 2D.
const ctx = tela.getContext("2d");
if (!ctx) throw new Error("questo browser non sa disegnare in 2D");

// 2) Parameter 'p' implicitly has an 'any' type
//    dentro map il tipo di solito è dedotto; se non lo è, si scrive.
const punti = MANO_FINTA.map((p: Punto) => aPixel(p, tela.width, tela.height));

Errori tipici in aula

• Comando lanciato nella cartella sbagliata: npm run dev risponde «Could not read package.json». Manca il cd mano-corso. Il terminale mostra sempre in quale cartella sei: si legge prima di scrivere.
• Spazi o accenti nel percorso: una cartella chiamata Documenti scuola/progètto prima o poi dà problemi. Usa nomi corti, minuscoli, senza spazi.
• Il server è già acceso: «Port 5173 is in use». Vite ne sceglie un'altra e lo scrive — oppure si ferma il primo con Ctrl + C.
• La pagina è bianca: quasi sempre un errore in main.ts. Si apre la console del browser con F12 e si legge. La console è il primo posto dove guardare, non l'ultimo.
• «L'ho corretto ma l'errore resta»: il file non era salvato. Ctrl + S. Il pallino accanto al nome del file, in alto, significa «non salvato».
• Percorso di import senza ./: import { … } from "disegna" fa cercare una libreria di nome «disegna» dentro node_modules. Ci vuole "./disegna".
• node_modules «occupa troppo spazio»: sì, centinaia di megabyte, ed è normale. Non si tocca, non si copia, non si mette in una chiavetta: si ricrea in trenta secondi con npm install.

Verifica veloce (5 domande)

Compito per casa (30-40 minuti)

Sistema il progetto e rendilo tuo: metti la mano finta al centro della tela qualunque sia la dimensione del canvas, aggiungi un terzo modulo src/colori.ts che esporta i colori usati dal disegno (così cambiando un file cambia tutto l'aspetto), e verifica che npx tsc --noEmit non dica niente. Porta la prossima volta il progetto che parte: la lezione 7 comincia con npm run dev già acceso.

La webcam: async, permessi, fotogrammi

Oggi la tua pagina guarda. Per riuscirci servono tre cose nuove: chiedere qualcosa che richiede tempo (async e await), reagire quando va storto (try/catch) e ridisegnare trenta volte al secondo senza inceppare il browser.

• Dove si lavora: nel proprio progetto mano-corso, con npm run dev acceso
• Concetti nuovi: Promise, async/await, try/catch, getUserMedia, contesto sicuro, l'elemento <video>, drawImage, requestAnimationFrame, fermare le tracce
• Alla fine lo studente sa: accendere e spegnere davvero la webcam, spiegare all'utente cosa è andato storto, e disegnare ogni fotogramma sul canvas contando quanti ne passano al secondo

Teoria

Alcune cose non sono pronte subito

Finora ogni riga di codice dava il suo risultato immediatamente. Accendere la webcam no: il browser deve chiedere il permesso all'utente, che magari ci pensa cinque secondi, poi deve accendere una telecamera fisica. Nel frattempo il programma non può fermarsi: se si fermasse, la pagina si bloccherebbe e nemmeno il pulsante «Consenti» funzionerebbe.

La soluzione di JavaScript si chiama Promise: non il risultato, ma la promessa di un risultato. Una funzione come getUserMedia ti restituisce subito una promessa, e quella promessa prima o poi si mantiene (arriva il flusso video) oppure si rompe (l'utente ha detto no).

Per lavorare con le promesse ci sono due parole:

async function accendi() {
  const flusso = await navigator.mediaDevices.getUserMedia({ video: true });
  console.log("acceso!", flusso);
}

• await vuol dire «aspetta che questa promessa si mantenga, poi dammi il valore». Mentre aspetta, il resto della pagina continua a funzionare: i pulsanti rispondono, le animazioni girano.
• async davanti a function è il permesso di usare await lì dentro. Se lo dimentichi, il compilatore te lo dice subito.

async function accendiCamera(video: HTMLVideoElement): Promise<MediaStream> {
  const flusso = await navigator.mediaDevices.getUserMedia({ video: true, audio: false });
  video.srcObject = flusso;
  await video.play();
  return flusso;
}

Quando va storto: try / catch

Una promessa può rompersi, e con la webcam si rompe spesso: permesso negato, nessuna telecamera, telecamera già usata da un altro programma. Se non fai niente, l'utente vede una pagina che non reagisce e non capisce perché.

try {
  flusso = await accendiCamera(video);
  // qui ci arrivi solo se è andata bene
} catch (e) {
  // qui ci arrivi solo se è andata male
  console.log("non ha funzionato:", e);
}

Il browser non ti manda una frase, ti manda un errore con un nome. I tre che vedrai in aula oggi:

Tradurli è banale e cambia tutto: è la differenza fra un'applicazione e un compito.

Il contesto sicuro

La webcam si accende solo se la pagina arriva da https://… oppure da localhost. Su un http:// normale, navigator.mediaDevices non esiste proprio: il codice fallisce con un errore oscuro.

Il motivo è serio. Su http:// chiunque stia in mezzo alla rete — il gestore del wi-fi, per dire — può cambiare la pagina mentre viaggia, e quindi far accendere la telecamera a una pagina che non lo aveva chiesto. https lo impedisce. localhost è ammesso perché non viaggia da nessuna parte: è il tuo computer.

if (!window.isSecureContext || !navigator.mediaDevices?.getUserMedia) {
  throw new Error("La camera funziona solo su una pagina HTTPS o su localhost.");
}

È esattamente il controllo che fa il progetto vero, prima di ogni altra cosa. E ti spiega anche perché alla lezione 10, quando parleremo di mettere il sito online, HTTPS non sarà un dettaglio facoltativo.

Dove finisce il video

Il flusso della webcam non si guarda da solo: va agganciato a un elemento <video>.

<video id="video" autoplay muted playsinline></video>
<canvas id="tela" width="640" height="480"></canvas>

Tre attributi, tre motivi:

• autoplay — parte da solo, senza un secondo clic;
• muted — senza questo i browser bloccano la riproduzione automatica; e comunque a noi l'audio non serve, infatti chiediamo audio: false;
• playsinline — sui telefoni impedisce che il video si apra a tutto schermo mangiandosi la pagina.

Il <video> però è solo una finestrella. Per disegnarci sopra i punti della mano ti serve il canvas, e per prima cosa devi copiarci dentro l'immagine:

ctx.drawImage(video, 0, 0, tela.width, tela.height);

Una riga, e nel canvas c'è il fotogramma corrente. Da lì in poi disegni quello che vuoi sopra: alla lezione 8 saranno 21 puntini.

Il ciclo dei fotogrammi

Disegnare una volta sola non basta: l'immagine cambia in continuazione. Serve un ciclo che riparta a ogni fotogramma, e lo fornisce il browser:

function ciclo(): void {
  requestAnimationFrame(ciclo);          // prenota il prossimo giro
  ctx.drawImage(video, 0, 0, tela.width, tela.height);
}
ciclo();                                  // il primo giro lo chiami tu

requestAnimationFrame — «chiedi un fotogramma di animazione» — dice al browser: richiamami un istante prima del prossimo ridisegno dello schermo. Di solito sono 60 volte al secondo.

Perché non un timer, cioè setInterval(ciclo, 16)? Tre motivi concreti:

• il timer non sa quando lo schermo si ridisegna, quindi ogni tanto disegni due volte fra un ridisegno e l'altro (lavoro buttato) o zero volte (scatto visibile);
• se il computer è lento, i timer si accumulano e la pagina si ingolfa; requestAnimationFrame invece salta semplicemente un giro;
• quando cambi scheda, il browser sospende requestAnimationFrame: niente batteria consumata per disegnare una pagina che nessuno guarda. Il timer continuerebbe imperterrito.

Il ciclo si ferma con cancelAnimationFrame, e per farlo bisogna essersi tenuti il numero che requestAnimationFrame restituisce:

let idCiclo = 0;

function ciclo(): void {
  idCiclo = requestAnimationFrame(ciclo);
  // …disegno…
}

function fermaCiclo(): void {
  cancelAnimationFrame(idCiclo);
}

Spegnere la camera davvero

Questa è la parte che quasi tutti sbagliano la prima volta. Mettere in pausa il <video> non spegne la telecamera: il flusso resta aperto e la lucina accanto all'obiettivo resta accesa. Bisogna fermare le tracce, cioè i singoli canali del flusso, una per una:

function spegniCamera(video: HTMLVideoElement, flusso: MediaStream | null): void {
  flusso?.getTracks().forEach((t) => t.stop());   // ← questa è la riga che conta
  video.pause();
  video.srcObject = null;
}

La verifica è fisica e non ammette discussioni: la spia della webcam deve spegnersi. Se resta accesa, non hai spento niente.

Demo del docente (15')

1. Pagina con due pulsanti e un <video>. Scrivi accendiCamera dal vivo e fai comparire la richiesta di permesso sul proiettore.
2. Nega il permesso apposta. Mostra che la pagina non dice niente, poi aggiungi il try/catch e il messaggio tradotto. È il momento più utile della lezione.
3. Scrivi spegniCamera prima senza getTracks().forEach(...): la spia resta accesa. Poi aggiungi la riga: la spia si spegne. Fai vedere la lucina, non il codice.
4. Aggiungi il ciclo con requestAnimationFrame e il drawImage sul canvas: adesso ci sono due immagini identiche, il video e la tela. Chiedi alla classe perché ne servono due — la risposta («sulla tela possiamo disegnarci sopra») è la lezione 8.

Laboratorio (60')

<!-- index.html -->
<button id="accendi">Accendi la camera</button>
<button id="spegni">Spegni</button>
<p id="messaggio"></p>
<video id="video" autoplay muted playsinline></video>
<canvas id="tela" width="640" height="480"></canvas>

// src/main.ts
import "./style.css";

const bottoneAccendi = document.getElementById("accendi") as HTMLButtonElement;
const video = document.getElementById("video") as HTMLVideoElement;

let flusso: MediaStream | null = null;

async function accendiCamera(): Promise<void> {
  flusso = await navigator.mediaDevices.getUserMedia({ video: true, audio: false });
  video.srcObject = flusso;
  await video.play();
}

bottoneAccendi.addEventListener("click", () => {
  void accendiCamera();
});

const messaggio = document.getElementById("messaggio") as HTMLParagraphElement;

/** I nomi standard degli errori del browser, tradotti in frasi utili. */
const MESSAGGI: Record<string, string> = {
  NotAllowedError: "Permesso negato: consenti l'uso della camera dalle impostazioni del browser e riprova.",
  NotFoundError: "Nessuna webcam trovata su questo dispositivo.",
  NotReadableError: "La webcam è occupata da un'altra applicazione.",
  OverconstrainedError: "La webcam non supporta la risoluzione richiesta.",
};

async function accendiCamera(): Promise<void> {
  messaggio.textContent = "";
  try {
    flusso = await navigator.mediaDevices.getUserMedia({ video: true, audio: false });
    video.srcObject = flusso;
    await video.play();
    messaggio.textContent = "● Camera accesa";
  } catch (e) {
    const nome = e instanceof DOMException ? e.name : "";
    messaggio.textContent = MESSAGGI[nome] ?? "Non riesco ad accendere la camera.";
  }
}

const bottoneSpegni = document.getElementById("spegni") as HTMLButtonElement;

function spegniCamera(): void {
  flusso?.getTracks().forEach((t) => t.stop());
  video.pause();
  video.srcObject = null;
  flusso = null;
  messaggio.textContent = "Camera spenta";
}

bottoneSpegni.addEventListener("click", spegniCamera);

const tela = document.getElementById("tela") as HTMLCanvasElement;
const ctx = tela.getContext("2d");
if (!ctx) throw new Error("questo browser non sa disegnare in 2D");

let idCiclo = 0;

function ciclo(): void {
  idCiclo = requestAnimationFrame(ciclo);

  ctx.save();                       // mette da parte l'orientamento attuale
  ctx.translate(tela.width, 0);     // sposta l'origine sul bordo destro
  ctx.scale(-1, 1);                 // ribalta l'asse x: ecco lo specchio
  ctx.drawImage(video, 0, 0, tela.width, tela.height);
  ctx.restore();                    // rimette tutto com'era
}

const etichettaFps = document.getElementById("fps") as HTMLSpanElement;

let fotogrammi = 0;
let inizioFinestra = performance.now();

function contaFps(): void {
  fotogrammi++;
  const adesso = performance.now();
  const trascorso = adesso - inizioFinestra;
  if (trascorso >= 1000) {
    etichettaFps.textContent = `${Math.round((fotogrammi * 1000) / trascorso)} fps`;
    fotogrammi = 0;
    inizioFinestra = adesso;
  }
}

document.addEventListener("visibilitychange", () => {
  if (document.hidden && flusso) spegniCamera();
});

Errori tipici in aula

• Permesso negato per sbaglio la prima volta: il browser ricorda e non richiede più niente, quindi la pagina sembra rotta. Si rimedia dall'icona della telecamera nella barra degli indirizzi. Da mostrare a tutti prima del laboratorio, non dopo.
• await fuori da una funzione async: errore del compilatore. La parolina async va davanti alla function che contiene l'await.
• Il video si vede ma la tela è nera: il ciclo non è partito, oppure il canvas ha larghezza e altezza zero. width e height del canvas si scrivono come attributi HTML, non come CSS.
• Tutto specchiato, scritte comprese: manca ctx.restore().
• La spia resta accesa dopo «Spegni»: manca getTracks().forEach((t) => t.stop()). È il motivo per cui questo controllo va fatto con gli occhi sulla webcam.
• Due cicli in parallelo: accendi, spegni, riaccendi, e improvvisamente gli fps raddoppiano. Ogni accensione avviava un ciclo senza fermare il precedente. Si risolve con cancelAnimationFrame(idCiclo) prima di ogni avvio.
• La webcam non parte nell'ambiente online: è l'anteprima incorniciata. Da qui in poi si lavora in locale, o in coppia con chi ce l'ha; l'anteprima in scheda separata è l'ultima possibilità (lezione 6).

Verifica veloce (5 domande)

Compito per casa (30-40 minuti)

Sposta tutto quello che riguarda la camera in un modulo src/camera.ts, che esporta due funzioni sole: accendiCamera(video) che restituisce Promise<MediaStream> e spegniCamera(video, flusso). In main.ts devono restare i pulsanti, i messaggi e il ciclo. Aggiungi anche il controllo del contesto sicuro all'inizio dell'accensione. È il file camera.ts del progetto vero, scritto da te: la prossima lezione lo userai così com'è.

MediaPipe: i 21 punti della mano vera

È la lezione in cui il progetto funziona. Alla fine di queste due ore muovi la mano davanti alla webcam e sullo schermo si muove una mano disegnata da te, con le tue dita e i tuoi movimenti. Tutto il resto del corso sono rifiniture.

• Dove si lavora: nel proprio progetto, con la camera funzionante della lezione 7
• Concetti nuovi: modelli di intelligenza artificiale, installare una libreria con npm install, versioni fissate, FilesetResolver, GestureRecognizer, runningMode: "VIDEO", recognizeForVideo, leggere un risultato annidato con ?.
• Alla fine lo studente sa: caricare un modello, ottenere i 21 punti della propria mano a ogni fotogramma, convertirli in pixel e disegnare punti, ossa e nome del gesto

Teoria

Cos'è un modello, in due paragrafi

Finora ogni riga del tuo programma diceva al computer esattamente cosa fare: «disegna un cerchio qui», «moltiplica questo per quello». Trovare una mano in un'immagine così non si può fare: nessuno sa scrivere le regole per riconoscere una mano — con qualunque luce, qualunque pelle, qualunque anello, qualunque sfondo. Ci hanno provato per vent'anni.

Un modello è un altro approccio: invece delle regole, gli esempi. Qualcuno — qui Google — ha raccolto decine di migliaia di fotografie di mani e ha segnato a mano, su ognuna, dove stanno le 21 articolazioni. Poi un programma di addestramento ha aggiustato, un pochino alla volta, milioni di numeri interni finché il sistema non ha cominciato a indovinare quei 21 punti anche su fotografie mai viste. Il risultato di quel lavoro è un file: gesture_recognizer.task, otto megabyte di numeri. Non contiene fotografie, non contiene mani: contiene solo i numeri che servono a fare quel calcolo.

Da questo discendono tre cose pratiche, che vale la pena avere chiare:

• Il modello si scarica una volta e gira sul tuo computer. Non c'è nessun server da interrogare: l'immagine della tua mano non esce dal browser, mai. È il motivo per cui questo progetto può promettere quello che promette.
• Il modello sbaglia. Non «può sbagliare»: sbaglia, e lo vedrai oggi. In controluce, con la mano storta o mezza fuori dall'inquadratura, i punti ballano o la mano sparisce. Non è un bug tuo: è la natura della cosa, e alla lezione 9 imparerai a conviverci.
• Il modello non capisce niente. Dà numeri, e i numeri hanno una confidenza. Non sa cos'è una mano, non sa che è la tua.

Installare una libreria, e fissarne la versione

npm install @mediapipe/tasks-vision@1.0.1

Questo comando scarica la libreria di Google dentro node_modules e aggiunge una riga in package.json. Quel @1.0.1 alla fine è la parte importante della lezione.

"dependencies": {
  "@mediapipe/tasks-vision": "1.0.1"
}

Scritto così — senza ^, senza ~, senza @latest — vuol dire «esattamente questa versione». Chiunque installi il progetto fra due anni avrà gli stessi identici file, e il progetto funzionerà come oggi.

Caricare il riconoscitore

Servono due indirizzi: il runtime (il motore di calcolo, scritto in WebAssembly) e il modello. Il caricamento richiede tempo — sono una ventina di megabyte la prima volta — quindi è tutto async, come la webcam della lezione scorsa.

// src/tracker.ts
import { FilesetResolver, GestureRecognizer } from "@mediapipe/tasks-vision";

const WASM = "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@1.0.1/wasm";
const MODELLO =
  "https://storage.googleapis.com/mediapipe-models/gesture_recognizer/gesture_recognizer/float16/1/gesture_recognizer.task";

export async function creaRiconoscitore(): Promise<GestureRecognizer> {
  const vision = await FilesetResolver.forVisionTasks(WASM);
  return GestureRecognizer.createFromOptions(vision, {
    baseOptions: { modelAssetPath: MODELLO },
    runningMode: "VIDEO",
    numHands: 1,
  });
}

Riga per riga, le tre cose che contano:

• FilesetResolver.forVisionTasks prepara il motore: guarda cosa sa fare il tuo processore e sceglie da solo la variante giusta del WebAssembly.
• runningMode: "VIDEO" dice «ti arriveranno fotogrammi in sequenza, non foto scollegate». In questa modalità il riconoscitore insegue la mano da un fotogramma all'altro invece di ricercarla ogni volta da zero: è molto più veloce e molto più stabile. L'alternativa è "IMAGE", per le fotografie singole.
• numHands: 1 — una mano basta per cominciare. Metterlo a 2 è l'esercizio 8.5.

Chiedere i punti, a ogni fotogramma

const risultato = riconoscitore.recognizeForVideo(video, performance.now());

Questa riga va dentro il ciclo della lezione 7. Due dettagli, entrambi fonte di errori il primo giorno:

1. Non è await. In modalità VIDEO il calcolo avviene subito e restituisce subito il risultato. È anche il motivo per cui, se il computer è lento, gli fps crollano: il disegno aspetta il riconoscimento.
2. Il tempo deve crescere sempre. Il secondo parametro è l'istante del fotogramma, in millisecondi. Se passi un tempo uguale o minore del precedente, la libreria si ferma con un errore. Con performance.now() non succede, perché un orologio va avanti — ma la regola va conosciuta, perché è la causa di un errore che altrimenti sembra incomprensibile.

C'è anche un accorgimento che fa risparmiare metà del lavoro. Lo schermo si ridisegna 60 volte al secondo, ma la webcam manda 30 fotogrammi al secondo: metà dei giri del ciclo vedono la stessa immagine di prima. Analizzarla due volte è lavoro buttato:

let ultimoIstante = -1;

function ciclo(): void {
  idCiclo = requestAnimationFrame(ciclo);

  // readyState >= 2 significa "c'è un fotogramma pronto"
  if (video.readyState >= 2 && video.currentTime !== ultimoIstante) {
    ultimoIstante = video.currentTime;
    const risultato = riconoscitore.recognizeForVideo(video, performance.now());
    disegnaTutto(risultato);
  }
}

Com'è fatto il risultato

risultato.landmarks è un array di mani; ogni mano è un array di 21 punti; ogni punto ha x, y, z. Tre livelli, e bisogna tenerli distinti:

risultato.landmarks            // [ [21 punti], [21 punti] ]  ← 0, 1 o 2 mani
risultato.landmarks[0]         // i 21 punti della prima mano
risultato.landmarks[0][8]      // la punta dell'indice
risultato.landmarks[0][8].x    // 0.42 — un numero fra 0 e 1

Sono le stesse coordinate fra 0 e 1 della mano finta della lezione 5, e non è un caso: il corso è stato costruito perché oggi tu debba cambiare una riga sola. Sono numeri relativi all'immagine, non pixel: se domani cambi la dimensione della tela, i punti continuano a funzionare.

E i numeri dei punti sono sempre gli stessi, per tutti: 0 il polso, 4 la punta del pollice, 8 la punta dell'indice, 12 il medio, 16 l'anulare, 20 il mignolo. Sono i numeri che hai già usato nella tabella delle ossa alla lezione 6.

Quando la mano non c'è

Se togli la mano dall'inquadratura, landmarks è un array vuoto. Scrivere risultato.landmarks[0][0].x senza controllare fa esplodere il programma. Il ?. della lezione 4 serve esattamente a questo:

const mano = risultato.landmarks[0];
if (!mano) return;          // niente mano in questo fotogramma: si salta il disegno

// oppure, in una riga:
const polso = risultato.landmarks[0]?.[0];
console.log(polso?.x ?? "nessuna mano");

Ed è la risposta pratica a quello che si diceva alla lezione 6: i tipi spariscono prima dell'esecuzione, quindi non ti proteggono mentre il programma gira. Il controllo lo devi scrivere tu.

Demo del docente (15')

1. npm install @mediapipe/tasks-vision@1.0.1 sul proiettore; apri package.json e mostra la riga comparsa, senza ^.
2. Scrivi creaRiconoscitore e chiamala all'avvio. Mostra il pannello Rete degli strumenti per sviluppatori: si vedono scendere i megabyte del modello. Poi ricarica: la seconda volta è istantaneo, perché il browser li ha in cache.
3. Nel ciclo, console.log(risultato.landmarks.length): muovi la mano dentro e fuori dall'inquadratura e commenta gli 1 e gli 0 che scorrono.
4. Stampa risultato.landmarks[0]?.[8] e muovi lentamente l'indice: fai leggere alla classe la x che va da 0,1 a 0,9. È il momento in cui i numeri diventano il proprio dito: vale la pena lasciarlo respirare mezzo minuto.
5. Sbaglia apposta: passa 0 invece di performance.now() e leggi l'errore sui tempi crescenti.

Laboratorio (60')

// src/main.ts — le parti nuove
import { creaRiconoscitore } from "./tracker";
import type { GestureRecognizer } from "@mediapipe/tasks-vision";

let riconoscitore: GestureRecognizer | null = null;
let ultimoIstante = -1;

async function avvia(): Promise<void> {
  messaggio.textContent = "Carico il modello…";
  riconoscitore = await creaRiconoscitore();   // prima il modello: non chiede niente all'utente
  await accendiCamera();                        // poi la camera: il permesso si chiede alla fine
  ciclo();
}

function ciclo(): void {
  idCiclo = requestAnimationFrame(ciclo);
  if (!riconoscitore) return;
  if (video.readyState < 2 || video.currentTime === ultimoIstante) return;
  ultimoIstante = video.currentTime;

  const risultato = riconoscitore.recognizeForVideo(video, performance.now());
  console.log("mani:", risultato.landmarks.length, "punti:", risultato.landmarks[0]?.length ?? 0);
}

import { disegnaPunti, type Punto } from "./disegna";
import { aPixel } from "./punti";

function mostra(punti: Punto[]): void {
  ctx.save();
  ctx.translate(tela.width, 0);
  ctx.scale(-1, 1);
  ctx.drawImage(video, 0, 0, tela.width, tela.height);
  ctx.restore();

  const inPixel = punti.map((p) => aPixel(p, tela.width, tela.height));
  disegnaPunti(ctx, inPixel);
}

// nel ciclo, dopo aver ottenuto il risultato:
const mano = risultato.landmarks[0];
if (mano) mostra(mano);
else ctx.clearRect(0, 0, tela.width, tela.height);

import { disegnaOssa, disegnaPunti } from "./disegna";

const inPixel = punti.map((p) => aPixel(p, tela.width, tela.height));
disegnaOssa(ctx, inPixel);    // prima le linee
disegnaPunti(ctx, inPixel);   // poi i pallini, sopra

const etichettaGesto = document.getElementById("gesto") as HTMLParagraphElement;

const GESTI: Record<string, string> = {
  Closed_Fist: "✊ Pugno",
  Open_Palm: "🖐️ Mano aperta",
  Pointing_Up: "☝️ Indice in su",
  Thumb_Down: "👎 Pollice giù",
  Thumb_Up: "👍 Pollice su",
  Victory: "✌️ Vittoria",
  ILoveYou: "🤟 Ti voglio bene",
};

const gesto = risultato.gestures[0]?.[0];
const nome = gesto?.categoryName;
etichettaGesto.textContent =
  nome && nome !== "None" ? GESTI[nome] ?? nome : "nessun gesto riconosciuto";

// tracker.ts: numHands: 2

// disegna.ts: le due funzioni prendono un colore in più
export function disegnaOssa(ctx: CanvasRenderingContext2D, punti: Punto[], colore: string): void {
  ctx.strokeStyle = colore;
  ctx.lineWidth = 3;
  for (const osso of OSSA) {
    const a = punti[osso[0]];
    const b = punti[osso[1]];
    ctx.beginPath();
    ctx.moveTo(a.x, a.y);
    ctx.lineTo(b.x, b.y);
    ctx.stroke();
  }
}

// main.ts
const COLORI = ["#38bdf8", "#f472b6"];

risultato.landmarks.forEach((mano, i) => {
  const inPixel = mano.map((p) => aPixel(p, tela.width, tela.height));
  disegnaOssa(ctx, inPixel, COLORI[i]);
  disegnaPunti(ctx, inPixel, "#ffffff");
});

Errori tipici in aula

• «Cannot read properties of undefined»: si è letto landmarks[0][0] in un fotogramma senza mani. Serve il controllo con if o il ?..
• Errore sui tempi non crescenti: si è passato un numero fisso, o lo stesso performance.now() salvato in una variabile e riusato. Il tempo si legge a ogni chiamata.
• La pagina si blocca per dieci secondi al primo avvio: è il download dei venti megabyte. Non è un bug — ma va detto all'utente con un messaggio «Carico il modello…», altrimenti sembra rotto.
• Punti tutti ammassati nell'angolo in alto a sinistra: sono le coordinate 0…1 disegnate come se fossero pixel. Manca aPixel.
• Punti specchiati rispetto all'immagine: hai specchiato il video ma non le coordinate (o viceversa). Decidi una volta e sii coerente.
• La scia: manca clearRect, oppure il drawImage del video non copre tutta la tela.
• Due o tre fotogrammi al secondo: il riconoscimento gira sul processore invece che sulla scheda grafica, cosa frequente sui portatili scolastici. Non si risolve oggi; si annota e si misura all'esercizio 7.5.

Verifica veloce (5 domande)

Compito per casa (30-40 minuti)

Rendi presentabile quello che hai: un messaggio «Carico il modello…» durante l'attesa, «Nessuna mano inquadrata» quando la mano non c'è, il nome del gesto in grande, e il contatore di fps della lezione 7 lasciato acceso in un angolo. Poi annota su un foglio quanti fps fa il tuo computer con il riconoscimento attivo e in quali condizioni la mano si perde (controluce? mano di taglio? troppo vicina?). Porta i numeri la prossima volta: la lezione 9 comincia da lì.

Rifinire: classi, stato, gesti, tremolio

Il progetto funziona già. Oggi si passa da «funziona» a «si può dare in mano a qualcuno»: la mano smette di vibrare, i pulsanti sanno sempre in che stato sono, e le mani fantasma smettono di lampeggiare.

• Dove si lavora: nel proprio progetto, con la mano già funzionante della lezione 8
• Concetti nuovi: class, costruttore, campi, metodi, private, tipi unione come stato, una funzione sola che applica lo stato, media mobile, conferma su più fotogrammi
• Alla fine lo studente sa: scrivere una classe piccola e usarla, tenere l'interfaccia coerente con un solo setState, e smorzare il tremolio sapendo cosa ci guadagna e cosa ci perde

Teoria

Le classi: un oggetto che si porta dietro le sue funzioni

Alla lezione 4 hai imparato gli oggetti: scatole con dentro dei valori. Una classe è la stessa idea, con una cosa in più: dentro ci stanno anche le funzioni che lavorano su quei valori.

Guarda il problema di oggi. Per smorzare il tremolio devi ricordarti gli ultimi cinque valori di una coordinata. Con quello che sai finora:

let ultimiValori: number[] = [];

function aggiungi(valore: number): void {
  ultimiValori.push(valore);
  if (ultimiValori.length > 5) ultimiValori.shift();
}

Funziona… per una coordinata. Ma le coordinate sono 21 punti × 3 assi = 63, e ognuna ha bisogno della propria memoria. Con le variabili sciolte servirebbero 63 array e 63 funzioni. Con una classe, ne scrivi una e ne crei 63.

class MediaMobile {
  private valori: number[] = [];      // campo: la memoria di QUESTO oggetto
  private readonly quanti: number;    // quanti valori tenere

  constructor(quanti = 5) {           // si esegue alla nascita dell'oggetto
    this.quanti = quanti;
  }

  aggiungi(valore: number): void {    // metodo: una funzione dell'oggetto
    this.valori.push(valore);
    if (this.valori.length > this.quanti) this.valori.shift();
  }

  valore(): number {
    let somma = 0;
    for (const v of this.valori) somma += v;
    return somma / this.valori.length;
  }
}

const x = new MediaMobile(5);
const y = new MediaMobile(5);   // memoria separata: due oggetti, due storie

x.aggiungi(0.42);
x.aggiungi(0.44);
console.log(x.valore());        // 0.43

Il vocabolario è tutto qui, e sono cinque parole:

• classe — lo stampo: dice com'è fatto e cosa sa fare un oggetto di quel tipo;
• new — costruisci un oggetto da quello stampo;
• costruttore — quello che va fatto alla nascita;
• campo — un valore che l'oggetto si tiene (valori, quanti);
• metodo — una funzione che l'oggetto sa eseguire (aggiungi, valore).

this vuol dire «questo oggetto qui, non gli altri 62». E private vuol dire «da fuori non si tocca»: chi usa un MediaMobile chiama aggiungi e valore, e non deve neanche sapere che dentro c'è un array. Se domani cambi il modo di calcolare la media, nessun altro file se ne accorge.

Lo stato dell'interfaccia

Guarda la tua pagina della lezione 8 e conta: il pulsante «Accendi», quello «Spegni», il messaggio, il riquadro d'errore, il contatore di fps. Cinque cose che devono essere coerenti fra loro. Se le accendi e le spegni una per una, sparse nel codice, prima o poi arrivi a una schermata assurda — «Camera spenta» scritto mentre la spia è accesa, il pulsante «Avvio in corso…» che resta lì per sempre dopo un errore.

La soluzione è dire per prima cosa quali stati esistono. È un tipo unione, come quelli della lezione 2:

type Stato = "spenta" | "avvio" | "accesa" | "errore";

Quattro parole, e nessun'altra: se scrivi "acesa", il compilatore ti ferma subito. Poi una sola funzione decide come si vede ogni stato:

function setState(stato: Stato, messaggio: string): void {
  etichettaStato.textContent = messaggio;
  bottoneAccendi.disabled = stato === "avvio" || stato === "accesa";
  bottoneSpegni.disabled = stato !== "accesa";
  riquadroErrore.hidden = stato !== "errore";
  document.body.dataset.stato = stato;   // utile al CSS e a chi legge la pagina
}

Da quel momento in poi, in tutto il resto del programma, non si tocca più nessun pulsante: si chiama setState("avvio", "Carico il modello…") e basta. Il vantaggio non è scrivere meno righe: è che gli stati impossibili diventano impossibili, invece di restare in agguato.

Perché i punti tremano

Tieni la mano ferma, ferma davvero. I punti sullo schermo continuano a ballare di qualche pixel. Non è colpa tua e non è un bug: il modello analizza ogni fotogramma da solo, e ogni fotogramma è leggermente diverso dal precedente — il rumore del sensore, un filo di luce che cambia. Piccole differenze in ingresso, piccole differenze in uscita. Trenta volte al secondo, e l'occhio le legge come una vibrazione.

L'idea più semplice per toglierla è quella che conosci già dai voti a scuola: invece del valore di adesso, la media degli ultimi cinque. I saltelli in su e in giù si compensano e la mano si calma.

// senza filtro                      con media su 5
// 0.412 0.418 0.409 0.421 0.414     0.415 0.415 0.416 0.415 0.416

Ma c'è un prezzo, e va capito bene perché è il cuore della lezione. Se muovi la mano di scatto, la media contiene ancora quattro valori vecchi: la mano sullo schermo arriva in ritardo, come se strisciasse dietro alla tua. Più il filtro è forte, più è lento. Con 5 valori il ritardo è appena percettibile; con 20 la mano sembra nella melassa. Provali entrambi: è l'esercizio 9.2.

La conferma su più fotogrammi

C'è un secondo difetto, più subdolo. Ogni tanto — un fotogramma su cinquanta, quando la luce cambia o passa qualcosa nell'inquadratura — il modello «vede» una mano che non esiste. Dura un fotogramma solo, ma sullo schermo è un lampo fastidioso.

Il rimedio costa tre righe: non fidarti della prima volta. Si conta da quanti fotogrammi consecutivi la mano è presente, e si disegna solo da tre in poi.

let consecutivi = 0;
const CONFERME = 3;

if (risultato.landmarks.length > 0) consecutivi++;
else consecutivi = 0;

if (consecutivi >= CONFERME) {
  // solo adesso la mano si disegna
}

Costo: un decimo di secondo di ritardo alla comparsa, che nessuno nota. Guadagno: le mani fantasma spariscono. È lo stesso ragionamento del filtro — si paga un pochino di ritardo per comprare stabilità — ed è una delle scelte più frequenti in tutto il mestiere.

Demo del docente (15')

1. Metti la mano ferma davanti alla webcam e zooma sullo schermo: tutta la classe deve vedere i punti che ballano da soli. Il problema prima della soluzione.
2. Scrivi MediaMobile dal vivo, con calma: è la prima classe che vedono. Fai notare che this.valori di due oggetti diversi sono due array diversi.
3. Applicala e riguarda la mano ferma: i punti si calmano. Poi muovi la mano di scatto e fai vedere il ritardo. Non nasconderlo, mostralo: è la lezione.
4. Alza la finestra a 20 valori: la mano diventa gelatina. Riportala a 5. Chiedi alla classe quale preferirebbe, e perché non esiste una risposta giusta per tutti gli usi.
5. Mostra il setState finito e prova la sequenza accendi → errore → spegni → riaccendi, per far vedere che i pulsanti non si ingarbugliano mai.

Laboratorio (60')

// src/filtro.ts
export class MediaMobile {
  private valori: number[] = [];
  private readonly quanti: number;

  constructor(quanti = 5) {
    this.quanti = quanti;
  }

  aggiungi(valore: number): void {
    this.valori.push(valore);
    if (this.valori.length > this.quanti) this.valori.shift();
  }

  /** La media dei valori in memoria. Se non ce n'è nessuno, restituisce 0. */
  valore(): number {
    if (this.valori.length === 0) return 0;
    let somma = 0;
    for (const v of this.valori) somma += v;
    return somma / this.valori.length;
  }
}

// prova
const m = new MediaMobile(3);
m.aggiungi(10);
console.log(m.valore());   // 10
m.aggiungi(20);
console.log(m.valore());   // 15
m.aggiungi(30);
m.aggiungi(60);            // il 10 esce dalla finestra
console.log(m.valore());   // 36.66…

// src/filtro.ts
import type { Punto } from "./disegna";

export class FiltroMano {
  private filtri: MediaMobile[] = [];

  constructor(quanti = 5) {
    // 21 punti × 3 coordinate: un filtro per ciascuna, con la sua memoria
    for (let i = 0; i < 21 * 3; i++) this.filtri.push(new MediaMobile(quanti));
  }

  smorza(punti: Punto[]): Punto[] {
    const risultato: Punto[] = [];
    for (let i = 0; i < punti.length; i++) {
      this.filtri[i * 3].aggiungi(punti[i].x);
      this.filtri[i * 3 + 1].aggiungi(punti[i].y);
      this.filtri[i * 3 + 2].aggiungi(punti[i].z);
      risultato.push({
        x: this.filtri[i * 3].valore(),
        y: this.filtri[i * 3 + 1].valore(),
        z: this.filtri[i * 3 + 2].valore(),
      });
    }
    return risultato;
  }
}

// main.ts
import { FiltroMano } from "./filtro";

let filtro: FiltroMano | null = null;

// quando la mano compare
filtro ??= new FiltroMano(5);
const addolciti = filtro.smorza(mano);
// …e da qui in poi si disegna `addolciti` invece di `mano`

// quando la mano sparisce: si butta il filtro
filtro = null;

type Stato = "spenta" | "avvio" | "accesa" | "errore";

function setState(stato: Stato, messaggio: string): void {
  etichettaStato.textContent = messaggio;
  bottoneAccendi.disabled = stato === "avvio" || stato === "accesa";
  bottoneSpegni.disabled = stato !== "accesa";
  riquadroErrore.hidden = stato !== "errore";
  document.body.dataset.stato = stato;
}

async function avvia(): Promise<void> {
  setState("avvio", "Carico il modello…");
  try {
    riconoscitore ??= await creaRiconoscitore();
    await accendiCamera();
    setState("accesa", "● Camera accesa");
    ciclo();
  } catch (e) {
    spegni();
    riquadroErrore.textContent = messaggioErrore(e);
    setState("errore", "Camera spenta");
  }
}

function spegni(): void {
  cancelAnimationFrame(idCiclo);
  spegniCamera(video, flusso);
  flusso = null;
  filtro = null;
  setState("spenta", "Camera spenta");
}

const mano = risultato.landmarks[0];

if (mano) {
  etichettaMani.textContent = "";
  // …filtra e disegna…
} else {
  etichettaMani.textContent = "Nessuna mano inquadrata";
  ctx.clearRect(0, 0, tela.width, tela.height);
  filtro = null;
}

const CONFERME = 3;
let consecutivi = 0;

if (mano) {
  consecutivi++;
  filtro ??= new FiltroMano(5);
  const addolciti = filtro.smorza(mano);   // si filtra sempre…
  if (consecutivi >= CONFERME) {
    disegnaOssa(ctx, addolciti.map((p) => aPixel(p, tela.width, tela.height)), "#38bdf8");
    disegnaPunti(ctx, addolciti.map((p) => aPixel(p, tela.width, tela.height)));
  }
} else {
  consecutivi = 0;
  filtro = null;
}

let precedenti: Punto[] | null = null;
let sommaMovimento = 0;
let misure = 0;

/** Spostamento medio dei 21 punti rispetto al fotogramma precedente (in unità 0…1). */
function misuraTremolio(punti: Punto[]): void {
  if (precedenti && precedenti.length === punti.length) {
    let somma = 0;
    for (let i = 0; i < punti.length; i++) {
      const dx = punti[i].x - precedenti[i].x;
      const dy = punti[i].y - precedenti[i].y;
      somma += Math.sqrt(dx * dx + dy * dy);
    }
    sommaMovimento += somma / punti.length;
    misure++;
  }
  // copia dei valori, non dei riferimenti: servono com'erano adesso
  precedenti = punti.map((p) => ({ x: p.x, y: p.y, z: p.z }));
}

// una volta al secondo, insieme agli fps:
if (misure > 0) {
  etichettaTremolio.textContent = `tremolio: ${(sommaMovimento / misure).toFixed(5)}`;
  sommaMovimento = 0;
  misure = 0;
}

Errori tipici in aula

• this dimenticato: dentro un metodo si scrive valori.push(...) invece di this.valori.push(...). Il compilatore dice «Cannot find name 'valori'»: il campo esiste solo attraverso this.
• new dimenticato: const f = FiltroMano(); non costruisce niente. Ci vuole new FiltroMano().
• Un filtro solo per tutti i punti: la mano si accartoccia verso un punto unico, ed è uno spettacolo memorabile. Servono 63 filtri indipendenti, uno per coordinata.
• Filtro mai buttato: la mano che rientra nell'inquadratura arriva strisciando da dove era uscita.
• La mano «nella melassa»: finestra troppo lunga. Riportala a 5 e riguarda.
• precedenti = punti invece della copia: si salva un riferimento all'array, non i valori; al confronto successivo le differenze risultano tutte zero e il tremolio misurato è 0,00000. Sembra un successo clamoroso e non lo è.
• Due setState in fila con messaggi contraddittori: l'ultimo vince, e spesso è quello sbagliato. Un cammino, uno stato.

Verifica veloce (5 domande)

Compito per casa (40 minuti)

Due cose. Una: rifinisci il progetto come vuoi tu — colori, dimensioni dei punti, un titolo, il gesto mostrato in grande, magari il colore della mano che cambia con il gesto riconosciuto. Due: prepara la presentazione della lezione 10. Tre o quattro minuti, in cui devi dire: cosa fa il tuo progetto, la parte di codice di cui sei più soddisfatto, la cosa che ti ha fatto perdere più tempo e come l'hai risolta. Niente diapositive: si mostra il progetto che gira.

La terza dimensione, la pubblicazione, le presentazioni

Ultima lezione, e si respira: la mano esce dal piano e diventa una figura nello spazio, si guarda cosa vuol dire mettere davvero online un sito, e poi si presenta. Venti ore fa nessuno di voi aveva scritto una riga di TypeScript.

• Dove si lavora: nel proprio progetto, partendo da un file di avvio fornito dal docente
• Concetti nuovi: Three.js, scena, telecamera, luci, mesh; da 21 punti 2D a 21 sfere nello spazio; npm run build, cosa serve per pubblicare, HTTPS, un cenno alla CSP
• Alla fine lo studente sa: collegare i punti della propria mano a una scena 3D, spiegare cosa succede quando un sito «va online», e raccontare il proprio progetto a qualcuno

Teoria

Three.js: scena, telecamera, luci, mesh

Il browser sa disegnare in tre dimensioni, ma l'interfaccia che offre (WebGL) è di una scomodità feroce: matrici, programmi per la scheda grafica, buffer di numeri. Three.js è la libreria che ci si mette in mezzo e parla come si parla in un teatro. Quattro parole e hai capito tutto quello che serve oggi:

• scena (Scene) — il palcoscenico: l'elenco delle cose che esistono;
• telecamera (PerspectiveCamera) — da dove si guarda, e con che angolo di campo: le cose lontane rimpiccioliscono, come nella realtà;
• luci — senza, è tutto nero. Una luce diffusa che schiarisce dappertutto, una direzionale che dà volume;
• mesh (Mesh) — un oggetto: una geometria (la forma: una sfera, un cilindro) più un materiale (il colore, quanto è lucido).

const sfera = new THREE.Mesh(
  new THREE.SphereGeometry(1, 20, 14),                    // forma
  new THREE.MeshStandardMaterial({ color: 0x38bdf8 }),    // aspetto
);
sfera.position.set(0, 0, 0);
scena.add(sfera);

E poi, a ogni fotogramma, una riga sola: renderer.render(scena, camera). Three.js guarda dove sono gli oggetti in quel momento e disegna il quadro.

Da 21 punti a 21 sfere

Qui c'è tutta la matematica della lezione, e sono tre righe. I punti che arrivano dalla webcam vivono in un mondo fatto così: x e y fra 0 e 1, origine nell'angolo in alto a sinistra, y che cresce verso il basso come in tutte le immagini. Il mondo 3D invece ha l'origine al centro e la y che cresce verso l'alto, come a scuola.

function nelloSpazio(p: Punto) {
  const larghezza = 6;    // quanto è largo, nel mondo 3D, il rettangolo del video
  const altezza = 4.5;
  return {
    x: (0.5 - p.x) * larghezza,       // centra E specchia
    y: (0.5 - p.y) * altezza,         // centra E rovescia
    z: -p.z * larghezza * 1.6,        // profondità, un po' esagerata
  };
}

Guarda cosa fa quel 0.5 - x, perché fa due lavori in una sottrazione:

• sposta l'origine dall'angolo al centro: il punto al centro dell'immagine (0,5) diventa 0, cioè il centro della scena;
• inverte il verso dell'asse. Sulla y serve a passare dalla «y in giù» delle immagini alla «y in su» della grafica 3D. Sulla x è l'effetto specchio: muovi la mano a destra e la mano sullo schermo va a destra, come davanti a uno specchio. Senza, sembra di guardare qualcun altro, ed è stranamente sgradevole.

La z ha il segno invertito (la profondità di MediaPipe è negativa verso la camera, in 3D l'osservatore sta dalla parte positiva) e viene moltiplicata per 1,6: la profondità stimata da una sola telecamera è piccola, e senza un po' di guadagno avvicinare la mano non si noterebbe quasi. Il valore è scelto a occhio — più in alto, la mano comincia a sembrare deformata.

Mettere online un sito

Finora hai lavorato su localhost, che è solo il tuo computer. «Mettere online» vuol dire tre cose, e nessuna è magica:

1. Costruire: npm run build. Il comando controlla i tipi, traduce il TypeScript in JavaScript, unisce i file, li accorcia e scrive tutto nella cartella dist/. Lì dentro c'è un sito normale — pagine, script, immagini — che non ha più bisogno né di Node né di Vite.
2. Un computer sempre acceso che serva quei file a chi li chiede, e un nome (un dominio) che punti a quel computer.
3. HTTPS, e qui non c'è scelta: senza certificato, come hai visto alla lezione 7, la webcam non si accende. Il tuo progetto online in http:// sarebbe una pagina morta.

Il sito che state guardando, per dire, gira su un piccolo computer in affitto: un programma serve la cartella dist/, un altro (Caddy) si occupa del dominio e si procura il certificato HTTPS da solo. Prima di pubblicare, uno script controlla che nei file costruiti non sia comparso niente di strano e che tutte le pagine ci siano; se un controllo fallisce, la pubblicazione si ferma e online resta la versione di ieri, che funzionava.

Due parole di chiusura: privacy e CSP

Il vostro progetto tratta immagini di persone. È il dato più delicato che esista, e voi l'avete gestito nel modo giusto senza quasi accorgervene: le immagini non escono dal browser, perché non c'è nessun posto dove mandarle; la camera si accende solo al clic; si spegne quando cambiate scheda. Non è un caso, è una scelta di progettazione — e la regola che ci sta sotto vale ben oltre questo corso: il dato che non raccogli è l'unico che non puoi perdere.

C'è anche un modo per non limitarsi a prometterlo. Un sito può dichiarare al browser cosa gli è permesso fare — è la Content Security Policy. Il sito della mano dichiara, fra le altre cose, che la pagina può parlare solo con il proprio dominio. Da quel momento non è più il programmatore a garantire che le immagini non vengano inviate a qualcuno: è il browser che rifiuta di inviarle, anche se il codice ci provasse. La differenza fra una promessa e una garanzia è tutta lì.

Nel progetto vero questa regola ha avuto un effetto collaterale interessante: ha bloccato una chiamata che nessuno aveva scritto. Era la libreria di riconoscimento, che ogni minuto mandava ai suoi server qualche dato d'uso — nessuna immagine, ma comunque una chiamata a un estraneo, e senza alcun modo di spegnerla. È stata disattivata. Senza la CSP, nessuno se ne sarebbe mai accorto.

Demo del docente (10')

1. Apri il file di avvio src/scena3d.ts (lo trovi qui sotto, nel riquadro del docente) e mostra che c'è già tutto: scena, telecamera, luci, 21 sfere allineate in fila.
2. Collega un solo punto, il polso, e muovilo con la mano davanti alla webcam. Una sfera che segue un polso è già un effetto notevole, e chiarisce il meccanismo meglio di venti.
3. Poi collega tutti e 21 i punti: la mano appare. Ruota la testa della classe verso lo schermo e avvicina la mano alla camera per far vedere la profondità.
4. Sbaglia apposta: togli il 0.5 - dalla y. La mano si capovolge. Rimettilo e spiega la sottrazione mentre tutti guardano l'effetto.

Laboratorio (80')

npm install three@0.186.0
npm install --save-dev @types/three@0.186.0

// src/scena3d.ts — scena 3D già pronta: tu devi solo chiamare mostraMano() e disegna()
import * as THREE from "three";
import type { Punto } from "./disegna";

const tela3d = document.getElementById("scena") as HTMLCanvasElement;

const scena = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(35, 1, 0.1, 100);
camera.position.set(0, 0, 10);

const renderer = new THREE.WebGLRenderer({ canvas: tela3d, antialias: true, alpha: true });

function adatta(): void {
  const w = tela3d.clientWidth || window.innerWidth;
  const h = tela3d.clientHeight || window.innerHeight;
  renderer.setSize(w, h, false);
  camera.aspect = w / h;
  camera.updateProjectionMatrix();   // obbligatorio dopo aver cambiato le proporzioni
}
window.addEventListener("resize", adatta);
adatta();

// Luci: una diffusa perché niente resti nero, una direzionale che dà volume.
scena.add(new THREE.HemisphereLight(0xdbeafe, 0x1e1b4b, 1.4));
const principale = new THREE.DirectionalLight(0xffffff, 2.2);
principale.position.set(3, 5, 8);
scena.add(principale);

// 21 sfere, create UNA volta sola: a ogni fotogramma si spostano soltanto.
const geometria = new THREE.SphereGeometry(1, 20, 14);
const materiale = new THREE.MeshStandardMaterial({ color: 0x38bdf8, roughness: 0.35 });
const sfere: THREE.Mesh[] = [];
for (let i = 0; i < 21; i++) {
  const s = new THREE.Mesh(geometria, materiale);
  s.position.set((i - 10) * 0.35, 0, 0);   // in fila, finché non arriva una mano vera
  s.scale.setScalar(0.12);
  scena.add(s);
  sfere.push(s);
}

const LARGHEZZA = 6;
const ALTEZZA = 4.5;

/** Sposta le 21 sfere sui 21 punti della mano (coordinate 0…1 di MediaPipe). */
export function mostraMano(punti: Punto[]): void {
  for (let i = 0; i < 21; i++) {
    const p = punti[i];
    sfere[i].position.set(
      (0.5 - p.x) * LARGHEZZA,
      (0.5 - p.y) * ALTEZZA,
      -p.z * LARGHEZZA * 1.6,
    );
  }
  mostra(true);
}

/** Mostra o nasconde la mano in blocco. */
export function mostra(visibile: boolean): void {
  for (const s of sfere) s.visible = visibile;
}

/** Un fotogramma. Va chiamata dentro il ciclo di main.ts. */
export function disegna(): void {
  renderer.render(scena, camera);
}

<!-- index.html: il canvas della scena, dietro a tutto il resto -->
<canvas id="scena"></canvas>

// main.ts
import { disegna, mostra, mostraMano } from "./scena3d";

function ciclo(): void {
  idCiclo = requestAnimationFrame(ciclo);

  if (riconoscitore && video.readyState >= 2 && video.currentTime !== ultimoIstante) {
    ultimoIstante = video.currentTime;
    const risultato = riconoscitore.recognizeForVideo(video, performance.now());
    const mano = risultato.landmarks[0];

    if (mano) {
      filtro ??= new FiltroMano(5);
      mostraMano(filtro.smorza(mano));    // punti 0…1: la conversione la fa la scena
    } else {
      filtro = null;
      mostra(false);
    }
  }

  disegna();   // fuori dall'if: la scena si ridisegna a ogni fotogramma
}

// dentro mostraMano, in scena3d.ts
const PUNTE = [4, 8, 12, 16, 20];
sfere[i].scale.setScalar(PUNTE.includes(i) ? 0.16 : 0.12);

// colore: il materiale è condiviso, quindi una riga cambia tutta la mano
export function coloraMano(colore: number): void {
  materiale.color.setHex(colore);
}
// in main.ts
coloraMano(nome === "Thumb_Up" ? 0x22c55e : 0x38bdf8);

// dimensione secondo la distanza: il polso più vicino = z più negativa
const vicinanza = 1 - punti[0].z * 2;
sfere[i].scale.setScalar(0.12 * Math.max(0.5, Math.min(2, vicinanza)));

npm run build
npm run preview     # apre http://localhost:4173

/** Indice, medio, anulare, mignolo: punta e nocca di ciascuno. */
const DITA = [
  { punta: 8, nocca: 5 },
  { punta: 12, nocca: 9 },
  { punta: 16, nocca: 13 },
  { punta: 20, nocca: 17 },
];

function contaDita(punti: Punto[]): number {
  let alzate = 0;
  for (const dito of DITA) {
    // y più piccola = più in alto nell'immagine
    if (punti[dito.punta].y < punti[dito.nocca].y) alzate++;
  }
  return alzate;
}

Le presentazioni (40')

Tre o quattro minuti a testa, con il progetto che gira. Quattro domande, sempre le stesse, perché tutti sappiano cosa preparare:

1. Cosa fa il tuo progetto? Mostralo, non descriverlo.
2. Qual è il pezzo di codice di cui sei più soddisfatto, e perché?
3. Cosa ti ha fatto perdere più tempo? Come ne sei uscito?
4. Se avessi altre due ore, cosa aggiungeresti?

La terza domanda è la più importante delle quattro. Raccontare un errore e come l'hai risolto è la cosa che, in questo mestiere, distingue chi sa lavorare da chi sa solo far funzionare: succederà in ogni colloquio, in ogni riunione, per il resto della vostra vita professionale. Tanto vale cominciare oggi.

Errori tipici in aula

• Schermo nero: mancano le luci, oppure il canvas non ha dimensioni nel CSS, oppure disegna() non viene mai chiamata. Si controllano in quest'ordine.
• La mano è capovolta: manca il 0.5 - sulla y, o è diventato p.y - 0.5.
• La mano si muove al contrario: manca lo specchio sulla x. È lo stesso ragionamento della y, ma per un motivo diverso — qui è comodità dell'utente, lì è una conversione fra due sistemi di coordinate.
• La mano è enorme o invisibile: le sono stati passati punti in pixel invece che fra 0 e 1.
• Tutto a scatti: si creano oggetti nuovi dentro il ciclo. Le sfere si creano una volta, poi si spostano.
• npm run build fallisce mentre npm run dev funzionava: è tsc che controlla i tipi sul serio. Gli errori sono veri e vanno corretti; in sviluppo erano solo sottolineature ignorate.

Verifica veloce (5 domande)

Compito per casa (nessuna scadenza)

Il corso finisce qui, il progetto no. Otto direzioni in cui può crescere, dalla più facile alla più ambiziosa:

1. Contare le dita alzate per bene, misurando le distanze dal polso invece delle altezze (esercizio 10.5, versione seria).
2. Disegnare con il dito: quando l'indice è alzato e gli altri chiusi, lascia una scia sul canvas. Pugno chiuso = cancella. Sono trenta righe e diverte moltissimo.
3. Pilotare un piccolo gioco: una racchetta che segue l'indice, un bersaglio da colpire, un punteggio. Tutto quello che serve lo sai già.
4. Due mani insieme, con colori diversi e le etichette destra/sinistra sistemate come si deve.
5. Gesti tuoi: misura le distanze fra le punte e inventa i tuoi comandi — pollice e indice che si toccano, mano a L, tre dita. Ricordati la conferma su più fotogrammi della lezione 9.
6. Il corpo intero: lo stesso identico giro con 33 punti da testa a piedi. Guarda la pagina Corpo di questo sito: cambia solo il modello.
7. Sostituire le sfere con una mano vera: cilindri per le ossa, un palmo semitrasparente. È quello che fa la demo di questo sito, e il codice è commentato in italiano riga per riga nel tutorial.
8. Pubblicare il tuo sito e mandare il link a qualcuno. È la cosa più semplice di tutto l'elenco e la più soddisfacente: npm run build, poi una qualunque piattaforma che ospita siti statici con HTTPS incluso.

Venti ore fa non avevi mai scritto console.log. Adesso hai un'applicazione che accende una telecamera, chiede a un modello di intelligenza artificiale dove sono le tue dita, smorza il rumore dei dati, disegna una figura in tre dimensioni sessanta volte al secondo e non manda i tuoi dati a nessuno. Non è un esercizio: è un programma vero. Continua.