Kā izveidot 3D režģi ar Aspose.3D Python

Aspose.3D FOSS for Python ļauj veidot 3D ģeometriju pilnīgi kodā: nav vajadzīgs ārējs modelēšanas rīks. Jūs izveidojat Mesh, piepildiet to virsotņu pozīcijām (control_points) and seju definīcijām (polygons), pievienojiet izvēles virsotņu atribūtus, piemēram, normāles, pēc tam saglabājiet ainu jebkurā atbalstītā formātā.

Solī pa solim rokasgrāmata

1. solis: Instalējiet pakotni

Instalējiet Aspose.3D FOSS no PyPI. Nav nepieciešami vietējie paplašinājumi vai kompilatora rīkkopa.

pip install aspose-3d-foss

Pārbaudiet instalāciju:

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

Atbalstītās Python versijas: 3.7, 3.8, 3.9, 3.10, 3.11, 3.12.

2. solis: Izveidojiet ainu un mezglu

Katram režģim jābūt iekļautam ainu grafā. Izveidojiet Scene un pievienojiet nosauktu Node lai saturētu režģi:

from aspose.threed import Scene

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

Mezgla nosaukums tiek saglabāts eksportētajā failā un ir noderīgs atkļūdošanai un vēlākai izgūšanai caur node.get_child("triangle").

3. solis: Izveidojiet Mesh objektu

Instancējiet Mesh ar izvēles aprakstošu nosaukumu:

from aspose.threed.entities import Mesh

mesh = Mesh("triangle")

Mesh sākotnēji ir tukšs: nav virsotņu, nav daudzstūru. Jūs to piepildīsiet turpmākajos soļos.

4. solis: Pievienojiet kontroles punktus (virsotnes)

Kontroles punkti ir virsotņu pozīcijas. Katrs virsotne tiek saglabāta kā a Vector4(x, y, z, w) kur w=1 norāda punktu trīsdimensiju telpā:

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

Svarīgi: mesh.control_points atgriež kopiju no iekšējā virsotņu saraksta (getter izpilda list(self._control_points)). Izsaucot mesh.control_points.append(v) pievieno kopijai, nevis režģim, tāpēc virsotne tiek klusi izlaista. Vienmēr lietojiet mesh._control_points.append(v) lai pievienotu virsotnes. Piekļūstot privātajam stāvoklim caur _control_points ir zināma apkārtpakaļceļš; interfeiss var mainīties nākotnes bibliotēkas versijā.

5. solis: Izveidojiet daudzstūru sejas

Definējiet sejas topoloģiju, izmantojot virsotnes indeksus. Pārsūtiet virsotnes indeksus uz create_polygon(). Trīs indeksi veido trīsstūri; četri veido četrstūri:

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

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

Četrstūra režģim jums būtu jānosūta četri indeksi: mesh.create_polygon(0, 1, 2, 3).

Indeksiem jābūt derīgām pozīcijām iekš control_points (0‑balstīts, diapazonā). Vējošanas secība ir pretpulksteņa virzienā, lai radītu ārējo virziena normāles.

6. solis: Pievienot virsotnes normāles

Virsotnes normāles tiek saglabātas kā VertexElement pievienotas tīklam. Izmantojiet mesh.create_element() ar VertexElementType.NORMAL, MappingMode.CONTROL_POINT, un 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 nozīmē vienu normāli uz virsotnes. ReferenceMode.DIRECT nozīmē, ka normāļu dati tiek nolasīti tādā pašā secībā kā kontroles punkti (nav papildu indeksa bufera).

Normālie vektori izmanto FVector4(x, y, z, w) ar w=0 lai norādītu virzienu, nevis pozīciju. FVector4 ir vienkāršas precizitātes peldošā komata vektors; virsotnes atribūtu dati iekš VertexElementFVector apakšklases izmanto šo tipu.

7. solis: Pievienot tīklu mezglam un saglabāt

Pievienojiet tīklu mezglam, pēc tam saglabājiet ainu:

node.add_entity(mesh)

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

Pilns darbosies skripts (visi soļi apvienoti):

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

Biežāk sastopamās problēmas

Problēma	Risinājums
`IndexError` iekš `create_polygon`	Pārbaudiet, vai visi indeksi ir iekš `range(len(mesh.control_points))`. Indeksi sākas ar 0.
Tīklu eksports ar nulles virsotnēm	`mesh.control_points.append(...)` klusi izmet virsotnes, jo īpašība atgriež kopiju. Izmantojiet `mesh._control_points.append(...)` tā vietā.
Normālu skaits neatbilst virsotņu skaitam	Izmantojot `MappingMode.CONTROL_POINT` + `ReferenceMode.DIRECT`, `normals.data` jābūt tieši `len(control_points)` ieraksti.
Mesh trūkst saglabātā failā	Apstipriniet, ka `node.add_entity(mesh)` tika izsaukts agrāk `scene.save()`. Tīkls, kas nav pievienots nevienam mezglam, netiek eksportēts.
Nepareiza vītnes kārtošana (virsma izskatās neredzama)	Pretpulksteņrādītāja virziena virsotņu secība rada ārējo normālu. Apgrieziet indeksa secību `create_polygon` lai to apgrieztu.
`polygon_count` atgriež 0	`polygon_count` lasa to pašu sarakstu kā `polygons`. Ja `create_polygon` netika izsaukts, saraksts ir tukšs.
Normāles izskatās nepareizas skatītājā	Pārliecinieties, ka visi normālie vektori ir vienības garuma. Aprēķiniet ar `n / abs(n)` vai nododiet iepriekš normalizētas vērtības.

Biežāk uzdotie jautājumi

Kāda ir atšķirība starp Vector3 un Vector4 kontroles punktiem?

control_points glabā Vector4 objektus. Šis w komponents ir homogēnā koordināta: izmantojiet w=1 virsotnes pozīcijām un w=0 virziena vektoriem, piemēram, normālēm. Vector3 tiek izmantots transformācijām (pārvietojums, mērogs), bet ne ģeometrijas glabāšanai.

Vai varu izveidot tīklu ar kvadrātiem, nevis trīsstūriem?

Jā. Izsauciet mesh.create_polygon(0, 1, 2, 3) ar četriem indeksiem, lai definētu kvadrātu. Daži saglabāšanas mērķi (STL, 3MF) pieprasa trīsstūrus un automātiski kvadrātus pārveidos par trīsstūriem. glTF un COLLADA saglabā kvadrātus.

Kā pievienot UV koordinātas?

Izmantojiet mesh.create_element_uv(TextureMapping.DIFFUSE, MappingMode.POLYGON_VERTEX) lai izveidotu VertexElementUV diffūzēšanas kanālam, tad aizpildiet tā data sarakstu ar Vector4 ierakstus. UV koordinātas izmanto x un y; z un w parasti ir 0. Pirmajam argumentam jābūt TextureMapping konstantei (piemēram,., TextureMapping.DIFFUSE) identificē, kuram tekstūras slotam UV slānis pieder.

Vai mesham ir vajadzīgi normāli, lai tas tiktu pareizi eksportēts?

Nē. Normāli ir izvēles. Ja tie tiek izlaisti, vairums skatītāju aprēķina per‑face normālus no daudzstūra virzības secības. Pievienojot eksplicitus per‑vertex normālus, tiek iegūta gludāka ēnošana.

Vai varu pievienot vairākus meshus vienam mezglam?

Jā. Izsauciet node.add_entity(mesh) vairākkārt. Katrs izsaukums pievieno jaunu objektu uz node.entities. Daži formāti var eksportējot apvienot vairākus objektus vienā.

Kā triangulēt meshu ar jauktām daudzstūra tipiem?

Izsaukt mesh.triangulate() lai pārvērstu visus kvadrātus un N-gonus trijstūros uz vietas. Tas ir noderīgi pirms saglabāšanas formātos, kas atbalsta tikai trijstūrus.