Import project sources

This commit is contained in:
2026-11-05 01:04:53 +08:00
commit 4da5d842f9
41 changed files with 2741 additions and 0 deletions
+22
View File
@@ -0,0 +1,22 @@
# 视觉与布局调校
地铁式工具地图依靠粗彩色主干、圆角转弯、白色黑边胶囊、线路编码和密集标注。时间谱系依靠更细主题线、年代、时代底纹、稀疏起点和后期分化。两者共享“信息沿线展开”的阅读方式,不强制共享线宽或节点样式。
先保留这些视觉语法,再考虑品牌 logo、纹理或装饰。此原型用文字、圆环和米白背景,未复刻参考图产品标志或车站插画。
## 调整顺序
1. **数据语义**:核对条目、归属、时间和关系,先修重复节点及矛盾的停靠顺序。
2. **线路邻接**:经常共享站点的类别放相邻位置,修改 `lane_order`。不相邻共享站点会穿过无关线路;引擎绘制覆盖桥,必要时换序或拆图。
3. **密度**:增大宽度和线路间距可创造文字间隙;增大行距/时间图高度可减少纵向拥挤。更多线路需要更宽画布。
4. **弯道**:地铁图默认不设置 `offsets`,使主干笔直、平行、等距。转弯应有分支、汇合、换位或避让的实际理由,不给整束线路加入装饰性漂移。当前 `offsets` 实现的是平滑曲线,适合需要曲线的时间谱系;严格直角或 45° 局部布线需要扩展路径算法,不能把它描述为现有功能。偏移差大于线路间距时会交换顺序,引擎不自动避免这些交叉。
5. **文字**:先试方向和 `label_dy`,再改字号。长文字可分到 `detail`,但不自动裁剪或换行。重要标签优先占位,小标签随后避让。
6. **成品**:检查 100% 及缩略图;全尺寸可读、缩略图能辨识主题结构。打印时以目标物理尺寸检查,不能用“SVG 可无限放大”代替字号判断。
## 质量边界
地铁图以拓扑排序安排层级,以输入顺序分配线路横向位置;不会求全局最优地铁网。标签用 Unicode 字宽估算、候选位置打分和侧栏避让;真实字形、引线交叉、路线碰撞、密集同年事件仍需视觉检查。
优先改 JSON,让生成可复现。若在设计软件里手修 SVG,区分手修版与生成版,并记录无法由 JSON 表达的调整,避免下次覆盖。
PNG 使用环境已有 SVG 渲染器导出即可,例如已有 Node `sharp` 时运行 `await sharp('OUTPUT.svg').png().toFile('OUTPUT.png')`。字体依赖本机安装状态,换环境应重新检查中文。无需为单张预览搭建网站或安装大型依赖。
+84
View File
@@ -0,0 +1,84 @@
# 数据格式
## 最小地铁图
```json
{
"mode": "metro",
"title": "研究方法地图",
"subtitle": "示意分类,不表示时间或推荐排名",
"routes": [
{"id":"qual","label":"定性","code":"A","color":"#208a87","stops":["interview","synthesis"]},
{"id":"quant","label":"定量","code":"B","color":"#3d64a3","stops":["survey","synthesis"]}
],
"nodes": [
{"id":"interview","label":"访谈"},
{"id":"survey","label":"问卷"},
{"id":"synthesis","label":"综合证据","major":true}
]
}
```
## 顶层字段
| 字段 | 含义 |
|---|---|
| `mode` | `metro` 或 `timeline`,默认前者 |
| `title`, `subtitle` | 主标题、解释性副标题 |
| `eyebrow`, `footer` | 页眉分类、来源/语义/刻度说明 |
| `routes`, `nodes` | 非空数组,下面说明 |
| `layout` | 可选尺寸与布局参数 |
| `theme.paper` | 背景色,`#RRGGBB`,默认米白 |
| `links` | 可选明确关联,`{"from":"节点ID","to":"节点ID","label":"关系依据"}`;画为细灰箭头,不自动创造 |
| `eras` | 时间图背景,`{"start":1800,"end":1900,"label":"阶段"}`;范围必须在时间轴内 |
| `ticks` | 时间图的刻度数字数组,不得超出节点时间范围 |
## 线路
`id` 唯一;`label` 显示名称;`code` 用短字母或数字;`color` 为 `#RRGGBB`;`group` 是图例栏目标题;`stops` 是节点 ID 的有序列表,非空、同一线路内不重复。
所有线路的 `stops` 共同定义归属;没有节点侧的第二套 `routes` 字段。多条线路引用同一个 ID 就是换乘节点。所有节点至少属于一条线路。
可选 `offsets` 控制横向弯道,如 `[[0,0],[0.25,0],[0.45,-50],[0.75,-50],[1,0]]`。地铁图默认省略此字段,保持主干笔直。每对值是 `[纵向归一化位置,水平偏移像素]`,位置 0/1 为全图首/末事件,严格递增并限制在 0—1。端部保持最近值,相邻点以平滑三次曲线连接;站点按同一函数定位。偏移不是自动布线,过大的偏移会造成相撞或换序,需看图调整。
## 节点
| 字段 | 含义 |
|---|---|
| `id` | 唯一、非空、稳定字符串 |
| `label` | 主名称,默认 ID |
| `detail` | 可选一行说明,不自动换行 |
| `major` | `true` 时强调文字和站点 |
| `order` | metro 排序优先值;只在满足线路先后约束的节点中生效,默认输入数组顺序 |
| `time` | timeline 必需有限数字,负数年代需解释记年法 |
| `label_side` | `left` / `right` 优先方向;冲突时可自动反向 |
| `label_dy` | 标签垂直偏移像素;设置后不再尝试其他垂直偏移,仍可反向、移到侧栏 |
共享节点是所有所属线路上的同一事件;名称相似或发生时间不同的条目应使用不同 ID,再以明确关联连接。
## 布局
| 字段 | 默认 | 含义 |
|---|---|---|
| `width` | 1320 | 需容纳全部线路、文字和侧栏 |
| `lane_gap` | 86 | 相邻线路横向间距,最小 32 |
| `row_gap` | 66 | metro 站点纵距,最小 36;高度按节点数计算 |
| `font_size` | 17 | 节点字号,最小 8 |
| `lane_order` | `routes` 顺序 | 所有线路 ID 的完整排列 |
| `height` | 2050 | timeline 高度,metro 忽略 |
| `time_scale` | 全范围线性 | timeline 分段映射 |
地铁图使用稳定拓扑排序,每个节点占一个纵向层级。当前版本不把独立节点压到同一行,也不做线路邻接的全局优化;可通过 `lane_order`、输入节点顺序和弯道进行编辑。
时间图每条线路按时间升序列出站点,同年事件允许并排,范围不能只有一个值。可用 `"time_scale":[[1800,0],[1900,0.28],[1950,0.59],[2000,1]]`。第一对必须为 `[最早节点时间,0]`,最后为 `[最晚节点时间,1]`,两列严格递增;相邻区段内线性插值。图中须注明压缩区段,脚本不自行决定压缩哪些年代。不能为避让修改年代。
## 输出与返回值
- SVG:真实文字、路径和几何节点,保留 `data-route` / `data-node`,字体未嵌入。
- `.report.json`:尺寸、数量、节点坐标、标签侧向/偏移/估计包围框、提示列表。
- `label_needs_review`:估计标签碰撞、越界或穿越线路;要修正并看图复核。
- `overpass`:非成员线路从共享胶囊上方通过,是信息提示;只有圆环表示归属。
- `route_outside`:线路越界,需要调整偏移或加宽。
- 退出码:0 成功;1 输入/文件错误;2 `--strict` 发现待复核问题。报告不是像素级碰撞证明。
额外来源字段可放入节点或关联,渲染器忽略它们,源 JSON 应保留以便追溯。只把经过核实或用户明确给出的关系加入 `links`。