Initial MDHelper implementation

This commit is contained in:
shenw
2026-05-25 17:12:00 +08:00
commit 50b15b02c7
45 changed files with 11654 additions and 0 deletions
+356
View File
@@ -0,0 +1,356 @@
# 几何建模
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 或增加分辨率。 |