7.0 KiB
7.0 KiB
Vertex
Overview
Vertex is the vertex class in SimpleCAD API, representing a point in 3D space. It wraps OCP's Vertex object and adds tag functionality for identifying and managing specific vertices in geometries.
Class Definition
class Vertex(TaggedMixin):
"""顶点类，包装OCP的Vertex，添加标签功能"""
Inheritance Relationships
- Inherits from
TaggedMixin, with tag and metadata functionality
Usage
- Represent points in 3D space
- Serve as building elements for edges, wires, faces, and other geometries
- Provide vertex coordinate information
- Support tag management and queries
Constructor
__init__(wrapped)
Initialize a vertex object.
Parameters:
wrapped(OCP TopoDS_Vertex): OCP vertex object
Exceptions:
ValueError: Raised when the input vertex object is invalid
Example:
from simplecadapi import make_point_rvertex
# 通过 SimpleCAD 函数创建顶点
vertex = make_point_rvertex(1.0, 2.0, 3.0)
Main Properties
wrapped: Underlying OCP vertex object_tags: Tag set (inherited from TaggedMixin)_metadata: Metadata dictionary (inherited from TaggedMixin)
Common Methods
get_coordinates()
Get the coordinates of the vertex.
Returns:
Tuple[float, float, float]: Vertex coordinates (x, y, z)
Exceptions:
ValueError: Raised when coordinate retrieval fails
Example:
from simplecadapi import make_point_rvertex
vertex = make_point_rvertex(1.0, 2.0, 3.0)
coords = vertex.get_coordinates()
print(coords) # (1.0, 2.0, 3.0)
Tagging and Metadata
Use the functional public API apply_tag(shape, tag) and list_tags(shape) for tags. Use set_metadata(key, value) and get_metadata(key, default=None) for structured metadata.
Example:
from simplecadapi import apply_tag, list_tags, make_point_rvertex
vertex = make_point_rvertex(0, 0, 0)
apply_tag(vertex, "role.origin")
apply_tag(vertex, "anchor.reference_point")
if "role.origin" in list_tags(vertex):
print("这是原点")
Metadata Management Methods
set_metadata(key, value)
Set metadata.
Example:
vertex = make_point_rvertex(0, 0, 0)
vertex.set_metadata("created_by", "user_input")
vertex.set_metadata("importance", "high")
get_metadata(key, default=None)
Get metadata.
Example:
vertex = make_point_rvertex(0, 0, 0)
vertex.set_metadata("created_by", "user_input")
creator = vertex.get_metadata("created_by")
print(creator) # "user_input"
unknown = vertex.get_metadata("unknown_key", "default_value")
print(unknown) # "default_value"
Usage Examples
Creating and Using Vertices
from simplecadapi import make_point_rvertex
# 创建顶点
vertex1 = make_point_rvertex(0, 0, 0)
vertex2 = make_point_rvertex(1, 1, 1)
# 获取坐标
coords1 = vertex1.get_coordinates()
coords2 = vertex2.get_coordinates()
print(f"顶点1坐标: {coords1}") # 顶点1坐标: (0.0, 0.0, 0.0)
print(f"顶点2坐标: {coords2}") # 顶点2坐标: (1.0, 1.0, 1.0)
Vertex Tag Management
from simplecadapi import make_point_rvertex
# 创建关键点
origin = make_point_rvertex(0, 0, 0)
corner1 = make_point_rvertex(10, 0, 0)
corner2 = make_point_rvertex(10, 10, 0)
corner3 = make_point_rvertex(0, 10, 0)
# 添加标签
apply_tag(origin, "origin")
apply_tag(origin, "reference")
apply_tag(corner1, "corner")
apply_tag(corner1, "x_axis")
apply_tag(corner2, "corner")
apply_tag(corner2, "diagonal")
apply_tag(corner3, "corner")
apply_tag(corner3, "y_axis")
# 查找所有角点
vertices = [origin, corner1, corner2, corner3]
corners = [v for v in vertices if "corner" in list_tags(v)]
print(f"找到 {len(corners)} 个角点")
Vertex Classification and Management
from simplecadapi import make_point_rvertex
def create_grid_vertices(width, height, spacing):
"""创建网格顶点"""
vertices = []
for i in range(width + 1):
for j in range(height + 1):
x = i * spacing
y = j * spacing
z = 0
vertex = make_point_rvertex(x, y, z)
# 添加位置标签
if i == 0 and j == 0:
apply_tag(vertex, "origin")
elif i == 0:
apply_tag(vertex, "left_edge")
elif i == width:
apply_tag(vertex, "right_edge")
if j == 0:
apply_tag(vertex, "bottom_edge")
elif j == height:
apply_tag(vertex, "top_edge")
# 添加角点标签
if (i == 0 or i == width) and (j == 0 or j == height):
apply_tag(vertex, "corner")
# 添加元数据
vertex.set_metadata("grid_position", (i, j))
vertex.set_metadata("distance_from_origin", (x*x + y*y)**0.5)
vertices.append(vertex)
return vertices
# 创建 5x3 网格
vertices = create_grid_vertices(5, 3, 1.0)
# 查找特定顶点
corners = [v for v in vertices if "corner" in list_tags(v)]
origin = [v for v in vertices if "origin" in list_tags(v)][0]
print(f"网格顶点总数: {len(vertices)}")
print(f"角点数量: {len(corners)}")
print(f"原点坐标: {origin.get_coordinates()}")
Vertex Distance Calculation
import math
from simplecadapi import make_point_rvertex
def calculate_distance(vertex1, vertex2):
"""计算两个顶点之间的距离"""
coords1 = vertex1.get_coordinates()
coords2 = vertex2.get_coordinates()
dx = coords2[0] - coords1[0]
dy = coords2[1] - coords1[1]
dz = coords2[2] - coords1[2]
return math.sqrt(dx*dx + dy*dy + dz*dz)
# 创建顶点
v1 = make_point_rvertex(0, 0, 0)
v2 = make_point_rvertex(3, 4, 0)
v3 = make_point_rvertex(0, 0, 5)
# 计算距离
dist12 = calculate_distance(v1, v2)
dist13 = calculate_distance(v1, v3)
dist23 = calculate_distance(v2, v3)
print(f"v1 到 v2 的距离: {dist12}") # 5.0
print(f"v1 到 v3 的距离: {dist13}") # 5.0
print(f"v2 到 v3 的距离: {dist23}") # 约 7.07
String Representation
from simplecadapi import make_point_rvertex
vertex = make_point_rvertex(1.234, 5.678, 9.012)
apply_tag(vertex, "test_point")
vertex.set_metadata("created_by", "example")
print(vertex)
Output:
Vertex:
coordinates: [1.234, 5.678, 9.012]
tags: [test_point]
metadata:
created_by: example
Relationships with Other Geometries
Vertices are the fundamental elements that compose more complex geometries:
- Edge: Defined by two vertices
- Wire: Composed of multiple connected edges, containing multiple vertices
- Face: Boundary defined by vertices
- Solid: Ultimately composed of vertices
Notes
- Vertex objects wrap OCP's underlying vertices; do not modify coordinates directly
- Tags are of string type and are case-sensitive
- Metadata can store values of any type
- Vertex coordinates are read-only; to modify positions, create new vertices
- Floating-point coordinates may have precision issues; consider tolerance when comparing