Funkcijas un iespējas

Aspose.3D FOSS for Python nodrošina pilnīgu ainas grafika API, lai lasītu, veidotu un rakstītu 3D saturu vairākos nozares standartos formātos. Šī lapa dokumentē katru galveno funkciju jomu ar darbos Python koda piemēriem, kas izmanto patieso bibliotēkas API.

Instalēšana un iestatīšana

Instalējiet bibliotēku no PyPI ar vienu komandu:

pip install aspose-3d-foss

Nav nepieciešami papildu sistēmas pakotnes, vietējie paplašinājumi vai kompilatora rīkkopas. Bibliotēka ir tīra Python un atbalsta Python 3.7 līdz 3.12 operētājsistēmās Windows, macOS un Linux.

Lai pārbaudītu instalāciju:

from aspose.threed import Scene

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

Funkcijas un iespējas

Formātu atbalsts

Aspose.3D FOSS for Python lasa un raksta šādus formātus:

OBJ ielāde ar opcijām

ObjLoadOptions kontrolē, kā tiek parsēti OBJ faili:

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

Saglabāšana uz STL

StlSaveOptions kontrolē binārā un ASCII izvadi, kā arī citus STL specifiskus iestatījumus:

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

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

Ainas grafiks

Visais 3D saturs ir organizēts kā koks no Node objektiem. Koka sakne ir scene.root_node. Katrs mezgls var saturēt bērna mezglus un nēsāt Entity (tīklu, kameru vai gaismu) plus a Transform.

Ainas hierarhijas pārlūkošana

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)

Ainas izveide programmatiski

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 pārbaude

GlobalTransform sniedz mezgla pasaules telpas transformāciju pēc visu priekšgājēju transformāciju uzkrāšanas:

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

Šis Mesh vienība nodrošina piekļuvi ģeometrijas datiem, ieskaitot kontroles punktus (virsotnes), daudzstūrus un virsotņu elementus normālēm, UV un krāsām.

Tīklu ģeometrijas nolasīšana

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

Virsotņu elementu piekļuve

Virsotņu elementi nes per-virsotnes vai per-daugstūru datus. Visbiežākie elementi ir normāles, UV koordinātas, virsotņu krāsas un gludināšanas grupas:

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

Materiālu sistēma

Aspose.3D FOSS atbalsta divus materiālu tipus: LambertMaterial (diffūzija ēnojums) un PhongMaterial (spoguļveida ēnojums). Abas tiek ielādētas automātiski no .mtl failiem, lietojot ObjLoadOptions ar enable_materials = True.

Materiālu nolasīšana no 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}")

Materiāla piešķiršana programmatiski

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

Matemātikas utilītprogrammas

Šis aspose.threed.utilities modulis nodrošina visus ģeometriskos matemātikas tipus, kas nepieciešami ainas izveidei un pārbaudei.

Darbs ar transformācijām

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

Apmēra kastes aprēķināšana

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ācija

Aspose.3D FOSS nodrošina animācijas modeli, kas balstīts uz AnimationClip, AnimationNode, KeyFrame, un KeyframeSequence. Animācijas dati, kas saglabāti ielādētos failos (glTF, COLLADA), ir pieejami caur šiem objektiem.

Animācijas klipu nolasīšana

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

Ielādes un saglabāšanas opcijas

Katram atbalstītajam formātam ir atbilstoša opciju klase, kas kontrolē parsēšanas un serializācijas uzvedību.

Lietošanas piemēri

Piemērs 1: OBJ uz STL formāta konvertēšana

Pārvērst OBJ failu (ar materiāliem) uz bināro STL, izdrukājot režģa statistiku ceļā:

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

Piemērs 2: Batch glTF uz GLB pakotne

Atkārtoti saglabāt direktoriju ar atsevišķiem glTF + tekstūru failiem kā pašpietiekamus GLB bināros failus:

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

Piemērs 3: Scēnas grafa pārbaude un eksporta ziņojums

Pāriet cauri COLLADA faila scēnas grafam, savāc katra režģa statistiku un izdrukā strukturētu ziņojumu:

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

Padomi un labākā prakse

Formāta izvēle

• glTF 2.0 / GLB ir ieteicamais apmaiņas formāts ainas, kas ietver materiālus, animācijas un sarežģītas hierarhijas. Dodiet priekšroku GLB (binārais) pār glTF (teksts + ārējie faili) portabilitātes dēļ.
• STL ir pareizā izvēle, kad lejupplūsmas patērētājs ir slicer, CAD rīks vai jebkurš rīks, kas nepieciešama tikai ģeometrija. STL nesatur materiālu vai animācijas datus.
• OBJ ir plaši atbalstīts un ir laba izvēle, kad materiālu datus jāapmaina ar vecākiem rīkiem. Vienmēr turiet .mtl failu blakus .obj failam.

Koordinātu sistēmas

• Dažādas lietojumprogrammas izmanto dažādas rokas orientācijas konvencijas. Iestatiet ObjLoadOptions.flip_coordinate_system = True importējot OBJ failus no rīkiem, kas izmanto labro roku koordinātu sistēmu, ja jūsu cauruļvads sagaida kreiso roku koordinātas, un otrādi.
• Pārbaudiet avota līdzekļa ass konvenciju pirms veicat jebkuru apgriešanu. Divkārša apgriešana rada nepareizu ģeometriju.

Normalizācija

• Vienmēr iestatiet ObjLoadOptions.normalize_normal = True kad lejupplūsmas cauruļvads sagaida vienības normāles (piemēram, pārsūtot normāles shaderim vai veicot punktu reizinājuma apgaismojuma aprēķinus). Nenormētas normāles no slikti veidotiem OBJ failiem izraisa apgaismojuma artefaktus.

Veiktspēja

• Ielādējiet failus tikai vienreiz un pārveidojiet atmiņā esošo ainas grafu, nevis pārlādējiet no diska katram izvades formātam. Viena Scene.from_file() izsaukums, kam seko vairāki scene.save() izsaukumi ir efektīvāki nekā atkārtoti ielādes.
• Apstrādājot lielas partijas, izveidojiet vienu ObjLoadOptions vai StlSaveOptions instance un atkārtoti izmantojiet to visos failos, nevis katram failam izveidot jaunu opciju objektu.

Kļūdu apstrāde

• Iesaiņojiet scene.open() un scene.save() izsauc try/except bloķē, apstrādājot neuzticamus vai lietotāja piegādātus failus. Ziņojiet faila nosaukumu izņēmumu ziņojumos, lai vienkāršotu atkļūdošanu partijas cauruļvados.

Biežāk sastopamās problēmas

Biežāk uzdotie jautājumi

Kādas Python versijas tiek atbalstītas? Python 3.7, 3.8, 3.9, 3.10, 3.11, un 3.12 visi tiek atbalstīti. Bibliotēka ir tīra Python bez jebkādām vietējām paplašinājumiem, tāpēc tā darbojas jebkurā platformā, kur darbojas CPython.

Vai bibliotēkai ir kādas ārējas atkarības? Nē. Aspose.3D FOSS priekš Python izmanto tikai Python standarta bibliotēku. Tas instalējas kā vienots pip install aspose-3d-foss komanda bez papildu soļiem.

Vai FBX tiek atbalstīts? FBX tokenizators ir implementēts un spēj parsēt bināro FBX tokenu plūsmu, bet virs tokenizatora esošais ainas grafika veidotājs ir zināmu kļūdu dēļ un nav gatavs ražošanai. Izmantojiet OBJ, STL, glTF, COLLADA vai 3MF, lai nodrošinātu uzticamu ražošanas lietošanu.

Vai varu izmantot Aspose.3D FOSS komerciālam produktam? Jā. Bibliotēka ir izlaista zem MIT licences, kas ļauj izmantot to īpašnieku un komerciālu programmatūru bez honorāru maksājumiem, ja tiek iekļauts licences paziņojums.

Kā ziņot par kļūdu vai pieprasīt formātu? Atveriet problēmu repozitorijā. Iekļaujiet minimālu reproducēšanas failu, kā arī Python versiju, operētājsistēmu un bibliotēkas versiju no pip show aspose-3d-foss.

API Atsauces Kopsavilkums

Pamatklases

• Scene: Augstākā līmeņa konteineram 3D aina. Ieejas punkts for open(), from_file(), un save().
• Node: Koka mezgls ainas grafā. Nēsā entity, transform, global_transform, material, child_nodes, un name.
• Entity: Pamata klase objektiem, kas pievienoti mezgliem (Mesh, Camera, Light).
• Transform: Lokālās telpas pozīcija, rotācija (Kvaternions) un mērogs mezglam.
• GlobalTransform: Tikai lasāma pasaules telpas transformācija, kas aprēķināta, uzkrājot visu priekšgājēju transformācijas.

Ģeometrija

• Mesh: Poligonu tīkls ar control_points (virsotņu saraksts) un polygons.
• VertexElementNormal: Normālie vektori uz katras virsotnes vai katras daudzstūra.
• VertexElementUV: UV tekstūras koordinātas uz katras virsotnes.
• VertexElementVertexColor: Krāsu dati uz katras virsotnes.
• VertexElementSmoothingGroup: Daudzstūru gludināšanas grupu piešķiršana.

Materiāli

• LambertMaterial: Difūzs ēnošanas modelis ar diffuse_color : un emissive_color.
• PhongMaterial: Spoguļveida ēnošanas modelis, pievienojot specular_color : un shininess.

: Matemātikas utilītprogrammas (aspose.threed.utilities)

• Vector2: 2D vektors.
• Vector3: 3D dubultprecizitātes vektors.
• Vector4: 4D dubultprecizitātes vektors.
• FVector3: 3D vienkāršprecizitātes vektors.
• Quaternion: Rotācijas kvaternions ar from_angle_axis() un to_matrix().
• Matrix4: 4×4 transformācijas matrica.
• BoundingBox: Ašas izlīdzināta robežkaste ar minimum un maximum stūri.

Animācija

• AnimationClip: Nosaukts konteineris kopai animācijas kanālu un to atslēgkadriem.
• AnimationNode: Animācijas dati katram mezglam klipa ietvaros.
• KeyFrame: Viens atslēgkadris ar laiku un vērtību.
• KeyframeSequence: Kārtota atslēgkadru secība vienai animētai īpašībai.

Ielādes / Saglabāšanas iespējas

• ObjLoadOptions: OBJ‑specifiski ielādes iestatījumi: enable_materials, flip_coordinate_system, normalize_normal, scale.
• StlSaveOptions: STL‑specifiski saglabāšanas iestatījumi (binārais vs. ASCII režīms).

Kameras un gaismas

• Camera: Kameras vienība ar projekcijas iestatījumiem, pievienojama pie Node.
• Light: Gaismas avota vienība, kas var tikt pievienota Node.