Kuinka rakentaa 3D-verkko Aspose.3D:lla Python:ssa

Aspose.3D FOSS for Python mahdollistaa 3D-geometrian rakentamisen kokonaan koodilla: ulkoista mallinnustyökalua ei tarvita. Luo Mesh, täytä se kärkipisteiden sijainneilla (control_points) ja kasvot määritelmillä (polygons), liitä valinnaisia kärkipisteattribuutteja kuten normaalit, ja tallenna sitten kohtaus mihin tahansa tuettuun formaattiin.

Vaiheittainen opas

Vaihe 1: Asenna paketti

Asenna Aspose.3D FOSS PyPI:stä. Ei vaadi natiiveja laajennuksia tai kääntäjätyökaluketjua.

pip install aspose-3d-foss

Vahvista asennus:

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

Tuetut Python-versiot: 3.7, 3.8, 3.9, 3.10, 3.11, 3.12.

Vaihe 2: Luo kohtaus ja solmu

Jokaisen verkon täytyy olla scene graphin sisällä. Luo Scene ja lisää nimetty Node pitämään verkkoa:

from aspose.threed import Scene

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

Solmun nimi säilyy vietyssä tiedostossa ja on hyödyllinen vianmäärityksessä sekä myöhemmässä hakemisessa kautta node.get_child("triangle").

Vaihe 3: Luo Mesh-objekti

Luo instanssi Mesh valinnaisella kuvaavalla nimellä:

from aspose.threed.entities import Mesh

mesh = Mesh("triangle")

Mesh on aluksi tyhjä: ei kärkiä, ei polygoneja. Täytät sen seuraavissa vaiheissa.

Vaihe 4: Lisää ohjauspisteet (kärjet)

Ohjauspisteet ovat kärkipisteiden sijainnit. Jokainen kärki tallennetaan muodossa Vector4(x, y, z, w) missä w=1 osoittaa pisteen 3D-tilassa:

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

Tärkeää: mesh.control_points palauttaa kopion sisäisen vertex-listan (getter suorittaa list(self._control_points)). Kutsutaan mesh.control_points.append(v) lisätään kopioon, ei meshiin, joten vertex hiljaisesti hylätään. Käytä aina mesh._control_points.append(v) lisätä solmuja. Yksityiseen tilaan pääsyä kautta _control_points on tunnettu kiertotapa; käyttöliittymä saattaa muuttua kirjaston tulevassa versiossa.

Vaihe 5: Luo polygonikasvot

Määritä pinnan topologia käyttämällä solmuindeksejä. Anna solmuindeksit kohteelle create_polygon().Kolme indeksiä muodostaa kolmion; neljä muodostaa nelikulmion:

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

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

Nelikulmioverkossa sinun tulisi antaa neljä indeksiä: mesh.create_polygon(0, 1, 2, 3).

Indeksien on oltava kelvollisia paikkoja kohteessa control_points (0-pohjainen, sallitulla alueella). Kierrejärjestys on vastapäivään ulospäin suuntautuville normaalivektoreille.

Vaihe 6: Lisää kärkinormaalit

Solmu normaalit tallennetaan muodossa VertexElement liitettynä verkkoon. Käytä mesh.create_element() kanssa VertexElementType.NORMAL, MappingMode.CONTROL_POINT, ja 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 tarkoittaa yhtä normaalia per solmu. ReferenceMode.DIRECT tarkoittaa, että normaalidata luetaan samassa järjestyksessä kuin ohjauspisteet (ei ylimääräistä indeksipuskurointia).

Normaalivektorit käyttävät FVector4(x, y, z, w) kanssa w=0 ilmaistakseen suuntaa eikä sijaintia. FVector4 on yksittäistarkkuuksinen liukulukuvektori; vertex attribute data in VertexElementFVector aliluokat käyttävät tätä tyyppiä.

Vaihe 7: Liitä verkko solmuun ja tallenna

Lisää verkko solmuun, sitten tallenna kohtaus:

node.add_entity(mesh)

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

Täydellinen toimiva skripti (kaikki vaiheet yhdistettynä):

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

Yleisiä ongelmia

Ongelma	Ratkaisu
`IndexError` sisään `create_polygon`	Varmista, että kaikki indeksit ovat `range(len(mesh.control_points))`. Indeksit ovat 0-pohjaisia.
Mesh viedään ilman vertexejä	`mesh.control_points.append(...)` hiljaisesti hylkää vertexit, koska ominaisuus palauttaa kopion. Käytä `mesh._control_points.append(...)` sen sijaan.
Normaalien määrä ei täsmää vertexien määrään	Kun käytetään `MappingMode.CONTROL_POINT` + `ReferenceMode.DIRECT`, `normals.data` täytyy sisältää tarkalleen `len(control_points)` merkintää.
Mesh puuttuu tallennetusta tiedostosta	Vahvista, että `node.add_entity(mesh)` kutsuttiin ennen `scene.save()`. Mesh, joka ei ole liitetty mihinkään solmuun, ei viedä.
Väärä kiertosuunta (kasvot näyttävät näkymättömiltä)	Vastapäivään kierretty vertex-järjestys tuottaa ulospäin suuntautuneen normaalin. Käännä indeksijärjestys in `create_polygon` kääntää sen.
`polygon_count` palauttaa 0	`polygon_count` lukee saman listan kuin `polygons`. Jos `create_polygon` ei kutsuttu, lista on tyhjä.
Normaalit näyttävät virheellisiltä katselijassa.	Varmista, että kaikki normaalivektorit ovat yksikköpituuksia. Laske käyttäen `n / abs(n)` tai anna esinormalisoidut arvot.

Usein kysytyt kysymykset

Mikä on ero välillä Vector3 ja Vector4 ohjauspisteille?

control_points tallentaa Vector4 objekteja. Tämä w komponentti on homogeeninen koordinaatti: käytä w=1 solmupisteiden sijainteihin ja w=0 suunnannvektoreihin, kuten normaalit. Vector3 käytetään muunnoksiin (siirto, skaalaus), mutta ei geometrian tallennukseen.

Voinko rakentaa verkon nelikulmioilla kolmioiden sijaan?

Kyllä. Kutsu mesh.create_polygon(0, 1, 2, 3) neljällä indeksillä nelikulmion määrittämiseksi. Jotkut tallennuskohteet (STL, 3MF) vaativat kolmioita ja muuntavat nelikulmiot automaattisesti kolmioiksi. glTF ja COLLADA säilyttävät nelikulmiot.

Kuinka lisään UV-koordinaatit?

Käytä mesh.create_element_uv(TextureMapping.DIFFUSE, MappingMode.POLYGON_VERTEX) luodaksesi VertexElementUV diffuusikanavalle, sitten täytä sen data lista Vector4 merkintöjä. UV-koordinaatteja käytetään x ja y; z ja w ovat tyypillisesti 0. Ensimmäisen argumentin täytyy olla TextureMapping vakio (esim., TextureMapping.DIFFUSE) tunnistaen, mihin tekstuuripaikkaan UV-kerros kuuluu.

Tarvitseeko mesh normaalit, jotta se viedään oikein?

Ei. Normaalit ovat valinnaisia. Jos ne jätetään pois, useimmat katseluohjelmat laskevat pinnan normaalit monikulmion kiertojärjestyksestä. Eksplisiittisten per-vertex -normaalien lisääminen tuottaa tasaisemman varjostuksen.

Voinko lisätä useita meshejä yhteen solmuun?

Kyllä. Kutsu node.add_entity(mesh) useita kertoja. Jokainen kutsu lisää uuden entiteetin node.entities. Jotkut formaatit saattavat litistää useita entiteettejä yhdeksi viennissä.

Kuinka trianguloidaan mesh, jossa on sekoitettuja monikulmioita?

Kutsu mesh.triangulate() muuntaa kaikki nelikulmiot ja N-gonit kolmioiksi paikallisesti. Tämä on hyödyllistä ennen tallentamista formaatteihin, jotka tukevat vain kolmioita.