Aspose.3D FOSS
Python
Příručka pro vývojáře
Charakteristika a funkčnost

Charakteristika a funkčnost

Aspose.3D FOSS pro Python poskytuje kompletní scénografické API pro čtení, konstrukci a psaní 3D obsahu v několika standardních formátech. Tato stránka dokumentuje každou hlavní oblast funkcí s pracovními příklady kódu Pythonu, které používají skutečnou knihovnu API .

Instalace a nastavení

Nainstalujte knihovnu z PyPI jediným příkazem:

asposefoss/3d is not yet published — build from source until it ships. See the project README for build instructions.

Knihovna je čistě Python a podporuje Python 3.7 až 3.12 na Windows, macOS a Linux.

Pro ověření zařízení:

from aspose.threed import Scene

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

Charakteristika a funkčnost

Podpora formátu

Aspose.3D FOSS pro Python čte a píše následující formáty:

FormátRozšířeníČtěte.Píšeš.Poznámky
OBJ.objAno , ano .Ano , ano .Podporuje se zatížení materiálu s vlnovou čelní oběžnou plochou.
STL.stlAno , ano .Ano , ano .Binární a ASCII varianty; ověřena cesta zpět
glTF.gltf / .glbAno , ano .Ano , ano .binární kontejner JSON a GLB v rámci systému glTF 2.0
COLLADA.daeAno , ano .Ano , ano .Hierarchie scén a materiály
3MF.3mfAno , ano .Ano , ano .Formát výrobního doplňku
FBX.fbxČástečná částNe, ne.Tokenizer funguje; parser má známé chyby

Naložení OBJ s možnostmi

ObjLoadOptions ovládá, jak jsou soubory OBJ analyzovány:

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

Ušetření na STL

StlSaveOptions ovládá výstup binární versus ASCII a další nastavení specifická pro STL:

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

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

Graf scény

Všechny 3D obsah je organizován jako strom Node Kořen stromu je… scene.root_node.Každý uzel může obsahovat dětské uzly a nesou Entity (mříž, kamera nebo světlo) plus a Transform.

Procházím hierarchii scén 

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)

Programatické stavění scény 

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

Inspekce společnosti GlobalTransform

GlobalTransform dává transformovanou světovou prostorovou hodnotu uzlu po akumulaci všech předků:

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

API pro sítě

Úřad pro bezpečnost a ochranu zdraví Mesh subjekt poskytuje přístup k geometrickým údajům včetně kontrolních bodů (křivek), polygonů a prvků vrcholu pro normály, UV a barvy.

Čtení geometrie sítí 

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

Přístup k prvkům vrcholu

Nejběžnější prvky jsou normály, UV souřadnice, barvy vrcholu a vyhlazující skupiny:

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ální systém

Aspose.3D FOSS podporuje dva typy materiálů: LambertMaterial (rozptýlené stínění) a PhongMaterial Obě jsou automaticky načteny z .mtl souborů při použití. ObjLoadOptions s: enable_materials = True.

Čtení materiálu z 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}")

Programatické přidělování materiálu 

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

Matematické nástroje

Úřad pro bezpečnost a ochranu zdraví aspose.threed.utilities Modul poskytuje všechny geometrické matematické typy potřebné pro konstrukci a inspekci scény.

TřídaÚčel:
Vector22D floating-point vector (UV coordinates)
Vector33D double-precision vector (positions, normals)
Vector44D double-precision vector (homogeneous coordinates)
FVector33D single-precision vector (compact storage)
QuaternionRotační zobrazení bez zámku na kolouši
Matrix44×4 transformation matrix
BoundingBoxOmezující pole s osovou rovinou a minimálními/maximalizovanými rohy

Práce s transformy 

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

Vypočítání omezujícího políčka 

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

Animování

Aspose.3D FOSS poskytuje animovaný model založený na: AnimationClip, AnimationNode, KeyFrame,a) KeyframeSequence.Daty animace uložené v načtených souborech (glTF, COLLADA) jsou přístupné prostřednictvím těchto objektů.

Čtení animovaných videoklipů 

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

Možnosti načítání a ukládání

Každý podporovaný formát má odpovídající třídu možností, která ovládá chování analýzy a serializace.

TřídaFormátKlíčové vlastnosti
ObjLoadOptionsOBJenable_materials, flip_coordinate_system, normalize_normal, scale
StlSaveOptionsSTLBinární versus ASCII výstupní režim
(glTF používá výchozí nastavení)GLB / GTFGraf scény a materiály automaticky zachované

Příklady použití

Příklad 1: Konverze formátu OBJ na STL

Konverze souboru OBJ (s materiály) na binární STL, tisk statistických sítí po cestě:

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říklad 2: Šarže glTF na balení GLB

Opětovné uložení adresáře samostatných texturních souborů glTF + jako samosprávných binárních dat GLB:

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říklad 3: Inspekce grafu scény a vývozná zpráva

Projděte grafickou scény souboru COLLADA, shromažďujte statistiku na síť a vytiskněte strukturovanou zprávu:

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

Tipy a nejlepší postupy

Výběr formátu

  • glTF 2.0 / GLB je doporučený formát pro výměnu scén, které obsahují materiály, animace a složité hierarchie. Preferujte GLB (binární) před glTF (text + externí soubory) pro přenositelnost.
  • STL je správnou volbou, pokud se spotřebitelům podél proudu jedná o řezačku, CAD nástroj nebo jakýkoli jiný nástroj, který potřebuje pouze geometrii. STL neobsahuje žádné materiály ani animační údaje.
  • OBJ je široce podporován a dobrá volba, když se musí výměna materiálních dat provádět s staršími nástroji. Vždy si uchovávajte soubor .mtl vedle souboru .obj.

Systémy koordinací

  • Různé aplikace používají různá konvence pro ruční ovládání. ObjLoadOptions.flip_coordinate_system = True při dovozu souborů OBJ z nástrojů, které používají systém pravostřelených souřadnic, pokud vaše potrubí očekává levá souprava a naopak.
  • Před použitím jakéhokoli otáčení ověřte osovou konvenci zdrojového aktiva. Dvakrát otáčení vytváří nesprávnou geometrii.

Normalizace

  • Vždy nastaven. ObjLoadOptions.normalize_normal = True když plynovod dále očekává jednotkové normály (například při předávání normálů shaderovi nebo provádění výpočtů osvětlení bodového produktu). Nenormální normality z špatně vytvořených souborů OBJ způsobují světelné artefakty.

Výkonnost

  • Nahrávka souborů jednou a přeměnit grafu scény v paměti místo načtení z disku pro každý výstupní formát. Scene.from_file() volání následované množinou scene.save() volání je efektivnější než opakované zatížení.
  • Při zpracování velkých šarží se vytvoří jednotná ObjLoadOptions nebo: StlSaveOptions Příklad a opětovně použít v rámci všech souborů namísto vytváření nového objektu pro každý soubory.

Zpracování chyb

  • Obalování scene.open() a) scene.save() volání do try/except bloky při zpracování nespolehlivých nebo uživatelsky dodaných souborů. Oznamte název souboru v výjimkách, aby se zjednodušilo debugging ve skupinových potrubích.

Obvyklé problémy

Výše:Příčina:Rozhodnutí
Oblečení sítě se po naložení zobrazuje jako zrcadlo.Nesoulad s kontrolou souřadnicového systémuPřepínání ObjLoadOptions.flip_coordinate_system
Normální jsou nulové.Zdrojový soubor má normální hodnoty .Sestavení: ObjLoadOptions.normalize_normal = True
Materiály neobsahující OBJenable_materials byla nastavena na: FalseSestavení: ObjLoadOptions.enable_materials = True (to je již standardní)
Scéna je načtená, ale všechny uzly jsou prázdné.Soubor používá formát FBXFBX parser je v průběhu; místo toho použijte OBJ, STL nebo glTF
Model je extrémně malý nebo velký.Zdrojový soubor používá nemetrické jednotkyPřihláška ObjLoadOptions.scale konverzovat do cílové jednotky.
AttributeError v roce 2007: mesh.polygonsEntita uzlu není síťová souprava .Stráž s: if node.entity is not None před přístupem k vlastnostem subjektu
Soubor GLB je odmítnut prohlížečem.Ušetřeno s … .gltf rozšířeníPoužití: .glb prodloužení při volání scene.save() k spustění binárního kontejneru.

Časté otázky

Jaké verze Pythonu jsou podporovány? Python 3.7, 3.8, 3.9, 3.10, 3.11 a 3.12 jsou všechny podporovány. Knihovna je čistý Python bez nativního rozšíření, takže funguje na jakékoli platformě, kde běží CPython .

Má knihovna nějaké externí závislosti? Ne. Aspose.3D FOSS pro Python používá pouze standardní knihovnu Pythonu. Instaluje se jako jednotný program, který je součástí programu a současně s jeho funkcí. pip install aspose-3d-foss Příkaz bez dalšího postupu.

Podporuje se FBX? Tokenizer FBX je implementován a může analyzovat binární tokensový proud FBx, ale stavitel scén-grafu na vrcholu tokenizera má známé chyby a není připraven k výrobě. Pro spolehlivé použití ve výrobní oblasti použijte OBJ, STL, glTF, COLLADA nebo 3MF.

Mohu použít Aspose.3D FOSS v komerčním produktu? Knihovna je vydána pod licencí MIT, která umožňuje použití v proprietárním a komerčním softwaru bez placení poplatků za licence.

Jak hlásím chybu nebo požaduji formát? Otevřete problém v úložišti. Zahrňte minimální reprodukční soubor a verzi Python, operačního systému a verze knihovny z pip show aspose-3d-foss.

Souhrnná referenční informace API

Jádro tříd

  • Scene: Kontejner nejvyšší úrovně pro 3D scénu. Vstupní místo pro open(), from_file(),a) save().
  • Node: Stromový uzel v grafu scény. Převádí: entity, transform, global_transform, material, child_nodes,a) name.
  • Entity: Základní třída pro objekty připojené k uzlům (Mesh, Kamera, Light).
  • Transform: Místní prostorová pozice, rotace (Quaternion) a měřítko pro uzel.
  • GlobalTransform: Transformace světového prostoru pouze pro čtení vypočítaná akumulací všech předků.

Geometrie

  • Mesh: Většina polygonů s: control_points (seznam vrcholů) a polygons.
  • VertexElementNormal: Normální vektory na vrchol nebo polygon.
  • VertexElementUV: Koordináty UV textury v rámci vrcholu.
  • VertexElementVertexColor: Získané barvové údaje.
  • VertexElementSmoothingGroup: Přidělení skupin pro vyhlazování polygonů.

Materiály

  • LambertMaterial: Model difúzního stínění s: diffuse_color a) emissive_color.
  • PhongMaterial: Přidání zrcadlového modelu stínění specular_color a) shininess.

Math Utilities (aspose.threed.utilities)

  • Vector2:Dvojrozměrný vektor.
  • Vector3:3D dvojitě přesný vektor.
  • Vector4: 4D dvojitě přesný vektor.
  • FVector3:3D jednotlivé přesné vektory.
  • Quaternion: rotační kvaternión s: from_angle_axis() a) to_matrix().
  • Matrix4:4x4 transformační matrice.
  • BoundingBox: Omezující pole se směřováním k ose s: minimum a) maximum Z rohů.

Animování

  • AnimationClip: Jmenovaný kontejner pro soubor animačních kanálů a jejich klíčové snímky.
  • AnimationNode: Animované údaje na jeden uzel v klipu.
  • KeyFrame:Jednotný klíčový rám s časem a hodnotou.
  • KeyframeSequence: Pořadí klíčových snímků pro jednu animovanou vlastnost.

Možnosti načítání / uložení

  • ObjLoadOptions: Nastavení zatížení specifické pro OBJ: enable_materials, flip_coordinate_system, normalize_normal, scale.
  • StlSaveOptions: Nastavení ukládání specifické pro STL (binární versus ASCII režim).

Kamery a světla

  • Camera: Kamera s projekčním nastavením, připojená k Node.
  • Light: Složka světelného zdroje, připojená k Node.
 Čeština