3D Model Studio

Studio per la generazione, ispezione e presentazione interattiva di modelli 3D basato su AI.

3D Model Studio è un prototipo realizzato con React e Three.js che trasforma immagini di riferimento o file GLB caricati in un ambiente di lavoro 3D interattivo e rifinito. Include controlli WebGL live per l'orbita, una postazione di lavoro a tre colonne con libreria modelli a sinistra, palcoscenico centrale e strumenti a destra, oltre a funzionalità come screenshot, esportazione GLB, cronologia upload compressa, modalità demo e una coda di generazione. Supporta provider opzionali per la generazione 3D da immagini.

Demo

Video demo: Demo MP4

Caratteristiche

• Visualizzatore di modelli interattivo costruito con React Three Fiber.
• Workbench a tre colonne: Libreria modelli a sinistra, palcoscenico WebGL al centro, strumenti di generazione/importazione a destra.
• Rotazione tramite drag, zoom con scroll, isolamento delle parti della struttura, ispezione dettagli dei modelli, esportazione della scena attuale.
• Ispezione intelligente degli oggetti con categoria inferita, fonte, stato provider, focus materiale, valore demo e tag per veicoli, aeromobili, navi, prodotti, artefatti e campioni organici.
• Valutazione qualità del modello GLB generato basata su dimensione file, conteggio triangoli, texture e idoneità per demo.
• Modalità Demo per screenshots e registrazioni, con pannelli laterali nascosti, percorsi cinematografici della camera e sovrapposizione pulita.
• Cassetto della Libreria modelli con miniature dei sorgenti, stato provider, id task, azioni GLB URL, confronto e cancellazione.
• Asset salvati rimangono compressi, mentre il modello attivo è fissato e cliccabile.
• Modelli generati/importati ripristinati dopo refresh tramite IndexedDB con fallback su localStorage.
• Dettagli parte generici, riferimenti asset, pannello confronto, note, galleria, log, progetti salvati e coda compatta di generazione.
• Modalità di generazione/importazione Hyper3D, Tripo, Fal.ai, Hunyuan3D, JS Depth, e importazione GLB locale.
• Modelli demo GLB memorizzati nella cache per uso offline.
• Modelli di riferimento Khronos glTF per verifiche di loader e materiali PBR.
• Chiavi API conservate lato server in .env.local, mai esposte al frontend.

Tecnologia

• React
• Vite
• Three.js
• React Three Fiber
• Drei
• Framer Motion
• Backend opzionale Tripo API
• Backend opzionale Fal.ai
• Backend locale opzionale Hunyuan3D

Avvio rapido

npm install
npm run dev

Aprire l'URL Vite mostrato nel terminale.

Flusso di lavoro del Workbench

• Selezionare il modello generato/importato attivo dalla colonna "Model Library" a sinistra.
• I modelli precedenti si trovano in "Saved Assets" compressi.
• Usare la colonna "Asset Source" a destra per scegliere il provider di generazione o importare file locali .glb/.gltf.
• Monitorare lo stato upload/generazione/importazione nel pannello "Generation Queue" a sinistra.
• Usare "Info" o "Inspect" per aprire il drawer con dettagli della parte.
• La navigazione superiore permette di accedere alla Libreria completa con catalogo, anteprime e gestione.
• "Demo" nella navigazione superiore attiva una modalità di presentazione pulita per screenshots e registrazioni.
• Verificare la scheda qualità sul stage prima di registrare; punteggi bassi indicano fonte o risultato non pronti per demo.
• L'animazione demo si adatta alla tipologia del modello (auto, aerei, navi, organici) con percorsi di camera specifici.

Comandi utili per validazione

npm run lint
npm run build
npm run test
npm run test:visual

npm run test:visual esegue controlli Playwright su layout e screenshot per workbench, libreria modelli e modalità demo.

Backend opzionale Image-to-3D

Per abilitare la generazione image-to-3D, creare .env.local copiando .env.example e impostare le chiavi API:

TRIPO_API_KEY=your_tripo_key
FAL_API_KEY=your_fal_key
RODIN_API_KEY=your_rodin_api_key
OPENAI_API_KEY=your_openai_key
API_HOST=127.0.0.1

OPENAI_API_KEY abilita l'analisi intelligente delle immagini tramite /api/3d/analyze per classificare asset e migliorare i prompt.

Per la modalità backup locale Hunyuan3D, avviare il server API locale e impostare:

HUNYUAN_API_BASE=http://127.0.0.1:8081
HUNYUAN_CREATE_PATH=/send
HUNYUAN_STATUS_PATH=/status

Provider di generazione supportati:

Modalità di caricamento file in upload:

Gli upload a Tripo e Fal seguono protocolli di storage e task specifici. I modelli GLB generati sono memorizzati in cache lato server sotto .generated-models/ per evitare duplicazioni.

Il frontend conserva la libreria modelli in IndexedDB per persistenza dopo reload.

Il backend Node si avvia con:

npm run dev:api

Il frontend si avvia con:

npm run dev

Per default, il frontend comunica con backend locale su http://127.0.0.1:8787.

Modelli Demo

Sono inclusi file GLB generati in cache sotto:

public/generated-models/

Questi consentono l'uso demo senza consumare crediti API.

Modelli di riferimento

La libreria include modelli glTF campione Khronos per verifiche materiali e caricamento:

• Transmission Test (CC0, Adobe tramite Khronos)
• Transmission Roughness Test (CC-BY 4.0)
• Mosquito In Amber (CC-BY 4.0 Sketchfab tramite Khronos)

Questi modelli sono caricati da repository esterni Khronos.

Sicurezza

Non inserire chiavi API reali nel codice frontend. Conservare sempre i segreti in .env.local, ignorato da git.

Licenza

MIT