三维查看器与图谱（0.3）

从上传到三维脑

上传矩阵或 ROI 时序 → 确认变量与数据形式 → 分析 → 打开结果 → 选择匹配图谱 → 明确矩阵每行的 ROI 顺序 → 验证并叠加连接。

首次安装标准图谱需要网络，其后同一工作区可离线使用。三维资源不是患者影像，不随 wheel 分发。Python AtlasRegistry(workspace / 'atlases') 与网页使用完全相同的导入、验证和表面生成代码。网页里的“图谱预览”只切换参考图谱，不改变已有矩阵。更换分区需要该分区对应的时序或矩阵；纠正已经保存的绑定，需要重新打开原始数据并生成新结果，历史结果保持原样。

三种风格与深夜蓝 / 论文白独立选择。初始参考脑不透明度 20%，可连续调整。普通边正值为橙色，负值为蓝色，宽度随同一图内的绝对权重变化。超边颜色只标识集合，不编码统计显著性。不同 ID 可能共用有限分类颜色，以 ID 和成员表为准。ROI 球体按图谱提供的分类颜色或半球着色；分区表面使用图谱颜色，缺失时按稳定 ROI ID 配色。两套皮肤不改变颜色语义。

0.2.1 的全局包络使用轻薄透明面与细轮廓，超边较多时只降低视觉强度，不删边。0.3 将球棍与骨架合并，使用轻微弯曲的成员连线与带 H 字的平面空心六边形锚点；曲线只表达集合成员关系，不表示真实纤维束。

点选后，无关节点不透明度为 2.5%，无关普通边 / 骨架 / 轮廓为 0.9%，无关包络面 / 分区面为 0.2%，无关标签为 2.5%。这些是实际透明度，不是把不透明物体涂成背景色。所选超边及全部成员保持清楚；选中节点时，该节点最突出，关联节点及结构次之。参考脑不透明度暂时降至最多 6.5%，恢复全局后使用原滑块值。成员标签优先布局，脑区坐标不动。选中的超边另加清晰的细管轮廓。

选择与标签

• 当前开启图层的结构不截断边数。选中脑区或连接后自动标出成员的简短名称，悬停显示完整名称；可开启前侧脑区名称，后侧普通标签不显示。标签只在屏幕上偏移，引线指向真实 ROI 坐标。
• 点击 ROI：显示缩写、源英文全名、半球、相邻普通边与所属超边；其他结构淡化。
• 点击普通边：显示两个端点及带符号连接值；显示值是分析输出的相关矩阵值，Fisher-z 输入已在分析时显式转换。
• 点击超边：按 ID 高亮完整成员列表；三维包络、成员表和热图共享选择。
• 重叠位置提供候选列表；具有相同成员的不同自定义超边保留独立 ID。
• “仅看所选”是用户主动的显示筛选，可随时“恢复全局”；底部显示当前 / 全部数量。
• 原始数值 ID 1 与字符串 ID "1" 在数据和显示选择中保持不同身份。内部视图键编码为 JSON ["number",1] / ["string","1"]，原始 ID 不改写。

三维相机支持旋转、平移、缩放和标准前 / 后 / 左 / 右 / 顶视角。方向以 RAS+ 毫米坐标标记，不根据当前屏幕左侧猜测半球。NiiVue 在底部显示原始分区叠加参考脑，用于切片核查，不负责重新配准。

标准目录及来源

图谱通过 Nilearn 官方下载器取得；Schaefer 下载链接固定 CBIG 的 v0.14.3-Update_Yeo2011_Schaefer2018_labelname 标签。参考脑使用 TemplateFlow 对应空间的 T1w 与 brain mask。安装器检查返回的 ROI 数量与空间，不接受未经核实的上游变化。缓存记录标签、来源、版本及内容哈希。

AAL 图像标签并不连续（例如 Precentral_L 的值是 2001），不能直接作为矩阵行号。116/90 行的矩阵也不能证明其图谱身份。Nilearn AAL 文档

AAL90 缩写及英文扩展采用论文补充材料 Table S9 的已发表字典；小脑分区保留上游标识。Schaefer 使用原图谱提供的网络 / 分区名称与缩写，不虚构传统解剖全名。AAL 字典来源、Schaefer 源版本

自定义图谱

1. 上传 3D 整数分区 .nii / .nii.gz，0 表示背景。概率图、4D fMRI、空分区和非有限值不接受。
2. 上传 CSV / TSV，每个非零标签对应一行：

label_value,roi_id,abbreviation,name,hemisphere,network,color
2001,Precentral_L,PreCG.L,Left Precentral gyrus,L,,
2002,Precentral_R,PreCG.R,Right Precentral gyrus,R,,

前五列必需；network、color 可选。缩写、ID、图像标签值均须唯一；脑区全名不能为空。半球为 L、R、M（中线）、B（双侧）。不能缺少缩写后让程序猜解剖名称。

1. 选择确切兼容参考空间；自定义空间需说明名称 / 版本并提供已经去颅骨且对齐的参考脑。
2. 显式确认已有空间对齐。检查 NIfTI 单位 mm、有限且非奇异 affine、已编码 qform/sform 一致、标签匹配、世界坐标重叠与矩阵顺序。不进行自动配准；空间声明和视觉切片核查仍需可靠的数据来源。
3. 验证后生成真实分区表面。ROI 定位点是离分区质心最近的内部体素，保证在本 ROI 中。显示表面采用轻度平滑的 marching cubes；它是分区和 brain mask 的外形，不是新推断的个体皮层或纤维束。原始分割不变。

每个影像最多 128 MiB（压缩文件）/ 3200 万体素，最多 1000 个非背景分区。矩阵映射按完整有序 ID 列表提供，不按图像标签数值排序。支持一个图谱的明确子集，但必须明确每行对应的 ROI。

保存、导出和重开

“保存”将 ViewConfig 写入结果工作区；地址中的 ?result=... 可直接打开同一结果。原始分析 JSON 保持原样，图谱映射与显示状态独立保存。

• 当前视角 PNG：包含脑、全部当前可见结构、标签与参考空间，实际从三维画布导出。
• 数据与视图 JSON：包含原始数值、图 / 超图、图谱绑定、来源、分析参数、相机和显示设置。
• 成员 CSV：每条超边 ID 与每个成员分别保存，包含 ID 类型；不会只导出普通图展开。
• 连接矩阵 CSV：完整带 ROI 顺序的输出矩阵。
• 恢复视图：打开对应分析结果后，导入其视图 JSON；校验结果内容与图谱版本，再恢复。已保存视图在重新打开结果时自动加载。

原有 Python 报告导出（HTML / PDF / SVG / GraphML / ZIP）仍可使用 hicbrain.export.export_result；这与当前相机 PNG 是不同导出内容。

大图显示

节点数增加时减少球面分段；超过 18000 条普通边或 400 个节点时使用线段降低几何成本，保留全部连接。画面静止时不重复绘制。共线、共面或不足三点的超边回退为骨架，并显示数量。包络不把内部的其他 ROI 当成员。

400 个长名称同时标注会拥挤，完整标签优先于自动删减。可主动关闭全局标签、搜索脑区、旋转 / 缩放或仅看所选。大图提示不等于自动删除结构；软件渲染的测试结果不代表用户 GPU 的帧率。