Lavorare con i formati di file 3D in Java usando Aspose.3D FOSS

Aspose.3D FOSS per Java supporta cinque formati di file 3D: OBJ, STL, glTF, GLB, e FBX (solo importazione).

Tutti gli esempi utilizzano il com.aspose.threed.* pacchetto:

import com.aspose.threed.*;

Dipendenza Maven:

<dependency>
    <groupId>com.aspose</groupId>
    <artifactId>aspose-3d-foss</artifactId>
    <version>26.1.0</version>
</dependency>

Panorama dei Formati

Prima di immergersi, ecco una rapida panoramica dei quattro formati supportati e dei loro tipici casi d’uso.

OBJ, STL, glTF e GLB supportano sia l’importazione che l’esportazione. FBX è supportato per solo importazione. GLB (binary glTF) è prodotto tramite GltfSaveOptions con setContentType(FileContentType.BINARY).

OBJ: Wavefront Object

OBJ è uno dei formati mesh 3D più ampiamente supportati. Memorizza la geometria come testo semplice, con un opzionale .mtl file di accompagnamento per i materiali.

Caricamento di file OBJ

L’approccio più semplice è passare direttamente il percorso del file:

Scene scene = Scene.fromFile("model.obj");

Per un maggiore controllo, usa ObjLoadOptions:

ObjLoadOptions opts = new ObjLoadOptions();
Scene scene = Scene.fromFile("model.obj", opts);

Quando il file OBJ fa riferimento a un file MTL (tramite un mtllib direttiva), la libreria cercherà di caricare automaticamente le definizioni dei materiali da esso. Il file MTL dovrebbe trovarsi nella stessa directory del file OBJ o nel percorso specificato nella direttiva.

Salvataggio come OBJ

Scene scene = Scene.fromFile("input.fbx");
scene.save("output.obj");

Casi d’uso di OBJ

• Scambio di dati mesh tra diversi strumenti 3D.
• Importazione di modelli da librerie di asset che distribuiscono in formato OBJ.
• Ispezione rapida della geometria senza gerarchie di scena complesse.

STL: Stereolitografia

STL è il formato standard per la stampa 3D. Rappresenta geometria triangolata grezza senza materiali, colori o gerarchia di scena. I file STL sono disponibili in due varianti: ASCII (leggibile dall’uomo) e binario (compatto).

Caricamento di file STL

// Simple load
Scene scene = Scene.fromFile("part.stl");

// With explicit options
StlLoadOptions opts = new StlLoadOptions();
Scene scene = Scene.fromFile("part.stl", opts);

Salvataggio come STL

Scene scene = Scene.fromFile("model.obj");
scene.save("output.stl");

Per controllare l’output, usa StlSaveOptions:

StlSaveOptions opts = new StlSaveOptions();
scene.save("output.stl", opts);

Considerazioni su STL

• STL memorizza solo geometria a triangoli. Materiali, texture e gerarchia di scena non sono supportati e vengono scartati durante l’esportazione.
• L’esportazione STL non triangola automaticamente. Il Binary STL scrive solo i primi 3 vertici di ogni faccia poligonale; le facce quad e n-gon vengono silenziosamente troncate. L’ASCII STL scrive tutti gli indici dei vertici per faccia, producendo output malformato per le facce non triangolari. Usa sempre mesh pre-triangolate (tutte le facce triangolari) quando esporti in STL.
• Il STL binario è significativamente più piccolo del STL ASCII per modelli di grandi dimensioni.
• STL è il formato preferito quando il target è una stampante 3D o un software slicer.

glTF: GL Transmission Format

glTF è un formato moderno progettato per la trasmissione e il caricamento efficienti di contenuti 3D, in particolare sul web e nelle applicazioni in tempo reale. Supporta materiali PBR, gerarchie di scena e animazioni.

Caricamento di file glTF

Scene scene = Scene.fromFile("scene.gltf");

// With options
GltfLoadOptions opts = new GltfLoadOptions();
Scene scene = Scene.fromFile("scene.gltf", opts);

Salvataggio come glTF

Il salvataggio di base utilizza l’estensione del file per determinare il formato:

scene.save("output.gltf");

Per un controllo dettagliato, usa GltfSaveOptions:

GltfSaveOptions opts = new GltfSaveOptions();
opts.setFlipCoordinateSystem(true);
opts.setPrettyPrint(true);

scene.save("output.gltf", opts);

Dettagli di GltfSaveOptions

Casi d’uso di glTF

• Visualizzatori 3D basati sul web (three.js, Babylon.js).
• Applicazioni in tempo reale e motori di gioco.
• Mantenere le definizioni dei materiali PBR tra gli strumenti.

FBX: Filmbox (Solo importazione)

FBX è un formato proprietario di Autodesk ampiamente utilizzato nello sviluppo di giochi e nella creazione di contenuti digitali. Aspose.3D FOSS per Java supporta FBX per solo importazione — l’esportazione in FBX non è disponibile.

Solo Binary FBX. L’importatore FBX legge solo file Binary FBX. Passare un file ASCII FBX genera ImportException("ASCII FBX format not yet supported - only binary FBX is supported"). La gerarchia dei nodi e l’estrazione dei materiali da FBX non sono completamente verificate; scene FBX complesse potrebbero non caricarsi completamente. Animazioni e rigging non sono implementati.

Caricamento di file FBX

Scene scene = Scene.fromFile("character.fbx");

// With options
FbxLoadOptions opts = new FbxLoadOptions();
Scene scene = Scene.fromFile("character.fbx", opts);

Conversione di FBX in altri formati

Poiché l’esportazione FBX non è supportata, converti le scene FBX importate in glTF, GLB, OBJ o STL:

Scene scene = Scene.fromFile("character.fbx");

// Save as GLB
GltfSaveOptions opts = new GltfSaveOptions();
opts.setContentType(FileContentType.BINARY);
scene.save("character.glb", opts);

Casi d’uso di FBX

• Importazione di asset mesh statici dagli strumenti Autodesk (Maya, 3ds Max) e conversione in altri formati.
• Caricamento della geometria FBX binaria e riesportazione in glTF/GLB, OBJ o STL.

Conversione batch

Un flusso di lavoro comune consiste nel convertire un’intera directory di file da un formato all’altro. Ecco un modello per la conversione batch:

import com.aspose.threed.*;
import java.io.File;

public class BatchConvert {
    public static void main(String[] args) throws Exception {
        File inputDir = new File("models/obj");
        File outputDir = new File("models/gltf");
        outputDir.mkdirs();

        GltfSaveOptions saveOpts = new GltfSaveOptions();
        saveOpts.setPrettyPrint(true);

        File[] objFiles = inputDir.listFiles(
            (dir, name) -> name.toLowerCase().endsWith(".obj")
        );

        if (objFiles == null) return;

        for (File objFile : objFiles) {
            String baseName = objFile.getName()
                .replaceFirst("\\.obj$", "");

            Scene scene = Scene.fromFile(objFile.getAbsolutePath());
            String outPath = new File(outputDir, baseName + ".gltf")
                .getAbsolutePath();

            scene.save(outPath, saveOpts);
            System.out.println("Converted: " + objFile.getName()
                + " -> " + baseName + ".gltf");
        }
    }
}

Questo carica ogni .obj file in una directory, converte ciascuno in glTF con output formattato in modo leggibile, e salva i risultati. Puoi adattare questo schema a qualsiasi combinazione di formato di origine e destinazione.

Riferimento alla conversione tra formati

La tabella seguente mostra cosa aspettarsi durante la conversione tra formati.

Linee guida generali per la conversione

• Geometria è generalmente preservato tra le coppie di formati, con una importante eccezione: quando si esporta in STL, le mesh devono essere composte interamente da facce triangolari. Lo STL binario tronca silenziosamente le facce quad e n-gon ai loro primi 3 vertici; lo STL ASCII genera output malformato per le facce non triangolari.
• Materiali sopravvivono meglio tra le scene importate da glTF e FBX che includono dati dei materiali. La conversione in STL elimina sempre i materiali. La conversione in OBJ semplifica i materiali al modello MTL di base.
• Gerarchia della scena è preservata tra i file in formato glTF. OBJ e STL producono strutture piatte. La gerarchia FBX e l’estrazione dei materiali non sono completamente verificate in questa versione.

Mettere tutto insieme

Ecco un esempio completo che carica un file OBJ, ispeziona i suoi nodi e lo esporta sia in glTF che in GLB:

import com.aspose.threed.*;

public class FormatWorkflow {
    public static void main(String[] args) throws Exception {
        // Load
        Scene scene = Scene.fromFile("input.obj");

        // Inspect
        System.out.println("Nodes in scene:");
        for (Node child : scene.getRootNode().getChildNodes()) {
            System.out.println("  " + child.getName());
            Transform t = child.getTransform();
            System.out.println("    Translation: "
                + t.getTranslation());
        }

        // Export to glTF with options
        GltfSaveOptions gltfOpts = new GltfSaveOptions();
        gltfOpts.setPrettyPrint(true);
        scene.save("output.gltf", gltfOpts);

        // Export to GLB (binary glTF)
        GltfSaveOptions glbOpts = new GltfSaveOptions();
        glbOpts.setContentType(FileContentType.BINARY);
        scene.save("output.glb", glbOpts);

        System.out.println("Export complete.");
    }
}

Riepilogo

Aspose.3D FOSS for Java ti offre un’API coerente su più formati. I punti chiave:

• OBJ – scambio semplice di mesh con materiali di base.
• STL – formato solo geometria per pipeline di stampa 3D.
• glTF / GLB – formato moderno compatibile PBR per uso web e in tempo reale. Usa GltfSaveOptions con setContentType(FileContentType.BINARY) per l’output GLB.
• FBX – solo importazione; formato ricco per caricare asset da motori di gioco e strumenti DCC.

Utilizza le classi di opzioni di caricamento e salvataggio specifiche per formato (ObjLoadOptions, StlLoadOptions, StlSaveOptions, GltfLoadOptions, GltfSaveOptions, FbxLoadOptions) quando hai bisogno di un controllo dettagliato sul processo di importazione o esportazione.

Per ulteriori dettagli, visita il Aspose.3D documentazione oppure sfoglia il sorgente su GitHub.