Three.js SVGLoader: dalla grafica piana alla mesh 3D

Per trasformare grafica SVG piana in una mesh Three.js, carica l'SVG, converti i tracciati in forme e passa quelle forme a ExtrudeGeometry. Controlla fori, orientamento verticale e dimensioni prima di aggiungere effetti. Una sagoma riconoscibile può comunque avere un'apertura riempita o un angolo capovolto.

Questa guida pratica usa un distintivo originale scritto a mano con un'apertura quadrata e un angolo superiore destro tagliato. L'asimmetria rende visibile un errore di orientamento. È un esempio di geometria nel browser, non un risultato di conversione PerfectVector né una prova di fabbricazione.

Inizia dalle forme a cui vuoi dare profondità

Usa un piccolo SVG con contorni chiusi e riempiti per il primo tentativo. Salva questo codice come badge.svg:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 240 180">
  <path fill="#e64b35" fill-rule="evenodd"
    d="M20 20H160L220 80V160H20Z M65 60H115V110H65Z"/>
</svg>

Ci sono due sottotracciati chiusi dentro un solo elemento path: un contorno esterno e un quadrato interno. La regola di riempimento evenodd rende quella regione interna un'apertura. Un rettangolo bianco separato coprirebbe soltanto la faccia in un'immagine piana; non descriverebbe la stessa regione vuota.

La grafica occupa 200 per 140 unità di coordinate dentro un viewBox di 240 per 180. Tieni presente questa differenza quando dimensioni la mesh. I margini vuoti fanno parte dell'area di visualizzazione SVG, non della sagoma estrusa.

Se hai un originale vettoriale modificabile, usalo. Se l'unico sorgente è un PNG o JPG, la procedura da immagine a vettore di PerfectVector può aiutarti a preparare grafica SVG composta da tracciati. Ispeziona l'anteprima e i contorni scaricati, soprattutto gli spazi negativi, prima di caricare il file in Three.js. La vettorializzazione fornisce la grafica 2D; il codice sotto fornisce profondità, materiali, illuminazione e posizionamento.

Carica l'SVG e renderizza la mesh

L'esempio è stato verificato con Three.js 0.186.0. Mantieni libreria principale e componente aggiuntivo alla stessa versione. In un progetto browser con importazioni di pacchetti, installa three@0.186.0, servi i file tramite HTTP e crea un contenitore:

<div id="viewer"></div>
<script type="module" src="./main.js"></script>

Lo strumento di compilazione deve risolvere le importazioni three. Per una pagina browser semplice senza strumento di compilazione, inserisci questa mappa di importazione prima dello script modulo, usando i file dello stesso pacchetto installato:

<script type="importmap">
{
  "imports": {
    "three": "./node_modules/three/build/three.module.js",
    "three/addons/": "./node_modules/three/examples/jsm/"
  }
}
</script>

Metti badge.svg accanto alla pagina HTML. L'URL relativo di caricamento sotto viene risolto rispetto all'URL di quella pagina. Salva poi questo codice come main.js:

import * as THREE from 'three';
import { SVGLoader } from 'three/addons/loaders/SVGLoader.js';
 
const data = await new SVGLoader().loadAsync('./badge.svg');
const artwork = new THREE.Group();
for (const path of data.paths) {
  if (path.userData.style.fill === 'none') continue;
  for (const shape of path.toShapes()) {
    const geometry = new THREE.ExtrudeGeometry(shape, {
      depth: 20, bevelEnabled: false, steps: 1
    });
    const material = new THREE.MeshStandardMaterial({
      color: path.color, roughness: 0.65, metalness: 0
    });
    artwork.add(new THREE.Mesh(geometry, material));
  }
}
if (!artwork.children.length) throw new Error('No filled shapes found');
 
// SVG y grows down; this scene uses y up.
artwork.scale.y = -1;
const bounds = new THREE.Box3().setFromObject(artwork);
const size = bounds.getSize(new THREE.Vector3());
const center = bounds.getCenter(new THREE.Vector3());
const scale = 4 / size.x;
artwork.scale.multiplyScalar(scale);
artwork.position.copy(center).multiplyScalar(-scale);
 
const scene = new THREE.Scene();
scene.background = new THREE.Color('#f1f3f5');
scene.add(artwork);
scene.add(new THREE.HemisphereLight(0xffffff, 0x596477, 2));
const light = new THREE.DirectionalLight(0xffffff, 3);
light.position.set(-3, 5, 7);
scene.add(light);
const camera = new THREE.PerspectiveCamera(35, 800 / 600, 0.1, 100);
camera.position.set(4, 3, 9);
camera.lookAt(0, 0, 0);
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(800, 600);
document.querySelector('#viewer').append(renderer.domElement);
renderer.render(scene, camera);

SVGLoader è un componente aggiuntivo importato separatamente. loadAsync() legge il file; parse(svgText) è l'alternativa quando possiedi già il markup SVG come stringa.

In r186, usa path.toShapes(). Gli esempi meno recenti chiamano spesso SVGLoader.createShapes(path). Quella funzione è stata deprecata in r185 e delega a toShapes() nella versione verificata. Controlla la versione installata prima di mescolare frammenti di tutorial diversi.

Il ciclo salta deliberatamente fill="none". Gestisce i riempimenti pieni di questo esempio; non è un renderer SVG completo. Gradienti, maschere, immagini incorporate, tratti, opacità e livelli di colore sovrapposti richiedono decisioni proprie, anziché presumere che l'aspetto piano diventi geometria 3D identica.

Imposta l'orientamento prima di misurare e centrare

Le coordinate verticali dell'SVG aumentano verso il basso. Questa scena guarda la grafica con y positiva rivolta verso l'alto, quindi artwork.scale.y = -1 ripristina l'orientamento previsto. L'angolo tagliato è il controllo: deve trovarsi in alto a destra.

Quel cambiamento di segno appartiene a questa configurazione delle coordinate. Non aggiungere un secondo ribaltamento perché la mesh sembra ancora sbagliata dopo aver ruotato una camera o un oggetto genitore. Confronta prima una caratteristica asimmetrica nota del sorgente con la scena renderizzata.

Le righe successive misurano il gruppo ribaltato, calcolano una scala uniforme e spostano il suo centro ridimensionato all'origine. Box3.setFromObject() misura i limiti includendo gli oggetti figli e le loro trasformazioni. Qui il gruppo non ha un genitore trasformato né una rotazione della grafica al momento della misurazione.

L'estrusione originale misura 200 per 140 per 20. Impostare la larghezza a 4 dà una scala di 4 / 200, ovvero 0.02. Poiché la scala si applica a tutti e tre gli assi, i limiti risultanti sono 4 per 2.8 per 0.4. Una profondità di 20 nel costruttore non rimane 20 dopo il ridimensionamento del gruppo.

Sono unità della scena. L'esempio non afferma che un'unità equivalga a un millimetro. Se l'applicazione richiede una particolare interpretazione fisica, definiscila esplicitamente e convalidala attraverso la procedura di destinazione.

Conferma il foro prima di decorare la superficie

La prova ha prodotto un tracciato caricato, una forma e un foro. Abbiamo anche proiettato un raggio attraverso l'apertura quadrata e un altro attraverso l'area piena: l'apertura non ha restituito intersezioni con la mesh, mentre l'area piena ne ha restituita una. Raggi attraverso l'angolo superiore destro tagliato e quello inferiore destro pieno hanno confermato l'orientamento verticale indipendentemente dalla vista inclinata.

Puoi iniziare con un controllo visivo più semplice nella tua scena: guarda la faccia frontalmente, poi inclinata contro uno sfondo contrastante. L'apertura dovrebbe mostrare lo sfondo, e le sue pareti laterali dovrebbero apparire quando la camera si muove. Una faccia bianca che copre l'area è un risultato diverso.

Se un'apertura si riempie, isola quella sola forma. Ispeziona se il sorgente usa sottotracciati, oggetti riempiti separati, un tracciato di ritaglio o una maschera. Non cercare di nascondere il problema con il colore del materiale. La guida ai fori SVG che si riempiono spiega le distinzioni nel file sorgente; la diagnosi dell'estrusione tratta la riparazione dei contorni quando la grafica sottostante è difettosa.

Aggiungi effetti di profondità soltanto dopo che l'estrusione semplice funziona

L'esempio disattiva gli smussi affinché le dimensioni iniziali siano facili da ispezionare. Le opzioni ExtrudeGeometry controllano separatamente profondità, dimensione dello smusso, spessore dello smusso e campionamento delle curve. Ricontrolla piccole aperture e limiti quando attivi gli smussi. Un bordo decorativo cambia la geometria appena misurata.

Per grafica curva, ispeziona la sagoma della mesh alle dimensioni e alla distanza della camera usate dall'applicazione. Aumenta il campionamento delle curve soltanto quando le sfaccettature lo richiedono; ridurre i nodi inutili dell'input è un'attività separata di modifica. Nessuna delle due impostazioni ripristina dettagli assenti dal sorgente.

Anche un disegno composto soltanto da tratti richiede una decisione diversa. Il caricatore espone pointsToStroke() per la geometria dei tratti, ma il ciclo delle forme riempite sopra omette intenzionalmente quei tracciati. Se la linea visibile deve diventare un nastro estruso, decidi prima quale contorno chiuso definisce quel nastro. Se deve rimanere una linea nella scena, costruisci invece una rappresentazione come linea o tratto.

Per un'applicazione React, esegui il caricamento e il lavoro del renderer riservati al browser sul client e libera geometria, materiali e renderer di tua proprietà quando la vista viene rimossa. L'esempio compatto renderizza una volta a dimensioni fisse; un visualizzatore di produzione richiede anche la gestione del ridimensionamento e un proprio ciclo di vita delle risorse.

Mantieni separati i controlli del sorgente e della destinazione

Una mesh nel browser è utile per un distintivo interattivo, un'anteprima di logo o una decorazione di scena. Non dimostra che il risultato sia un pezzo con una mesh chiusa (watertight) e dimensioni adatte allo scopo. Se la destinazione è la fabbricazione, usa la procedura separata da immagine a SVG per la stampa 3D e ispeziona lì il modello importato.

Per la procedura a schermo, mantieni distinti tre file o stadi: sorgente SVG modificabile, mesh derivata e presentazione della scena. Questo rende più facile capire se un risultato errato proviene dalla geometria dei tracciati, dalla costruzione della mesh o da camera e illuminazione. Altre guide alle procedure SVG trattano il sorgente quando la grafica richiede riparazioni prima del caricamento.

FAQ

Perché il mio SVG è capovolto in Three.js? Le coordinate verticali SVG aumentano verso il basso. In una scena con y positiva verso l'alto che guarda il fronte della grafica, ribaltare la scala y del gruppo grafico può ripristinare l'orientamento sorgente. Controlla una caratteristica asimmetrica prima di aggiungere un altro ribaltamento o una rotazione.

Devo usare createShapes o toShapes? Questo esempio usa path.toShapes() con Three.js 0.186.0. SVGLoader.createShapes() è stato deprecato in r185. Usa l'API documentata per la versione installata nel progetto, con pacchetto principale e componente aggiuntivo alla stessa versione.

SVGLoader trasforma un PNG dentro un SVG in una mesh? Un'immagine raster incorporata non fornisce i contorni riempiti usati da questo esempio. Ottieni prima grafica adatta composta da tracciati, oppure usa l'immagine come texture quando l'obiettivo effettivo è conservarne l'aspetto.

L'estrusione conserva lo spessore del tratto SVG? Questo esempio estrude forme riempite e salta i tracciati con fill impostato a none. La geometria dei tratti richiede una procedura separata; una linea disegnata spessa non è automaticamente il contorno chiuso di un nastro estruso.

Fonti

1. Three.js — SVGLoader — Documenta l'importazione del componente aggiuntivo, metodi di analisi e caricamento, funzione per i tratti e deprecazione di createShapes.
2. Three.js — ShapePath — Documenta la conversione di raccolte di tracciati in forme con toShapes.
3. Three.js — ExtrudeGeometry — Definisce estrusione delle forme e opzioni di profondità, smusso e campionamento delle curve.
4. Three.js — Box3 — Documenta la misurazione dei limiti di oggetti trasformati e come ottenerne dimensioni e centro.

Lavori da un emblema solo raster? Prepara un candidato SVG, ispeziona contorni riempiti e aperture, poi prova quel file in questa piccola scena prima di costruire il visualizzatore completo.