Unreal nel browser: servizio Pixel Streaming
Il servizio R47 collega il Viewer Unreal al browser usando le librerie ufficiali Epic Pixel Streaming per Unreal 5.5. Ogni lavoro BIM ottiene un processo Viewer e un signalling dedicati. Il browser riceve video e invia input; la GPU che genera le immagini è quella del server.
1. Componenti e prerequisiti
Servono il Viewer compilato con Unreal 5.5 su Windows o Linux, una GPU con encoder compatibile con Pixel Streaming, Node.js 22 o successivo, il worker engineering Nexsoon e un dominio HTTPS dedicato al player. Il PHP del sito inoltra i comandi al worker autenticato. Un hosting condiviso PHP senza GPU e senza processi persistenti non ospita questo servizio: il worker grafico deve risiedere su un PC, workstation o VPS GPU separato.
Compilare native/unreal/NexsoonViewer con Build-Windows.ps1 oppure Build-Unix.sh. La dipendenza glTFRuntime è inclusa con SHA-256 fissato. Il plugin PixelStreaming è abilitato per Win64 e Linux. La build del Viewer per Mac usa la visualizzazione locale: lo streaming R47 è predisposto per i server Windows e Linux.
2. Installare il servizio Node
cd native/pixel-streaming npm ci npm run build
Il lockfile fissa le dipendenze del signalling e del player. Il secondo comando genera public/player.js; il bundle generato non viene caricato nel sito BIM principale. Non pubblicare questa cartella come directory generica del server web: usare soltanto le route del servizio Node dietro proxy.
3. Configurazione privata del server GPU
Definire le seguenti variabili nell’ambiente del servizio. Usare percorsi assoluti della propria installazione e due segreti casuali diversi, di almeno 32 caratteri. Generare un segreto con node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" e ripetere per l’altro.
| Variabile | Valore e funzione |
|---|---|
| NEXSOON_UNREAL_RUNTIME | Eseguibile compilato NexsoonViewer; nessun percorso arriva dal browser. |
| NEXSOON_UNREAL_HOME | Cartella privata di scambio, identica a quella del worker. |
| NEXSOON_STREAM_PUBLIC_URL | Origine HTTPS del dominio dedicato, senza sottocartella. |
| NEXSOON_STREAM_ADMIN_TOKEN | Segreto per il controllo dal worker; almeno 32 caratteri. |
| NEXSOON_STREAM_TICKET_SECRET | Secondo segreto per firmare i ticket del player; diverso dal precedente. |
| NEXSOON_STREAM_PORT | Porta pubblica locale, predefinita 8880; ascolta solo 127.0.0.1. |
| NEXSOON_STREAM_ADMIN_PORT | Porta amministrativa locale, predefinita 8881; non esporla nel proxy. |
| NEXSOON_STREAM_MAX_SESSIONS | Massimo processi concorrenti, predefinito 2; dimensionarlo alla VRAM disponibile. |
| NEXSOON_STREAM_SESSION_SECONDS | Durata massima sessione, predefinita 3600 secondi. |
| NEXSOON_STREAM_IDLE_SECONDS | Arresto senza player collegato, predefinito 120 secondi. |
| NEXSOON_STREAM_ICE_JSON | Configurazione JSON iceServers per STUN/TURN della propria infrastruttura. |
Il servizio passa alla connessione WebRTC le impostazioni ICE. Su Internet o attraverso NAT/firewall può essere necessario TURN; predisporre credenziali temporanee del proprio servizio TURN e le porte firewall richieste. I segreti amministrativi non sono inviati al player.
Avviare con npm start. Per Linux è incluso nexsoon-stream.service: adattare utente, percorsi e EnvironmentFile al server, quindi installarlo con il gestore servizi. Lo stesso utente del worker e del Viewer deve poter leggere e scrivere la cartella lavori. Su Windows eseguire il processo con il proprio sistema di gestione servizi o una sessione controllata della workstation.
4. Collegare il worker e il sito
Nel servizio del worker engineering impostare NEXSOON_STREAM_ADMIN_URL=http://127.0.0.1:8881 e lo stesso NEXSOON_STREAM_ADMIN_TOKEN. Impostare anche NEXSOON_UNREAL_HOME alla cartella condivisa. Il controllo amministrativo accetta esclusivamente un indirizzo loopback: worker e servizio Node devono essere sulla stessa macchina. Le richieste non seguono redirect né proxy d’ambiente.
Nel gateway PHP mantenere la configurazione HTTPS autenticata del worker già prevista dall’app. I nuovi comandi streaming controllano il proprietario del lavoro prima dell’inoltro; la sola conoscenza dell’ID non concede l’accesso. Configurare il proxy HTTPS del dominio player con nginx.conf.template, inoltrando solo la porta 8880 e preservando gli header WebSocket e Origin. Non registrare i ticket nei log del proxy.
5. Utilizzo nel BIM
- Accedere al proprio account sul sito e aprire il progetto.
- Aprire il pannello Unreal e scegliere Streaming GPU dal server.
- Premere Verifica motore. Il servizio deve risultare configurato.
- Premere Trasferisci scena BIM e attendere il completamento del caricamento. Sono trasferiti geometrie visibili, materiali e ID BIM.
- Premere Avvia sessione streaming e poi Apri Viewer nel browser. Il player attende il signalling e il motore; il primo caricamento dipende dalla scena e dal server.
- Se il browser blocca la riproduzione automatica premere Avvia video.
- Usare Aggiorna stato scena prima di inviare selezione e camera o leggere nel BIM la selezione fatta nel Viewer.
- Premere Arresta sessione GPU al termine. La chiusura della scheda avvia il periodo di inattività; la sessione viene poi terminata automaticamente.
Il link di accesso è valido 5 minuti per l’apertura. Una sessione già connessa resta attiva fino all’arresto o alla durata massima. Per riconnettersi con un link scaduto, premere nuovamente Avvia sessione streaming: se il processo è ancora attivo viene restituito un nuovo ticket senza avviare un secondo Viewer.
Dopo cambiamenti al progetto trasferire una nuova scena e arrestare la sessione precedente per liberare la GPU. Una nuova scena riceve un lavoro separato; il servizio non mescola i progetti di account diversi.
6. Protezione e gestione processi
I ticket sono firmati e legati al singolo lavoro, trasmessi nel frammento del link e rimossi dalla cronologia della pagina al caricamento. Il collegamento WebSocket verifica origine, firma, scadenza, lavoro e disponibilità della sessione. È consentito un player per sessione. Gli endpoint amministrativi richiedono il bearer token. La capacità massima e la scadenza limitano i processi GPU aperti.
Il processo Unreal riceve un filtro sul solo ID assegnato e scrive il proprio heartbeat nella cartella di quel lavoro. Uno stato pronto di un altro Viewer o di una vecchia sessione non viene considerato una scena caricata. Arresto e perdita del processo di controllo chiudono anche il Viewer; il servizio Linux usa inoltre il gruppo di processi del gestore servizi.
7. Diagnostica
| Messaggio | Verifica |
|---|---|
| Servizio non configurato | Variabili del worker, processo Node, porta 8881 e token identico. |
| GPU occupata | Arrestare la sessione precedente o dimensionare la capacità del server. |
| Sessione scaduta | Generare un nuovo collegamento dal pannello. |
| Player connesso ma senza video | Log stream-viewer.log del lavoro, build Unreal, driver/encoder GPU, WebRTC, firewall e TURN. |
| Scena pronta ma comandi disabilitati | Aggiornare lo stato; verificare heartbeat, ID progetto e sessione corrente. |
| Importazione fallita | Controllare stato del lavoro e risorse GLB; ridurre la scena o correggere l’oggetto sorgente segnalato. |
Lo streaming non aumenta il dettaglio di modelli semplificati: persone, veicoli e arredi mantengono geometria e materiali sorgenti. Non sostituisce il kernel di modifica BIM. Per immagini Cycles e video di rendering resta disponibile Blender.