Značajke i funkcionalnosti

Aspose.3D FOSS za Python pruža kompletan API za graf scena za čitanje, izgradnju i pisanje 3D sadržaja u više industrijskih standardnih formata. Ova stranica dokumentira svako glavno područje značajki s radnim Python kodnim primjerima koji koriste stvarni API biblioteke.

Instalacija i postavljanje

Instalirajte biblioteku s PyPI-a jednim naredbom:

pip install aspose-3d-foss

Nisu potrebni dodatni sustavni paketi, izvorni proširenja ili alati za kompilaciju. Biblioteka je čista Python i podržava Python 3.7 do 3.12 na Windowsu, macOS-u i Linuxu.

Za provjeru instalacije:

from aspose.threed import Scene

scene = Scene()
print("Aspose.3D FOSS installed successfully")
print(f"Root node name: {scene.root_node.name}")

Značajke i funkcionalnosti

Podrška za formate

Aspose.3D FOSS za Python čita i piše sljedeće formate:

Učitavanje OBJ-a s opcijama

ObjLoadOptions kontrolira kako se OBJ datoteke parsiraju:

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

options = ObjLoadOptions()
options.enable_materials = True        # Load accompanying .mtl file
options.flip_coordinate_system = False # Preserve original handedness
options.normalize_normal = True        # Normalize vertex normals to unit length
options.scale = 1.0                    # Apply a uniform scale factor at load time

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

print(f"Loaded {len(scene.root_node.child_nodes)} top-level nodes")

Spremanje u STL

StlSaveOptions kontrolira binarni vs. ASCII izlaz i druge STL‑specifične postavke:

from aspose.threed import Scene
from aspose.threed.formats import StlSaveOptions

scene = Scene.from_file("model.obj")
options = StlSaveOptions()
scene.save("output.stl", options)

Graf scene

Sav 3D sadržaj je organiziran kao stablo Node objekti. Korijen stabla je scene.root_node. Svaki čvor može sadržavati podčvorove i nositi Entity (mesh, kamera ili svjetlo) plus a Transform.

Prolazak kroz hijerarhiju scene

from aspose.threed import Scene

scene = Scene.from_file("model.glb")

def traverse(node, depth=0):
    indent = "  " * depth
    entity_type = type(node.entity).__name__ if node.entity else "none"
    print(f"{indent}{node.name} [{entity_type}]")
    for child in node.child_nodes:
        traverse(child, depth + 1)

traverse(scene.root_node)

Programatsko izgradnja scene

from aspose.threed import Scene, Node, Entity
from aspose.threed.entities import Mesh
from aspose.threed.utilities import Vector3

scene = Scene()
root = scene.root_node

##Create a child node and position it
child = root.create_child_node("my_object")
child.transform.translation = Vector3(1.0, 0.0, 0.0)
child.transform.scaling = Vector3(2.0, 2.0, 2.0)

scene.save("constructed.glb")

Ispitivanje GlobalTransform

GlobalTransform daje transformaciju u svjetskom prostoru čvora nakon akumuliranja svih transformacija pretka:

from aspose.threed import Scene

scene = Scene.from_file("model.dae")

for node in scene.root_node.child_nodes:
    gt = node.global_transform
    print(f"Node: {node.name}")
    print(f"  World translation: {gt.translation}")
    print(f"  World scale: {gt.scale}")

Mesh API

The Mesh entitet omogućuje pristup podacima o geometriji, uključujući kontrolne točke (vrhove), poligone i elemente vrhova za normale, UV koordinate i boje.

Čitanje geometrije Mesh-a

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

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

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

for node in scene.root_node.child_nodes:
    if node.entity is None:
        continue
    mesh = node.entity
    print(f"Mesh: {node.name}")
    print(f"  Vertices: {len(mesh.control_points)}")
    print(f"  Polygons: {len(mesh.polygons)}")

Pristup elementima vrhova

Elementi vrhova sadrže podatke po vrhu ili po poligonu. Najčešći elementi su normali, UV koordinate, boje vrhova i grupe zaglađivanja:

from aspose.threed import Scene
from aspose.threed.entities import VertexElementNormal, VertexElementUV

scene = Scene.from_file("model.obj")

for node in scene.root_node.child_nodes:
    if node.entity is None:
        continue
    mesh = node.entity

    # Iterate vertex elements to find normals and UVs
    for element in mesh.vertex_elements:
        if isinstance(element, VertexElementNormal):
            print(f"  Normals count: {len(element.data)}")
        elif isinstance(element, VertexElementUV):
            print(f"  UV count: {len(element.data)}")

Sustav materijala

Aspose.3D FOSS podržava dvije vrste materijala: LambertMaterial (difuzno sjenčanje) i PhongMaterial (specularno sjenčanje). Oba se automatski učitavaju iz .mtl datoteka pri korištenju ObjLoadOptions s enable_materials = True.

Čitanje materijala iz OBJ-a

from aspose.threed import Scene
from aspose.threed.shading import LambertMaterial, PhongMaterial
from aspose.threed.formats import ObjLoadOptions

options = ObjLoadOptions()
options.enable_materials = True

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

for node in scene.root_node.child_nodes:
    mat = node.material
    if mat is None:
        continue
    print(f"Node: {node.name}")
    if isinstance(mat, PhongMaterial):
        print(f"  Type: Phong")
        print(f"  Diffuse: {mat.diffuse_color}")
        print(f"  Specular: {mat.specular_color}")
    elif isinstance(mat, LambertMaterial):
        print(f"  Type: Lambert")
        print(f"  Diffuse: {mat.diffuse_color}")

Programatsko dodjeljivanje materijala

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

scene = Scene.from_file("model.glb")

material = PhongMaterial()
material.diffuse_color = Vector3(0.8, 0.2, 0.2)   # Red diffuse
material.specular_color = Vector3(1.0, 1.0, 1.0)  # White specular

##Apply to the first mesh node
for node in scene.root_node.child_nodes:
    if node.entity is not None:
        node.material = material
        break

scene.save("recolored.glb")

Matematički alati

The aspose.threed.utilities modul pruža sve vrste geometrijske matematike potrebne za izgradnju i inspekciju scene.

Rad s transformacijama

from aspose.threed.utilities import Vector3, Quaternion, Matrix4
import math

##Build a rotation quaternion from axis-angle
axis = Vector3(0.0, 1.0, 0.0)          # Y-axis
angle_rad = math.radians(45.0)
q = Quaternion.from_angle_axis(angle_rad, axis)

print(f"Quaternion: x={q.x:.4f} y={q.y:.4f} z={q.z:.4f} w={q.w:.4f}")

##Convert to rotation matrix
mat = q.to_matrix()
print(f"Rotation matrix row 0: {mat[0, 0]:.4f} {mat[0, 1]:.4f} {mat[0, 2]:.4f}")

Izračunavanje ograničnog okvira

from aspose.threed import Scene

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

# NOTE: mesh.get_bounding_box() is a stub — it always returns an empty BoundingBox()
# regardless of geometry. Compute bounds manually from control_points:
for node in scene.root_node.child_nodes:
    if node.entity is None:
        continue
    mesh = node.entity
    pts = mesh.control_points  # returns a copy of the vertex list
    if not pts:
        continue
    xs = [p.x for p in pts]
    ys = [p.y for p in pts]
    zs = [p.z for p in pts]
    print(f"Mesh: {node.name}")
    print(f"  Min: ({min(xs):.3f}, {min(ys):.3f}, {min(zs):.3f})")
    print(f"  Max: ({max(xs):.3f}, {max(ys):.3f}, {max(zs):.3f})")

Animacija

Aspose.3D FOSS pruža model animacije temeljen na AnimationClip, AnimationNode, KeyFrame, i KeyframeSequence. Podaci o animaciji pohranjeni u učitanim datotekama (glTF, COLLADA) dostupni su putem ovih objekata.

Čitanje animacijskih isječaka

from aspose.threed import Scene

scene = Scene.from_file("animated.glb")

for clip in scene.animation_clips:
    print(f"Clip: {clip.name}  ({clip.start:.2f}s – {clip.stop:.2f}s)")
    for anim_node in clip.animations:
        print(f"  Animation node: {anim_node.name}")
        for sub in anim_node.sub_animations:
            print(f"    Sub-animation: {sub.name}")
        for bp in anim_node.bind_points:
            print(f"    Bind point: {bp.name}")

Opcije učitavanja i spremanja

Svaki podržani format ima odgovarajuću klasu opcija koja kontrolira ponašanje parsiranja i serijalizacije.

Primjeri upotrebe

Primjer 1: Pretvorba formata OBJ u STL

Pretvorite OBJ datoteku (s materijalima) u binarni STL, ispisujući statistiku mreže tijekom procesa:

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

##Load OBJ with material support
load_opts = ObjLoadOptions()
load_opts.enable_materials = True
load_opts.flip_coordinate_system = False
load_opts.normalize_normal = True

scene = Scene()
scene.open("input.obj", load_opts)

##Report what was loaded
total_vertices = 0
total_polygons = 0
for node in scene.root_node.child_nodes:
    if node.entity is not None:
        mesh = node.entity
        total_vertices += len(mesh.control_points)
        total_polygons += len(mesh.polygons)
        print(f"  {node.name}: {len(mesh.control_points)} vertices, {len(mesh.polygons)} polygons")

print(f"Total: {total_vertices} vertices, {total_polygons} polygons")

##Save as STL
save_opts = StlSaveOptions()
scene.save("output.stl", save_opts)
print("Saved output.stl")

Primjer 2: Pakiranje glTF u GLB u seriji

Ponovno spremite direktorij odvojenih glTF + teksturnih datoteka kao samostalne GLB binarne datoteke:

import os
from aspose.threed import Scene

input_dir = "gltf_files"
output_dir = "glb_files"
os.makedirs(output_dir, exist_ok=True)

for filename in os.listdir(input_dir):
    if not filename.endswith(".gltf"):
        continue
    src = os.path.join(input_dir, filename)
    dst = os.path.join(output_dir, filename.replace(".gltf", ".glb"))
    scene = Scene.from_file(src)
    scene.save(dst)
    print(f"Packed {filename} -> {os.path.basename(dst)}")

Primjer 3: Inspekcija grafova scene i izvještaj o izvozu

Prođite kroz graf scene COLLADA datoteke, prikupite statistiku po mreži i ispišite strukturirani izvještaj:

from aspose.threed import Scene

scene = Scene.from_file("assembly.dae")

report = []

def collect(node, path=""):
    full_path = f"{path}/{node.name}" if node.name else path
    if node.entity is not None:
        mesh = node.entity
        gt = node.global_transform
        report.append({
            "path": full_path,
            "vertices": len(mesh.control_points),
            "polygons": len(mesh.polygons),
            "world_x": gt.translation.x,
            "world_y": gt.translation.y,
            "world_z": gt.translation.z,
        })
    for child in node.child_nodes:
        collect(child, full_path)

collect(scene.root_node)

print(f"{'Path':<40} {'Verts':>6} {'Polys':>6} {'X':>8} {'Y':>8} {'Z':>8}")
print("-" * 78)
for entry in report:
    print(
        f"{entry['path']:<40} "
        f"{entry['vertices']:>6} "
        f"{entry['polygons']:>6} "
        f"{entry['world_x']:>8.3f} "
        f"{entry['world_y']:>8.3f} "
        f"{entry['world_z']:>8.3f}"
    )

Savjeti i najbolje prakse

Odabir formata

• glTF 2.0 / GLB je preporučeni format za razmjenu scena koje uključuju materijale, animacije i složene hijerarhije. Preferirajte GLB (binarni) nad glTF (tekst + vanjske datoteke) radi prenosivosti.
• STL je pravi izbor kada je krajnji korisnik slicer, CAD alat ili bilo koji alat koji treba samo geometriju. STL ne sadrži podatke o materijalima ili animacijama.
• OBJ je široko podržan i dobar izbor kada se podaci o materijalima moraju razmjenjivati sa starijim alatima. Uvijek držite .mtl datoteku uz .obj datoteku.

Koordinatni sustavi

• Različite aplikacije koriste različite konvencije desničarnosti. Postavite ObjLoadOptions.flip_coordinate_system = True prilikom uvoza OBJ datoteka iz alata koji koriste desni koordinatni sustav ako vaš pipeline očekuje lijevi koordinatni sustav, i obrnuto.
• Provjerite konvenciju osi izvornog sredstva prije primjene bilo kakvog preokretanja. Dvostruko preokretanje rezultira netočnom geometrijom.

Normalizacija

• Uvijek postavite ObjLoadOptions.normalize_normal = True kada krajnji pipeline očekuje jedinične normale (na primjer, pri prosljeđivanju normala shaderu ili izračunavanju osvjetljenja pomoću skalarnih produkata). Nenormalizirane normale iz loše oblikovanih OBJ datoteka uzrokuju artefakte osvjetljenja.

Performanse

• Učitajte datoteke jednom i transformirajte graf scena u memoriji umjesto ponovnog učitavanja s diska za svaki izlazni format. Jedan Scene.from_file() poziv, a zatim više scene.save() poziva je učinkovitiji od ponovljenih učitavanja.
• Pri obradi velikih serija, konstruirajte jedan ObjLoadOptions ili StlSaveOptions instancu i ponovno je upotrijebite u svim datotekama umjesto stvaranja novog objekta opcija po datoteci.

Rukovanje pogreškama

• Omotaj scene.open() i scene.save() pozive u try/except blokove prilikom obrade nepouzdanih ili korisnički dostavljenih datoteka. Prijavite naziv datoteke u porukama iznimaka kako biste pojednostavili otklanjanje pogrešaka u serijskim cjevovodima.

Uobičajeni problemi

Često postavljana pitanja

Koje Python verzije su podržane? Python 3.7, 3.8, 3.9, 3.10, 3.11 i 3.12 su svi podržani. Biblioteka je čista Python bez izvornih ekstenzija, pa radi na bilo kojoj platformi na kojoj se izvršava CPython.

Ima li biblioteka neke vanjske ovisnosti? Ne. Aspose.3D FOSS za Python koristi samo standardnu biblioteku Python. Instalira se kao jedinstveni pip install aspose-3d-foss naredba bez dodatnih koraka.

Je li FBX podržan? FBX tokenizator je implementiran i može parsirati binarni FBX token stream, ali graditelj scene‑graph builder iznad tokenizatora ima poznate greške i nije spreman za produkciju. Koristite OBJ, STL, glTF, COLLADA ili 3MF za pouzdanu upotrebu u produkciji.

Mogu li koristiti Aspose.3D FOSS u komercijalnom proizvodu? Da. Biblioteka je objavljena pod MIT licencom, koja dopušta korištenje u vlasničkom i komercijalnom softveru bez plaćanja royaltyja, pod uvjetom da je uključena obavijest o licenci.

Kako mogu prijaviti grešku ili zatražiti format? Otvorite problem (issue) u repozitoriju. Uključite minimalnu datoteku za reprodukciju i Python verziju, operativni sustav i verziju biblioteke iz pip show aspose-3d-foss.

Sažetak API reference

Osnovne klase

• Scene: Kontejner najviše razine za 3D scenu. Ulazna točka za open(), from_file(), i save().
• Node: Čvor stabla u grafu scene. Prenosi entity, transform, global_transform, material, child_nodes, i name.
• Entity: Bazna klasa za objekte pričvršćene uz čvorove (Mesh, Camera, Light).
• Transform: Lokalni položaj, rotacija (kvaternion) i skala za čvor.
• GlobalTransform: Transformacija u svjetskom prostoru samo za čitanje, izračunata akumulacijom svih transformacija pretka.

Geometrija

• Mesh: Poligonalna mreža s control_points (popis vrhova) i polygons.
• VertexElementNormal: Vektori normala po vrhu ili po poligonu.
• VertexElementUV: UV koordinate teksture po vrhu.
• VertexElementVertexColor: Podaci o boji po vrhu.
• VertexElementSmoothingGroup: Dodjele grupa zaglađivanja poligona.

Materijali

• LambertMaterial: Model difuznog sjenčanja s diffuse_color i emissive_color.
• PhongMaterial: Dodavanje spekularnog modela sjenčanja specular_color i shininess.

Matematički alati (aspose.threed.utilities)

• Vector2: 2D vektor.
• Vector3: 3D vektor dvostruke preciznosti.
• Vector4: 4D vektor dvostruke preciznosti.
• FVector3: 3D vektor jednostruke preciznosti.
• Quaternion: Rotacijski kvaternion s from_angle_axis() i to_matrix().
• Matrix4: 4×4 transformacijska matrica.
• BoundingBox: Okvir usklađen s osama s minimum i maximum kutovima.

Animacija

• AnimationClip: Imenovani spremnik za skup animacijskih kanala i njihovih ključnih okvira.
• AnimationNode: Podaci o animaciji po čvoru unutar isječka.
• KeyFrame: Jedan ključni okvir s vremenom i vrijednošću.
• KeyframeSequence: Uređeni niz ključnih okvira za jedno animirano svojstvo.

Opcije učitavanja / spremanja

• ObjLoadOptions: Postavke učitavanja specifične za OBJ: enable_materials, flip_coordinate_system, normalize_normal, scale.
• StlSaveOptions: Postavke spremanja specifične za STL (binarni vs. ASCII način).

Kamere i svjetla

• Camera: Entitet kamere s postavkama projekcije, koji se može pričvrstiti na a Node.
• Light: Entitet izvora svjetla, koji se može pričvrstiti na a Node.