Aspose.3D FOSS
Python
Príručka pre vývojárov
Funkcie a vlastnosti

Funkcie a vlastnosti

Aspose.3D FOSS pre Python poskytuje kompletné API scény-grafu na čítanie, konštruovanie a zápis 3D obsahu v niekoľkých priemyselných štandardných formátoch. Táto stránka dokumentuje každú hlavnú oblasť funkcií s funkčnými príkladmi kódu Python, ktoré používajú skutočné API knižnice.

Inštalácia a nastavenie

Nainštalujte knižnicu z PyPI jedným príkazom:

pip install aspose-3d-foss

Nie sú potrebné žiadne ďalšie systémové balíky, natívne rozšírenia ani kompilátorské nástroje. Knižnica je čistý Python a podporuje Python 3.7 až 3.12 na Windows, macOS a Linux.

Na overenie inštalácie:

from aspose.threed import Scene

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

Funkcie a vlastnosti

Podpora formátov

Aspose.3D FOSS pre Python číta a zapisuje nasledujúce formáty:

FormátRozšírenieČítanieZápisPoznámky
Wavefront OBJ.objÁnoÁno.mtl podpora načítania materiálu
STL (binárny).stlÁnoÁnoOverený roundtrip (39 testov)
STL (ASCII).stlÁnoÁnoOverený roundtrip
glTF 2.0.gltfÁnoÁnoÚplný graf scény zachovaný
GLB (binárny glTF).glbÁnoÁnoJednosúborový binárny kontajner
COLLADA.daeÁnoÁnoHierarchia scény a materiály
3MF.3mfÁnoÁnoFormát aditívnej výroby
FBX.fbxČiastočnýNieTokenizer funguje; parser má známe chyby

Načítanie OBJ s možnosťami

ObjLoadOptions riadi, ako sa parsujú OBJ súbory:

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

Ukladanie do STL

StlSaveOptions riadi binárny vs. ASCII výstup a ďalšie nastavenia špecifické pre STL:

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

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

Scénový graf

Všetok 3D obsah je organizovaný ako strom Node objekty. Koreň stromu je scene.root_node. Každý uzol môže obsahovať poduzly a niesť Entity (mesh, kamera alebo svetlo) plus a Transform.

Prechádzanie hierarchie scény 

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)

Programové vytváranie scény 

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

Kontrola GlobalTransform

GlobalTransform poskytuje transformáciu vo svetovom priestore uzla po akumulácii všetkých transformácií predkov:

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 entita poskytuje prístup k geometrickým údajom vrátane kontrolných bodov (vrcholov), polygonov a prvkov vrcholov pre normály, UV a farby.

Čítanie geometrie Mesh 

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

Prístup k prvkom vrcholov

Prvky vrcholov nesú dáta na úrovni vrcholu alebo polygonu. Najbežnejšie prvky sú normály, UV súradnice, farby vrcholov a skupiny vyhladzovania:

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

Systém materiálov

Aspose.3D FOSS podporuje dva typy materiálov: LambertMaterial (difúzne osvetlenie) a PhongMaterial (zrkadlové osvetlenie). Obe sa načítavajú automaticky zo súborov .mtl pri použití ObjLoadOptions s enable_materials = True.

Čítanie materiálov z OBJ 

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

Priradenie materiálu programovo 

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

Matematické nástroje

The aspose.threed.utilities modul poskytuje všetky geometrické matematické typy potrebné pre konštrukciu a kontrolu scény.

TriedaÚčel
Vector22D floating-point vector (UV coordinates)
Vector33D double-precision vector (positions, normals)
Vector44D double-precision vector (homogeneous coordinates)
FVector33D single-precision vector (compact storage)
QuaternionReprezentácia rotácie bez gimbal locku
Matrix44×4 transformation matrix
BoundingBoxOsa zarovnaná ohraničujúca krabica s min/max rohovými bodmi

Práca s transformáciami 

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

Výpočet ohraničujúcej krabice 

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

Animácia

Aspose.3D FOSS poskytuje animačný model založený na AnimationClip, AnimationNode, KeyFrame, a KeyframeSequence. Animačné dáta uložené v načítaných súboroch (glTF, COLLADA) sú prístupné prostredníctvom týchto objektov.

Čítanie animačných klipov 

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

Možnosti načítania a ukladania

Každý podporovaný formát má zodpovedajúcu triedu možností, ktorá riadi správanie pri parsovaní a serializácii.

TriedaFormátKľúčové vlastnosti
ObjLoadOptionsOBJenable_materials, flip_coordinate_system, normalize_normal, scale
StlSaveOptionsSTLBinárny vs. ASCII režim výstupu
(glTF používa predvolené hodnoty)glTF / GLBGraf scény a materiály sa automaticky zachovajú

Príklady použitia

Príklad 1: Konverzia formátu OBJ na STL

Preveďte súbor OBJ (s materiálmi) na binárny STL a počas toho vypisujte štatistiky siete:

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

Príklad 2: Dávkové balenie glTF do GLB

Znovu uložte adresár samostatných súborov glTF + textúr ako samostatné binárne súbory GLB:

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

Príklad 3: Inšpekcia grafu scény a exportný report

Prejdite graf scény súboru COLLADA, zozbierajte štatistiky pre každú sieť a vypíšte štruktúrovaný report:

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

Tipy a osvedčené postupy

Výber formátu

  • glTF 2.0 / GLB je odporúčaný výmenný formát pre scény, ktoré obsahujú materiály, animácie a zložité hierarchie. Uprednostnite GLB (binárny) pred glTF (text + externé súbory) pre prenosnosť.
  • STL je správna voľba, keď je koncový spotrebiteľ slicer, CAD nástroj alebo akýkoľvek nástroj, ktorý potrebuje iba geometriu. STL neobsahuje žiadne materiálové ani animačné dáta.
  • OBJ je široko podporovaný a dobrá voľba, keď je potrebné vymieňať materiálové dáta so staršími nástrojmi. Vždy uchovávajte súbor .mtl vedľa súboru .obj.

Súradnicové systémy

  • Rôzne aplikácie používajú rôzne konvencie pravotočivosti. Nastavte ObjLoadOptions.flip_coordinate_system = True pri importe OBJ súborov z nástrojov, ktoré používajú pravotočivý súradnicový systém, ak váš pipeline očakáva ľavotočivé súradnice, a naopak.
  • Overte konvenciu osí zdrojového aktíva pred aplikovaním akéhokoľvek preklopenia. Dvojité preklopenie spôsobí nesprávnu geometriu.

Normalizácia

  • Vždy nastavte ObjLoadOptions.normalize_normal = True keď downstream pipeline očakáva jednotkové normály (napríklad pri odovzdávaní normálov shaderu alebo pri výpočtoch osvetlenia pomocou skalárneho súčinu). Nenormalizované normály z nekvalitných OBJ súborov spôsobujú artefakty v osvetlení.

Výkon

  • Načítajte súbory raz a transformujte graf scény v pamäti namiesto opätovného načítania z disku pre každý výstupný formát. Jedno Scene.from_file() volanie nasledované viacerými scene.save() volaniami je efektívnejšie ako opakované načítania.
  • Pri spracovávaní veľkých dávok vytvorte jediný ObjLoadOptions alebo StlSaveOptions inštanciu a používajte ju pre všetky súbory namiesto vytvárania nového objektu možností pre každý súbor.

Riešenie chýb

  • Zabaliť scene.open() a scene.save() volania v try/except bloky pri spracovaní nedôveryhodných alebo používateľom dodaných súborov. Uveďte názov súboru v správach výnimiek, aby ste zjednodušili ladenie v dávkových potrubiach.

Bežné problémy

ProblémPríčinaRiešenie
Sieť sa po načítaní javí ako zrkadlováNesúlad orientácie súradnicového systémuPrepnúť ObjLoadOptions.flip_coordinate_system
Normály majú nulovú dĺžkuZdrojový súbor má nenormalizované normályNastaviť ObjLoadOptions.normalize_normal = True
Materiály neboli načítané z OBJenable_materials je False (predvolené)Nastaviť ObjLoadOptions.enable_materials = True
Scéna sa načíta, ale všetky uzly sú prázdneSúbor používa formát FBXParser FBX je vo vývoji; namiesto toho použite OBJ, STL alebo glTF
Model je extrémne malý alebo veľkýZdrojový súbor používa nemetrické jednotkyPoužiť ObjLoadOptions.scale pre konverziu na vašu cieľovú jednotku
AttributeError zapnuté mesh.polygonsEntita uzla nie je MeshChráňte pomocou if node.entity is not None pred prístupom k vlastnostiam entity
Súbor GLB je odmietnutý prehliadačomUložené s .gltf príponouPoužite .glb príponu pri volaní scene.save() na spustenie binárneho kontajnera

Často kladené otázky

Aké verzie Python sú podporované? Python 3.7, 3.8, 3.9, 3.10, 3.11 a 3.12 sú všetky podporované. Knižnica je čistý Python bez natívnych rozšírení, takže funguje na akejkoľvek platforme, kde beží CPython.

Má knižnica nejaké externé závislosti? Nie. Aspose.3D FOSS pre Python používa iba štandardnú knižnicu Python. Inštaluje sa ako jediný pip install aspose-3d-foss príkaz bez ďalších krokov.

Je FBX podporovaný? Tokenizér FBX je implementovaný a dokáže parsovať binárny tokenový prúd FBX, ale scene-graph builder nad tokenizérom má známe chyby a nie je pripravený na produkčné nasadenie. Použite OBJ, STL, glTF, COLLADA alebo 3MF pre spoľahlivé použitie v produkcii.

Môžem použiť Aspose.3D FOSS v komerčnom produkte? Áno. Knižnica je vydaná pod licenciou MIT, ktorá umožňuje použitie v proprietárnom a komerčnom softvéri bez platenia poplatkov, za predpokladu, že je zahrnuté oznámenie o licencii.

Ako môžem nahlásiť chybu alebo požiadať o formát? Otvorte problém v repozitári. Priložte minimálny reprodukčný súbor a verziu Python, operačný systém a verziu knižnice z pip show aspose-3d-foss.

Zhrnutie referencie API

Základné triedy

  • Scene: Kontajner najvyššej úrovne pre 3D scénu. Vstupný bod pre open(), from_file(), a save().
  • Node: Uzol stromu v grafu scény. Nesie entity, transform, global_transform, material, child_nodes, a name.
  • Entity: Základná trieda pre objekty pripojené k uzlom (Mesh, Camera, Light).
  • Transform: Lokálna pozícia, rotácia (Quaternion) a škála pre uzol.
  • GlobalTransform: Iba na čítanie transformácia vo svetovom priestore vypočítaná akumuláciou všetkých transformácií predkov.

Geometria

  • Mesh: Polygonová sieť s control_points (zoznam vrcholov) a polygons.
  • VertexElementNormal: Normálové vektory na vrchol alebo na polygon.
  • VertexElementUV: UV textúrové súradnice na vrchol.
  • VertexElementVertexColor: Farebné dáta na vrchol.
  • VertexElementSmoothingGroup: Priradenia skupín vyhladzovania polygonov.

Materiály

  • LambertMaterial: Difúzny osvetľovací model s diffuse_color a emissive_color.
  • PhongMaterial: Pridávanie spekulárneho tieňovacieho modelu specular_color a shininess.

Matematické nástroje (aspose.threed.utilities)

  • Vector2: 2D vektor.
  • Vector3: 3D vektor s dvojitou presnosťou.
  • Vector4: 4D vektor s dvojitou presnosťou.
  • FVector3: 3D vektor s jednoduchou presnosťou.
  • Quaternion: Rotácia kvaternionu s from_angle_axis() a to_matrix().
  • Matrix4: 4×4 transformačná matica.
  • BoundingBox: Osovo zarovnaný ohraničovací box s minimum a maximum rohov.

Animácia

  • AnimationClip: Pomenovaný kontajner pre sadu animačných kanálov a ich kľúčových snímok.
  • AnimationNode: Dáta animácie na uzle v rámci klipu.
  • KeyFrame: Jedna kľúčová snímka s časom a hodnotou.
  • KeyframeSequence: Usporiadaná sekvencia kľúčových snímok pre jedinú animovanú vlastnosť.

Možnosti načítania / ukladania

  • ObjLoadOptions: Nastavenia načítania špecifické pre OBJ: enable_materials, flip_coordinate_system, normalize_normal, scale.
  • StlSaveOptions: Nastavenia ukladania špecifické pre STL (binárny vs. ASCII režim).

Kamery a svetlá

  • Camera: Entita kamery s nastaveniami projekcie, pripojiteľná k a Node.
  • Light: Entita svetelného zdroja, pripojiteľná k Node.
 Slovenčina