Daniele Ferla

Introduzione

In alcuni contesti specifici, come il trattamento di elementi meccanici provenienti da progettazione CAD, si rende necessario visualizzare a schermo il risultato di una estrusione di tale tracciato così da poterne vedere in tre dimensioni il risultato di lavorazione finale. Contesti più specifici necessitano di estrudere tali elementi in direzioni arbitrarie mantenendone l’uniformità, così come altri necessitano di giunzioni con tagli ad angolo per creare strutture più complesse… pensiamo ad esempio alle cornici dei quadri.

Per il test di questo articolo è stata utilizzata una Shape rappresentate una semplice forma di cuore, utile soprattutto per testare l’approccio in contesti di curve e archi.

Caricamento di file SVG sotto forma di Shape singole

L’oggetto THREE.Shape (derivato da THREE.Path) è un oggetto che permette di disegnare componenti 2D vettoriali nel canvas 3D di Three.js.
Sebbene sia uno strumento molto potente è anche molto complesso da utilizzare quindi il suo uso più frequente è quello di trovarlo implementato nel THREE.SVGLoader. Tale loader estrapola dal file .svg oggetti Path e Shape così da poterli usare per generare la geometria desiderata.

Qui sotto una procedura standard per ottenere le singole Shape dell’SVG che sfrutta la funzione toShape() delle Path:

 const loader = new THREE.SVGLoader();
        loader.load(
            'heart.svg',
            function (data) {
                const paths = data.paths;
                let counter = 0;
                for (let i = 0; i < paths.length; i++) {
                    const shapes = paths[i].toShapes(true);
                    counter = counter + shapes.length;
                    for (let j = 0; j < shapes.length; j++) {
                        let newShape = shapes[j]resize; //Shape corrente
                        //Operazioni sulla shape
                        //...
                    }
                }
            },

            // called when loading is in progresses
            function (xhr) {
                console.log((xhr.loaded / xhr.total * 100) + '% loaded');
            },
            // called when loading has errors
            function (error) {
                console.log(error);
            }
        );

Normalizzazione delle dimensioni della Shape

Uno dei problemi che si deve affrontare durante il caricamento di una Shape è quello che l’unità di misura della Shape può essere diversa rispetto a quella della scena in cui dobbiamo includerla. Per questo motivo si rende necessario normalizzare le dimensioni della Shape (e non della Geometry o della Shape successive).

Una tecnica è quella di utilizzare la funzione Shape.getSpacedPoints(…) che permette di ottenere tutti i punti che compongono la Shape e quindi rimapparli con un fattore di scala unico oppure con dimensioni desiderate.

function GetShapeResized(shape, targetWidth, targetHeight)
{
    const boundingBox = new THREE.Box2();
    boundingBox.setFromPoints(shape.getSpacedPoints(100)); 

    const originalWidth = boundingBox.max.x - boundingBox.min.x;
    const originalHeight = boundingBox.max.y - boundingBox.min.y;

    const scaleX = targetWidth / originalWidth;
    const scaleY = targetHeight / originalHeight;

    const points = shape.getSpacedPoints(100);
    const resizedPoints = points.map(point => {
        return new THREE.Vector2(point.x * scaleX, point.y * scaleY);
    });

    const resizedShape = new THREE.Shape(resizedPoints);
    return resizedShape;
}

A questo link del blog sono spiegate in dettaglio le 2 tecniche utilizzabili.

Generazione di una geometria unificata

Come detto un file SVG può essere composto da molte Shape e non da una sola Shape. Per questo motivo si rende necessario, al termine del caricamento e della normalizzazione, la creazione di un unico oggetto Geometry e non diversi oggetti, in quanto sarebbero dispendiosi e poco controllabili.

La funzione che ci viene in aiuto, durante il caricamento delle Shape dell’SVG, è la seguente:

const result = THREE.BufferGeometryUtils.mergeBufferGeometries(geometriesArray);

Tale funzione permette di unire in un unica geometria tutte le geometrie presenti nell’array di geometrie passato alla funzione. Tale oggetto può essere poi facilmente convertito in Mesh e aggiunta alla scena corrente che la renderizzerà a video.

Creazione di una estrusione lungo direzioni arbitrarie basate su punti

Three.js implementa di base la funzione THREE.ExtrudeGeometry che permette di estrudere una Shape. Uno dei parametri che si possono passare alla funzione è la path lungo cui estrudere la forma. Sebbene questa sia una funzionalità molto interessante soffre di due problemi principali: crea un’unica geometria finale e non è possibile generare geometrie chiuse. Seppur utile i contesti di applicazione sono molto ristretti spesso a demo o semplici trasformazioni di oggetti da 2D a 3D spessorato.

L’obiettivo è invece quello di implementare una funzione che permetta, passando la forma della Shape e una serie di punti 2D, di estrudere la forma nella direzione di quei punti nello spazio, poter decidere se le componenti geometriche sono separate e implementare un metodo per chiudere l’estrusione generata (affinché non vi sia un sormontare tra la prima geometria e l’ultima). Esistono diversi approcci a questo tipo di attività e vanno tutti nell’usare sapientemente gli indici della geometria calcolando l’angolo tra i bordi del contorno e applicando matrici di taglio/trasformazione, rotazione e traslazione ai punti del profilo per ciascun punto del contorno.

for (let i = 0; i < this.pathPoints.length; i++)
{
    let angle1 = 90;    //Arbitrario
    let angle2 = 45;    //Arbitrario

    let cutAngle = angle2 - angle1;
    let oppositeAngle = (Math.PI * 0.5) + angle2;

    let side = new THREE.Matrix4().set(1, 0, 0, 0, -Math.tan(cutAngle * 0.5 - Math.PI * 0.5), 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1);
    THREE.ShapeGeometry(shape).attributes.position.applyMatrix4(side);

    let rotation = new THREE.Matrix4().set(Math.cos(oppositeAngle), -Math.sin(oppositeAngle), 0, 0, Math.sin(oppositeAngle), Math.cos(oppositeAngle), 0, 0, 0, 0, 1, 0, 0, 0, 0, 1);
    THREE.ShapeGeometry(shape).attributes.position.applyMatrix4(rotation);

    let move = new THREE.Matrix4().set(1, 0, 0, pathPoints[i].x, 0, 1, 0, pathPoints[i].y, 0, 0, 1, 0, 0, 0, 0, 1);
    THREE.ShapeGeometry(shape).attributes.position.applyMatrix4(move);
}

Tagli ad angoli arbitrari

Come visto il passaggio precedente crea estrusioni lungo direzioni arbitrarie, anche di geometrie che devono essere necessariamente chiuse. E’ possibile però specificare alla funzione di produrre unicamente la Shape estrusa originaria ed utilizzare le estrusioni secondarie unicamente come elemento di rimozione dei punti eccedenti e quindi generare tagli ad angoli arbitrari.

L’espediente che possiamo usare è quantomai semplice: si può definire un booleano che nei cicli di generazione degli indici della geometria risultante escluda quelli che generano la componente grafica dell’estrusione ad angolo. Otterremo così un profilo estruso in due direzioni ma di cui la seconda parte della geometria non viene renderizzata. In sostanza stiamo usando le geometrie estruse unicamente per “scavare” la geometria di interesse. Questo approccio permette di non dover riscrivere la funzione del punto precedente ma invece di riutilizzarla per questo contesto. Seppur con qualche calcolo di troppo risulta comunque la soluzione vincente in termini di implementazione e di riusabilità del codice.

Qui sotto un taglio a 45° in cui viene mostrata, unicamente per debug, l’estrusione usata per generarlo:

Qui sotto due semplici esempi ottenuti con un taglio da 45° e uno da 30°:

Specchiatura della Mesh risultante (se necessario)

Per poter utilizzare la Mesh prodotta anche in situazioni dove il profilo deve trovarsi in situazione specchiata è necessario attuare una semplice operazione di inversione dei punti. L’approccio più semplice è quello di usare un espediente basato sulla scalatura al quale viene passato una unità con valore negativo, sull’asse di specchiatura desiderato.

La semplice funzione da utilizzare è la seguente (specchiatura su asse X):

mesh.scale.multiply(new THREE.Vector3(-1,1,1));

Considerazioni sulla velocità di esecuzione

E’ chiaro che parlando di Three.js e rendering realtime sul web sia strettamente necessario tenere in considerazione la velocità di esecuzione di operazioni così a basso livello. Proprio perchè operazioni a basso livello (siamo partiti da un file SVG caricato da disco, passando da oggetti Path e Shape, da geometrie ricalcolate, estrusioni e tagli arbitrari) esse sono altamente performanti.

Dai nostri test il caricamento di un .svg semplice da disco con la creazione di un riquadro sagomato tramite Shape a forma di cuore ha impiegato tra i 10 e i 15 millisecondi in totale contemplando il caricamento del file, la generazione delle Shape e delle geometrie, la normalizzazione, l’estrusione arbitraria e il taglio di 4 oggetti (uno per lato, colorati nell’immagine sottostante).

In alcuni contesti specifici dell’uso di Three.js può essere necessario lavorare intensivamente con l’oggetto THREE.Shape (il quale è una estensione dell’oggetto THREE.Path); viene solitamente usato durante il caricamento di file SVG (tramite THREE.SVGLoader) in quanto rappresenta bene un profilo 2D vettoriale.

Lavorando con questo oggetto può rendersi necessario attuare delle operazioni di ridimensionamento o scalatura in quanto spesso le forme posso avere dimensioni eccessive o fuori scala. Per questo motivo di seguito vengono riportate 3 funzioni Javascript fondamentali durante l’uso di THREE.Shape.

Calcolare la dimensione di una Shape

Funzione per il calcolo delle componenti larghezza e altezza (su un piano 2D) dell’oggetto THREE.Shape.

function GetShapeSize(shape)
{
    let boundingBox = new THREE.Box2();
    boundingBox.setFromPoints(shape.getSpacedPoints(100));
    let bbWidth = boundingBox.max.x - boundingBox.min.x;
    let bbHeight = boundingBox.max.y - boundingBox.min.y;
    return { width:bbWidth, height:bbHeight };
}

Ridimensionare una Shape tramite fattore di scala

Funzione per scalare un oggetto THREE.Shape di due fattori di scala distinti (X e Y).

function GetShapeScaled(shape, scaleX, scaleY) 
{
    const points = shape.getSpacedPoints(100);
    const resizedPoints = points.map(point => {
        return new THREE.Vector2(point.x * scaleX, point.y * scaleY);
    });

    const resizedShape = new THREE.Shape(resizedPoints);
    return resizedShape;
}

Ridimensionare una Shape a dimensioni specifiche

Funzione per ridimensionare un oggetto THREE.Shape a valori di larghezza e altezza definiti.

function GetShapeResized(shape, targetWidth, targetHeight)
{
    const boundingBox = new THREE.Box2();
    boundingBox.setFromPoints(shape.getSpacedPoints(100)); 

    const originalWidth = boundingBox.max.x - boundingBox.min.x;
    const originalHeight = boundingBox.max.y - boundingBox.min.y;

    const scaleX = targetWidth / originalWidth;
    const scaleY = targetHeight / originalHeight;

    const points = shape.getSpacedPoints(100);
    const resizedPoints = points.map(point => {
        return new THREE.Vector2(point.x * scaleX, point.y * scaleY);
    });

    const resizedShape = new THREE.Shape(resizedPoints);
    return resizedShape;
}

Come nella Parte 1 e nella Parte2, ci occuperemo di indicare in questo post tutti quegli spunti e riflessioni su Three.js che da uno studio superficiale della libreria potrebbero sfuggire. Sono argomenti tecnici particolari e profondi che però cercano di mettere in guardia lo sviluppatore da potenziali problemi ed errori.

L’antialiasing sul Render Composer non funziona

E’ bene ricordare che se si utilizza il Render Composer per visualizzare la propria scena, l’attributo antialising:true del renderer non ha valenza. Le uniche due possibilità sono:

• Aggiungere un FXAA Pass dentro il flusso di render pass prima di renderizzare l’output, avendo cura di passare la risoluzione corretta
• Passare al WebGLRenderTarget il parametro “samples: 4” (o un valore definito) durante la sua creazione (ma non è compatibile con WebGL1) – Dalla versione 138 di WebGLMultisampleRenderTarget è stato rimosso in favore del parametro samples

Se si utilizza il MaskPass è necessario abilitare lo Stencil Buffer

Se durante l’utilizzo del Render Composer si rende necessario l’inserimento di MaskPass (e ClearMaskPass) è necessario abilitare nel WebGLRenderTarget, passato al momento delle creazione del Composer, il parametro “stencilBuffer: true”

Debuggare il Frame Buffer non è facile

Qualora servisse avere una visualizzazione chiara di tutti i passaggi di rendering del Frame Buffer della scena corrente, l’unica soluzione è affidarsi ad un sistema di monitoraggio esterno. In questo caso si rende molto utile l’estensione Chrome chiamata Spectator.js, installabile attraverso questo link.

Impostare correttamente l’environment map

Quando si imposta l’environmentMap e la background texture di una scena è sempre necessario impostare un ToneMapping del renderer.

Come nella Parte 1, ci occuperemo di indicare in questo post tutti quegli spunti e riflessioni su Three.js che da uno studio superficiale della libreria potrebbero sfuggire. Sono argomenti tecnici particolari e profondi che però cercano di mettere in guardia lo sviluppatore da potenziali problemi ed errori.

La funzione repeat delle textures di un materiale è condivisa

Da come è strutturata la gestione delle singole textures può sembrare che applicando il .repeat.set questo possa essere fatto indipendentemente su qualsiasi mappa del materiale, ad esempio map(1,1) e emissiveMap(3,3). In realtà non è così in quanto il repeat è condiviso su tutte le mappe del materiale, con questa priorità:

• color map
• specular map
• displacement map
• normal map
• bump map
• roughness map
• metalness map
• alpha map
• emissive map

Questo NON si applica alla “light map”, alla “ao map” e alla “env map” che invece sono riferite ad un uv set differente.

In sostanza Three.js considera che tutto quello che riguarda la definizione del materiale in sé abbia lo stesso repeat, mentre ciò che riguarda la definizione di attività esterne al materiale (appunto luci o ambiente) abbia un repeat differente. E’ quindi inutile impostare tutti i repeat se si hanno mappe diverse ma unicamente quello della color map (se ovviamente si ha la color).

Il calcolo delle dimensioni del BoundingBox di una TextGeometry è sbagliato

Purtroppo il primo approccio che si pensa al calcolo delle dimensioni di un elemento TextGeometry è quello di utilizzare la funzione getSize della geometria, come segue:

let textMeshMeasures = new THREE.Vector3();
textMesh.geometry.boundingBox.getSize(textMeshMeasures);

Purtroppo tale calcolo risulta essere errato in quanto non tiene in considerazioni eventuali scalature, padding etc.

Per eseguire correttamente il calcolo delle dimensioni (width, height, depth) è necessario usare questo approccio (il quale è utilizzato anche nel file BoxHelper di Threejs stesso):

let box = new THREE.Box3();
box = box.setFromObject(textMesh);
let textMeshMeasures = new THREE.Vector3();
box.getSize(textMeshMeasures);

Il raycast può dare problemi con elementi di tipo Line

Ad esempio quando si esegue il raycast per individuare gli oggetti cliccati in scena, l’oggetto Raycaster ritorna un array di intersezioni con tutti gli oggetti coinvolti. Se in scena sono presenti delle mesh creare con THREE.Line può includere intersezioni non veritiere (dopotutto a chi può servire fare un raycast su delle linee). Il consiglio è quindi, prima di interrogare l’array, di eseguire una funzione .filter sull’array.

Per disegnare il raggio è possibile usare questa funzione:

let arrow = new THREE.ArrowHelper(raycaster.ray.direction, raycaster.ray.origin, 100, Math.random() * 0xff0000);

Gestione dello z-fighting

Può capire di dover gestire lo z-fighting per poligoni con la stessa coordinata (ad esempio con z = 0). Lo z-fighting è quell’artefatto grafico dove la pipeline di rendering non capisce quale poligono disegnare prima di un altro e dunque può generare problemi di visualizzazione. Una delle soluzioni è spostare di poco la coordinate per gli elementi che si vogliono renderizzare prima/dopo. In ThreeJS esiste però un altro metodo da applicare al materiale del poligono stesso, da usare nel modo seguente:

material.depthTest: true,
material.depthWrite: false,
material.polygonOffset: true,
material.polygonOffsetFactor: -4

più il valore di Factor è inferiore (anche negativo) e più il poligono viene renderizzato per primo.
E’ da indicare che questo metodo non funziona con poligoni associati a LineBasicMaterial.

Gestione dell’ordine delle trasparenze

Sfortunatamente, l’alpha blending (material.transparent = true) introduce molta complessità nel processo di rendering e rende i risultati molto sensibili all’ordine di rendering. Anche quando si imposta material.opacity=1, si possono comunque ottenere risultati significativamente diversi rispetto a un oggetto opaco con material.transparent = false. Non esistono soluzioni “perfette” che funzionino in tutti i casi, ma ci sono alcune soluzioni alternative che si possono provare:

• Utilizzare material.DepthWrite = true sui materiali trasparenti
• Impostare material.transparent=false una volta che l’opacità dell’oggetto è a 1
• Impostare renderer.sortObjects: true

Three.js è una potente libreria per implementare WebGL (e quindi grafica 3D realtime) nel browser.

E’ indubbiamente la libreria con la community più attiva (Github, Stackoverflow, etc) ma molto spesso i problemi, e le loro risoluzioni, scalfiscono solo la superficie delle potenzialità di tale libreria in quanto la quasi totalità degli utilizzi si ferma ad un suo uso basilare.

Di seguito una raccolta, costantemente aggiornata, di spunti e riflessioni su argomenti non propriamente “di base” ma con cui sicuramente ci si può scontrare appena si entra nel vivo dell’utilizzo di Three.js

Risolvere aberrazioni visive di Z-buffer dovute alla distanza delle camera

Il problema dello Z-buffer è uno dei più noti in ambito 3D in quanto produce delle aberrazioni visive notevoli in concomitanza con la distanza degli oggetti rispetto alla camera. Questo perché il Depth Buffer non riesce a visualizzare correttamente superfici che si sono in overlap (o quasi).

Per ovviare a questo problema, Three.js espone un parametro del renderer che imposta il Depth Buffer su scala logaritmica e che, se impostato a true (non di default), non mostra aberrazioni di sorta.

renderer.logarithmicDepthBuffer = true;

Qui si può trovare un approfondimento “matematico” al problema.

E’ da segnalare come l’abilitazione di questa opzione possa impattare negativamente sulle performance dell’antialias del renderer.

Ottimizzare le ombre di una scena statica

Qualora si debba lavorare con una scena statica (quindi senza elementi in scena che si muovono come modelli o le luci stesse), è possibile ottimizzare la scena generale disabilitando, dopo qualche istante, l’aggiornamento automatico delle ombre (della shadowMap). Questo farà in modo che nei primi istanti la shadowMap venga generata correttamente ma subito dopo non venga più ricalcolata. Eventualmente, se qualcosa in scena si potrà muovere, si potrà riabilitare e disabilitare tale funzione.

setTimeout(() => { this.renderer.shadowMap.autoUpdate = false; }, 500);

Caricare una immagine HDR ed assegnarla come envMap ad ogni materiale fisico in scena

Per scene statiche è possibile ottimizzare l’uso delle luci escludendo quelle dinamiche in scena (point, direction, etc) ed implementando un ambiente con immagine HDR (un particolare formato “raw” che include tutto lo spettro dei colori). Questa tecnica permette di illuminare gli oggetti in scena utilizzando le informazioni presenti in tale immagine. E’ necessario caricare (attraverso il componente aggiuntivo RGBELoader di Three.js) una immagine .hdr, mapparla come EquirectangularReflectionMapping e impostarla per il background e l’environment della scena, unitamente a specificarla in ogni mappa envMap degli oggetti Mesh presenti.

 new THREE.RGBELoader().load('Contrastata.hdr', function (texture) {
    texture.mapping = THREE.EquirectangularReflectionMapping;
    mainScene.background = texture;
    mainScene.environment = texture;
    mainScene.traverse(function (obj) {
        if (obj instanceof THREE.Mesh) {
            try {
                obj.material.envMap = texture;
                obj.material.envMapIntensity = 1.0;
            } catch{ console.log(obj.name + ": setting envMap ERROR"); }
        }
    });
});

Qui il download della immagine HDR dell’esempio.

Flippare le mappe dei materiali di un file GTLF/GLB sull’asse verticale (V)

Sembra essere una prerogativa del formato .gltf/.glb ma, qualora si volesse applicare una mappa ad un materiale di un file esportato in tale formato, è necessario invertire l’asse verticale della mappa UV (quindi sull’asse V).
Di seguito un modo semplice per flippare entrambi gli assi a piacimento.

let repeatX, repeatY = 1.0;
let flipU = false;
let flipV = true;
texture.center.set(0.5, 0.5);
texture.repeat.set(repeatX * (flipU ? -1 : 1), repeatY * (flipV ? -1 : 1));

Aggiungere un set di coordinate UV2 aggiuntivo ad una mesh

Può capitare di dover aggiungere un set aggiuntivo di coordinate ad una mesh, ad esempio per collocare una aoMap generata custom. Per fare questo l’unico modo plausibile è quello di duplicare il primo set (solitamente già presente) attraverso questa semplice associazione:

child.geometry.setAttribute('uv2', child.geometry.attributes.uv);

Gestire le coordinate UVs in un modello GLTF

Come da guida di Three.js, la mappa di Ambient Occlusion (aoMap) e quella delle luci (lightMap) necessita di un set di UV differente rispetto alle altre mappe dei materiali. Questo perché è logico pensare che il primo set riguardi la possibilità di ruotare, ripetere o scalare a piacimento l’aspetto estetico del materiale, mentre il secondo riguarda informazioni di mappa proveniente da un calcolo di scena che tendenzialmente è fisso (luci, ombre, occlusioni, etc).

Il formato GLTF, per quanto riguarda le UVS, considera questi assunti:

• Se è presente una sola UV: questa viene impostata sull’attributo geometry.attributes.uv (solitamente la Color Map)
• Se sono presenti due UVs: sull’attributo geometry.attributes.uv viene associata la Baked Map (es: aoMap), sull’attributo geometry.attributes.uv2 viene associata la Color Map

Come si può immaginare questo crea non pochi problemi in quanto la Color Map (la mappa principale di un materiale, presente praticamente sempre) si può trovare in due posizioni diverse in base ai casi (uv o uv2). Per questo motivo può essere necessario prevedere una modalità per invertire le mappature in modo da riportare la Color Map sempre sulla uv (e non uv2), cosi:

if (child.geometry.attributes.uv != null && child.geometry.attributes.uv2 != null) {
    let tempUV = child.geometry.attributes.uv2;
    child.geometry.setAttribute('uv2', child.geometry.attributes.uv);
    child.geometry.setAttribute('uv', tempUV);
}

Ottimizzare il filtro anisotropico

Il filtro anisotropico applicato alle mappe dei modelli permette di ridurre la sfuocatura delle texture sulla distanza. Di base questo valore è 1, oggettivamente molto basso. In nostro aiuto c’è una funzione del renderer che ritorna il valore anisotropico massimo impostabile dalla scheda video. Tale valore è solitamente un multiplo di 2 (2, 4, 8, 16, etc). Un valore troppo alto però mostra le immagini in modo troppo nette producendo anch’esso (strano a dirsi) artefatti sulla distanza. Per questo motivo il consiglio è di dividere per 2 il valore ritornato dalla funzione del renderer.

texture.anisotropy = renderer.capabilities.getMaxAnisotropy() / 2;