Hur man bygger en 3D-mash med Aspose.3D i Python

Aspose.3D FOSS för Python låter dig bygga 3D geometri helt i kod: ingen extern modelleringsverktyg krävs. Mesh,och för att få den i vertexpositioner (control_pointsoch förklarar definitionen (polygons), bifoga valfria vertex attribut som normala, spara sedan scenen till något stöds format.

Steg för steg guide

Steg 1: Installera paketet

Installera Aspose.3D FOSS från PyPI. Inga inhemska förlängningar eller verktygskedjor krävs.

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

Kontrollera installationen:

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

Stödda versioner av Python: 3.7, 3.8, 3.9, 3.10, 3.11, 3.12.

Steg 2: Skapa en scen och ett noder

Varje mäs måste leva inuti en scen graf. Skapa ett Scene och lägga till ett namn Node För att hålla mesh:

from aspose.threed import Scene

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

Noden är bevarad i den exporterade filen och är användbar för debugging och senare återhämtning via node.get_child("triangle").

Steg 3: Skapa ett Mesh Object

Instant A Mesh Med ett alternativt beskrivande namn:

from aspose.threed.entities import Mesh

mesh = Mesh("triangle")

Mässa är ursprungligen tom: inga vertikaler, ingen polygon. Du populerar den i följande steg.

Steg 4: Lägg till kontrollpunkter (vertikaler)

Kontrollpunkter är vertexpositionerna. var och en av vertikalerna lagras som en Vector4(x, y, z, w) Var är w=1 Anger en punkt i 3D-utrymmet:

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

Viktigt är: -här är detmesh.control_points Återkommer A Kopiera från den interna vertexlistan (gettaren utför list(self._control_points)* ringer mesh.control_points.append(v) ansluter till kopian, inte till mässen, så vertexen är tyst bort. alltid använda mesh._control_points.append(v) att lägga till vertikaler. tillgång till privat staten via _control_points är en känd arbetsplats; gränssnittet kan ändras i en framtida version av biblioteket.

Steg 5: Skapa polygon ansikten

Definiera ansiktstopologi med vertexindex. pass vertesindex till create_polygon().Tre index producerar en triangel; fyra producerar en quad:

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

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

För en quad mesh skulle du passera fyra indikatorer: mesh.create_polygon(0, 1, 2, 3).

Indikatorer måste vara giltiga positioner i control_points (0-baserad, inom intervallet). Winding order är motklockvis för utomhus-före normala.

Steg 6: Lägg till Vertex normaler

Vertex normaler lagras som en VertexElement Anslut till mässa. användning mesh.create_element() med VertexElementType.NORMAL, MappingMode.CONTROL_POINT,och 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 Det är en normal per vertex. ReferenceMode.DIRECT Det betyder att normala data läses i samma ordning som kontrollpunkterna (ingen extra indexbuffer).

Vanliga vector användning FVector4(x, y, z, w) med w=0 Att ange en riktning snarare än en position. FVector4 är en enkel precision flödesvektor; vertex attribut data i VertexElementFVector Subklasser använder denna typ.

Steg 7: Anslut mässen till knuten och spara

Lägg till knappen i noden och spara sedan scenen:

node.add_entity(mesh)

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

Den kompletta arbetsskriptet (alla steg kombinerade):

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

Vanliga frågor

Problemet	resolution
`IndexError` i `create_polygon`	Kontrollera att alla indikatorer är inuti `range(len(mesh.control_points))`.Indikatorer är 0 baserade.
Mesh export med noll vertikal	`mesh.control_points.append(...)` tyst avskär vertikaler eftersom egendomen returnerar en kopia. `mesh._control_points.append(...)` I stället .
Normala räkningar matchar inte vertex räkning	När man använder `MappingMode.CONTROL_POINT` + `ReferenceMode.DIRECT`, `normals.data` måste ha exakt `len(control_points)` och entré.
Mesh saknas från sparat fil	bekräfta att `node.add_entity(mesh)` kallades förut `scene.save()`.En mesh som inte är ansluten till någon nod exporteras inte.
Felaktig vindriktning (fönstret verkar osynlig)	Kontra-klockvägs vertexord producerar en utomhusvänlig normal. Omvänd indexordningen i `create_polygon` att flip det.
`polygon_count` Återkommer 0	`polygon_count` Läser samma lista som `polygons`.Om `create_polygon` Det är inte kallat, listan är tom.
Normaler verkar fel i tittaren	Se till att alla normala vectorer är enhetslängd. `n / abs(n)` eller överför förnormaliserade värden.

Ofta ställda frågor

Vad är skillnaden mellan Vector3 och Vector4 För kontrollpunkter?

control_points butiker Vector4 föremål - den w komponenten är den homogena koordinaten: användning w=1 för vertexpositioner och w=0 för riktningvektorer som normala. Vector3 används för transformationer (översättning, skala) men inte för geometrisk lagring.

Kan jag bygga en mesh med quads istället för trianglar?

Ja, ringa till mesh.create_polygon(0, 1, 2, 3) Vissa sparar mål (STL, 3MF) kräver trianglar och kommer att triangel quads automatiskt. glTF och COLLADA bevarar quad.

Hur lägger jag till UV-koordinater?

Användning mesh.create_element_uv(TextureMapping.DIFFUSE, MappingMode.POLYGON_VERTEX) För att skapa en VertexElementUV för diffuskanalen, sedan populera den data Lista med Vector4 Användning av UV-koordinater x och y; z och w är typiskt 0 och det första argumentet måste vara ett TextureMapping konstant (t.ex., TextureMapping.DIFFUSE) identifiera vilken textur slott UV-skiktet tillhör.

Behöver mässen normala för att exportera korrekt?

No. Normaler är valfria. om de inte görs räknar de flesta tittarna per-face normaler från polygonventilationskorrigering. Lägga till uttryckliga pervertex normala ger en smalare skugga.

Kan jag lägga till flera mesh till en nod?

Ja, ringa till node.add_entity(mesh) flera gånger. varje samtal bifogar en ny entitet till node.entities.Vissa format kan fläta flera enheter i ett på export.

Hur trianglar jag en mesh med blandade polygontyper?

Ringa till mesh.triangulate() konvertera alla quads och N-gons till trianglar på plats. Detta är användbart innan spara till format som endast stöder triangel.