Práce s 3D formáty souborů v Java pomocí Aspose.3D FOSS

Aspose.3D FOSS pro Java podporuje pět formátů 3D souborů: OBJ, STL, glTF, GLB, a FBX (pouze import).

Všechny příklady používají com.aspose.threed.* balíček:

import com.aspose.threed.*;

Maven závislost:

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

Přehled formátů

Než se ponoříte dál, zde je rychlý přehled čtyř podporovaných formátů a jejich typických případů použití.

OBJ, STL, glTF a GLB podporují jak import, tak export. FBX je podporován pro pouze import. GLB (binární glTF) je vytvářen pomocí GltfSaveOptions s setContentType(FileContentType.BINARY).

OBJ: Wavefront Object

OBJ je jedním z nejrozšířenějších formátů 3D sítí. Ukládá geometrii jako prostý text, s volitelným .mtl doprovodný soubor pro materiály.

Načítání souborů OBJ

Nejjednodušší přístup je předat cestu k souboru přímo:

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

Pro větší kontrolu použijte ObjLoadOptions:

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

Když OBJ soubor odkazuje na MTL soubor (prostřednictvím mtllib direktiva), knihovna se pokusí načíst definice materiálů z něj automaticky. MTL soubor by měl být ve stejném adresáři jako OBJ soubor nebo na cestě určené v direktivě.

Ukládání jako OBJ

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

Případy použití OBJ

• Výměna dat sítí mezi různými 3D nástroji.
• Importování modelů z knihoven aktiv, které jsou distribuovány ve formátu OBJ.
• Rychlá kontrola geometrie bez složitých hierarchií scény.

STL: Stereolitografie

STL je standardní formát pro 3D tisk. Reprezentuje surovou triangulovanou geometrii bez materiálů, barev ani hierarchie scény. Soubory STL jsou ve dvou variantách: ASCII (čitelné pro člověka) a binární (kompaktní).

Načítání souborů STL

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

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

Ukládání jako STL

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

Pro řízení výstupu použijte StlSaveOptions:

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

Úvahy o STL

• STL ukládá pouze triangulovanou geometrii. Materiály, textury a hierarchie scény nejsou podporovány a při exportu jsou vynechány.
• Export STL ne automaticky triangulovat. Binární STL zapisuje pouze první 3 vrcholy každé polygonální plochy; čtyřúhelníkové a n‑úhelníkové plochy jsou tiše zkráceny. ASCII STL zapisuje všechny indexy vrcholů pro každou plochu, což vede k poškozenému výstupu u ne‑trojúhelníkových ploch. Vždy používejte předem triangulované sítě (všechny plochy jsou trojúhelníky) při exportu do STL.
• Binární STL je pro velké modely podstatně menší než ASCII STL.
• STL je preferovaný formát, když je cílem 3D tiskárna nebo slicer software.

glTF: GL Transmission Format

glTF je moderní formát navržený pro efektivní přenos a načítání 3D obsahu, zejména na webu a v aplikacích v reálném čase. Podporuje PBR materiály, hierarchie scén a animace.

Načítání souborů glTF

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

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

Ukládání jako glTF

Základní ukládání používá příponu souboru k určení formátu:

scene.save("output.gltf");

Pro podrobnější řízení použijte GltfSaveOptions:

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

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

Podrobnosti GltfSaveOptions

Případy použití glTF

• Weboví 3D prohlížeče (three.js, Babylon.js).
• Aplikace v reálném čase a herní enginy.
• Zachování definic PBR materiálů napříč nástroji.

FBX: Filmbox (pouze import)

FBX je proprietární formát od Autodesk, který je široce používán ve vývoji her a tvorbě digitálního obsahu. Aspose.3D FOSS pro Java podporuje FBX pro pouze import — export do FBX není k dispozici.

Pouze binární FBX. Importér FBX načítá pouze binární soubory FBX. Předání ASCII souboru FBX vyvolá ImportException("ASCII FBX format not yet supported - only binary FBX is supported"). Hierarchie uzlů a extrakce materiálů z FBX nejsou plně ověřeny; složité scény FBX se nemusí načíst kompletně. Animace a rigging nejsou implementovány.

Načítání souborů FBX

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

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

Převod FBX do jiných formátů

Protože export FBX není podporován, převádějte importované scény FBX do glTF, GLB, OBJ nebo STL:

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

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

Případy použití FBX

• Import statických mesh aktiv z nástrojů Autodesk (Maya, 3ds Max) a jejich převod do jiných formátů.
• Načítání binární geometrie FBX a její opětovný export do glTF/GLB, OBJ nebo STL.

Dávková konverze

Běžný pracovní postup spočívá v konverzi celého adresáře souborů z jednoho formátu do druhého. Zde je vzor pro dávkovou konverzi:

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");
        }
    }
}

Toto načte každý .obj soubor v adresáři, převede každý do glTF s pěkně formátovaným výstupem a uloží výsledky. Tento vzor můžete přizpůsobit pro libovolnou kombinaci vstupního a výstupního formátu.

Reference pro konverzi mezi formáty

Následující tabulka ukazuje, co lze očekávat při konverzi mezi formáty.

Obecné pokyny pro konverzi

• Geometrie je obecně zachována mezi páry formátů, s jednou důležitou výjimkou: při exportu do STL musí meshes sestávat výhradně z trojúhelníkových ploch. Binary STL tiše zkracuje quad a n‑gon plochy na jejich první 3 vrcholy; ASCII STL produkuje poškozený výstup pro ne‑trojúhelníkové plochy.
• Materiály přežívají nejlépe mezi scénami importovanými z glTF a FBX, které obsahují data o materiálech. Převod do STL vždy odstraní materiály. Převod do OBJ zjednodušuje materiály na základní model MTL.
• Hierarchie scény je zachována mezi soubory ve formátu glTF. OBJ a STL vytvářejí ploché struktury. Hierarchie FBX a extrakce materiálů nejsou v této verzi plně ověřeny.

Skládání všeho dohromady

Zde je kompletní příklad, který načte soubor OBJ, prozkoumá jeho uzly a exportuje jej jak do glTF, tak do 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.");
    }
}

Shrnutí

Aspose.3D FOSS pro Java vám poskytuje konzistentní API napříč více formáty. Klíčové body:

• OBJ – jednoduchá výměna meshů se základními materiály.
• STL – formát pouze pro geometrii pro 3D tiskové řetězce.
• glTF / GLB – moderní formát podporující PBR pro web a real‑time použití. Použijte GltfSaveOptions s setContentType(FileContentType.BINARY) pro výstup GLB.
• FBX – pouze import; bohatý formát pro načítání assets z herních enginů a DCC nástrojů.

Použijte třídy možností načítání a ukládání specifické pro formát (ObjLoadOptions, StlLoadOptions, StlSaveOptions, GltfLoadOptions, GltfSaveOptions, FbxLoadOptions) když potřebujete detailní kontrolu nad procesem importu nebo exportu.

Pro více podrobností navštivte Aspose.3D dokumentace nebo procházejte zdroj na GitHub.