scibox-diagram

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

论文与研究示意图（draw.io）

Research and Paper Diagrams (draw.io)

主产物是可编辑的 .drawio，PNG/PDF 是附带导出。模板、手写、复刻、校验、预览、导出全在本目录内。

The main output is editable .drawio files, with PNG/PDF as supplementary exports. Templates, manual authoring, replication, validation, preview, and export are all handled within this directory.

先判断走哪条路

First Determine Which Approach to Take

情况	路径	入口
全文脉络、研究框架、执行流程，或课题的任务分解	A 套模板	下方模板索引
其他示意图：算法流程、模型架构、实验设计、机制示意…	B 从零手写 XML	`references/authoring.md`
给了参考图，要照着重画成可编辑矢量图	C 高保真复刻	`references/replication.md`

三条路的 XML 写法一致，产物可互相接着改；区别只在流程纪律的严格程度。

Scenario	Approach	Entry Point
Full-text context, research framework, execution flow, or task breakdown of a project	A. Use Templates	Template Index below
Other schematics: algorithm flow, model architecture, experimental design, mechanism illustration…	B. Write XML from Scratch	`references/authoring.md`
Given a reference diagram, need to redraw it into an editable vector diagram	C. High-Fidelity Replication	`references/replication.md`

The XML syntax is consistent across all three approaches, and outputs can be modified further interchangeably; the only difference lies in the strictness of the process discipline.

A. 套模板

A. Use Templates

模板 id	版式	适合表达	说明
`roadmap-5band`	954×1296 竖版，五条点线带 + 左旗标 + 右竖排标签	提出问题 → 数据与指标 → 方法与机制 → 结果对比 → 评价推广	`references/roadmap-5band.md`
`framework-3col`	1026 宽三栏，左阶段链 / 中内容块 / 右方法清单，高度自适应	研究内容全景：每个阶段对应哪些研究内容、用什么方法	`references/framework-3col.md`
`stageflow-3col`	1000 宽三栏，中栏每块实色标题条 + 独立色系，高度自适应	研究/系统的执行流程：阶段推进、决策分支、成果分发	`references/stageflow-3col.md`
`taskflow-land`	横版 1360 宽，若干任务块，块内流水线 + 每步挂做法细节	课题拆成「任务一…任务四」，每步要写清方法与结论；适合 16:9	`references/taskflow-land.md`

读模板说明的两节：语义约定（哪些槽位并列、哪些汇流、哪两组必须可对比）与字数预算。语义放错比字数超框严重。
从用户材料抽内容，不要编；有源文件（
```
.tex
```
/
```
.md
```
/代码）时逐个核对数值，术语用原文。
复制
```
assets/<template_id>/example.json
```
改写，
```
"\n"
```
手动断行。
渲染（写文件前逐槽校验字数，超框报出具体预算）：

bash

python3 scripts/roadmap_5band.py content.json -o out.drawio     # 模板 roadmap-5band
python3 scripts/framework_3col.py content.json -o out.drawio    # 模板 framework-3col
python3 scripts/stageflow_3col.py content.json -o out.drawio    # 模板 stageflow-3col
python3 scripts/taskflow_land.py  content.json -o out.drawio    # 模板 taskflow-land（横版）

新增模板见

references/adding-templates.md

。

Template ID	Layout	Suitable for Expressing	Description
`roadmap-5band`	954×1296 vertical layout, five dotted bands + left flag label + right vertical label	Problem proposal → Data and indicators → Methods and mechanisms → Result comparison → Evaluation and promotion	`references/roadmap-5band.md`
`framework-3col`	1026-width 3-column layout, left stage chain / middle content blocks / right method list, height adaptive	Panoramic view of research content: which research content corresponds to each stage and what methods are used	`references/framework-3col.md`
`stageflow-3col`	1000-width 3-column layout, middle column with solid color title bars per block + independent color schemes, height adaptive	Execution flow of research/system: stage progression, decision branches, result distribution	`references/stageflow-3col.md`
`taskflow-land`	Horizontal 1360-width layout, multiple task blocks with internal pipelines + detailed methods attached to each step	Break down projects into "Task 1…Task 4", with clear methods and conclusions for each step; suitable for 16:9 aspect ratio	`references/taskflow-land.md`

Read the two sections in the template documentation: Semantic Conventions (which slots are parallel, which converge, which two groups must be comparable) and Word Count Budget. Misplacing semantics is more serious than exceeding the word count limit.
Extract content from user materials, do not invent content; verify values one by one when source files (
```
.tex
```
/
```
.md
```
/code) are available, use original terminology.
Copy and rewrite
```
assets/<template_id>/example.json
```
, use
```
"\n"
```
for manual line breaks.
Render (check word count per slot before writing the file, report specific budget if exceeded):

bash

python3 scripts/roadmap_5band.py content.json -o out.drawio     # Template roadmap-5band
python3 scripts/framework_3col.py content.json -o out.drawio    # Template framework-3col
python3 scripts/stageflow_3col.py content.json -o out.drawio    # Template stageflow-3col
python3 scripts/taskflow_land.py  content.json -o out.drawio    # Template taskflow-land (horizontal)

For adding new templates, see

references/adding-templates.md

B. 从零手写 XML

B. Write XML from Scratch

读

references/authoring.md

：骨架、样式速查、中文字宽预算、连接器写法、四个必踩的坑。图标与特殊图元见

references/icons.md

。

三条最容易翻车的：

先排栅格再写图元：定死画布、列基线、步距；同族同宽同步距，数量可变的组用等分公式。
中文手动断行：全角≈字号、半角≈字号/2、行高≈字号+3；16px 字号下 160px 宽的盒子每行最多 9 个汉字。竖排逐字
```
&lt;br&gt;
```
堆叠，不要用
horizontal=0
（中文会躺倒）。
连接器端点离盒边 1px；一分多/多合一画成"竖线+横母线+分支"，不要画成 N 条独立斜线。

画之前想清楚每根箭头的语义（谁到谁、单向还是双向、扇入还是扇出）；说不出含义的箭头不要画。

Read

references/authoring.md

: skeleton, style quick reference, Chinese character width budget, connector syntax, four common pitfalls. For icons and special shapes, see

references/icons.md

Three key points to avoid mistakes:

Set up the grid first before adding shapes: Fix the canvas, column baselines, and step sizes; elements in the same group should have the same width and step size, use equal division formulas for groups with variable quantities.
Manual line breaks for Chinese text: Full-width characters ≈ font size, half-width characters ≈ font size/2, line height ≈ font size+3; for a 16px font size, a 160px-wide box can hold a maximum of 9 Chinese characters per line. For vertical layout, stack characters with
```
&lt;br&gt;
```
one by one, do not use
horizontal=0
(Chinese characters will be rotated incorrectly).
Connector endpoints should be 1px away from box edges; draw one-to-many/many-to-one connections as "vertical line + horizontal bus + branches" instead of N independent diagonal lines.

Before drawing, clarify the semantics of each arrow (who points to whom, one-way or two-way, fan-in or fan-out); do not draw arrows whose meaning cannot be explained.

C. 高保真复刻参考图

C. High-Fidelity Replication

比 B 多一套证据链，照

references/replication.md

执行，要点：

先标定再动笔：连通域抠盒子坐标与填充色、行列扫描找框线、颜色普查取配色、量字宽反推字号。不要目测，也不要假设"标题一定比正文大"。
四件中间产物：
```
visual-spec.md
```
（看到了什么）、
```
layout-grid.md
```
（坐标计划）、
```
asset-ledger.md
```
（哪些是近似的，防止悄悄丢元素）、
```
defect-log.md
```
（首次截图后只增不改）。
≥3 轮"截图 → 九区盘点 → 修完所有 P0/P1 → 重渲 → 逐条核销"；截图必须是画布本身。
红队复审 + 自评分卡（见
```
references/self-check.md
```
）：总分 <40 或任一维 ≤4 不交付。
像素差分定位残留差异，逐条写进
```
defect-log.md
```
，不写"已完美还原"。

This approach requires an additional evidence chain, follow

references/replication.md

, key points:

Calibrate first before drawing: Extract box coordinates and fill colors via connected components, find frame lines via row-column scanning, collect color schemes via color census, infer font size by measuring character width. Do not estimate by eye, and do not assume "titles must be larger than body text".
Four intermediate outputs:
```
visual-spec.md
```
(what is observed),
```
layout-grid.md
```
(coordinate plan),
```
asset-ledger.md
```
(which elements are approximated to prevent accidental loss),
```
defect-log.md
```
(only add entries after the first screenshot, no modifications).
≥3 rounds of "screenshot → 9-region inventory → fix all P0/P1 issues → re-render → verify item by item"; screenshots must be of the canvas itself.
Red team review + self-assessment scorecard (see
```
references/self-check.md
```
): Do not deliver if total score <40 or any dimension ≤4.
Use pixel difference to locate remaining discrepancies, record each item in
```
defect-log.md
```
, do not write "perfectly restored".

通用：校验、预览、导出

General: Validation, Preview, Export

bash

python3 scripts/check_layout.py fig.drawio      # 溢出/越界/重复 id/重叠/穿盒/位图（--strict 作门禁）
python3 scripts/export_figure.py fig.drawio     # 1:1 PNG + 矢量 PDF（需 drawio 命令行）
python3 scripts/preview_html.py fig.drawio      # 浏览器预览，无需 drawio 命令行

check_layout

用中文字宽模型、噪声低，正常的图应当 FAIL 0 / WARN 0；报警就值得认真看。它刻意不查紧密堆叠的行列间距和同族尺寸对齐（前者是刻意排版，后者机器判族必然误报）——这两项交给眼睛。规则详解与四个规避手法见

references/preflight-rules.md

。

不看渲染图不算画完：XML 里看不出文字溢出、箭头压字、盒子挤扁。打开 PNG 至少过两轮：① 文字溢出/压线；② 箭头方向与语义；③ 同族元素对齐同宽；④ 数值有没有抄错。完整的九区盘点与交付清单见

references/self-check.md

。

交付

.drawio

+ PNG/PDF；走模板路径时保留 content JSON 作为可复现源。尺寸提醒：954px 宽、16px 字号的图压到 A4 正文

0.97\textwidth

约 6.5pt，建议整页横排或答辩使用，正文小图另做精简版。

bash

python3 scripts/check_layout.py fig.drawio      # Check overflow/out-of-bounds/duplicate IDs/overlapping/box penetration/bitmaps (use --strict as gatekeeping)
python3 scripts/export_figure.py fig.drawio     # Export 1:1 PNG + vector PDF (requires drawio command line)
python3 scripts/preview_html.py fig.drawio      # Preview in browser, no drawio command line required

check_layout

uses a Chinese character width model with low noise; a normal diagram should FAIL 0 / WARN 0; any alerts deserve careful attention. It intentionally does not check tightly stacked row/column spacing and alignment of same-group element sizes (the former is intentional layout, the latter will inevitably have false positives when the machine judges groups) — these two items are checked manually. For detailed rules and four avoidance techniques, see

references/preflight-rules.md

The diagram is not considered complete without checking the rendered version: Text overflow, arrow overlapping text, and squashed boxes cannot be seen in XML. Review the PNG at least twice: ① Text overflow/line crossing; ② Arrow direction and semantics; ③ Alignment and uniform width of same-group elements; ④ Whether values are copied correctly. For the complete 9-region inventory and delivery checklist, see

references/self-check.md

Deliver

.drawio

+ PNG/PDF; when using the template approach, retain the content JSON as a reproducible source. Size reminder: A diagram with 954px width and 16px font size compressed to A4 body text

0.97\textwidth

is approximately 6.5pt, it is recommended to use full-page horizontal layout for defense, create a simplified version for small in-text diagrams.

参考索引

Reference Index

文件	何时读
`authoring.md`	手写示意图：骨架、样式串、字宽预算、连接器
`icons.md`	需要图标、旗标、块箭头、弯箭头等特殊图元
`roadmap-5band.md`	用五带路线图模板
`framework-3col.md`	用三栏研究框架模板（内容全景）
`stageflow-3col.md`	用三栏阶段流程模板（执行流程）
`taskflow-land.md`	用横版任务流水线模板
`adding-templates.md`	新增一个模板
`replication.md`	复刻参考图：标定方法、四件产物、迭代闭环
`self-check.md`	九区盘点、红队复审、自评分卡、交付清单
`preflight-rules.md`	静态检查在查什么、误报如何绕开

File	When to Read
`authoring.md`	For manual diagram authoring: skeleton, style snippets, character width budget, connectors
`icons.md`	When needing icons, flags, block arrows, curved arrows and other special shapes
`roadmap-5band.md`	When using the 5-band roadmap template
`framework-3col.md`	When using the 3-column research framework template (content panorama)
`stageflow-3col.md`	When using the 3-column stage flow template (execution flow)
`taskflow-land.md`	When using the horizontal task pipeline template
`adding-templates.md`	When adding a new template
`replication.md`	For replicating reference diagrams: calibration methods, four outputs, iterative loop
`self-check.md`	9-region inventory, red team review, self-assessment scorecard, delivery checklist
`preflight-rules.md`	What static checks are looking for, how to avoid false positives

不适用

Not Applicable

折线图、热图、统计图等数据图表 → 用
```
scibox-figure
```
技能；
需要 LaTeX 排版的公式推导链 → 用 TikZ 或写进正文。

Line charts, heatmaps, statistical charts and other data charts → Use the
```
scibox-figure
```
skill;
Formula derivation chains requiring LaTeX typesetting → Use TikZ or include in the main text.