Savybės ir funkcionalumas

Aspose.3D FOSS for Python suteikia visapusišką scenų grafų API, skirtą skaityti, kurti ir rašyti 3D turinį keliais pramonės standartiniais formatais. Šiame puslapyje dokumentuojamos visos pagrindinės funkcijų sritys su veiksniais Python kodo pavyzdžiais, kurie naudoja tikrąją bibliotekos API.

Įdiegimas ir konfigūracija

Įdiekite biblioteką iš PyPI viena komanda:

pip install aspose-3d-foss

Nereikia jokių papildomų sistemos paketų, natūralių plėtinių ar kompiliatorių įrankių grandinių. Biblioteka yra grynas Python ir palaiko Python 3.7–3.12 Windows, macOS ir Linux operacinėse sistemose.

Norėdami patikrinti įdiegimą:

from aspose.threed import Scene

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

Savybės ir funkcionalumas

Formatų palaikymas

Aspose.3D FOSS for Python skaito ir rašo šiuos formatus:

OBJ įkėlimas su parinktimis

ObjLoadOptions valdo, kaip OBJ failai yra skaidomi:

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

Išsaugojimas į STL

StlSaveOptions valdo dvejetainį ir ASCII išvestį bei kitus STL specifinius nustatymus:

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

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

Scenos grafas

Visas 3D turinys organizuotas kaip medžio struktūra, sudaryta iš Node objektų. Medžio šaknis yra scene.root_node. Kiekvienas mazgas gali turėti vaikų mazgus ir nešti Entity (tinklelį, kamerą arba šviesą) ir Transform.

Scenos hierarchijos naršymas

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)

Scenos kūrimas programiškai

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 peržiūra

GlobalTransform nurodo mazgo pasaulio erdvės transformaciją po visų tėvų transformacijų sukaupimo:

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 objektas suteikia prieigą prie geometrijos duomenų, įskaitant valdymo taškus (viršūnes), daugiakampius ir viršūnių elementus normalioms, UV koordinatėms ir spalvoms.

Mesh geometrijos skaitymas

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

Viršūnių elementų prieiga

Viršūnių elementai talpina duomenis, priskirtus kiekvienai viršūnei arba daugiakampiui. Dažniausiai pasitaikantys elementai yra normalių, UV koordinatės, viršūnių spalvos ir glotninimo grupės:

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

Medžiagų sistema

Aspose.3D FOSS palaiko du medžiagų tipus: LambertMaterial (difuzinis apšvietimas) ir PhongMaterial (speculiarus apšvietimas). Abu įkelti automatiškai iš .mtl failų naudojant ObjLoadOptions su enable_materials = True.

Medžiagų skaitymas iš 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}")

Medžiagos priskyrimas programiškai

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

Matematinės priemonės

Šis aspose.threed.utilities modulį suteikia visus geometrinius matematikos tipus, reikalingus scenos kūrimui ir inspekcijai.

Darbas su transformacijomis

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

Ribinės dėžės skaičiavimas

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

Animacija

Aspose.3D FOSS suteikia animacijos modelį, pagrįstą AnimationClip, AnimationNode, KeyFrame, ir KeyframeSequence. Animacijos duomenys, saugomi įkeltuose failuose (glTF, COLLADA), yra prieinami per šiuos objektus.

Animacijos klipų skaitymas

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

Įkėlimo ir išsaugojimo parinktys

Kiekvienas palaikomas formatas turi atitinkamą parinkčių klasę, kuri kontroliuoja analizės ir serializacijos elgseną.

Naudojimo pavyzdžiai

Pavyzdys 1: OBJ į STL formato konvertavimas

Konvertuokite OBJ failą (su medžiagomis) į binarinį STL, spausdindami tinklo statistiką kelio metu:

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

Pavyzdys 2: Masinis glTF į GLB pakavimas

Iš naujo įrašykite katalogą su atskirais glTF + tekstūros failais kaip savarankiškus GLB binarinius 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)}")

Pavyzdys 3: Scenos grafiko patikrinimas ir eksporto ataskaita

Eikite per COLLADA failo scenos grafiką, surinkite kiekvieno tinklo statistiką ir atspausdinkite struktūruotą ataskaitą:

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

Patarimai ir geriausia praktika

Formato pasirinkimas

• glTF 2.0 / GLB yra rekomenduojamas keitimosi formatas scenoms, kurios apima medžiagas, animacijas ir sudėtingas hierarchijas. Rekomenduojama naudoti GLB (binarinį) vietoje glTF (teksto + išorinių failų) dėl perkeliamosios savybės.
• STL yra tinkamas pasirinkimas, kai galutinis vartotojas yra pjaustymo programa, CAD įrankis arba bet kuris įrankis, kuriam reikia tik geometrijos. STL neperduoda medžiagų ar animacijos duomenų.
• OBJ yra plačiai palaikomas ir geras pasirinkimas, kai medžiagų duomenys turi būti keičiamasi su senesniais įrankiais. Visada laikykite .mtl failą šalia .obj failo.

Koordinačių sistemos

• Skirtingos programos naudoja skirtingas dešinės/kairės rankos konvencijas. Nustatykite ObjLoadOptions.flip_coordinate_system = True kai importuojate OBJ failus iš įrankių, kurie naudoja dešiniąją koordinatinę sistemą, jei jūsų duomenų srautas tikisi kairiosios koordinatės, ir atvirkščiai.
• Patikrinkite šaltinio turinio ašies konvenciją prieš atlikdami bet kokį apvertimą. Dvigubas apvertimas sukelia neteisingą geometriją.

Normalizavimas

• Visada nustatykite ObjLoadOptions.normalize_normal = True kai galutinis duomenų srautas tikisi vienetinių normalių (pavyzdžiui, perduodant normales į šėminių programą arba atliekant taškų sandaugos apšvietimo skaičiavimus). Nenormalizuotos normalių iš blogai suformuotų OBJ failų sukelia apšvietimo artefaktus.

Našumas

• Įkelkite failus vieną kartą ir transformuokite atmintyje esantį scenos grafiką, o ne pakartotinai įkelkite iš disko kiekvienam išvesties formatui. Vienas Scene.from_file() kvietimas, po kurio seka keli scene.save() kvietimai yra efektyvesni nei pakartotiniai įkėlimai.
• Apdorojant didelius paketus, sukurkite vieną ObjLoadOptions arba StlSaveOptions instanciją ir naudokite ją visų failų metu, vietoj to, kad kiekvienam failui sukurtumėte naują parametrų objektą.

Klaidų tvarkymas

• Apgaubti scene.open() ir scene.save() kvietimus į try/except blokus, kai apdorojami nepatikimi arba vartotojo pateikti failai. Praneškite failo pavadinimą išimčių pranešimuose, kad supaprastintumėte derinimą paketiniuose konvejeriuose.

Dažnos problemos

Dažnai užduodami klausimai

Kokios Python versijos palaikomos? Python 3.7, 3.8, 3.9, 3.10, 3.11 ir 3.12 yra visi palaikomi. Biblioteka yra grynas Python be jokių natūralių plėtinių, todėl veikia bet kurioje platformoje, kurioje veikia CPython.

Ar biblioteka turi kokių nors išorinių priklausomybių? Ne. Aspose.3D FOSS for Python naudoja tik Python standartinę biblioteką. Ji įdiegiama kaip vienas pip install aspose-3d-foss komanda be jokių papildomų žingsnių.

Ar FBX palaikomas? FBX tokenizatorius yra įgyvendintas ir gali analizuoti binarinį FBX tokenų srautą, tačiau scenų grafiko kūrėjas, veikiantis virš tokenizatoriaus, turi žinomų klaidų ir nėra paruoštas gamybai. Naudokite OBJ, STL, glTF, COLLADA arba 3MF patikimam gamybos naudojimui.

Ar galiu naudoti Aspose.3D FOSS komerciniame produkte? Taip. Biblioteka išleista pagal MIT licenciją, kuri leidžia naudoti ją nuosavybinėje ir komercinėje programinėje įrangoje be autorinių mokėjimų, jei įtraukiamas licencijos pranešimas.

Kaip pranešti apie klaidą arba paprašyti formato? Atidarykite problemos pranešimą saugykloje. Įtraukite minimalų reprodukcijos failą ir Python versiją, operacinę sistemą bei bibliotekos versiją iš pip show aspose-3d-foss.

API nuorodų santrauka

Pagrindinės klasės

• Scene: Aukščiausio lygio konteineris 3D scenai. Įėjimo taškas for open(), from_file(), ir save().
• Node: Medžio mazgas scenos grafike. Neša entity, transform, global_transform, material, child_nodes, ir name.
• Entity: Bazinė klasė objektams, prisegtų prie mazgų (Mesh, Camera, Light).
• Transform: Vietos erdvės pozicija, sukimas (Quaternion) ir mastelis mazgui.
• GlobalTransform: Tik skaitymui skirtas pasaulio erdvės transformavimas, apskaičiuojamas sukaupti visų protėvių transformacijas.

Geometry

• Mesh: Poligono tinklelis su control_points (viršūnių sąrašas) ir polygons.
• VertexElementNormal: Kiekvienos viršūnės arba poligono normaliniai vektoriai.
• VertexElementUV: Kiekvienos viršūnės UV tekstūros koordinatės.
• VertexElementVertexColor: Kiekvienos viršūnės spalvų duomenys.
• VertexElementSmoothingGroup: Poligono glotninimo grupių priskyrimai.

Medžiagos

• LambertMaterial: Difuzinis apšvietimo modelis su diffuse_color ir emissive_color.
• PhongMaterial: Spekuliarinio šešėliavimo modelio pridėjimas specular_color ir shininess.

Matematinės priemonės (aspose.threed.utilities)

• Vector2: 2D vektorius.
• Vector3: 3D dvigubo tikslumo vektorius.
• Vector4: 4D dvigubo tikslumo vektorius.
• FVector3: 3D viengubo tikslumo vektorius.
• Quaternion: Sukimo kvaternionas su from_angle_axis() ir to_matrix().
• Matrix4: 4×4 transformacijos matrica.
• BoundingBox: Ašies lygiavietė ribinė dėžė su minimum ir maximum kampais.

Animacija

• AnimationClip: Pavadintas konteineris, skirtas animacijos kanalų rinkiniui ir jų raktiniams kadrams.
• AnimationNode: Kiekvieno mazgo animacijos duomenys klipo viduje.
• KeyFrame: Vienas raktinis kadras su laiku ir verte.
• KeyframeSequence: Surikiuota raktinių kadrų seka vienam animuotam požymiui.

Įkėlimo / Išsaugojimo parinktys

• ObjLoadOptions: OBJ specifiniai įkėlimo nustatymai: enable_materials, flip_coordinate_system, normalize_normal, scale.
• StlSaveOptions: STL specifiniai įrašymo nustatymai (dvejetainis vs. ASCII režimas).

Kameros ir šviesos

• Camera: Kameros objektas su projekcijos nustatymais, prijungiamas prie a Node.
• Light: Šviesos šaltinio objektas, prijungiamas prie a Node.