Cách xây dựng lưới 3D với Aspose.3D trong Python

Aspose.3D FOSS for Python cho phép bạn xây dựng hình học 3D hoàn toàn bằng mã: không cần công cụ mô hình bên ngoài. Bạn tạo một Mesh, điền nó bằng các vị trí đỉnh (control_points) và định nghĩa mặt (polygons), gắn các thuộc tính đỉnh tùy chọn như pháp tuyến, sau đó lưu cảnh vào bất kỳ định dạng hỗ trợ nào.

Hướng Dẫn Từng Bước

Bước 1: Cài đặt gói

Cài đặt Aspose.3D FOSS từ PyPI. Không cần phần mở rộng gốc hoặc bộ công cụ biên dịch.

pip install aspose-3d-foss

Xác minh việc cài đặt:

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

Các phiên bản Python được hỗ trợ: 3.7, 3.8, 3.9, 3.10, 3.11, 3.12.

Bước 2: Tạo một Scene và một Node

Mỗi lưới phải tồn tại trong một đồ thị cảnh. Tạo một Scene và thêm một Node có tên để chứa lưới:

from aspose.threed import Scene

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

Tên nút được giữ nguyên trong tệp đã xuất và hữu ích cho việc gỡ lỗi và truy xuất sau này qua node.get_child("triangle").

Bước 3: Tạo một Đối tượng Mesh

Khởi tạo một Mesh với tên mô tả tùy chọn:

from aspose.threed.entities import Mesh

mesh = Mesh("triangle")

Lưới ban đầu trống rỗng: không có đỉnh, không có đa giác. Bạn sẽ điền dữ liệu vào nó theo các bước sau.

Bước 4: Thêm các điểm điều khiển (đỉnh)

Các điểm điều khiển là vị trí các đỉnh. Mỗi đỉnh được lưu dưới dạng Vector4(x, y, z, w) trong đó w=1 chỉ một điểm trong không gian 3D:

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

Important: mesh.control_points trả về một bản sao của danh sách đỉnh nội bộ (getter thực thi list(self._control_points)). Gọi mesh.control_points.append(v) sẽ thêm vào bản sao, không phải vào lưới, vì vậy đỉnh sẽ bị loại bỏ một cách im lặng. Luôn sử dụng mesh._control_points.append(v) để thêm đỉnh. Truy cập trạng thái riêng qua _control_points là một cách khắc phục đã biết; giao diện có thể thay đổi trong phiên bản tương lai của thư viện.

Bước 5: Tạo các mặt đa giác

Xác định cấu trúc mặt bằng cách sử dụng chỉ số đỉnh. Truyền các chỉ số đỉnh vào create_polygon(). Ba chỉ số tạo thành một tam giác; bốn chỉ số tạo thành một hình tứ giác:

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

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

Đối với lưới tứ giác, bạn sẽ truyền bốn chỉ mục: mesh.create_polygon(0, 1, 2, 3).

Các chỉ mục phải là các vị trí hợp lệ trong control_points (đánh số từ 0, trong phạm vi). Thứ tự quấn là ngược chiều kim đồng hồ cho các pháp tuyến hướng ra ngoài.

Bước 6: Thêm pháp tuyến đỉnh

Các pháp tuyến đỉnh được lưu dưới dạng VertexElement gắn vào lưới. Sử dụng mesh.create_element() với VertexElementType.NORMAL, MappingMode.CONTROL_POINT và 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 có nghĩa là một pháp tuyến cho mỗi đỉnh. ReferenceMode.DIRECT có nghĩa là dữ liệu pháp tuyến được đọc theo cùng thứ tự với các điểm điều khiển (không có bộ đệm chỉ mục phụ).

Vector pháp tuyến sử dụng FVector4(x, y, z, w) với w=0 để chỉ một hướng thay vì một vị trí. FVector4 là một vector số thực đơn độ chính xác; dữ liệu thuộc tính đỉnh trong các lớp con VertexElementFVector sử dụng kiểu này.

Bước 7: Gắn Mesh vào Node và Lưu

Thêm mesh vào node, sau đó lưu scene:

node.add_entity(mesh)

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

Kịch bản hoạt động hoàn chỉnh (tất cả các bước được kết hợp):

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

Các vấn đề thường gặp

Vấn đề	Giải pháp
`IndexError` trong `create_polygon`	Xác minh rằng tất cả các chỉ số đều nằm trong `range(len(mesh.control_points))`. Các chỉ số bắt đầu từ 0.
Lưới xuất với số đỉnh bằng 0	`mesh.control_points.append(...)` âm thầm loại bỏ các đỉnh vì thuộc tính trả về một bản sao. Thay vào đó, sử dụng `mesh._control_points.append(...)`.
Số lượng pháp tuyến không khớp với số lượng đỉnh	Khi sử dụng `MappingMode.CONTROL_POINT` + `ReferenceMode.DIRECT`, `normals.data` phải có đúng `len(control_points)` mục.
Lưới bị thiếu trong tệp đã lưu	Xác nhận rằng `node.add_entity(mesh)` đã được gọi trước `scene.save()`. Một lưới không được gắn vào bất kỳ nút nào sẽ không được xuất.
Thứ tự vòng xoáy sai (mặt hiển thị vô hình)	Thứ tự đỉnh ngược chiều kim đồng hồ tạo ra pháp tuyến hướng ra ngoài. Đảo ngược thứ tự chỉ mục trong `create_polygon` để lật nó.
`polygon_count` trả về 0	`polygon_count` đọc cùng danh sách với `polygons`. Nếu `create_polygon` không được gọi, danh sách sẽ rỗng.
Pháp tuyến hiển thị không đúng trong trình xem	Đảm bảo tất cả các vector pháp tuyến có độ dài đơn vị. Tính toán bằng `n / abs(n)` hoặc truyền các giá trị đã được chuẩn hoá trước.

Câu hỏi thường gặp

Sự khác biệt giữa Vector3 và Vector4 cho các điểm điều khiển là gì?

control_points lưu trữ các đối tượng Vector4. Thành phần w là tọa độ đồng nhất: sử dụng w=1 cho vị trí đỉnh và w=0 cho các vectơ hướng như pháp tuyến. Vector3 được dùng cho các phép biến đổi (dịch chuyển, tỉ lệ) nhưng không dùng để lưu trữ hình học.

Tôi có thể xây dựng một mesh bằng các quad thay vì tam giác không?

Vâng. Gọi mesh.create_polygon(0, 1, 2, 3) với bốn chỉ số để định nghĩa một quad. Một số đích lưu (STL, 3MF) yêu cầu tam giác và sẽ tự động chuyển đổi quad thành tam giác. glTF và COLLADA giữ lại quad.

Làm thế nào để thêm tọa độ UV?

Sử dụng mesh.create_element_uv(TextureMapping.DIFFUSE, MappingMode.POLYGON_VERTEX) để tạo một VertexElementUV cho kênh diffuse, sau đó điền danh sách data của nó bằng các mục Vector4. Tọa độ UV sử dụng x và y; z và w thường là 0. Đối số đầu tiên phải là một hằng số TextureMapping (ví dụ, TextureMapping.DIFFUSE) xác định khe texture nào mà lớp UV thuộc về.

Lưới có cần các pháp tuyến để xuất đúng không?

Không. Các pháp tuyến là tùy chọn. Nếu bỏ qua, hầu hết các trình xem sẽ tính các pháp tuyến theo mặt dựa trên thứ tự vòng polygon. Thêm các pháp tuyến theo đỉnh một cách rõ ràng sẽ tạo ra độ bóng mượt hơn.

Có thể thêm nhiều lưới vào một nút không?

Vâng. Gọi node.add_entity(mesh) nhiều lần. Mỗi lần gọi sẽ thêm một thực thể mới vào node.entities. Một số định dạng có thể làm phẳng nhiều thực thể thành một khi xuất.

Làm thế nào để tôi chia lưới thành các tam giác khi nó có các loại đa giác hỗn hợp?

Gọi mesh.triangulate() để chuyển đổi tất cả các quad và N‑gon thành tam giác tại chỗ. Điều này hữu ích trước khi lưu sang các định dạng chỉ hỗ trợ tam giác.