# 四个完整使用场景与下游消费示例

输入由 `scripts/fixtures.py` 确定性生成，约 5×4×3×2 的合成体数据，包含斜切
qform、带剪切且原点不同的 sform、负 qfac 和缩放。它们不是真实医学影像，
不用于证明临床有效性。`scripts/scenarios.py` 执行流程并用 NiBabel 独立验收。
以下均为本项目自建的预期使用场景和可运行集成，尚无外部机构采用证明。

## 1. 科研/教学的 4D 切片与坐标提取

用户已有授权体数据，希望在 MoonBit 中检查时间帧、取出二维数据并知道体素空间
位置，无需让 Python 参与产品运行。

输入：`input/phantom.nii.gz`，时间帧 1、数据轴 2、第 1 层。
流程：inspect 解码样本及缩放 → slice 取层 → world 显式选择 qform 计算
`[2,1,1]` 的世界坐标。qform 和 sform 分别显示，不要求两者相同。
输出：`01-inspect.json`、`01-slice.json`、`01-world.json`。
验收：与 NiBabel 缩放体素及 qform 乘积一致；形状、单位、非有限值计数明确。
限制：数据轴切片，不做解剖正交重采样或疾病判断。

## 2. 图像与标签的空间网格门控

用户需叠加分割标签，但尺寸相同不代表空间原点/方向相同。

输入：4D phantom、3D 二值 labels，以及 sform 原点沿 x 偏移 5 mm 的负例。
流程：grid 比较空间尺寸、坐标系代码和毫米坐标误差；错位负例退出码 2，拒绝
直接配对；匹配标签通过后提取原图第 0 帧与标签同层。
输出：`02-grid-rejected.json`、`02-grid-compatible.json`、
`02-gated-overlay-data.json`（供消费端绘制的配对数据，不宣称已实现查看器）。
验收：同尺寸错位负例必须失败，匹配正例通过；不自动“修好”不匹配文件。
限制：只证明采样网格一致，不证明受试者相同、解剖配准或标注质量。

## 3. 保持世界位置的 ROI 与轴重排导出

用户要减小分析样例或适配后续工具的轴顺序，希望保留原始值与空间位置。

输入：phantom；起点 `[1,1,1]`，大小 `[3,2,2]`；轴排列 `[2,0,1]`，翻转新轴 0。
流程：裁剪保留全部时间帧 → 分别更新两套原点 → 重排原始样本字节 → 独立写回
qform 四元数和 sform 矩阵 → 新文件重新解码。
输出：`03-roi.nii.gz`、`03-reoriented.nii` 与操作/元数据损失报告。
验收：NiBabel 读回形状、原始值、缩放、字节序、单位、形式代码；比较新旧对应
体素坐标。未知扩展不会静默传播到错误位置。
限制：不做插值、任意旋转、向量分量旋转或非线性配准。

## 4. 静态分割标签驱动的 4D 区域分析与批量导出

预期使用者：MoonBit 数据应用开发者。需求：把一批图像及分类标签转换为可审查的
逐帧区域统计表，并给下游工具提供保留坐标的较小矩形数据，不让运行时依赖 Python。

输入：清单 `[{"id":"sample","image":"image.nii.gz","mask":"labels.nii","label":2}]`；
路径相对清单位置。每份静态标签可以对应 3D 或 4D 图像，必须通过空间网格检查。

流程：检查全部清单 ID → 对每个案例调用 MoonBit `roi` → 计算缩放后标签的
逐帧统计、体积、中心 → `roi-crop` 同时保留原始样本和两套坐标 → 汇总 CSV。
失败案例仅写原因，不进入统计表；不会自动配准、修复错位或静默删除扩展。

输出：成功案例 `.nii.gz` 与 JSON、`time-series.csv`、含每例状态的 `report.json`。
有拒绝案例时进程返回 2；清单无效或目录已存在时返回 1；全成功返回 0。
一次运行允许部分成功，不提供整批事务回滚。空区域不能裁剪，所以该批处理会拒绝该例。

已实现集成：[batch-roi.mjs](../examples/batch-roi.mjs) 只负责编排进程和输出表格，
影像计算在 MoonBit 中。另有 [MoonBit 内部消费流水线](../examples/library/pipeline.mbt)。

验收：`python scripts/roi_acceptance.py work/roi-acceptance` 生成独立 NiBabel 输入并调用
消费程序。匹配案例产生三行均值 116、2116、4116；同尺寸但偏移 5 mm 的案例被拒绝；
输出由 NiBabel 读回检查。附带 12 个固定种子随机标签/统计/直方图属性案例。

限制：只接受静态标签；`nonzero` 是二值选择，不是加权分析；体积不是临床诊断。
纯 Python 工作流通常直接使用 NiBabel 更合适，无须为了本例换语言。

## 复现与产物

README 的运行命令生成全部输入、输出及 `summary.json`。输出目录必须不存在，
防止混入旧结果。CI 的两平台附件含全部合成输入和输出，可以直接下载检查。