Aspose.3D を Python で 3D メッシュを構築する方法

Aspose.3D FOSS for Python は、コードだけで 3D ジオメトリを構築でき、外部のモデリングツールは不要です。あなたは Mesh,、頂点位置 (control_points) と面定義 (polygons) を設定し、法線などのオプションの頂点属性を付加し、次にシーンをサポートされている任意のフォーマットで保存します。.

ステップバイステップガイド

ステップ 1: パッケージをインストールする

PyPI から Aspose.3D FOSS をインストールします。ネイティブ拡張やコンパイラツールチェーンは不要です。.

pip install aspose-3d-foss

インストールを確認します:

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

サポートされている Python バージョン: 3.7, 3.8, 3.9, 3.10, 3.11, 3.12.

ステップ 2: シーンとノードを作成する

すべてのメッシュはシーングラフ内に存在しなければなりません。作成します Scene 、名前付き Node をメッシュを保持するために追加します:

from aspose.threed import Scene

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

ノード名はエクスポートされたファイルに保持され、デバッグや後の取得に via node.get_child("triangle").

ステップ 3: Mesh オブジェクトを作成する

インスタンス化する Mesh 任意の説明名を付けて:

from aspose.threed.entities import Mesh

mesh = Mesh("triangle")

Mesh は最初は空です: 頂点もポリゴンもありません。以下の手順で内容を追加します。.

ステップ 4: コントロールポイント（頂点）を追加する

コントロールポイントは頂点位置です。各頂点は a Vector4(x, y, z, w) どこで w=1 3次元空間の点を示します:

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

重要: mesh.control_points 返します コピー 内部頂点リストのコピー（getter が実行する list(self._control_points)）。呼び出し mesh.control_points.append(v) コピーに追加し、メッシュには追加しないため、頂点は黙って破棄されます。常に使用してください mesh._control_points.append(v) 頂点を追加するために。プライベート状態にアクセスするには _control_points は既知の回避策です；インターフェースは将来のバージョンで変更される可能性があります。.

ステップ 5: ポリゴン面を作成する

頂点インデックスを使用して面のトポロジーを定義します。頂点インデックスを渡す先は create_polygon().。3つのインデックスで triangle が生成され、4つで quad が生成されます：:

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

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

quad メッシュの場合、4つのインデックスを渡します：: mesh.create_polygon(0, 1, 2, 3).

インデックスは、次の中の有効な位置である必要があります control_points (0ベース、範囲内)。ワインディング順序は outward-facing normals のために counter-clockwise です。.

ステップ 6: 頂点法線を追加

Vertex normals は、次のように格納されます VertexElement メッシュに添付されます。使用するのは mesh.create_element() と共に使用します VertexElementType.NORMAL, MappingMode.CONTROL_POINT,、そして 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 は、頂点ごとに1つの法線があることを意味します。. ReferenceMode.DIRECT は、法線データが制御点と同じ順序で読み取られることを意味します（追加のインデックスバッファはありません）。.

法線ベクトルは使用 FVector4(x, y, z, w) と w=0 位置ではなく方向を示すために。. FVector4 は単精度浮動小数点ベクトルです; 頂点属性データは VertexElementFVector サブクラスはこの型を使用します。.

ステップ 7: メッシュをノードにアタッチして保存

メッシュをノードに追加し、シーンを保存します:

node.add_entity(mesh)

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

完全に動作するスクリプト（すべてのステップを統合）:

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

よくある問題

問題	解決策
`IndexError` で `create_polygon`	すべてのインデックスが範囲内であることを確認してください `range(len(mesh.control_points))`.。インデックスは0ベースです。.
メッシュが頂点ゼロでエクスポートされます	`mesh.control_points.append(...)` プロパティがコピーを返すため、頂点が黙って破棄されます。代わりに使用してください `mesh._control_points.append(...)` 代わりに。.
法線の数が頂点の数と一致しません	使用する場合 `MappingMode.CONTROL_POINT` + `ReferenceMode.DIRECT`, `normals.data` は正確に `len(control_points)` エントリ。.
保存されたファイルにメッシュがありません	次を確認してください `node.add_entity(mesh)` が以前に呼び出された `scene.save()`. ノードにアタッチされていないメッシュはエクスポートされません。.
ワインディング順序が間違っています（面が見えなくなります）	反時計回りの頂点順序は外向きの法線を生成します。インデックス順序を逆にすると `create_polygon` それを反転させます。.
`polygon_count` 0 を返します	`polygon_count` 次と同じリストを読み取ります `polygons`.。もし `create_polygon` が呼び出されなかった場合、リストは空です。.
ビューアで法線が正しく表示されません	すべての法線ベクトルが単位長さであることを確認してください。次で計算します `n / abs(n)` または事前に正規化された値を渡してください。.

よくある質問

～と～の違いは何ですか Vector3 と Vector4 制御点用ですか？?

control_points 格納します Vector4 オブジェクトです。 w コンポーネントは同次座標です: 使用してください w=1 頂点位置に使用し、 w=0 法線などの方向ベクトル用です。. Vector3 は変換（平行移動、スケール）に使用されますが、ジオメトリの保存には使用されません。.

三角形ではなく四角形でメッシュを作成できますか？?

はい。呼び出してください mesh.create_polygon(0, 1, 2, 3) 4つのインデックスでクアッドを定義します。STL や 3MF などの一部の保存形式は三角形を必要とし、クアッドを自動的に三角形化します。glTF と COLLADA はクアッドを保持します。.

UV 座標はどうやって追加しますか？?

使用してください mesh.create_element_uv(TextureMapping.DIFFUSE, MappingMode.POLYGON_VERTEX) を作成するために VertexElementUV 拡散チャンネル用に、次にそれを data リストに Vector4 エントリ。UV座標は使用 x と y; z と w は通常0です。最初の引数は TextureMapping 定数（例:., TextureMapping.DIFFUSE）は、UVレイヤーが属するテクスチャスロットを特定します。.

メッシュは正しくエクスポートするために法線が必要ですか？?

いいえ。法線は任意です。省略した場合、ほとんどのビューアはポリゴンの winding order から面ごとの法線を計算します。明示的に頂点ごとの法線を追加すると、シェーディングがより滑らかになります。.

1つのノードに複数のメッシュを追加できますか？?

はい。呼び出す node.add_entity(mesh) 複数回。各呼び出しは新しいエンティティを node.entities.。いくつかのフォーマットでは、エクスポート時に複数のエンティティが1つにフラット化されることがあります。.

混合ポリゴンタイプを持つメッシュをどのように三角形化しますか？?

呼び出し mesh.triangulate() すべての quads と N-gons をその場で三角形に変換します。三角形のみをサポートするフォーマットに保存する前に便利です。.