Jellemzők és funkciók

Aspose.3D FOSS for Python teljes körű scene-graph API-t biztosít 3D tartalom olvasásához, létrehozásához és írásához több iparági szabványos formátumban. Ez az oldal minden fő funkcióterületet dokumentál működő Python kódpéldákkal, amelyek a tényleges könyvtár API-t használják.

Telepítés és beállítás

Telepítsd a könyvtárat a PyPI-ról egyetlen paranccsal:

pip install aspose-3d-foss

Nem szükséges további rendszercsomag, natív kiterjesztés vagy fordító eszközkészlet. A könyvtár tisztán Python, és támogatja a Python 3.7‑től 3.12‑ig terjedő verziókat Windows, macOS és Linux rendszereken.

A telepítés ellenőrzéséhez:

from aspose.threed import Scene

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

Jellemzők és funkciók

Formátumtámogatás

Aspose.3D FOSS for Python a következő formátumokat olvassa és írja:

OBJ betöltése beállításokkal

ObjLoadOptions szabályozza, hogyan kerülnek feldolgozásra az OBJ fájlok:

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

Mentés STL-be

StlSaveOptions szabályozza a bináris és ASCII kimenetet, valamint egyéb STL-specifikus beállításokat:

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

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

Jelenet gráf

Minden 3D tartalom egy fa struktúrában van szervezve. Node objektumok. A fa gyökere scene.root_node. Minden csomópont tartalmazhat gyermekcsomópontokat és hordozhat egy Entity (háló, kamera vagy fény) plusz egy Transform.

A jelenet hierarchiájának bejárása

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)

Jelenet programozott felépítése

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

GlobalTransform vizsgálata

GlobalTransform megadja egy csomópont világkoordinátás transzformációját, miután összegyűjtötte az összes ős transzformációt:

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

A Mesh az entitás hozzáférést biztosít a geometriai adatokhoz, beleértve a vezérlőpontokat (csúcsok), poligonokat, és a csúcs elemeket a normálokhoz, UV-khez és színekhez.

Mesh geometria olvasása

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

Csúcs elemek elérése

A csúcs elemek csúcsonkénti vagy poligononkénti adatot tartalmaznak. A leggyakoribb elemek a normálok, UV koordináták, csúcsszínek és simítási csoportok:

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

Anyagrendszer

Aspose.3D FOSS támogat két anyagtípust: LambertMaterial (diffúz árnyalás) és PhongMaterial (speculáris árnyalás). Mindkettő automatikusan betöltődik .mtl fájlokból, amikor használja ObjLoadOptions a enable_materials = True.

Anyagok olvasása OBJ-ből

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

Anyag hozzárendelése programozottan

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

Matematikai segédeszközök

A aspose.threed.utilities modul minden geometriai matematikai típust biztosít, amely a jelenet felépítéséhez és ellenőrzéséhez szükséges.

Transzformációk kezelése

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

Határoló doboz számítása

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áció

Aspose.3D FOSS animációs modellt biztosít, amely alapul AnimationClip, AnimationNode, KeyFrame, és KeyframeSequence. A betöltött fájlokban (glTF, COLLADA) tárolt animációs adatok ezen objektumokon keresztül érhetők el.

Animációs klippek olvasása

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

Betöltési és mentési beállítások

Minden támogatott formátumnak van egy megfelelő beállítási osztálya, amely a feldolgozási és sorosítási viselkedést szabályozza.

Használati példák

Példa 1: OBJ → STL formátumkonverzió

Konvertáljon egy OBJ fájlt (anyagokkal) bináris STL-re, miközben kiírja a háló statisztikákat:

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

Példa 2: Tömeges glTF → GLB csomagolás

Mentse újra egy könyvtárban lévő különálló glTF + textúra fájlokat önálló GLB binárisokként:

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

Példa 3: Jelenetgrafikon ellenőrzése és exportjelentés

Járja be egy COLLADA fájl jelenetgrafikonját, gyűjtsön per-háló statisztikákat, és írjon ki egy strukturált jelentést:

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

Tippek és bevált gyakorlatok

Formátum kiválasztása

• glTF 2.0 / GLB az ajánlott csereformátum olyan jelenetekhez, amelyek anyagokat, animációkat és összetett hierarchiákat tartalmaznak. A hordozhatóság érdekében részesítsd előnyben a GLB-t (bináris) a glTF-vel (szöveg + külső fájlok) szemben.
• STL a megfelelő választás, ha a downstream fogyasztó egy szeletelő, CAD eszköz vagy bármely olyan program, amely csak geometriára van szüksége. Az STL nem tartalmaz anyag- vagy animációs adatokat.
• OBJ széles körben támogatott, és jó választás, ha anyagadatokat kell cserélni régebbi eszközökkel. Mindig tartsd a .mtl fájlt a .obj fájl mellett.

Koordináta rendszerek

• Különböző alkalmazások különböző jobb-bal koordináta konvenciókat használnak. Állítsd be ObjLoadOptions.flip_coordinate_system = True OBJ fájlok importálásakor olyan eszközökből, amelyek jobbkezes koordináta rendszert használnak, ha a csővezetéked balkezes koordinátákat vár, és fordítva.
• Ellenőrizze a forráseszköz tengelykonvencióját, mielőtt bármilyen átalakítást alkalmazna. Kétszeri átalakítás helytelen geometriát eredményez.

Normalizálás

• Mindig állítsd be ObjLoadOptions.normalize_normal = True amikor a downstream csővezeték egységnyi normálvektorokat vár (például normálok shadernek való átadása vagy pontszorzatos fényszámítások során). A rosszul formázott OBJ fájlokból származó nem normalizált normálok fényárnyalat hibákat okoznak.

Teljesítmény

• Töltsd be a fájlokat egyszer, és alakítsd át a memóriában lévő jelenetgrafikont ahelyett, hogy minden kimeneti formátumhoz újra betöltenéd a lemezről. Egyetlen Scene.from_file() hívás, majd több scene.save() hívás hatékonyabb, mint az ismételt betöltések.
• Nagy kötegek feldolgozásakor hozz létre egyetlen ObjLoadOptions vagy StlSaveOptions példányt, és használd újra minden fájlban, ahelyett, hogy minden fájlhoz új opciós objektumot hoznál létre.

Hibakezelés

• Befoglal scene.open() és scene.save() hívásokat try/except blokkokat, amikor nem megbízható vagy felhasználó által biztosított fájlokat dolgoz fel. Jelentse a fájlnevet a kivételüzenetekben, hogy egyszerűsítse a hibakeresést kötegelt folyamatokban.

Gyakori problémák

Gyakran Ismételt Kérdések

Mely Python verziók támogatottak? Python 3.7, 3.8, 3.9, 3.10, 3.11 és 3.12 mind támogatott. A könyvtár tiszta Python natív kiterjesztés nélkül, így bármely platformon működik, ahol a CPython fut.

Van a könyvtárnak bármilyen külső függősége? Nem. Aspose.3D FOSS for Python csak a Python szabványos könyvtárat használja. Egyetlen pip install aspose-3d-foss parancsként, további lépések nélkül.

Támogatott-e az FBX? Az FBX tokenizáló meg van valósítva, és képes feldolgozni a bináris FBX tokenfolyamot, de a tokenizáló fölött lévő jelenetgrafikon-építő ismert hibákkal rendelkezik, és nem késztermékhez alkalmas. Használja az OBJ, STL, glTF, COLLADA vagy 3MF formátumokat a megbízható termelési használathoz.

Használhatom a Aspose.3D FOSS-t egy kereskedelmi termékben? Igen. A könyvtár az MIT license alatt kerül kiadásra, amely lehetővé teszi a használatot zárt forráskódú és kereskedelmi szoftverekben jogdíjfizetés nélkül, feltéve hogy a licencértesítést belefoglalják.

Hogyan jelenthetek hibát vagy kérhetek egy formátumot? Nyisson egy hibajegyet a tárolóban. Mellékeljen egy minimális reprodukáló fájlt, valamint a Python verziót, az operációs rendszert és a könyvtár verzióját a pip show aspose-3d-foss.

API-referencia összefoglaló

Alap Osztályok

• Scene: 3D-s jelenet felső szintű tárolója. Belépési pont a open(), from_file(), és save().
• Node: Fa csomópont a jelenet gráfjában. Tartalmaz entity, transform, global_transform, material, child_nodes, és name.
• Entity: Alaposztály a csomópontokhoz csatolt objektumok számára (Mesh, Camera, Light).
• Transform: Helyi térbeli pozíció, forgatás (Quaternion) és méretezés egy csomóponthoz.
• GlobalTransform: Csak olvasható világ-térbeli transzformáció, amelyet az összes ős transzformáció összegzésével számolnak ki.

Geometria

• Mesh: Poligon háló a control_points (csúcspontlista) és polygons.
• VertexElementNormal: Csúcsonkénti vagy poligononkénti normálvektorok.
• VertexElementUV: Csúcsonkénti UV textúra koordináták.
• VertexElementVertexColor: Csúcsonkénti színadatok.
• VertexElementSmoothingGroup: Poligon simítási csoport hozzárendelések.

Anyagok

• LambertMaterial: Diffúz árnyalási modell a diffuse_color : és emissive_color.
• PhongMaterial: Speculáris árnyalási modell, amely hozzáad specular_color : és shininess.

: Matematikai segédfüggvények (aspose.threed.utilities)

• Vector2: 2D vektor.
• Vector3: 3D dupla pontosságú vektor.
• Vector4: 4D dupla pontosságú vektor.
• FVector3: 3D egyszeres pontosságú vektor.
• Quaternion: Rotációs kvaternion a from_angle_axis() : és to_matrix().
• Matrix4: 4×4 transzformációs mátrix.
• BoundingBox: Tengelyekhez igazított határoló doboz a minimum : és maximum : sarkok.

Animáció

• AnimationClip: Nevet kapott tároló egy animációs csatornák és azok kulcskockáik halmazához.
• AnimationNode: Csomópontonkénti animációs adatok egy klipben.
• KeyFrame: Egyetlen kulcskocka idővel és értékkel.
• KeyframeSequence: Rendezett sorozat kulcskockákból egyetlen animált tulajdonsághoz.

Betöltési / Mentési beállítások

• ObjLoadOptions: OBJ-specifikus betöltési beállítások: enable_materials, flip_coordinate_system, normalize_normal, scale.
• StlSaveOptions: STL-specifikus mentési beállítások (bináris vs. ASCII mód).

Kamerák és fények

• Camera: Kamera entitás projekciós beállításokkal, csatolható egy Node.
• Light: Fényforrás entitás, csatolható egy Node.