Functies en functionaliteiten

Aspose.3D FOSS voor Python biedt een volledige scene‑graph API voor het lezen, construeren en schrijven van 3D‑inhoud in meerdere industriestandaardformaten. Deze pagina documenteert elk belangrijk functiegebied met werkende Python code‑voorbeelden die de daadwerkelijke bibliotheek‑API gebruiken.

Installatie en configuratie

Installeer de bibliotheek vanaf PyPI met één enkele opdracht:

pip install aspose-3d-foss

Er zijn geen extra systeempakketten, native extensies of compiler‑toolchains nodig. De bibliotheek is pure Python en ondersteunt Python 3.7 tot en met 3.12 op Windows, macOS en Linux.

Om de installatie te verifiëren:

from aspose.threed import Scene

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

Functies en functionaliteiten

Formaatondersteuning

Aspose.3D FOSS voor Python leest en schrijft de volgende formaten:

OBJ laden met opties

ObjLoadOptions bepaalt hoe OBJ-bestanden worden geparseerd:

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

Opslaan naar STL

StlSaveOptions bepaalt binaire versus ASCII-uitvoer en andere STL-specifieke instellingen:

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

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

Scene‑graph

Alle 3D-inhoud is georganiseerd als een boom van Node objecten. De wortel van de boom is scene.root_node. Elk knooppunt kan onderliggende knooppunten bevatten en een Entity (mesh, camera, of licht) plus een Transform.

Doorlopen van de scene‑hiërarchie

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)

Programma­matig een scene opbouwen

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

Inspecteren van GlobalTransform

GlobalTransform geeft de wereldruimtetransformatie van een knooppunt na het accumuleren van alle vooroudertransformaties:

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

De Mesh entity geeft toegang tot geometrische gegevens inclusief controlepunten (vertices), polygonen en vertex-elementen voor normalen, UV’s en kleuren.

Mesh‑geometry lezen

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

Toegang tot vertex‑elementen

Vertex‑elementen bevatten per‑vertex‑ of per‑polygon‑gegevens. De meest voorkomende elementen zijn normalen, UV‑coördinaten, vertexkleuren en smoothing‑groepen:

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

Materiaal Systeem

Aspose.3D FOSS ondersteunt twee materiaaltypen: LambertMaterial (diffuse shading) en PhongMaterial (specular shading). Beide worden automatisch geladen uit .mtl-bestanden bij gebruik van ObjLoadOptions met enable_materials = True.

Materialen lezen uit 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}")

Een materiaal programmatisch toewijzen

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

Wiskundige hulpprogramma’s

De aspose.threed.utilities module biedt alle geometrische wiskundige types die nodig zijn voor scenebouw en inspectie.

Werken met transformaties

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

Een begrenzingsvak berekenen

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

Animatie

Aspose.3D FOSS biedt een animatiemodel gebaseerd op AnimationClip, AnimationNode, KeyFrame, en KeyframeSequence. Animatiegegevens die zijn opgeslagen in geladen bestanden (glTF, COLLADA) zijn toegankelijk via deze objecten.

Animatieclips lezen

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

Laad- en opslaanopties

Elk ondersteund formaat heeft een bijbehorende optiesklasse die het parse- en serialisatiegedrag regelt.

Voorbeelden van gebruik

Voorbeeld 1: OBJ-naar-STL-formaatconversie

Converteer een OBJ-bestand (met materialen) naar binair STL, waarbij meshstatistieken worden afgedrukt:

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

Voorbeeld 2: Batch glTF-naar-GLB-verpakking

Sla een map met afzonderlijke glTF- + textuurbestanden opnieuw op als zelfstandige GLB-binaire bestanden:

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

Voorbeeld 3: Inspectie van de scènegrafiek en exportrapport

Doorloop de scènegrafiek van een COLLADA-bestand, verzamel per-mesh-statistieken en druk een gestructureerd rapport af:

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

Tips en best practices

Formaatselectie

• glTF 2.0 / GLB is het aanbevolen uitwisselingsformaat voor scènes die materialen, animaties en complexe hiërarchieën bevatten. Geef de voorkeur aan GLB (binair) boven glTF (tekst + externe bestanden) voor draagbaarheid.
• STL is de juiste keuze wanneer de downstream‑gebruiker een slicer, CAD‑tool of een andere tool is die alleen geometrie nodig heeft. STL bevat geen materiaal‑ of animatiegegevens.
• OBJ wordt breed ondersteund en is een goede keuze wanneer materiaalgegevens moeten worden uitgewisseld met oudere tools. Houd altijd het .mtl‑bestand naast het .obj‑bestand.

Coördinatensystemen

• Verschillende toepassingen gebruiken verschillende handvoorkeurconventies. Stel ObjLoadOptions.flip_coordinate_system = True in bij het importeren van OBJ‑bestanden van tools die een rechtshandig coördinatensysteem gebruiken als je pipeline linkshandige coördinaten verwacht, en omgekeerd.
• Controleer de asconventie van de bronasset voordat u een flip toepast. Tweemaal flippen levert onjuiste geometrie op.

Normalisatie

• Stel altijd ObjLoadOptions.normalize_normal = True in wanneer de downstream‑pipeline eenheidsnormaalvectoren verwacht (bijvoorbeeld bij het doorgeven van normaalvectoren aan een shader of bij dot‑product verlichtingsberekeningen). Niet-genormaliseerde normaalvectoren uit slecht gevormde OBJ‑bestanden veroorzaken verlichtingsartefacten.

Prestaties

• Laad bestanden één keer en transformeer de in‑memory scènegraph in plaats van elke keer van schijf te herladen voor elk uitvoerformaat. Een enkele Scene.from_file() aanroep gevolgd door meerdere scene.save() aanroepen is efficiënter dan herhaalde loads.
• Bij het verwerken van grote batches, maak één enkele ObjLoadOptions of StlSaveOptions instantie en hergebruik deze voor alle bestanden in plaats van per bestand een nieuw opties‑object te construeren.

Foutafhandeling

• Omwikkel scene.open() en scene.save() aanroepen in try/except blokken bij het verwerken van onbetrouwbare of door de gebruiker geleverde bestanden. Rapporteer de bestandsnaam in exceptieberichten om het debuggen in batch‑pijplijnen te vereenvoudigen.

Veelvoorkomende problemen

Veelgestelde vragen

Welke Python-versies worden ondersteund? Python 3.7, 3.8, 3.9, 3.10, 3.11 en 3.12 worden allemaal ondersteund. De bibliotheek is pure Python zonder native extensie, dus werkt hij op elk platform waar CPython draait.

Heeft de bibliotheek externe afhankelijkheden? Nee. Aspose.3D FOSS voor Python gebruikt alleen de Python standaardbibliotheek. Het wordt geïnstalleerd als een enkele pip install aspose-3d-foss commando zonder vervolg stappen.

Wordt FBX ondersteund? De FBX-tokenizer is geïmplementeerd en kan de binaire FBX-tokenstroom parseren, maar de scene-graph builder bovenop de tokenizer heeft bekende bugs en is niet productie‑klaar. Gebruik OBJ, STL, glTF, COLLADA of 3MF voor betrouwbaar productiegebruik.

Kan ik Aspose.3D FOSS gebruiken in een commercieel product? Ja. De bibliotheek wordt uitgebracht onder de MIT-licentie, die gebruik in propriëtaire en commerciële software zonder royaltybetalingen toestaat, mits de licentieverklaring is opgenomen.

Hoe rapporteer ik een bug of vraag ik een formaat aan? Open een issue in de repository. Voeg een minimaal reproducerend bestand toe en de Python versie, het besturingssysteem en de bibliotheekversie van pip show aspose-3d-foss.

API-referentieoverzicht

Kernklassen

• Scene: Top-level container voor een 3D‑scène. Ingangspunt voor open(), from_file(), en save().
• Node: Boomknooppunt in de scenegrafiek. Bevat entity, transform, global_transform, material, child_nodes, en name.
• Entity: Basisklasse voor objecten die aan knooppunten zijn gekoppeld (Mesh, Camera, Light).
• Transform: Lokale positie, rotatie (Quaternion) en schaal voor een knooppunt.
• GlobalTransform: Alleen‑lezen wereldruimte‑transformatie berekend door alle vooroudertransformaties op te tellen.

Geometrie

• Mesh: Polygoonmesh met control_points (vertexlijst) en polygons.
• VertexElementNormal: Per‑vertex of per‑polygon normaalvectoren.
• VertexElementUV: Per‑vertex UV‑textuurcoördinaten.
• VertexElementVertexColor: Per‑vertex kleurgegevens.
• VertexElementSmoothingGroup: Toewijzingen van polygoon‑smoothinggroepen.

Materialen

• LambertMaterial: Diffuse schaduwmodel met diffuse_color en emissive_color.
• PhongMaterial: Specular shading model toevoegen specular_color en shininess.

Wiskundige hulpprogramma’s (aspose.threed.utilities)

• Vector2: 2D-vector.
• Vector3: 3D double-precisie vector.
• Vector4: 4D double-precisie vector.
• FVector3: 3D single-precisie vector.
• Quaternion: Rotatiequaternion met from_angle_axis() en to_matrix().
• Matrix4: 4×4 transformatie-matrix.
• BoundingBox: Asgealigneerde begrenzingsbox met minimum en maximum hoeken.

Animatie

• AnimationClip: Benoemde container voor een set animatiekanalen en hun keyframes.
• AnimationNode: Per-node animatiegegevens binnen een clip.
• KeyFrame: Enkele keyframe met tijd en waarde.
• KeyframeSequence: Geordende reeks keyframes voor een enkele geanimeerde eigenschap.

Laad- / opslaanopties

• ObjLoadOptions: OBJ-specifieke laadinstellingen: enable_materials, flip_coordinate_system, normalize_normal, scale.
• StlSaveOptions: STL-specifieke opslaginstellingen (binaire vs. ASCII-modus).

Camera’s en lampen

• Camera: Camera-entiteit met projectie-instellingen, koppelbaar aan een Node.
• Light: Lichtbron entiteit, koppelbaar aan een Node.