# Cumcm Visualization

> 为 CUMCM 及其他数学建模竞赛或项目规划、生成并审校模型框架图、算法流程图与结果可视化；默认输出 PNG，逻辑图可用 Visio 并保留 VSDX，数据图保留可复现代码。适用于论文配图、模型解释、算法展示、结果比较和稳健性验证；不用于脱离真实模型与数据的装饰性配图。

- Skill: `xxszyh/cumcm-visualization` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add xxszyh/cumcm-visualization`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xxszyh/cumcm-visualization/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: xxszyh (https://skillmd.com/u/xxszyh)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/xxszyh/cumcm-visualization

---


# CUMCM 建模可视化

把一张图当作一段可核验的论证：评委应能快速看懂“问题如何进入模型、算法如何求解、结果如何支持结论”。美观服务于逻辑，不用装饰替代证据。

## 开始前先建立图形契约

对每张图先写清：

1. **核心结论**：评委看完后应记住的一句话。
2. **证据来源**：对应哪一问、哪份真实数据、哪个模型或算法输出。
3. **图形角色**：原理解释、模型框架、算法流程、结果比较、误差诊断、敏感性/稳健性或方案落地。
4. **阅读顺序**：箭头、编号和层级如何形成单一路径。
5. **交付形式**：PNG 必需；Visio 图同时保留 VSDX；代码图同时保留脚本和输入数据路径。
6. **版面尺寸**：预先决定单栏、双栏或页内插图宽度，不先画一张无限大的图再硬塞进论文。

信息不足时，先从现有赛题、模型说明、代码和结果文件中提取，不凭空补造步骤或数值。若缺少影响图义的关键输入，明确列出缺口再询问用户。示意数据必须在图题、图内或 README 中明确标为“示意”，不得冒充实测结果。

涉及数值模型对照、移动边界、收敛性或敏感性图时，读取 [模型比较与数据追溯](references/model-comparison.md)。先核对运行是否完成、输入版本及实际时空坐标；区分数值误差、结构差异与统计不确定性，不把输出的小数位数当作精度证据。

## 全局版式原则（经多轮论文图迭代验证）

这些规则适用于地图、网络、流程图、算法示意、结果图和多目标模型图，不局限于某一道题。

### 1. 先做信息分层，再决定是否合图

- 一张图只承担一个主结论；辅助解释不应与主证据争夺视觉焦点。
- 若三个步骤、三个视角或两类证据挤在一起导致文字缩小，拆成连续的子图或独立图；“两级图”（主图 + 小型放大/流程面板）只有在阅读顺序仍然单一时才使用。
- 用简化结构（例如少量节点、代表性路径或局部样本）解释算法机制时，保留真实变量含义，明确这是机制示意，不伪造数据规模。
- 右侧说明栏、底部长段落和正文级公式不是默认组件；能用箭头、分组、短标签表达时，不把整段论文搬进图里。

### 2. 画布与论文尺寸优先

- 先按论文最终插入宽度排版，单栏通常约 6–7 英寸，复杂双栏组合可约 10–12 英寸；具体以模板为准。
- 标题、轴标签和必要注释放在有明确留白的区域；图题由论文排版系统统一管理时，图内不要重复一条长图题。
- 任何文字都要在最终插入尺寸下可读。若 `bbox_inches="tight"` 使像素宽度不足，优先提高导出 DPI 保持物理尺寸，不要无限放大画布把图撑满一页。
- 图形需要留出稳定的边界和内边距，避免标题贴边、注释被裁切、坐标轴占满页面。

### 3. 标签优先于装饰

- 默认使用普通文字和手动偏移，避免大块说明框、渐变、阴影和图标墙。
- 边线标签不使用不透明填充框；先通过偏移、缩短文字或调整线型解决遮挡。确实需要压住复杂背景时，只使用轻量白色描边/光晕，不要绘制可见的色块底。
- 预留标签安全区，避免标签同时压住节点、箭头和虚线。标签位置应由数据坐标或结构关系决定，不能只靠自动布局后不检查。
- 坐标区内不放长句。算法结论、模型限制和投影说明放在图外的短句或论文正文中。
- 标题、说明和图例之间留出明确垂直间距；禁止标题与外置结论贴在同一基线上。

### 4. 节点与连接线的绘制顺序

- 节点填充默认透明（`facecolor="none"` 或等价设置），只保留边框和字母/编号；不要擅自用白底圆圈遮住连接线。
- 只有在用户明确要求“遮罩连接线”或该遮罩是图义的一部分时，才使用白色节点填充，并在 QA 中确认没有误遮挡。
- 推荐绘制顺序：底层连接线 → 高亮路径/边 → 节点边框 → 节点文字。若箭头应停在节点边界，使用 `shrinkA/shrinkB`、裁剪或端点计算，而不是让线穿过节点内部。
- 节点尺寸、边框宽度和字母字号应成比例；先用少量代表节点校准，再统一应用到全部节点，避免重点节点意外大到遮挡路径。

### 5. 共享边、重叠路径与多系列编码

- 识别不同路径/方法的共享边，不要把虚线叠在实线上再让底层颜色从虚线间隙露出；这会制造“第三条路径”的错觉。
- 默认采用“共享边单层绘制”：选定语义明确的一种颜色和线型，其他路径只绘制独有边；在图例或正文中说明共享边规则。
- 若必须同时保留两条路径，使用对称偏移、弧线或并行细线，保证每条线都连续可追踪。
- 颜色不是唯一编码：同时使用线型、标记或直接标签；灰度打印时仍应区分主路径和次路径。

### 6. 三维模型与二维解释图

- 三维坐标只在三个维度本身需要被比较或展示时使用；避免为了“看起来高级”而使用 3D。
- 3D 图的点标签要分散偏移，坐标主体内不塞长解释句；上下界、支配关系等结论用坐标外短句表达。
- 高维结构（如三维成本向量）若用二维投影解释分区、索引或 KD-tree，必须在标题/注释中明确“二维投影”，同时说明模型仍在原始维度中计算。
- 能将复杂三维机制拆成“结果空间 + 算法局部示意”时，优先拆图或使用小型投影面板，而不是把所有信息堆在同一 3D 轴内。

### 7. 颜色与可编辑性

- 采用白底、深灰文字、中性灰辅助元素，加一个主色和一个强调色；不要依赖红/绿单独编码。
- 统一全文语义颜色，例如同一方法、同一路径或同一类结果在所有图中保持同色。
- 源数据、脚本、规格 JSON 和最终 PNG 一起交付；不要只交一张不可追溯的截图。

## 选择绘图轨道

- **Visio**：优先用于模型总框架、算法流程、变量传递、模块依赖、决策分支、泳道和时序逻辑。使用 [references/visio-workflow.md](references/visio-workflow.md)。交付 `.vsdx` + `.png`。
- **Python**：优先用于由数据或模型结果驱动的图，如预测对比、残差、敏感性、热力图、空间路径、Pareto 前沿和消融对比。使用 [references/python-workflow.md](references/python-workflow.md)。交付 `.py` + `.png`，必要时附 CSV/JSON。
- **混合**：一组论文图可以同时采用两轨，但单张图不要把无法追溯的截图拼贴在一起。组合时保留每个面板的独立源文件。

默认逻辑图选择 Visio，默认结果图选择 Python。只有 Visio 不可用、用户要求纯代码，或图需要从结构化数据频繁重生成时，才用 Graphviz/NetworkX 绘制逻辑图。

## 工作流

1. 读取当前题目、分问、模型路线、算法伪代码和真实结果。
2. 按 [references/figure-routing.md](references/figure-routing.md) 制定最小图组，先确认每张图的核心结论和最终插入尺寸。
3. 在项目中建立 `paper_output/plan/figure_plan.json`、`paper_output/figures/`、`paper_output/figures/source/`、`paper_output/code/visualization/` 和 `paper_output/figure_index.json`。
4. 逻辑图先写节点与边的结构化规格；Visio 规格同时记录论文最终插入宽度和最终字号，再生成 VSDX/PNG/字号报告。数据图必须直接读取真实结果文件。示意图输入文件必须显式标注用途。
5. 先搭建信息层级和绘制顺序，再放标签；对于共享边、投影、上下界和分区等容易误读的关系，先制定编码规则再画。
6. 图题采用“图 N + 结论性标题”，正文必须解释读图结论，不只写“如下图所示”。
7. 运行文件检查和人工视觉检查：PNG 可打开、中文无乱码、文字不截断、颜色在灰度下仍可区分、节点填充/连接线层级符合契约、数值与源数据一致。
8. 在 `figure_index.json` 记录图号、用途、PNG、源文件、输入数据、生成脚本、验证尺寸和对应结论。修订优先使用版本号或新输出目录，避免覆盖用户已有同名文件。

可用 `scripts/init_figure_workspace.py` 初始化目录；Visio 逻辑图可用 `scripts/render_visio_flowchart.ps1`；PNG 用 `scripts/validate_png.py` 做基础门禁。

用 `scripts/validate_figure_index.py` 检查索引中的文件和已声明哈希；定量图交付可加 `--strict-provenance` 要求输入哈希及计算完成记录。文件检查通过不代表单位、模型或图中结论已验证，仍需核对源数据和人工审图。

## 论文图的硬约束

- 最终必须有 PNG，优先 300 dpi；通常宽度不少于 1800 px，单栏图也不得小于 1200 px。像素分辨率与物理字号分别检查：Visio 规格默认按 6.5 英寸最终宽度换算，最终标题不小于 10 pt、节点不小于 8 pt、边标签不小于 7.5 pt，并保留 `.typography.json` 报告。
- 白底、少色、强层级。通常使用中性灰 + 一个主色 + 一个强调色；红绿不得成为唯一编码。
- 节点默认透明填充；不使用未经确认的白色遮罩或不透明标签框。
- 流程图每个节点只表达一个动作或判断，正文级公式不要塞进节点。
- 结果图必须有单位、样本范围、误差定义或统计口径；比较图保持同一坐标尺度。
- 不使用 3D 柱状图、饼图堆叠、彩虹色图、厚阴影、渐变背景、装饰性图标墙。
- 不生成虚假数据，不把 AI 生成插画当作模型证据，不伪造软件界面或实验场景。
- 不能保证任何“AI 检测率”下降。降低模板感的可靠方式是使用团队真实模型、真实数据、可编辑源文件、清楚的图文对应关系，并由参赛者最终复核和改写。

## 交付前检查

按 [references/qa-checklist.md](references/qa-checklist.md) 和 [references/visual-design-patterns.md](references/visual-design-patterns.md) 完成检查。发现数值、单位或因果方向不确定时停止交付该图并回到证据来源核对；只改美观不能掩盖逻辑错误。

## 参考资料路由

- 图形类型与 CUMCM 常用证据链：[references/figure-routing.md](references/figure-routing.md)
- 通用版式、标注、节点和重叠路径模式：[references/visual-design-patterns.md](references/visual-design-patterns.md)
- Visio 自动化、源文件保留与导出：[references/visio-workflow.md](references/visio-workflow.md)
- Python 静态图规范、中文字体与导出：[references/python-workflow.md](references/python-workflow.md)
- 数值模型比较、坐标口径与数据追溯：[references/model-comparison.md](references/model-comparison.md)
- 最终质量门禁：[references/qa-checklist.md](references/qa-checklist.md)
- 本地优秀论文抽样与开源项目调研记录：[references/source-notes.md](references/source-notes.md)