first commit

2026-07-22 13:48:46 +08:00
commit c87751c3dc
2820 changed files with 726976 additions and 0 deletions
@@ -0,0 +1,287 @@
+# 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
+
+```python
+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:**
+```python
+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:**
+```python
+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:**
+```python
+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:**
+```python
+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:**
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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