Ominaisuudet ja toiminnot

Aspose.3D FOSS for Python tarjoaa täydellisen scene-graph API:n 3D-sisällön lukemiseen, rakentamiseen ja kirjoittamiseen useissa teollisuuden standardimuodoissa. Tämä sivu dokumentoi jokaisen tärkeän ominaisuusalueen toimivilla Python koodiesimerkeillä, jotka käyttävät kirjaston todellista API:a.

Asennus ja käyttöönotto

Asenna kirjasto PyPI:stä yhdellä komennolla:

pip install aspose-3d-foss

Lisäjärjestelmäpaketteja, natiivilaajennuksia tai kääntäjätyökaluja ei tarvita. Kirjasto on puhdas Python ja tukee Python 3.7–3.12 Windowsissa, macOSissa ja Linuxissa.

Asennuksen varmistamiseksi:

from aspose.threed import Scene

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

Ominaisuudet ja toiminnot

Formaattituen

Aspose.3D FOSS for Python lukee ja kirjoittaa seuraavat formaatit:

OBJ:n lataaminen asetuksilla

ObjLoadOptions ohjaa, miten OBJ-tiedostot jäsennetään:

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

Tallentaminen STL:ksi

StlSaveOptions ohjaa binäärisen ja ASCII-tulosteen välistä valintaa sekä muita STL-spesifisiä asetuksia:

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

Kaikki 3D-sisältö on järjestetty puuna, jonka Node objekteja. Puun juuri on scene.root_node. Jokainen solmu voi sisältää alisolmuja ja kantaa Entity (verkko, kamera tai valo) sekä Transform.

Scene-hierarkian läpikäynti

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)

Kohtauksen rakentaminen ohjelmallisesti

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

GlobalTransformin tarkastelu

GlobalTransform antaa solmun maailmanavaruuden transformaation sen jälkeen, kun kaikki vanhempien solmujen transformoinnit on kerätty:

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

Se Mesh entiteetti antaa pääsyn geometriatietoihin, mukaan lukien ohjauspisteet (vertices), polygonit ja solmu-elementit normaalien, UV:iden ja värien osalta.

Mesh-geometrian lukeminen

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

Vertex-elementtien käyttö

Vertex-elementit sisältävät per-solmu- tai per-polygon-tietoja. Yleisimpiä elementtejä ovat normaalit, UV-koordinaatit, vertex-värit ja tasoitusryhmät:

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

Materiaalijärjestelmä

Aspose.3D FOSS tukee kahta materiaalityyppiä: LambertMaterial (diffuusinen varjostus) ja PhongMaterial (spekulaarinen varjostus). Molemmat ladataan automaattisesti .mtl-tiedostoista, kun käytetään ObjLoadOptions kanssa enable_materials = True.

Materiaalien lukeminen OBJ:stä

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

Materiaalin asettaminen ohjelmallisesti

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

Matematiikka-apuohjelmat

Se aspose.threed.utilities moduuli tarjoaa kaikki geometriseen matematiikkaan liittyvät tyypit, joita tarvitaan kohtauksen rakentamiseen ja tarkasteluun.

Transformaatioiden käyttö

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

Rajauslaatikon laskeminen

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

Animaatio

Aspose.3D FOSS tarjoaa animaatiomallin, joka perustuu AnimationClip, AnimationNode, KeyFrame, ja KeyframeSequence. Animaatiodata, joka on tallennettu ladattuihin tiedostoihin (glTF, COLLADA), on käytettävissä näiden objektien kautta.

Animaatioleikkeiden lukeminen

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

Lataus- ja tallennusasetukset

Jokaisella tuetulla formaatilla on vastaava asetusluokka, joka hallitsee jäsentämis- ja sarjoituskäyttäytymistä.

Käyttöesimerkit

Esimerkki 1: OBJ → STL -muunnos

Muunna OBJ‑tiedosto (materiaalien kanssa) binaariksi STL:ksi, tulostaessa verkon tilastot matkan varrella:

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

Esimerkki 2: Eräajopakkaus glTF → GLB

Tallenna hakemisto, jossa on erillisiä glTF‑ ja tekstuuritiedostoja, uudelleen itse sisältävinä GLB‑binaareina:

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

Esimerkki 3: Kohtausgraafin tarkastelu ja vientiraportti

Käy läpi COLLADA‑tiedoston kohtausgraafi, kerää verkko‑kohtaiset tilastot ja tulosta jäsennelty raportti:

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

Vinkkejä ja parhaita käytäntöjä

Formaattivalinta

• glTF 2.0 / GLB on suositeltu vaihtomuoto kohtauksille, jotka sisältävät materiaaleja, animaatioita ja monimutkaisia hierarkioita. Suosi GLB:tä (binääri) glTF:n (teksti + ulkoiset tiedostot) sijaan siirrettävyyden vuoksi.
• STL on oikea valinta, kun alavirran kuluttaja on viipalointiohjelma, CAD-työkalu tai mikä tahansa työkalu, joka tarvitsee vain geometriaa. STL ei sisällä materiaali- tai animaatiotietoja.
• OBJ on laajasti tuettu ja hyvä valinta, kun materiaali­tiedot on vaihdettava vanhojen työkalujen kanssa. Säilytä .mtl‑tiedosto aina .obj‑tiedoston rinnalla.

Koordinaatistojärjestelmät

• Eri sovellukset käyttävät erilaisia kädenkäsitys­konventioita. Aseta ObjLoadOptions.flip_coordinate_system = True kun tuot OBJ‑tiedostoja työkaluista, jotka käyttävät oikeakätistä koordinaatistojärjestelmää, jos putkistosi odottaa vasenkätisiä koordinaatteja, ja päinvastoin.
• Varmista lähde‑aineiston akselikäytäntö ennen flipin soveltamista. Flipin tekeminen kahdesti tuottaa virheellistä geometriaa.

Normalisointi

• Aseta aina ObjLoadOptions.normalize_normal = True kun alavirran putkisto odottaa yksikkövektoreita (esimerkiksi kun vektoreita siirretään shaderiin tai tehdään pistetulolaskelmia valaistuksessa). Normalisoimattomat normaalit huonosti muodostetuista OBJ‑tiedostoista aiheuttavat valaistusvirheitä.

Suorituskyky

• Lataa tiedostot kerran ja muunna muistissa oleva kohtausgrafi sen sijaan, että ladataan uudelleen levyltä jokaiselle lähtömuodolle. Yksi Scene.from_file() kutsu, jota seuraa useita scene.save() kutsua on tehokkaampaa kuin toistuvat lataukset.
• Kun käsitellään suuria eräitä, rakenna yksi ObjLoadOptions tai StlSaveOptions instanssi ja käytä sitä uudelleen kaikissa tiedostoissa sen sijaan, että rakentaisi uuden asetuskohteen jokaiselle tiedostolle.

Virheenkäsittely

• Kääri scene.open() ja scene.save() kutsut try/except lohkoihin, kun käsitellään epäluotettavia tai käyttäjän toimittamia tiedostoja. Ilmoita tiedostonimi poikkeusviesteissä, jotta eräputkistojen vianmääritys olisi helpompaa.

Yleisiä ongelmia

Usein kysytyt kysymykset

Mitä Python-versioita tuetaan? Python 3.7, 3.8, 3.9, 3.10, 3.11 ja 3.12 kaikki ovat tuettuja. Kirjasto on puhdas Python ilman natiivilaajennuksia, joten se toimii kaikilla alustoilla, joilla CPython toimii.

Onko kirjastolla ulkoisia riippuvuuksia? Ei. Aspose.3D FOSS for Python käyttää vain Python standardikirjastoa. Se asennetaan yhdellä pip install aspose-3d-foss komennolla ilman lisätoimia.

Onko FBX tuettu? FBX-tokenisoija on toteutettu ja pystyy jäsentämään binäärisen FBX-tokenvirran, mutta tokenisoijan päällä oleva kohtausgrafiikkarakentaja sisältää tunnettuja virheitä eikä ole tuotantokelpoinen. Käytä OBJ-, STL-, glTF-, COLLADA- tai 3MF-muotoja luotettavaa tuotantokäyttöä varten.

Voinko käyttää Aspose.3D FOSS:ia kaupallisessa tuotteessa? Kyllä. Kirjasto on julkaistu MIT-lisenssin alla, joka sallii käytön suljetussa ja kaupallisessa ohjelmistossa ilman rojaltimaksuja, edellyttäen että lisenssiviesti sisällytetään.

Kuinka raportoida virhe tai pyytää formaattia? Avaa issue repositoriossa. Sisällytä minimaalinen toistotiedosto sekä Python-versio, käyttöjärjestelmä ja kirjaston versio kohteesta pip show aspose-3d-foss.

API-viitteiden yhteenveto

Ydinluokat

• Scene: 3D‑kohtauksen ylimmän tason säiliö. Sisäänkäyntipiste open(), from_file(), ja save().
• Node: Kohtausgrafiikan puusolmu. Sisältää entity, transform, global_transform, material, child_nodes, ja name.
• Entity: Perusluokka solmuihin liitetylle objektille (Mesh, Camera, Light).
• Transform: Paikallisen koordinaatiston sijainti, kierto (Quaternion) ja skaalaus solmulle.
• GlobalTransform: Vain luku -maailmankoordinaattimuunnos, joka lasketaan kumuloimalla kaikkien esivanhempien muunnokset.

Geometria

• Mesh: Polygoniverkko, jossa control_points (solmuluettelo) ja polygons.
• VertexElementNormal: Kunkin solmun tai kunkin polygonin normaalivektorit.
• VertexElementUV: Kunkin solmun UV-tekstuurikoordinaatit.
• VertexElementVertexColor: Kunkin solmun väritiedot.
• VertexElementSmoothingGroup: Polygonien tasoitusryhmien määrittelyt.

Materiaalit

• LambertMaterial: Diffuusinen varjostusmalli, jossa diffuse_color ja emissive_color.
• PhongMaterial: Spekulaarinen varjostusmalli, joka lisää specular_color ja shininess.

Matematiikka-työkalut (aspose.threed.utilities)

• Vector2: 2D-vektori.
• Vector3: 3D double-precision -vektori.
• Vector4: 4D double-precision -vektori.
• FVector3: 3D single-precision -vektori.
• Quaternion: Kiertokvaternion, jossa from_angle_axis() ja to_matrix().
• Matrix4: 4×4-muunnosmatriisi.
• BoundingBox: Akselisuuntainen raja-ala, jossa minimum ja maximum kulmat.

Animaatio

• AnimationClip: Nimetty säiliö animaatiokanavien joukolle ja niiden avainruuduille.
• AnimationNode: Solmukohtaiset animaatiotiedot leikkeessä.
• KeyFrame: Yksi avainruutu, jossa on aika ja arvo.
• KeyframeSequence: Järjestetty sarja avainruutuja yhdelle animoidulle ominaisuudelle.

Lataus- / tallennusasetukset

• ObjLoadOptions: OBJ-kohtaiset latausasetukset: enable_materials, flip_coordinate_system, normalize_normal, scale.
• StlSaveOptions: STL-kohtaiset tallennusasetukset (binääri- vs. ASCII-tila).

Kamerat ja valot

• Camera: Kamerakohde, jossa on projektioasetukset, liitettävissä Node.
• Light: Valonlähde, liitettävissä Node.