Ako zostaviť 3D sieť s Aspose.3D v Pythone

Aspose.3D FOSS for Python vám umožňuje vytvárať 3D geometriu výlučne v kóde: nie je potrebný žiadny externý modelovací nástroj. Vytvoríte Mesh, naplníte ho pozíciami vrcholov (control_points) a definíciami plôch (polygons), pripojíte voliteľné atribúty vrcholov, ako sú normály, a potom uložíte scénu do akéhokoľvek podporovaného formátu.

Krok za krokom sprievodca

Krok 1: Nainštalujte balík

Nainštalujte Aspose.3D FOSS z PyPI. Nie sú potrebné natívne rozšírenia ani kompilátorový nástrojový reťazec.

pip install aspose-3d-foss

Overte inštaláciu:

from aspose.threed import Scene
print("Aspose.3D FOSS ready")

Podporované verzie Pythonu: 3.7, 3.8, 3.9, 3.10, 3.11, 3.12.

Krok 2: Vytvorte scénu a uzol

Každá sieť musí byť v grafu scény. Vytvorte Scene a pridajte pomenovaný Node na uchovanie siete:

from aspose.threed import Scene

scene = Scene()
node = scene.root_node.create_child_node("triangle")

Názov uzla je zachovaný v exportovanom súbore a je užitočný pre ladenie a neskoršie načítanie prostredníctvom node.get_child("triangle").

Krok 3: Vytvoriť Mesh objekt

Vytvorte inštanciu Mesh s voliteľným opisným názvom:

from aspose.threed.entities import Mesh

mesh = Mesh("triangle")

Sieť je spočiatku prázdna: žiadne vrcholy, žiadne polygóny. Naplníte ju nasledujúcimi krokmi.

Krok 4: Pridať kontrolné body (vrcholy)

Kontrolné body sú pozície vrcholov. Každý vrchol je uložený ako Vector4(x, y, z, w), kde w=1 označuje bod v 3D priestore:

from aspose.threed.utilities import Vector4

##Vertex 0: origin
# Note: control_points returns a copy of the internal vertex list.
# Appending to the returned copy discards the vertex silently.
# Use _control_points to mutate the backing list directly.
# This is a known library limitation — a public add_control_point() API is not yet available.
mesh._control_points.append(Vector4(0.0, 0.0, 0.0, 1.0))

##Vertex 1: 1 unit along X
mesh._control_points.append(Vector4(1.0, 0.0, 0.0, 1.0))

##Vertex 2: apex
mesh._control_points.append(Vector4(0.5, 1.0, 0.0, 1.0))

print(f"Vertices added: {len(mesh.control_points)}")

Dôležité: mesh.control_points vracia kópiu interného zoznamu vrcholov (getter vykoná list(self._control_points)). Volanie mesh.control_points.append(v) pridá do kópie, nie do siete, takže vrchol je ticho zahodený. Vždy používajte mesh._control_points.append(v) na pridávanie vrcholov. Prístup k súkromnému stavu cez _control_points je známy obchádzkový spôsob; rozhranie sa môže v budúcej verzii knižnice zmeniť.

Krok 5: Vytvoriť polygonové plochy

Definujte topológiu plochy pomocou indexov vrcholov. Predajte indexy vrcholov do create_polygon(). Tri indexy vytvoria trojuholník; štyri vytvoria štvoruholník:

##Triangle: connect vertices 0 → 1 → 2
mesh.create_polygon(0, 1, 2)

print(f"Polygon count: {mesh.polygon_count}")

Pre štvoruholníkovú sieť by ste odovzdali štyri indexy: mesh.create_polygon(0, 1, 2, 3).

Indexy musia byť platné pozície v control_points (základom 0, v rozsahu). Poradie otáčania je proti smeru hodinových ručičiek pre normály smerujúce von.

Krok 6: Pridať normály vrcholov

Normály vrcholov sú uložené ako VertexElement pripojený k meshu. Použite mesh.create_element() s VertexElementType.NORMAL, MappingMode.CONTROL_POINT a ReferenceMode.DIRECT:

from aspose.threed.entities import VertexElementType, MappingMode, ReferenceMode, VertexElementNormal
from aspose.threed.utilities import Vector4, FVector4

##Create the normal element (returns VertexElementNormal, a VertexElementFVector subclass)
normals: VertexElementNormal = mesh.create_element(
    VertexElementType.NORMAL,
    MappingMode.CONTROL_POINT,
    ReferenceMode.DIRECT
)

##One normal per vertex: all pointing out of the XY plane (0, 0, 1)
normals.set_data([
    FVector4(0, 0, 1, 0),   # vertex 0
    FVector4(0, 0, 1, 0),   # vertex 1
    FVector4(0, 0, 1, 0),   # vertex 2
])

print("Normal layer attached.")

MappingMode.CONTROL_POINT znamená jeden normál na vrchol. ReferenceMode.DIRECT znamená, že normálové dáta sa čítajú v rovnakom poradí ako kontrolné body (žiadny extra indexový buffer).

Normálové vektory používajú FVector4(x, y, z, w) s w=0 na označenie smeru namiesto polohy. FVector4 je jednopresný floatový vektor; dáta atribútu vrchola v podtriedach VertexElementFVector používajú tento typ.

Krok 7: Pripojte mesh k uzlu a uložte

Pridajte sieť do uzla, potom uložte scénu:

node.add_entity(mesh)

scene.save("triangle.gltf")
print("Saved triangle.gltf")

Kompletný funkčný skript (všetky kroky skombinované):

from aspose.threed import Scene
from aspose.threed.entities import Mesh, VertexElementType, MappingMode, ReferenceMode, VertexElementNormal
from aspose.threed.utilities import Vector3, Vector4, FVector4

scene = Scene()
node = scene.root_node.create_child_node("triangle")

mesh = Mesh("triangle")

##Add 3 vertices (x, y, z, w)
# Use _control_points to mutate the backing list directly (control_points returns a copy)
mesh._control_points.append(Vector4(0.0, 0.0, 0.0, 1.0))
mesh._control_points.append(Vector4(1.0, 0.0, 0.0, 1.0))
mesh._control_points.append(Vector4(0.5, 1.0, 0.0, 1.0))

##Create a triangle polygon
mesh.create_polygon(0, 1, 2)

##Add normals (create_element returns VertexElementNormal, a VertexElementFVector subclass)
normals: VertexElementNormal = mesh.create_element(VertexElementType.NORMAL, MappingMode.CONTROL_POINT, ReferenceMode.DIRECT)
normals.set_data([
    FVector4(0, 0, 1, 0),
    FVector4(0, 0, 1, 0),
    FVector4(0, 0, 1, 0),
])

node.add_entity(mesh)
scene.save("triangle.gltf")

Bežné problémy

Issue	Resolution
`IndexError` v `create_polygon`	Overte, že všetky indexy sú v `range(len(mesh.control_points))`. Indexy sú číslované od 0.
Export siete s nulovým počtom vrcholov	`mesh.control_points.append(...)` ticho zahadzuje vrcholy, pretože vlastnosť vracia kópiu. Namiesto toho použite `mesh._control_points.append(...)`.
Počet normál nie je rovnaký ako počet vrcholov	Pri použití `MappingMode.CONTROL_POINT` + `ReferenceMode.DIRECT` musí mať `normals.data` presne `len(control_points)` položiek.
Sieť chýba v uloženom súbore	Potvrďte, že `node.add_entity(mesh)` bolo zavolané pred `scene.save()`. Sieť, ktorá nie je pripojená k žiadnemu uzlu, sa neexportuje.
Nesprávne usporiadanie vrcholov (tvár sa javí ako neviditeľná)	Proti smeru hodinových ručičiek usporiadanie vrcholov vytvára normálu smerujúcu von. Obráťte poradie indexov v `create_polygon`, aby ste to zmenili.
`polygon_count` vracia 0	`polygon_count` číta rovnaký zoznam ako `polygons`. Ak nebolo zavolané `create_polygon`, zoznam je prázdny.
Normály sa v prehliadači javia nesprávne	Uistite sa, že všetky normálové vektory majú jednotkovú dĺžku. Vypočítajte ich pomocou `n / abs(n)` alebo odovzdajte prednormované hodnoty.

Často kladené otázky

Aký je rozdiel medzi Vector3 a Vector4 pre kontrolné body?

control_points ukladá objekty Vector4. Komponent w je homogénna súradnica: použite w=1 pre pozície vrcholov a w=0 pre smerové vektory, ako sú normály. Vector3 sa používa na transformácie (posunutie, mierka), ale nie na ukladanie geometrie.

Môžem vytvoriť sieť so štvoruholníkmi namiesto trojuholníkov?

Áno. Zavolajte mesh.create_polygon(0, 1, 2, 3) so štyrmi indexmi na definovanie štvorca. Niektoré cieľové formáty ukladania (STL, 3MF) vyžadujú trojuholníky a automaticky štvorce triangulujú. glTF a COLLADA zachovávajú štvorce.

Ako pridám UV súradnice?

Použite mesh.create_element_uv(TextureMapping.DIFFUSE, MappingMode.POLYGON_VERTEX) na vytvorenie VertexElementUV pre difúzny kanál, potom naplňte jeho zoznam data položkami Vector4. UV súradnice používajú x a y; z a w sú zvyčajne 0. Prvý argument musí byť konštanta TextureMapping (napr. TextureMapping.DIFFUSE), ktorá určuje, do ktorého slotu textúry patrí UV vrstva.

Potrebuje sieť normály pre správny export?

Nie. Normály sú voliteľné. Ak sú vynechané, väčšina prehliadačov vypočíta normály pre každú tvár z poradia vrcholov polygonu. Pridanie explicitných normál na vrchole produkuje hladšie osvetlenie.

Môžem pridať viacero meshov do jedného uzla?

Áno. Zavolajte node.add_entity(mesh) viackrát. Každé volanie pridá novú entitu do node.entities. Niektoré formáty môžu pri exporte zlúčiť viacero entít do jednej.

Ako triangulovať sieť s kombinovanými typmi polygonov?

Zavolajte mesh.triangulate() na konverziu všetkých štvoruholníkov a N-gónov na trojuholníky na mieste. Toto je užitočné pred uložením do formátov, ktoré podporujú iba trojuholníky.