VertexElement — Aspose.3D Python API Reference
Package: aspose.threed.entities (aspose-3d-foss 26.1.0)
VertexElement is the abstract base class for all per-vertex data layers that can be attached to a Geometry object. Each layer holds an array of data values together with mapping_mode and reference_mode metadata that describe how the data maps onto the underlying geometry. Subclasses are specialised for normals, UV coordinates, vertex colours, tangents, binormals, and smoothing groups.
VertexElement (base)
from aspose.threed.entities import VertexElementInheritance
VertexElement
Properties
| Property | Type | Access | Description |
|---|---|---|---|
vertex_element_type | VertexElementType | read | Semantic type of this layer (e.g., NORMAL, UV, VERTEX_COLOR). |
name | str | read/write | Optional name for this layer. |
mapping_mode | MappingMode | read/write | Controls which geometry primitive each data value is associated with. |
reference_mode | ReferenceMode | read/write | Controls whether values are addressed directly or through an indices array. |
indices | list[int] | read | Index array used when reference_mode is INDEX_TO_DIRECT. |
data | list[FVector4] | read | Raw data values stored as FVector4 entries (available on VertexElementFVector subclasses). |
Methods
| Method | Returns | Description |
|---|---|---|
set_data(data) | None | Replace the data array. Accepts list[FVector2], list[FVector3], or list[FVector4]; values are normalised to FVector4 internally. |
set_indices(data) | None | Replace the indices array with a list of integers. |
clear() | None | Remove all data values and indices from the layer. |
copy_to(target) | None | Copy data and indices to another VertexElementFVector instance. |
VertexElementNormal
Stores surface normal vectors. Normal data is typically used by renderers for lighting calculations.
from aspose.threed.entities import VertexElementNormalInheritance
VertexElement → VertexElementFVector → VertexElementNormal
Constructor
VertexElementNormal(name="", mapping_mode=None, reference_mode=None)vertex_element_type is fixed to VertexElementType.NORMAL.
VertexElementUV
Stores UV texture coordinates. A mesh may carry multiple UV layers for different texture channels.
from aspose.threed.entities import VertexElementUVInheritance
VertexElement → VertexElementFVector → VertexElementUV
Constructor
VertexElementUV(texture_mapping=None, name="", mapping_mode=None, reference_mode=None)| Parameter | Type | Description |
|---|---|---|
texture_mapping | TextureMapping | The texture channel this UV layer serves. Defaults to TextureMapping.DIFFUSE. |
Additional property
| Property | Type | Access | Description |
|---|---|---|---|
texture_mapping | TextureMapping | read | The texture channel this UV layer is associated with. |
add_data(data)
Append UV coordinate data. Accepts list[Vector2], list[Vector3], list[FVector2], list[FVector3], or list[FVector4]. All values are stored internally as FVector4 with unused components set to 0.0.
VertexElementVertexColor
Stores per-vertex RGBA colour values in the range 0–1.
from aspose.threed.entities import VertexElementVertexColorInheritance
VertexElement → VertexElementFVector → VertexElementVertexColor
Constructor
VertexElementVertexColor(name="", mapping_mode=None, reference_mode=None)vertex_element_type is fixed to VertexElementType.VERTEX_COLOR.
VertexElementTangent
Stores per-vertex or per-corner tangent vectors, used for normal map rendering.
from aspose.threed.entities import VertexElementTangentInheritance
VertexElement → VertexElementFVector → VertexElementTangent
vertex_element_type is fixed to VertexElementType.TANGENT.
VertexElementBinormal
Stores per-vertex or per-corner binormal (bitangent) vectors, complementing VertexElementTangent for tangent-space normal mapping.
from aspose.threed.entities import VertexElementBinormalInheritance
VertexElement → VertexElementFVector → VertexElementBinormal
vertex_element_type is fixed to VertexElementType.BINORMAL.
VertexElementSmoothingGroup
Stores per-polygon integer smoothing group IDs. Loaded from OBJ files that contain s declarations.
from aspose.threed.entities import VertexElementSmoothingGroupInheritance
VertexElement → VertexElementIntsTemplate → VertexElementSmoothingGroup
vertex_element_type is fixed to VertexElementType.SMOOTHING_GROUP.
VertexElementType enumeration
Identifies the semantic role of a vertex element layer.
from aspose.threed.entities import VertexElementType| Value | Description |
|---|---|
NORMAL | Surface normal vectors. |
UV | Texture UV coordinates. |
VERTEX_COLOR | Per-vertex RGBA colour. |
TANGENT | Tangent vectors for normal mapping. |
BINORMAL | Binormal (bitangent) vectors. |
SMOOTHING_GROUP | Per-polygon smoothing group integer IDs. |
MATERIAL | Per-polygon material index. |
POLYGON_GROUP | Polygon grouping index. |
VERTEX_CREASE | Subdivision vertex crease weights. |
EDGE_CREASE | Subdivision edge crease weights. |
USER_DATA | Arbitrary user-defined data. |
VISIBILITY | Per-element visibility flags. |
SPECULAR | Specular colour or intensity. |
WEIGHT | Blend weights for skinning. |
HOLE | Polygon hole flags. |
MappingMode enumeration
Controls which geometry primitive each vertex element value is associated with.
from aspose.threed.entities import MappingMode| Value | Description |
|---|---|
CONTROL_POINT | One value per control point (vertex). |
POLYGON_VERTEX | One value per polygon corner (face-vertex). |
POLYGON | One value per polygon. |
EDGE | One value per edge. |
ALL_SAME | A single value applies to the entire mesh. |
ReferenceMode enumeration
Controls how the data array is indexed.
from aspose.threed.entities import ReferenceMode| Value | Description |
|---|---|
DIRECT | Data is accessed sequentially without a separate indices array. |
INDEX | Data is accessed via a separate indices array. |
INDEX_TO_DIRECT | An indices array maps each mapping primitive to a position in the data array. |
Examples
Attach a normal layer to a mesh (DIRECT mapping):
from aspose.threed import Scene
from aspose.threed.entities import Mesh, VertexElementType, MappingMode, ReferenceMode
from aspose.threed.utilities import Vector4, FVector4
mesh = Mesh()
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))
mesh.create_polygon(0, 1, 2)
normals = mesh.create_element(
VertexElementType.NORMAL,
MappingMode.CONTROL_POINT,
ReferenceMode.DIRECT,
)
normals.set_data([
FVector4(0.0, 0.0, 1.0, 0.0),
FVector4(0.0, 0.0, 1.0, 0.0),
FVector4(0.0, 0.0, 1.0, 0.0),
])
scene = Scene()
scene.root_node.create_child_node("tri", mesh)
scene.save("triangle_normals.glb")Attach UV coordinates (INDEX_TO_DIRECT mapping):
from aspose.threed import Scene
from aspose.threed.entities import Mesh, TextureMapping, MappingMode, ReferenceMode
from aspose.threed.utilities import Vector4, FVector4
mesh = Mesh()
for x, z in [(0, 0), (1, 0), (1, 1), (0, 1)]:
mesh.control_points.append(Vector4(float(x), 0.0, float(z), 1.0))
mesh.create_polygon(0, 1, 2, 3)
uv = mesh.create_element_uv(
TextureMapping.DIFFUSE,
MappingMode.POLYGON_VERTEX,
ReferenceMode.INDEX_TO_DIRECT,
)
uv.set_data([
FVector4(0.0, 0.0, 0.0, 0.0),
FVector4(1.0, 0.0, 0.0, 0.0),
FVector4(1.0, 1.0, 0.0, 0.0),
FVector4(0.0, 1.0, 0.0, 0.0),
])
uv.set_indices([0, 1, 2, 3])
scene = Scene()
scene.root_node.create_child_node("quad", mesh)
scene.save("quad_uv.glb")