Aspose.3D FOSS
Python
Panduan Pengembang
Dukungan Format

Dukungan Format

Aspose.3D FOSS untuk Python dapat membaca dan menulis tujuh format 3D menggunakan satu representasi adegan dalam memori. Perpustakaan ini menerjemahkan setiap format ke dalam objek umum Scene objek saat dimuat dan menyerialkan objek tersebut kembali ke format target saat disimpan. Ini berarti adegan yang dimuat dari OBJ dapat disimpan langsung ke glTF tanpa langkah konversi menengah apa pun.

Format yang Didukung

FormatEkstensiBacaTulisKelas OptionsCatatan
Wavefront OBJ.objYaYaObjLoadOptions.mtl pemuatan material didukung
STL (biner).stlYaYaStlSaveOptionsBaca biner dan ASCII; penyimpanan default ke biner
STL (ASCII).stlYaYaStlSaveOptionsVerifikasi perjalanan pulang-pergi
glTF 2.0.gltfYaYaGltfSaveOptionsGraf adegan lengkap, material, dan animasi dipertahankan
GLB (binary glTF).glbYaYaGltfSaveOptionsKontainer biner satu-berkas
COLLADA.daeYaYaColladaLoadOptions / ColladaSaveOptionsHirarki adegan dan material
3MF.3mfYaYaThreeMfSaveOptionsFormat manufaktur aditif
FBX.fbxSebagianTidakN/ATokenizer berfungsi; parser lengkap sedang dalam prosestidak siap produksi)

Format OBJ

Wavefront OBJ adalah format pertukaran yang paling banyak didukung untuk mesh statis. Aspose.3D FOSS memuat geometri (vertex, normal, koordinat UV, dan wajah poligonal) dan secara opsional berkas pendamping .mtl berkas material.

ObjLoadOptions

PropertiTipeBawaanDeskripsi
enable_materialsboolTrueMengurai .mtl file yang dirujuk oleh header OBJ
flip_coordinate_systemboolFalseKonversi dari Y-up right-handed ke Z-up right-handed
normalize_normalboolTrueNormalisasi semua normal permukaan yang diimpor menjadi panjang satu
scalefloat1.0Faktor skala seragam yang diterapkan pada semua posisi vertex

Memuat file OBJ 

from aspose.threed import Scene
from aspose.threed.formats import ObjLoadOptions

options = ObjLoadOptions()
options.enable_materials = True
options.flip_coordinate_system = False
options.scale = 1.0

scene = Scene()
scene.open("model.obj", options)

print(f"Top-level nodes: {len(scene.root_node.child_nodes)}")

Menyimpan ke OBJ 

scene.save("output.obj")

Ekspor OBJ menulis posisi vertex dan wajah poligon. Jika adegan berisi LambertMaterial atau PhongMaterial objek, perpustakaan menulis sebuah file pendamping .mtl file secara otomatis.

Format STL

STL (STereoLithography) menyimpan mesh segitiga sebagai daftar facet yang tidak terindeks. Kedua varian biner dan ASCII didukung untuk pembacaan; perpustakaan secara default menggunakan biner saat menyimpan.

StlSaveOptions

StlSaveOptions tidak memiliki bidang wajib. Buat instansinya untuk diteruskan ke scene.save():

from aspose.threed.formats import StlSaveOptions

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

Contoh round‑trip 

from aspose.threed import Scene

##Load
scene = Scene.from_file("model.stl")

##Inspect
for node in scene.root_node.child_nodes:
    if node.entity:
        print(f"{node.name}: {len(node.entity.control_points)} vertices")

##Save
scene.save("roundtrip.stl")

STL hanya menyimpan geometri segitiga, tanpa normal selain normal facet, tanpa koordinat UV, tanpa material, dan tanpa hierarki. Jika adegan Anda berisi kuad atau poligon berorde lebih tinggi, mereka akan ditriangulasi secara otomatis saat disimpan.

Format glTF / GLB

glTF 2.0 adalah format yang direkomendasikan untuk pertukaran 3D modern. Ia mempertahankan grafik adegan lengkap (hierarki node, node bernama, transformasi), material (LambertMaterial, PhongMaterial → konversi PBR), dan klip animasi. GLB adalah varian kontainer biner satu-berkas.

GltfSaveOptions 

from aspose.threed.formats import GltfSaveOptions

opts = GltfSaveOptions()
scene.save("output.gltf", opts)   # JSON + external .bin
scene.save("output.glb",  opts)   # Self-contained binary

Dukungan material

Material Aspose.3D FOSS dipetakan ke glTF pbrMetallicRoughness pada ekspor:

from aspose.threed import Scene
from aspose.threed.shading import PhongMaterial
from aspose.threed.utilities import Vector3

scene = Scene()
node = scene.root_node.create_child_node("object")

mat = PhongMaterial()
mat.diffuse_color  = Vector3(0.8, 0.2, 0.2)   # red
mat.specular_color = Vector3(1.0, 1.0, 1.0)
mat.shininess = 50.0
node.material = mat

scene.save("colored.gltf")

Verifikasi output glTF 

import json

with open("output.gltf") as f:
    data = json.load(f)

print(f"Asset version : {data['asset']['version']}")
print(f"Nodes         : {len(data.get('nodes', []))}")
print(f"Meshes        : {len(data.get('meshes', []))}")

Format COLLADA

COLLADA (.dae) adalah format berbasis XML yang mendukung hierarki adegan, material, beberapa saluran UV, dan animasi rangka. Aspose.3D FOSS membaca dan menulis seluruh pohon node serta definisi material.

from aspose.threed import Scene

##Load a COLLADA file
scene = Scene.from_file("model.dae")

##Inspect top-level nodes
for node in scene.root_node.child_nodes:
    print(f"  {node.name}")

##Save back to COLLADA
scene.save("output.dae")

COLLADA adalah pilihan yang baik ketika Anda perlu melakukan round-trip hierarki dengan node dan material yang bernama tanpa kehilangan data apa pun.

3MF Format

3MF (3D Manufacturing Format) targets additive manufacturing (3D printing) workflows. It stores triangle geometry, colour, and print-specific metadata in a ZIP-based container.

from aspose.threed import Scene
from aspose.threed.formats import ThreeMfSaveOptions

scene = Scene.from_file("part.stl")   # Load from STL
opts  = ThreeMfSaveOptions()
scene.save("part.3mf", opts)          # Write as 3MF

3MF is the recommended export format when targeting slicer software (Cura, PrusaSlicer, Bambu Studio, etc.).

Format FBX

Status: dalam proses (belum siap produksi).

FBX (.fbx) dukungan dalam Aspose.3D FOSS saat ini berada pada tahap tokenizer. Tokenizer FBX biner dapat mengurai struktur file, tetapi parser lengkap untuk node, mesh, dan material memiliki bug yang diketahui dan belum selesai. Hasil pembacaan FBX harus dianggap eksperimental.

Jangan gunakan FBX dalam alur produksi dengan rilis ini. Jika data sumber Anda berada dalam format FBX, konversikan terlebih dahulu ke glTF atau OBJ menggunakan Blender atau FBX Review sebelum memuatnya dengan Aspose.3D FOSS.

Penulisan FBX tidak didukung.

Deteksi Otomatis Format

Scene.from_file() dan scene.open() deteksi format secara otomatis menggunakan ekstensi file dan, bila tersedia, magic byte di header file:

from aspose.threed import Scene

##The library detects each format without being told explicitly
scene_obj  = Scene.from_file("model.obj")
scene_glb  = Scene.from_file("model.glb")
scene_stl  = Scene.from_file("model.stl")
scene_dae  = Scene.from_file("model.dae")
scene_3mf  = Scene.from_file("model.3mf")

Jika ekstensi tidak ada atau ambigu, perpustakaan akan kembali ke inspeksi header (magic byte). File yang tidak didukung atau tidak dikenali akan memunculkan sebuah IOError dengan pesan deskriptif.

Tips dan Praktik Terbaik

  • Gunakan glTF atau GLB untuk pipeline modern. glTF mempertahankan seluruh grafik adegan, material, dan data animasi. Ini adalah format paling lengkap untuk pertukaran dengan mesin game dan penampil web.
  • Gunakan OBJ untuk kompatibilitas maksimum. OBJ didukung oleh hampir semua alat 3D. Ini terbatas pada mesh statis tetapi sangat portabel.
  • Gunakan 3MF untuk pencetakan. 3MF carries colour, orientation hints, and print settings that STL cannot express.
  • Hindari FBX sampai siap untuk produksi. Periksa catatan rilis untuk versi di mana parsing FBX lengkap selesai.
  • Sesuaikan ekstensi penyimpanan dengan format. Jangan lewati sebuah .gltf ekstensi ketika Anda menginginkan GLB biner; gunakan .glb secara eksplisit. Ekstensi menentukan serialiser mana yang digunakan.
  • Periksa kompatibilitas poligon. STL dan 3MF memerlukan segitiga. Quads dan N-gon ditriangulasi secara otomatis saat disimpan, tetapi jumlah vertex akan meningkat. Jika Anda perlu mengontrol triangulasi, panggil mesh.triangulate() sebelum menyimpan.
 Bahasa Indonesia