Hogyan építsünk 3D hálót az Aspose.3D segítségével Pythonban

Az Aspose.3D FOSS for Python lehetővé teszi, hogy teljesen kódból építs 3D geometriát: nincs szükség külső modellező eszközre. Létrehoz egy Mesh‑t, feltölti csúcspont‑pozíciókkal (control_points) és felületdefiníciókkal (polygons), opcionálisan csúcsattribútumokat, például normálvektorokat csatol, majd elmenti a jelenetet bármely támogatott formátumba.

Lépésről‑lépésre útmutató

1. lépés: A csomag telepítése

Telepítse az Aspose.3D FOSS-t a PyPI-ról. Nem szükséges natív kiterjesztés vagy fordító eszközkészlet.

pip install aspose-3d-foss

Ellenőrizze a telepítést:

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

Támogatott Python verziók: 3.7, 3.8, 3.9, 3.10, 3.11, 3.12.

2. lépés: Jelenet és csomópont létrehozása

Minden hálónak egy jelenetgrafikon belsejében kell élni. Hozzon létre egy Scene-t, és adjon hozzá egy névvel ellátott Node-t a háló tárolásához:

from aspose.threed import Scene

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

A csomópont neve megmarad az exportált fájlban, és hasznos a hibakereséshez és a későbbi lekérdezéshez a node.get_child("triangle") segítségével.

3. lépés: Háló objektum létrehozása

Példányosítson egy Mesh-t opcionális leíró névvel:

from aspose.threed.entities import Mesh

mesh = Mesh("triangle")

A háló kezdetben üres: nincsenek csúcsok, nincsenek sokszögek. A következő lépésekben töltöd fel.

4. lépés: Vezérlőpontok (csúcsok) hozzáadása

A vezérlőpontok a csúcs pozíciói. Minden csúcs egy Vector4(x, y, z, w)‑ként van tárolva, ahol w=1 egy 3D térbeli pontot jelöl:

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

Fontos: mesh.control_points egy másolatot ad vissza a belső csúcspontlista (a lekérdező végrehajtja list(self._control_points)). A mesh.control_points.append(v) hívása a másolathoz ad hozzá, nem a hálóhoz, ezért a csúcspont csendben elvész. Mindig használja a mesh._control_points.append(v)‑t a csúcspontok hozzáadásához. A privát állapot _control_points‑val való elérése ismert megoldás; a felület a könyvtár egy későbbi verziójában változhat.

5. lépés: Sokszög felületek létrehozása

Határozza meg a felület topológiáját csúcsindexekkel. Adja át a csúcsindexeket a create_polygon()-nek. Három index háromszöget, négy index quad-ot eredményez:

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

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

Quad mesh esetén négy indexet adna át: mesh.create_polygon(0, 1, 2, 3).

Az indexeknek érvényes pozícióknak kell lenniük a control_points‑ben (0‑bázisú, a tartományon belül). A csavart sorrend az kifelé néző normálok esetén óramutató járásával ellentétes.

6. lépés: Csúcsnormálok hozzáadása

A csúcsponti normálok egy VertexElement‑ként tárolódnak, amely a hálóhoz van csatolva. Használja a mesh.create_element()‑t a VertexElementType.NORMAL, MappingMode.CONTROL_POINT és ReferenceMode.DIRECT‑vel:

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 azt jelenti, hogy csúcsonként egy normál van. ReferenceMode.DIRECT azt jelenti, hogy a normál adatokat ugyanabban a sorrendben olvassák be, mint a vezérlőpontok (nincs extra indexpuffer).

A normálvektorok a FVector4(x, y, z, w)-t használják a w=0-vel, hogy irányt jelezzenek, nem pozíciót. A FVector4 egy egyszeres pontosságú lebegőpontos vektor; a VertexElementFVector alosztályokban a csúcsattribútum adatok ezt a típust használják.

7. lépés: Háló csatolása a csomóhoz és mentés

Adja hozzá a hálót a csomóponthoz, majd mentse a jelenetet:

node.add_entity(mesh)

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

A teljes működő szkript (összes lépés egyben):

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

Gyakori problémák

Issue	Resolution
`IndexError` a `create_polygon`‑ben	Ellenőrizze, hogy minden index a `range(len(mesh.control_points))` tartományán belül van. Az indexek 0‑alapúak.
A háló exportálása nulla csúcsokkal	`mesh.control_points.append(...)` csendben eldobja a csúcsokat, mert a tulajdonság egy másolatot ad vissza. Használja helyette a `mesh._control_points.append(...)`‑t.
A normálok száma nem egyezik a csúcsok számával	`MappingMode.CONTROL_POINT` + `ReferenceMode.DIRECT` használatakor a `normals.data`‑nek pontosan `len(control_points)` bejegyzése kell legyen.
A háló hiányzik a mentett fájlból	Győződjön meg róla, hogy a `node.add_entity(mesh)` a `scene.save()` előtt lett meghívva. A csomóponthoz nem csatolt háló nem kerül exportálásra.
Helytelen csavart sorrend (a felület láthatatlanná válik)	Az óramutatóval ellentétes csúcssorrend kifelé mutató normált eredményez. Fordítsa meg az index sorrendet a `create_polygon`‑ben a megfordításhoz.
`polygon_count` 0‑t ad vissza	`polygon_count` ugyanazt a listát olvassa, mint a `polygons`. Ha a `create_polygon` nem lett meghívva, a lista üres.
A normálok helytelennek tűnnek a megjelenítőben	Győződjön meg róla, hogy minden normálvektor egység hosszú. Számítsa ki a `n / abs(n)`‑vel, vagy adjon át előre normalizált értékeket.

Gyakran Ismételt Kérdések

Mi a különbség a Vector3 és Vector4 vezérlőpontok között?

control_points tárol Vector4 objektumokat. A w komponens a homogen koordináta: használja a w=1-t a csúcspontok pozíciójához és a w=0-t irányvektorokhoz, például normálokhoz. A Vector3-t transzformációkhoz (transzláció, skálázás) használják, de nem geometriai tároláshoz.

Építhetek hálót négyszögekkel a háromszögek helyett?

Igen. Hívja meg a mesh.create_polygon(0, 1, 2, 3)-t négy indexszel egy négyszög definiálásához. Néhány mentési cél (STL, 3MF) háromszögeket igényel, és automatikusan háromszögíti a négyszögeket. A glTF és a COLLADA megőrzi a négyszögeket.

Hogyan adhatok hozzá UV koordinátákat?

Használja a mesh.create_element_uv(TextureMapping.DIFFUSE, MappingMode.POLYGON_VERTEX)‑t egy VertexElementUV létrehozásához a diffúz csatornához, majd töltse fel a data listáját Vector4 bejegyzésekkel. Az UV koordináták a x és y‑t használják; a z és w általában 0. Az első argumentumnak egy TextureMapping állandónak kell lennie (például TextureMapping.DIFFUSE), amely meghatározza, hogy a UV réteg melyik textúrahelyhez tartozik.

A hálónak szüksége van normálokra a helyes exportáláshoz?

Nem. A normálvektorok opcionálisak. Ha kihagyják, a legtöbb megjelenítő a poligon szélrendje alapján számítja ki az egyes felületek normálvektorait. Az explicit per-vertex normálok hozzáadása simább árnyékolást eredményez.

Hozzáadhatok több hálót egy csomóponthoz?

Igen. Hívja meg node.add_entity(mesh) többször. Minden hívás egy új entitást fűz hozzá node.entities-hez. Néhány formátum exportáláskor több entitást egybe lapíthat.

Hogyan triangulálhatok egy vegyes poligon típusú hálót?

Hívja meg a mesh.triangulate() parancsot, hogy helyben átalakítsa az összes négyszöget és N-gont háromszögekké. Ez hasznos, mielőtt olyan formátumokba mentene, amelyek csak háromszögeket támogatnak.