Buone pratiche
3DVue

Formati accettati

La piattaforma 3DVue accetta diversi formati 3D. GLTF è il formato raccomandato — offre il miglior rapporto qualità/dimensione file per il rendering web in tempo reale.

Convertire da SolidWorks — STEP / STL → GLTF

I file di software CAD (SolidWorks, Fusion 360, CATIA) sono generalmente in formato .STEP, .STP o .STL. Devono essere convertiti prima dell'integrazione.

1. Aprire FreeCAD
2. Importare il file STEP/STL
   Ctrl + I → selezionare il file .stp o .stl

3. Esportare in GLTF o DAE
   Ctrl + E → scegliere il formato DAE o GLTF

Convertitore online (alternativa rapida):
   https://imagetostl.com/fr/convertir/un-fichier/stp/en/glb

Esportazione da Blender

Se lavorate direttamente in Blender, ecco le impostazioni di esportazione GLTF raccomandate per la piattaforma 3DVue. Usare la compressione Draco riduce significativamente la dimensione del file.

Formato:          glTF Binary (.glb)  ← raggruppa tutto in un file
Compressione:     Draco attivato      ← riduce la dimensione del 60-80%
Texture:          Includi → spuntare
Materiali:        Esporta materiali → spuntare
Trasformazioni:   Applica → spuntare   ← obbligatorio, vedere sezione Trasformazioni

Nomenclatura delle collezioni in Blender

Gli script automatizzano l'esportazione dei file GLTF e delle mappe UV. Per funzionare correttamente, le collezioni di Blender devono seguire una struttura precisa.

Collection
  └── nome-prodotto           ← senza accenti né spazi
        ├── modelisation         ← tutti gli oggetti 3D
        └── gltf                 ← file di esportazione generati

Esempi corretti:
  nome-prodotto: butterfly-chair      ✓
  nome-prodotto: tolix-chair-a        ✓

Esempi errati:
  nome-prodotto: Butterfly Chair      ✗ maiuscole + spazio
  nome-prodotto: sedia-scaffalé       ✗ caratteri accentati

Trasformazioni & scala

• Applicare sempre le trasformazioni Ctrl + A → Tutte le Trasformazioni prima di esportare — altrimenti le mappe UV sono errate
• Lavorare a scala 1 (scala reale in metri) — evita errori di scala nel configuratore
• Se un oggetto non tocca il suolo (es. una lampada a sospensione), aggiungere un piano invisibile chiamato RA di dimensione 0.0001m in posizione 0,0,0 per la realtà aumentata

Addon consigliati per Blender

Questi addon sono usati sistematicamente dal team di 3DVue per garantire UV di qualità su tutti i progetti.

Coerenza della Texel Density

La densità texel definisce quanti pixel di texture coprono una determinata superficie reale. Se due oggetti dello stesso cliente hanno densità texel diverse, una texture in legno apparirà a scale diverse su ciascun oggetto — il che non è realistico.

Privilegiare sviluppi UV basati su cuciture con il metodo Conformal — eccetto per oggetti di colore uniforme che non richiedono uno sviluppo preciso.

UV per BAT SVG

Quando il configuratore usa un BAT SVG (personalizzazione con caricamento logo o testo), si applicano regole aggiuntive allo sviluppo UV.

• Tutti gli UV devono rientrare in un'unica mappa UV
• Esportare la mappa UV a 4096×4096 px
• Il GLTF deve corrispondere esattamente alla mappa UV esportata
• Uno script Blender automatizza l'esportazione del GLTF e della mappa UV — le collezioni devono essere correttamente nominate perché funzioni
• Se necessario, dipingere sulla mappa UV per aiutare a creare il file Illustrator (allineamento dei pattern)

Nomenclatura dei file di texture

Ogni canale PBR corrisponde a un file di texture con un nome standardizzato. La piattaforma identifica il ruolo di ogni texture tramite il suo nome.

Formati & risoluzione

• Formato quadrato obbligatorio — 1024×1024 o 2048×2048 (massimo 2K)
• Formato file: PNG (raccomandato per trasparenza e qualità) o JPEG (dimensione file più leggera)
• Una mappa normal troppo pesante può essere compressa senza perdita tramite imagecompressor.com

Regole generali

• Formato quadrato obbligatorio, risoluzione 4K (4096×4096 px)
• Nomenclatura: BAT-nomemodello-dimensione_albedo.svg
• Nessun carattere accentato, nessuno spazio nel nome del file
• Tutti gli elementi modificabili devono essere vettorizzati nell'SVG — nessun elemento raster

Formato:  BAT-nomemodello-dimensione_albedo.svg

Esempi:
  BAT-maglietta-tagliaL_albedo.svg    ✓
  BAT-tazza-25cl_albedo.svg           ✓
  BAT-maglietta taglia L albedo.svg   ✗ spazi non ammessi
  BAT-maglietta-tagliaé_albedo.svg    ✗ caratteri accentati non ammessi

Struttura dei livelli in Illustrator

I livelli di Illustrator devono essere organizzati secondo una struttura precisa perché il configuratore possa identificare le zone modificabili e le zone di riferimento.

Esportazione SVG da Illustrator

• Vettorizzare tutti gli elementi modificabili prima di esportare — Shift + Ctrl + O
• Nominare il file esportato con la convenzione nomedesign_albedo.svg
• Nessun elemento raster nel file esportato — tutto deve essere vettoriale
• Verificare che i livelli gabarit e présentation siano nascosti durante l'esportazione

Includere lo script

Aggiungete lo script una volta nel vostro <head> o prima di </body>. Una sola inclusione è sufficiente per tutte le pagine del vostro sito.

<script src="https://cdn.jsdelivr.net/gh/3dvue/api@v4/viewer-3dvue-min.js"></script>

Dichiarare il componente

Posizionate il tag <viewer-3dvue> dove volete che appaia il viewer. Due attributi sono obbligatori: name (identificatore unico nella pagina) e src (URL del vostro configuratore, fornita da 3DVue alla consegna).

<!-- Attributi obbligatori -->
<viewer-3dvue
  name="mioViewer"
  src="https://app.3dvue.fr/view?p=AB01-CD02"
></viewer-3dvue>

<!-- Con debug attivato (log in console) -->
<viewer-3dvue
  name="mioViewer"
  src="https://app.3dvue.fr/view?p=AB01-CD02"
  debug
></viewer-3dvue>

Controllo senza JavaScript

Il componente ascolta automaticamente gli eventi click e change su qualsiasi elemento che abbia i seguenti attributi. Nessun JavaScript necessario.

<!-- Pulsante che cambia più materiali al clic -->
<button
  viewer-3dvue="mioViewer"
  viewer-3dvue-clic="setMaterial"
  viewer-3dvue-meshs-materials='{"1":"0n","3":"2b"}'
>
  Blu Notte
</button>

<!-- Select che applica il valore scelto -->
<select
  viewer-3dvue="mioViewer"
  viewer-3dvue-change="setMaterial"
  viewer-3dvue-mesh="2,4"
>
  <option value="0n">Rosso</option>
  <option value="1a">Blu</option>
</select>

API JavaScript

Per casi avanzati — caricamento dinamico, cattura immagine, esportazione SVG. Recuperare il riferimento del componente tramite querySelector.

Eventi

Ascoltare gli eventi direttamente sull'elemento viewer-3dvue tramite addEventListener.

// Ottenere il riferimento del componente
const viewer = document.querySelector('viewer-3dvue[name="mioViewer"]');

// Attendere che il viewer sia pronto (consigliato per loadFonts)
viewer.addEventListener("onLoadComplete", () => {
  viewer.loadFonts([{ family: "Bebas Neue" }, { family: "Pacifico" }]);
});

// Cambiare materiali
viewer.setMaterial({ "1": "0n", "3": "2b" });

// Modificare l'elemento SVG selezionato
viewer.setSVGElementParam("fill", "#ff0000");          // colore
viewer.setSVGElementParam("text", "Il mio testo");      // contenuto testo
viewer.setSVGElementParam("colorStop.0", "#7C3AED", "zone-id"); // gradiente

// Reagire alla selezione di un elemento SVG
viewer.addEventListener("onSVGObjectSelected", (e) => {
  const obj = e.detail.obj;
  if (obj.type === "text") inputText.value = obj.text ?? "";
});
viewer.addEventListener("onSVGObjectDeselected", () => { inputText.value = ""; });

// Catturare il render attuale
viewer.captureToBase64();
viewer.addEventListener("onCaptureBase64Complete", (e) => {
  const { base64, error } = e.detail;
  if (!error) document.querySelector("#preview").src = base64;
});