Ako vytvoriť 3D sieť s Aspose.3D v Python

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

Postupný návod

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 Python: 3.7, 3.8, 3.9, 3.10, 3.11, 3.12.

Krok 2: Vytvorte scénu a uzol

Každá sieť (mesh) musí existovať v rámci grafu scény. Vytvorte Scene a pridajte pomenovaný Node pre 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 získavanie prostredníctvom node.get_child("triangle").

Krok 3: Vytvorte objekt Mesh

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 v nasledujúcich krokoch.

Krok 4: Pridajte 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 z vnútorného zoznamu vrcholov (getter vykoná list(self._control_points)). Volanie mesh.control_points.append(v) pridáva do kópie, nie do mesh, takže vrchol je ticho zahodený. Vždy používajte mesh._control_points.append(v) pridať vrcholy. Prístup k súkromnému stavu cez _control_points je známy obchádzací spôsob; rozhranie sa môže v budúcej verzii knižnice zmeniť.

Krok 5: Vytvorte polygonálne plochy

Definujte topológiu plôch pomocou indexov vrcholov. Prejdite 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 sieti. 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á jedna normála na vrchol. ReferenceMode.DIRECT znamená, že dáta normál sú čítané 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 pozície. FVector4 je jednoprecízny float vektor; dáta atribútu vrchola v VertexElementFVector podtriedy používajú tento typ.

Krok 7: Pripojiť mesh k uzlu a uložiť

Pridajte mesh k uzlu, 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

Problém	Riešenie
`IndexError` v `create_polygon`	Overte, že všetky indexy sú v rozsahu `range(len(mesh.control_points))`. Indexy sú číslované od 0.
Mesh exportuje s nulovým počtom vrcholov	`mesh.control_points.append(...)` tichým spôsobom zahadzuje vrcholy, pretože vlastnosť vracia kópiu. Použite `mesh._control_points.append(...)` namiesto toho.
Počet normál nesúhlasí s počtom vrcholov	Pri použití `MappingMode.CONTROL_POINT` + `ReferenceMode.DIRECT`, `normals.data` musí mať presne `len(control_points)` záznamov.
Mesh chýba v uloženom súbore	Potvrďte, že `node.add_entity(mesh)` bolo zavolané pred `scene.save()`. Mesh, ktorý nie je pripojený k žiadnemu uzlu, sa neexportuje.
Nesprávne usporiadanie smeru (tvár sa javí ako neviditeľná)	Proti smeru hodinových ručičiek usporiadanie vrcholov vytvára vonkajšiu normálu. Obráťte poradie indexov v `create_polygon` preklopiť to.
`polygon_count` vracia 0	`polygon_count` číta rovnaký zoznam ako `polygons`. Ak `create_polygon` nebol zavolaný, 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 pomocou `n / abs(n)` alebo odovzdajte prednormované hodnoty.

Často kladené otázky

Aký je rozdiel medzi Vector3 a Vector4 pre riadiace body?

control_points ukladá Vector4 objekty. The w komponent 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, škálovanie), ale nie na ukladanie geometrie.

Môžem vytvoriť mesh s kvádrami namiesto trojuholníkov?

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

Ako pridám UV súradnice?

Použite mesh.create_element_uv(TextureMapping.DIFFUSE, MappingMode.POLYGON_VERTEX) vytvoriť VertexElementUV pre difúzny kanál, potom naplniť jeho data zoznam s Vector4 záznamy. UV súradnice používajú x a y; z a w sú typicky 0. Prvý argument musí byť TextureMapping konštanta (napr., TextureMapping.DIFFUSE) identifikujúca, do ktorého textúrovacieho slotu patrí UV vrstva.

Potrebujú mesh normály na správny export?

Nie. Normály sú voliteľné. Ak sú vynechané, väčšina prehliadačov vypočíta normály na úrovni plôch z poradia vrcholov polygonu. Pridanie explicitných normál na úrovni vrcholov zabezpečí 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ť mesh s kombináciou rôznych typov polygonov?

Zavolajte mesh.triangulate() na konverziu všetkých štvorcov 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.