Files
MDHelper/docs/geometry_manual.md
T
2026-05-25 17:12:00 +08:00

357 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 几何建模
M3Frame 的几何建模由 `geometry/cad.h` 和 `cad.xml` 控制,主要用于生成后续网格划分或粒子划分的几何源。
## 基本结构
```xml
<M3FrameCAD version="1.0" name="geometry">
<Metadata author="M3Frame" unit="SI" />
<MeshOptions segments="32" rings="16" />
<Primitives>
<Primitive id="box_0" type="box" basis="corner"
x="0" y="0" z="0" length="1" width="1" height="1" />
</Primitives>
<Exports>
<Export source="box_0" format="stl" path="outputs/cad/box.stl" />
<Export source="box_0" format="obj" path="outputs/cad/box.obj" />
</Exports>
</M3FrameCAD>
```
## CAD XML 关键词总表
`geometry/cad.h` 中定义的 CAD 配置关键词如下。新案例优先使用本表中的标准写法。
| 关键词 | 位置 | 说明 |
|---|---|---|
| `M3FrameCAD` | 根节点 | CAD 配置文件根节点。 |
| `version` | 根节点属性 | 配置格式版本。 |
| `name` | 根节点或对象属性 | 模型或对象名称。 |
| `Metadata` | 根节点子节点 | 元信息节点,可保存作者、单位、说明等扩展信息。 |
| `MeshOptions` | 根节点子节点 | primitive 离散导出选项。 |
| `segments` | `MeshOptions` 属性 | 圆周、经向或曲线离散段数。 |
| `rings` | `MeshOptions` 属性 | 球面纬向或环向离散段数。 |
| `Primitives` | 根节点子节点 | 基础几何对象集合。 |
| `Primitive` | `Primitives` 子节点 | 一个基础几何对象。 |
| `Boolean` | 根节点子节点 | 布尔组合对象。 |
| `Exports` | 根节点子节点 | 几何导出任务集合。 |
| `Export` | `Exports` 子节点 | 一个导出任务。 |
| `source` | `Export` 属性 | 被导出的 primitive 或 boolean id。 |
| `format` | `Export` 属性 | `obj`、`stl`、`stp`。 |
| `path` | `Export` 属性 | 输出文件路径。 |
常用对象属性:
| 关键词 | 说明 |
|---|---|
| `id` | 对象唯一编号,供 `source/lhs/rhs/ref` 引用。 |
| `type` | primitive、curve、surface 或边类型。 |
| `basis` | `corner` 或 `center`。 |
| `x/y/z` | 中心、角点或点坐标。 |
| `nx/ny/nz` | 法向或轴向。 |
| `radius` | 半径。 |
| `major_radius/minor_radius` | 椭圆长半径和短半径。 |
| `height` | 高度。 |
| `length/width` | 长度和宽度。 |
| `hx/hy/hz` | 兼容旧写法的半长字段;新案例优先使用 `length/width/height`。 |
| `x0/y0/z0`、`x1/y1/z1` | 线段起点和终点。 |
| `tx/ty/tz` | 平移量。 |
| `rx/ry/rz` | 旋转轴或方向半径,具体含义取决于上下文。 |
| `rotation_angle` | 旋转角。 |
| `start_angle/end_angle` | 圆弧、椭圆弧或扇形起止角。 |
| `array_x/array_y/array_z` | 阵列数量。 |
| `array_sx/array_sy/array_sz` | 阵列间距。 |
| `points` | polyline 点列表。 |
| `method` | 布尔或导出等高级路径的方法选择,为扩展字段。 |
| `ref` | B-Rep 或拓扑对象引用的目标 id。 |
## 常用 Primitive
| 类型 | 说明 |
|---|---|
| `point` | 点。 |
| `line_segment` | 线段,可导出为 wire geometry。 |
| `polyline` | 多点折线。 |
| `box` | 长方体。 |
| `cube` | 正方体。 |
| `sphere` | 球体。 |
| `cylinder` | 圆柱体。 |
| `cone` | 圆锥体。 |
| `plane` | 平面,适合表达参考面或接触面;无限平面不能直接用于有限体积粒子采样。 |
| `square_boundary` | 正方形边界线。 |
| `circle` / `ellipse` | 圆和椭圆边界。 |
| `arc` / `ellipse_arc` | 圆弧和椭圆弧。 |
| `rectangle_face` / `square_face` | 矩形面和正方形面。 |
| `disk` / `ellipse_disk` | 圆形面和椭圆形面。 |
| `sector` | 扇形面。 |
## Primitive 参数
常用几何体的核心参数如下。所有长度均使用真实长度,不使用半长作为用户输入。
| 类型 | 关键参数 | 说明 |
|---|---|---|
| `point` | `x y z` | 点坐标。 |
| `line_segment` | `x0 y0 z0 x1 y1 z1` | 线段起点和终点。 |
| `polyline` | `points` | 多点折线,建议使用空格或分号分隔点坐标。 |
| `box` | `x y z length width height basis` | 长方体。 |
| `cube` | `x y z length basis` | 正方体,`length` 为边长。 |
| `sphere` | `x y z radius` | 球体,`x/y/z` 为中心。 |
| `cylinder` | `x y z radius height nx ny nz` | 圆柱体,法向为轴向。 |
| `cone` | `x y z radius height nx ny nz` | 圆锥体,法向为轴向。 |
| `circle` | `x y z radius nx ny nz` | 圆边界。 |
| `ellipse` | `x y z major_radius minor_radius nx ny nz` | 椭圆边界。 |
| `arc` | `x y z radius start_angle end_angle` | 圆弧,角度单位建议使用弧度。 |
| `rectangle_face` | `x y z length width basis` | 矩形面。 |
| `square_face` | `x y z length basis` | 正方形面。 |
| `disk` | `x y z radius nx ny nz` | 圆形面。 |
| `sector` | `x y z radius start_angle end_angle` | 扇形面。 |
示例:
```xml
<Primitive id="water" type="box" basis="corner"
x="0" y="0" z="0"
length="0.3" width="0.6" height="0.2" />
<Primitive id="ball" type="sphere"
x="0.05" y="0.1" z="0.05" radius="0.005" />
<Primitive id="beam_axis" type="line_segment"
x0="0" y0="0" z0="0" x1="1" y1="0" z1="0" />
```
## 基准点
盒、正方体、矩形和正方形支持:
- `basis="corner"`:`x/y/z` 是最小角点。
- `basis="center"`:`x/y/z` 是中心点。
尺寸参数使用实际长度,而不是半长。
## 坐标、方向和变换
默认坐标系采用右手系。对圆、圆柱、圆锥、面片等带方向的对象,可用 `nx/ny/nz` 指定法向或轴向。
几何体支持平移、旋转和阵列参数:
| 参数 | 说明 |
|---|---|
| `tx ty tz` | 平移量。 |
| `rx ry rz` | 旋转轴。 |
| `rotation_angle` | 绕旋转轴的旋转角。 |
| `array_x array_y array_z` | 阵列数量。 |
| `array_sx array_sy array_sz` | 阵列间距。 |
建议先使用简单坐标直接建模,确认尺寸正确后再加入旋转和阵列。阵列对象用于粒子或网格划分时,要确保阵列体之间不发生意外重叠。
## 几何导出
常用格式:
- `stl`:适合表面检查、粒子划分和部分网格划分。
- `obj`:适合可视化和调试。
- `stp`:适合 CAD/CAE 工作流交换。
对于复杂工程几何,优先使用一个整体几何文件保持拓扑关系;只有需要分边界 id 或分材料时才拆分多个几何源。
导出示例:
```xml
<Exports>
<Export source="tank" format="stl" path="outputs/cad/tank.stl" />
<Export source="tank" format="obj" path="outputs/cad/tank.obj" />
<Export source="tank" format="stp" path="outputs/cad/tank.stp" />
</Exports>
```
线段类几何会按 wire geometry 导出,适合梁单元、路径线或一维网格测试。
## 导出文件选择
| 目标 | 推荐格式 | 说明 |
|---|---|---|
| ParaView 快速检查 | `stl` 或 `obj` | 直观看几何位置、尺寸和封闭性。 |
| SPH 粒子划分 | `stl` 或直接引用 CAD primitive | 体采样时更关注几何包围盒和 inside 判断。 |
| FEM 四面体网格 | `stl` 或内部 CAD primitive | 曲面需要足够细的 `segments/rings`。 |
| CAD/CAE 软件交换 | `stp` | 当前是 faceted STEP 路径,适合交换与调试。 |
| 梁/线网格 | wire geometry | 由 `line_segment` 或 `polyline` 导出。 |
## 布尔操作
支持并集、交集、差集等基础 CSG 操作。若用于 SPH 边界粒子生成,注意避免边界实体重叠,否则可能产生粒子重叠或过近。
布尔操作 `op` 可取:
| `op` | 说明 |
|---|---|
| `union` | 并集。 |
| `intersection` | 交集。 |
| `difference` | 差集,保留 `lhs` 并扣除 `rhs`。 |
XML 示例:
```xml
<Primitive id="block" type="box" basis="corner"
x="0" y="0" z="0" length="1" width="1" height="1" />
<Primitive id="hole" type="sphere"
x="0.5" y="0.5" z="0.5" radius="0.2" />
<Boolean id="block_with_hole" op="difference" lhs="block" rhs="hole" />
```
布尔结果用于导出或粒子划分时,应优先检查三角面是否封闭、交界线是否连续。球体与盒体相交、圆柱切割、圆孔板等问题对交界线离散质量比较敏感。
## NURBS 与 B-Rep
`geometry/cad.h` 中已保留 NURBS 曲线、NURBS 曲面和 B-Rep 拓扑数据结构。当前用户手册建议把它们视为高级几何入口:
- NURBS 适合保留曲线/曲面参数化信息。
- B-Rep 适合表达顶点、边、环、面、壳、实体之间的拓扑关系。
- 对大多数 benchmark,优先使用 primitive 和 CSG;只有需要高保真 CAD 语义时再使用 NURBS/B-Rep。
如果 NURBS/B-Rep 几何需要进入网格划分,应先导出或离散成可检查的曲面网格,再进入 meshing 阶段。
NURBS 关键词:
| 关键词 | 说明 |
|---|---|
| `NURBS` | NURBS 几何集合。 |
| `Curve` | 一条 NURBS 曲线。 |
| `Surface` | 一张 NURBS 曲面。 |
| `type` | 可取 `nurbs_curve` 或 `nurbs_surface`。 |
| `degree` | 曲线次数。 |
| `u_degree/v_degree` | 曲面 u/v 方向次数。 |
| `u_count/v_count` | 曲面 u/v 方向控制点数量。 |
| `Knots` | 节点向量。 |
| `ControlPoint` | 控制点。 |
| `weight` | 控制点权重。 |
示例:
```xml
<NURBS>
<Curve id="curve_0" type="nurbs_curve" degree="3">
<Knots>0 0 0 0 1 1 1 1</Knots>
<ControlPoint x="0" y="0" z="0" weight="1" />
<ControlPoint x="1" y="0" z="0" weight="1" />
<ControlPoint x="1" y="1" z="0" weight="1" />
<ControlPoint x="0" y="1" z="0" weight="1" />
</Curve>
<Surface id="surface_0" type="nurbs_surface"
u_degree="3" v_degree="3" u_count="4" v_count="4">
<Knots axis="u">0 0 0 0 1 1 1 1</Knots>
<Knots axis="v">0 0 0 0 1 1 1 1</Knots>
<ControlPoint x="0" y="0" z="0" weight="1" />
</Surface>
</NURBS>
```
B-Rep 关键词:
| 关键词 | 说明 |
|---|---|
| `BRep` | B-Rep 拓扑集合。 |
| `Vertices` / `Vertex` | 顶点集合和顶点。 |
| `Edges` / `Edge` | 边集合和边。 |
| `Faces` / `Face` | 面集合和面。 |
| `Loop` | 面的边界环。 |
| `CoEdge` | 有方向的共边引用。 |
| `Shell` | 壳。 |
| `Solid` | 实体。 |
| `curve` | Edge 引用的几何曲线 id。 |
| `surface` | Face 引用的几何曲面 id。 |
| `start/end` | Edge 的起止顶点或引用。 |
| `orientation` | `forward` 或 `reversed`。 |
示意:
```xml
<BRep>
<Vertices>
<Vertex id="v0" x="0" y="0" z="0" />
</Vertices>
<Edges>
<Edge id="e0" type="line" start="v0" end="v1" curve="curve_0" />
</Edges>
<Faces>
<Face id="f0" surface="surface_0" orientation="forward">
<Loop>
<CoEdge ref="e0" orientation="forward" />
</Loop>
</Face>
</Faces>
<Shell id="shell_0" ref="f0" />
<Solid id="solid_0" ref="shell_0" />
</BRep>
```
## 边界 id 和材料区域
几何阶段应尽早规划边界和材料分区。推荐做法:
- 不同材料域使用不同 `Primitive id` 或不同布尔结果 id。
- SPH 边界实体使用明确 id,例如 `wall_bottom`、`wall_left`、`wall_right`。
- FEM 需要施加载荷或约束的面,应在网格阶段保留 `boundary_id`。
- 后处理需要分开显示的对象,应在几何或离散阶段保留可追踪的名称或 id。
命名示例:
```text
fluid_water
wall_bottom
wall_top_moving
inlet_buffer
outlet_buffer
solid_ball
```
## SPH 边界建模建议
SPH 固壁通常建议在 CAD 阶段建成具有厚度的实体边界,再在粒子划分阶段生成 `role="boundary"` 的边界粒子。这样可以用边界 id 将几何实体、粒子集和求解器边界条件对应起来。
注意事项:
- 壁面厚度通常取 2 到 3 层粒子间距。
- 不同壁面实体之间不要重叠,否则会产生重复粒子。
- 角点和棱边处应保证粒子连续覆盖,避免流体粒子从角点漏出。
- 周期方向不需要布置固壁粒子,应使用周期边界条件。
盒形水箱建议不要用 6 个相互重叠的厚壁块直接拼接。更稳妥的做法是将壁面分块时预留不重叠区间,或使用一个外盒减去内盒形成整体边界实体,再按需要给边界分组。
## FEM 几何建模建议
FEM 体网格划分更依赖几何闭合性。用于 `tet4` 或贴体网格时:
- 曲面几何应提高 `segments`、`rings` 等离散精度。
- 圆柱、球体、圆孔板等曲面 benchmark 应优先检查表面三角面片是否贴合真实曲面。
- 如果需要按边界施加载荷或约束,应在几何或网格阶段保留边界 id。
典型 FEM 几何检查清单:
- 实体是否封闭。
- 曲面法向是否一致。
- 体积是否为正。
- 尺寸单位是否与材料参数一致。
- 需要施加载荷/约束的边界是否能在网格中被选中。
## 推荐建模流程
1. 只写 `cad.xml`,导出 `.stl` 和 `.obj`。
2. 在 ParaView、MeshLab 或其他工具中检查几何。
3. 确认几何无误后,再写 `meshing.xml` 或 `particle_meshing.xml`。
4. 对 SPH 案例,先输出粒子并按 `role`、`boundary_id` 着色。
5. 对 FEM 案例,先检查网格质量和边界 id。
6. 最后再接入 SPH/FEM 求解器。
## 常见错误
| 现象 | 可能原因 |
|---|---|
| 导出的长方体尺寸错误 | `basis` 或 `length/width/height` 使用错误。 |
| 粒子重叠 | 边界实体重叠或多个任务采样同一区域。 |
| 网格不贴体 | 几何表面离散太粗或使用了体素化方法。 |
| 布尔合并后表面不封闭 | 相交线未充分离散,需使用更高保真 CSG 或增加分辨率。 |