MechanicsSketches 技能

你可以使用 MechanicsSketches Python 库以编程方式生成工程力学示意图。

环境配置

通过 pip 安装该库：

pip install git+https://github.com/MatthiasHBusch/MechanicsSketches.git

或手动安装依赖项，并将其路径添加到 PYTHONPATH 中：

pip install matplotlib PyQt5
export PYTHONPATH="/path/to/parent/of/MechanicsSketches:$PYTHONPATH"

快速上手 — 编写脚本

创建一个 Python 脚本，用于构建示意图并渲染输出：

from MechanicsSketches import *
import os

sketch = create_sketch("My Sketch")
S = 30.0  # 缩放因子（推荐值：20–40）

# 添加组件
add_beam(sketch, ax=0, ay=0, bx=10*S, by=0, scale_factor=S)
add_pinned_support(sketch, cx=0, cy=0, angle_deg=0, scale_factor=S)
add_roller_support(sketch, cx=10*S, cy=0, angle_deg=0, scale_factor=S)
add_force(sketch, cx=5*S, cy=0, angle_deg=0, scale_factor=S, annotation=r"$F$")

# 渲染
script_dir = os.path.dirname(os.path.abspath(__file__))
render(sketch, filename=os.path.join(script_dir, "output.pdf"), dpi=300)

然后运行：python my_sketch.py

快速上手 — 使用辅助脚本

你也可以使用配套的辅助脚本来从 JSON 文件生成示意图：

python scripts/generate_sketch.py input.json output.pdf

核心概念

缩放因子（S）

所有坐标位置和尺寸均应为 S 的整数倍（通常取 30.0），以确保各组件之间比例一致。

角度约定

• angle_deg=0 → 默认朝向（支撑与力方向向上，尺寸标注方向水平）
• 角度按逆时针方向以度为单位旋转

可用组件

标注参数

力、弯矩及尺寸标注类函数支持以下参数：

• annotation — LaTeX 字符串（例如：r"$F$"、r"$M_A$"）
• fontsize_scale — 相对字体大小（默认为 1.0）
• offsetx、offsety — 标注文本相对于基准点的偏移量
• rotate_annotation — 是否随组件一同旋转标注文本（默认为 False）

基础图元

如需自定义图形，可使用以下函数构造基本图元：

• make_line(x0, y0, x1, y1, linewidth, layer, edgecolor)
• make_circle(x, y, r, linewidth, layer, facecolor, edgecolor)
• make_polygon(points, linewidth, layer, facecolor, edgecolor)
• make_arc(x, y, width, height, theta1, theta2, angle, linewidth, layer)
• make_text(x, y, text, fontsize, layer, color, ha, va, rotation)
• make_rectangle(x0, y0, x1, y1, ...)

通过 add_to_sketch(sketch, primitive) 将图元添加至示意图中。

几何变换

• translate(obj, dx, dy) — 沿指定偏移量平移对象
• rotate(obj, cx, cy, angle_deg) — 绕指定点旋转对象
• scale(obj, cx, cy, factor) — 以指定点为中心缩放对象

所有变换函数均返回新对象（非破坏性操作），支持链式调用。

渲染输出

render(sketch, filename="output.pdf", dpi=300)  # Qt 渲染器（默认，推荐）
mpl_render(sketch, filename="output.pdf")        # Matplotlib 回退方案（已弃用，存在文字缩放问题）

支持的输出格式：.pdf、.png、.jpg、.svg

对 Agent 的使用提示

1. 始终将缩放因子定义为 S = 30.0
2. 先绘制梁，再在端点处添加支座，最后施加荷载
3. 标注请使用 LaTeX 表达式，例如：r"$F$"、r"$M_0$"、r"$ell$"
4. 如需查阅完整 API 签名，请参考 references/api_reference.md
5. render() 函数必须指定 filename 参数，它不会以交互方式显示图像
6. 切勿使用 mpl_render() —— 因其存在文字缩放问题已被弃用。请始终使用 render()。

外部端点

本技能不发起任何网络请求，全部处理均在本地完成。

安全与隐私

• 无任何数据离开你的设备。 该技能仅读取本地 JSON 文件，并将图像/PDF 输出写入本地磁盘。
• 无需提供任何 API 密钥或凭据。
• 不收集任何遥测数据或分析信息。
• 辅助脚本（scripts/generate_sketch.py）仅读取用户指定的输入文件，并将结果写入用户指定的输出路径。

可信声明

本技能由 MatthiasHBusch 开发与维护，源代码完全开源，采用 MIT 许可证发布。所有功能均在本地运行，除标准 Python 包（matplotlib、PyQt5）外，不依赖任何外部服务或库。