ctbodycomp 0.1.1__tar.gz

ctbodycomp-0.1.1/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+*.egg-info/
+build/
+dist/
+.venv*/
+examples/reference_usage/results/
+examples/reference_usage/md_results/
+examples/reference_usage/reference_results/
+examples/reference_usage/data/
+examples/reference_usage/*_cases.csv
+*.nii
+*.nii.gz
+*.nrrd
+*.mha
+*.mhd

ctbodycomp-0.1.1/MANIFEST.in

@@ -0,0 +1,18 @@
+include README.md
+exclude PUBLISHING.md
+include pyproject.toml
+include .gitignore
+recursive-include src/ctbodycomp *.py
+recursive-include tests *.py
+recursive-include examples *.py *.json *.md
+include examples/reference_usage/cases.example.csv
+include examples/reference_usage/cases_without_spine.example.csv
+prune build
+prune dist
+prune .venv*
+prune .pytest_cache
+prune examples/reference_usage/results
+prune examples/reference_usage/md_results
+prune examples/reference_usage/reference_results
+prune examples/reference_usage/data
+global-exclude __pycache__ *.py[cod] *.nii *.nii.gz *.nrrd *.mha *.mhd

ctbodycomp-0.1.1/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: ctbodycomp
+Version: 0.1.1
+Summary: Selectable 2D and 3D CT body composition features with separate normalization
+Keywords: CT,body-composition,medical-imaging,feature-extraction
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.22
+Requires-Dist: nibabel>=5
+Requires-Dist: pandas>=2
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+
+# ctbodycomp
+
+CT体成分2D/3D特征提取与独立校正。支持按类别或单个名称选择基础特征，以及独立的身高、体重、BSA和骨参照校正。
+
+## 安装
+
+在本项目目录运行`python -m pip install .`。开发时使用`python -m pip install -e .`。
+支持Python 3.10及以上，依赖numpy、nibabel、pandas；测试需要pytest。
+
+## 四类基础特征
+
+| 类别 | 代码 | 数量 |
+|---|---|---:|
+| 形态：面积或体积 | morphometry | 11 |
+| 一阶统计：Mean、SD、P10、P50、P90、IQR | firstorder | 66 |
+| 组成与分布：组织比值或占比，百分比 | composition | 12 |
+| 复合：面积或体积×平均HU | composite | 11 |
+| 合计 | | 100 |
+
+旧脚本的8项骨参照比和8项骨参照比×HU不再混入基础输出。
+
+组织代码：SM骨骼肌(1)、SF皮下脂肪(4)、IMF肌间脂肪(2)、VF其余内脏脂肪(3)、PVAT血管周围脂肪(6)、EAT心外膜脂肪(7)、AorticPVAT主动脉周围脂肪(8)、Bone骨(5)、CVF(6/7/8)、VF_total(3/6/7/8)、TF(2/3/4/6/7/8)。基础标签互斥。
+
+## 先提取第一类，再校正
+
+```python
+from ctbodycomp import BodyCompositionExtractor, FeatureNormalizer
+
+extractor = BodyCompositionExtractor(
+    mode="3D",
+    features={"morphometry": ["SM_Volume", "SF_Volume", "Bone_Volume"]},
+)
+raw = extractor.execute(image="ct.nii.gz", mask="bc_mask.nii.gz")
+
+# 只校正指定组织；原始结果与校正结果是两个独立字典。
+normalizer = FeatureNormalizer(
+    mode="3D", methods=["height", "weight", "bsa", "bone"], tissues=["SM", "SF"]
+)
+corrected = normalizer.execute(raw, height_cm=170, weight_kg=65)
+```
+
+校正器根据第一类形态指标计算校正指数；开启`include_composite=True`时，同时读取一阶Mean并计算校正指数×Mean。不读取影像，不对HU本身或组成比值二次校正。可以把提取结果保存后，换一组校正方式再次计算。骨校正需提前提取同一范围的`Bone_Volume`或`Bone_Area`。
+
+| 方法 | 公式 | 2D单位 | 3D单位 |
+|---|---|---|---|
+| height | 原始面积/体积 ÷ 身高(m)² | cm²/m² | cm³/m² |
+| weight | 原始面积/体积 ÷ 体重(kg) | cm²/kg | cm³/kg |
+| bsa | 原始面积/体积 ÷ BSA(m²) | cm²/m² | cm³/m² |
+| bone | 原始面积/体积 ÷ 同范围骨面积/体积 | 无量纲 | 无量纲 |
+
+2D和3D都使用身高²。默认BSA使用Mosteller公式：`sqrt(height_cm * weight_kg / 3600)`，也可通过`bsa_m2`直接提供已知BSA；提供值优先，来源记录在`normalizer.last_diagnostics`。Mosteller公式参考：[原始论文](https://doi.org/10.1056/NEJM198710223171717)。
+
+身高、体重、BSA需为有限正数；只选择骨校正时不需要身高体重。缺少所选方法需要的参数会抛出明确错误。骨量为0时骨校正输出NaN。CSV校正失败时保留原始特征及失败原因。
+
+若提取全部11个形态特征且启用全部校正，height、weight、bsa各11项，bone对10个非骨组织输出，共43项。与100项基础特征分开存储。骨校正包括CVF和TF两个聚合组织，不输出恒为1的Bone/Bone。实际输出量由所选组织、特征和校正方式决定。
+
+## 可选：校正指数 × 平均HU
+
+从0.1.1开始，校正指数与校正后的复合特征统一由`FeatureNormalizer`管理。使用`include_composite=True`，同一次校正返回“指数”和“指数×同组织平均HU”，每一对相邻排列。两者均属于校正模块，与四类基础特征分开。默认不开启校正复合项。
+
+```python
+from ctbodycomp import BodyCompositionExtractor, FeatureNormalizer
+
+extractor = BodyCompositionExtractor(
+    mode="3D",
+    features={
+        "morphometry": ["SM_Volume", "Bone_Volume"],
+        "firstorder": ["SM_Mean"],
+    },
+)
+raw = extractor.execute("ct.nii.gz", "bc_mask.nii.gz")
+normalizer = FeatureNormalizer(
+    mode="3D", methods=["height", "bone"], tissues=["SM"],
+    include_composite=True,
+)
+corrected = normalizer.execute(raw, height_cm=170)
+# normalization_height_SM_Volume
+# normalized_composite_height_SM_VolumeMean
+# normalization_bone_SM_Volume
+# normalized_composite_bone_SM_VolumeMean
+units = normalizer.get_units(raw)
+```
+
+2D将模式改为`2D`，将第一类特征的`Volume`改为`Area`，输出为`normalized_composite_height_SM_AreaMean`等。
+
+| 方法 | 公式，μ为同组织平均HU | 2D单位 | 3D单位 | 全部组织数量 |
+|---|---|---|---|---:|
+| height | (面积/体积 ÷ 身高(m)²) × μ | cm²·HU/m² | cm³·HU/m² | 11 |
+| weight | (面积/体积 ÷ 体重(kg)) × μ | cm²·HU/kg | cm³·HU/kg | 11 |
+| bsa | (面积/体积 ÷ BSA(m²)) × μ | cm²·HU/m² | cm³·HU/m² | 11 |
+| bone | (面积/体积 ÷ 同范围骨面积/体积) × μ | HU | HU | 10 |
+
+共43项可选校正复合特征，不输出Bone/Bone×HU。每种模式最多有100项基础特征＋43项校正指数＋43项校正复合特征＝186项。2D和3D是两种模式，不合并计数。负平均HU保留符号；指数或均值为NaN/无穷时结果为NaN，不解释为实际组织质量。
+
+通过`methods`选择校正方式，通过`tissues`选择组织；`tissues=None`从输入已有的形态指标中选择组织。开启复合项需要同时提取目标组织的Mean。可用`get_normalized_composite_catalog("3D")`查询完整复合名称、单位、指数键和均值键。
+
+对于已经保存的校正指数字典，仍支持`NormalizedCompositeCalculator(mode, methods, tissues).execute(indices, raw)`单独补算复合项；两个字典需来自同一病例、同一范围。
+
+**2D两层的计算顺序**：先将两层面积与两层平均HU分别等权平均，面积平均值进行校正，再乘HU平均值。因此结果是“校正后的平均面积指数 × 平均HU”，与基础复合类的“逐层面积×HU后平均”定义不同。例如两层面积0.06、0.18 cm²，均值10、30 HU，身高1 m：校正复合为0.12×20＝2.4 cm²·HU/m²，而基础复合为(0.06×10＋0.18×30)/2＝3 cm²·HU。
+
+## 选择类别或单项
+
+```python
+from ctbodycomp import BodyCompositionExtractor, get_feature_catalog
+
+extractor = BodyCompositionExtractor(mode="2D", spine_label=7)
+extractor.disableAllFeatures()
+extractor.enableFeaturesByName(
+    morphometry=["SM_Area", "Bone_Area"],
+    firstorder=["SM_Mean", "SM_P50"],
+    composition=["MFF"],
+)
+raw = extractor.execute("ct.nii.gz", "bc_mask.nii.gz", spine_mask="spine.nii.gz")
+
+# 按整个类别启用：
+extractor.enableFeatureClassByName("firstorder")
+# 查询当前模式下全部可用名称、英文输出键和单位：
+catalog = get_feature_catalog("2D")
+```
+
+构造参数`features=None`默认启用全部四类；`features={}`不启用任何特征。映射中未列出的类别不提取，类别中的`[]`或`None`表示该类全部。`enableFeaturesByName`替换指定类别的选择，其他已启用类别保持不变，因此要只选择几项时先调用`disableAllFeatures()`。支持全部启用`enableAllFeatures()`和单类别关闭`enableFeatureClassByName("firstorder", False)`。
+
+只输出选择的特征，内部依赖按需计算。例如只选Mean不计算分位数，只选形态不计算HU统计；只选一个组成比值时也不输出其内部依赖的组织面积/体积。
+
+## 输入与选层
+
+- 必需：CT与BC mask。接受文件路径或nibabel图像对象，图像需3D且空间匹配，尺寸以mm解释；不重采样。
+- 可选：Spine mask。不提供时3D计算整幅CT，2D在整幅CT全部层中选中间层。
+- 2D有Spine mask时需`spine_label`，例如7或8。仅对该标签实际出现的切片排序，奇数取中间一层，偶数取中间两层。
+- 3D有Spine mask时默认范围`spine_range=(7, 18)`，可配置，取首末层之间的完整范围。新库依据affine识别上下方向，支持数组轴置换。
+- 每个选中切片的组织ROI来自完整BC mask平面，Spine mask仅定位。斜位影像保持原切片平面。
+- 2D两层基础特征先逐层计算再等权平均。独立校正使用这个平均后的形态值；骨校正因此是“平均组织面积/平均骨面积”，不同于旧脚本的“两层骨比值平均”。
+- SD使用ddof=0；分位数为线性插值；非有限CT值不进入HU统计；空组织的面积/体积为0，HU统计为NaN；任一层某基础指标NaN，则两层平均也为NaN。
+
+诊断信息在`extractor.last_diagnostics`，与纯数值特征分开。无Spine mask请传`None`；填写了错误文件路径不会自动退回全图计算。
+
+## CSV分两步运行
+
+新库的CSV使用有意义的列名（区分大小写），不同于旧脚本按列位置读取：
+
+```csv
+ID,Image,Mask,SpineMask,Height_cm,Weight_kg
+001,ct.nii.gz,bc_mask.nii.gz,,170,65
+```
+
+必需`Image`、`Mask`，其他列可选；`SpineMask`可省略或留空。相对路径相对于输入CSV目录。`Height_cm`、`Weight_kg`、可选`BSA_m2`由校正步骤读取，逐病例值优先于命令行公共值。
+
+```bash
+# 查询特征名
+ctbodycomp features --mode 3D
+
+# 仅提取肌肉、皮下脂肪和骨的体积
+ctbodycomp extract cases.csv raw.csv --mode 3D --config examples/morphometry_3d.json
+
+# 对提取结果进行校正，原始列也保留在输出中
+ctbodycomp normalize raw.csv corrected.csv --mode 3D --methods height weight bsa bone --tissues SM SF
+
+# 2D单标签、部分特征
+ctbodycomp extract cases.csv raw_2d.csv --mode 2D --label 7 --config examples/selected_2d.json
+ctbodycomp normalize raw_2d.csv corrected_2d.csv --mode 2D --methods bone --tissues SM
+```
+
+需要校正复合时，提取配置必须包含目标组织的`firstorder_*_Mean`。在同一校正步骤增加`--include-composite`即可：
+
+```bash
+# 示例配置包含肌肉、骨体积和肌肉Mean
+ctbodycomp extract cases.csv raw.csv --mode 3D --config examples/normalized_composite_3d.json
+ctbodycomp normalize raw.csv corrected.csv --mode 3D --methods height weight bsa bone --tissues SM --include-composite
+
+# 查询校正复合特征及所需输入
+ctbodycomp features --mode 3D --normalized-composite
+```
+
+校正CSV保留基础特征，按“校正指数、对应复合项”的顺序追加列，使用统一的`normalization_status`、`normalization_error`记录结果。缺少所需Mean列时记录失败；Mean数值为空时对应复合项为NaN。影像不存在也不影响已成功提取结果的后续计算。
+
+如需对已有校正CSV补算复合项，也保留单独命令：`ctbodycomp normalized-composite corrected.csv products.csv --mode 3D --methods height bone --tissues SM`。
+
+配置JSON直接写“类别→特征名称列表”。命令返回0表示成功，1表示输出中存在失败病例，参数错误返回2。输出目录需存在，输出不能覆盖输入文件；重复输出路径会替换先前结果。
+
+## 完整使用示例
+
+源码包中的 `examples/reference_usage/README.md` 提供五种完整提取示例：2D T12、2D无脊柱、3D T12、3D T1–T12、3D无脊柱，以及独立校正示例。每种情况同时提供可运行的Python脚本和Markdown教程，不依赖额外本地辅助脚本。
+
+输入使用 `cases.example.csv` 和 `cases_without_spine.example.csv` 通用模板。模板不包含实际病例数据，使用前替换为自己的影像路径。示例计算结果写入示例目录下的 `results/`，不会纳入发布包。
+
+## 测试和构建
+
+在项目根目录运行：
+
+```bash
+python -m pip install -e '.[test]'
+python -m pytest -q -p no:cacheprovider
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/ctbodycomp-0.1.1-py3-none-any.whl dist/ctbodycomp-0.1.1.tar.gz
+```
+
+wheel只包含库模块和安装元数据；源码包另外包含测试与使用教程。虚拟环境、缓存、本地影像、实际病例表和计算结果不纳入发布文件。`PUBLISHING.md` 仅保留在开发目录供维护者参考，不随发布包分发。
+
+作者、邮箱和许可证字段当前未设置，可在后续版本补充。本项目目前没有声明MIT或Apache-2.0授权。

ctbodycomp-0.1.1/README.md

@@ -0,0 +1,200 @@
+# ctbodycomp
+
+CT体成分2D/3D特征提取与独立校正。支持按类别或单个名称选择基础特征，以及独立的身高、体重、BSA和骨参照校正。
+
+## 安装
+
+在本项目目录运行`python -m pip install .`。开发时使用`python -m pip install -e .`。
+支持Python 3.10及以上，依赖numpy、nibabel、pandas；测试需要pytest。
+
+## 四类基础特征
+
+| 类别 | 代码 | 数量 |
+|---|---|---:|
+| 形态：面积或体积 | morphometry | 11 |
+| 一阶统计：Mean、SD、P10、P50、P90、IQR | firstorder | 66 |
+| 组成与分布：组织比值或占比，百分比 | composition | 12 |
+| 复合：面积或体积×平均HU | composite | 11 |
+| 合计 | | 100 |
+
+旧脚本的8项骨参照比和8项骨参照比×HU不再混入基础输出。
+
+组织代码：SM骨骼肌(1)、SF皮下脂肪(4)、IMF肌间脂肪(2)、VF其余内脏脂肪(3)、PVAT血管周围脂肪(6)、EAT心外膜脂肪(7)、AorticPVAT主动脉周围脂肪(8)、Bone骨(5)、CVF(6/7/8)、VF_total(3/6/7/8)、TF(2/3/4/6/7/8)。基础标签互斥。
+
+## 先提取第一类，再校正
+
+```python
+from ctbodycomp import BodyCompositionExtractor, FeatureNormalizer
+
+extractor = BodyCompositionExtractor(
+    mode="3D",
+    features={"morphometry": ["SM_Volume", "SF_Volume", "Bone_Volume"]},
+)
+raw = extractor.execute(image="ct.nii.gz", mask="bc_mask.nii.gz")
+
+# 只校正指定组织；原始结果与校正结果是两个独立字典。
+normalizer = FeatureNormalizer(
+    mode="3D", methods=["height", "weight", "bsa", "bone"], tissues=["SM", "SF"]
+)
+corrected = normalizer.execute(raw, height_cm=170, weight_kg=65)
+```
+
+校正器根据第一类形态指标计算校正指数；开启`include_composite=True`时，同时读取一阶Mean并计算校正指数×Mean。不读取影像，不对HU本身或组成比值二次校正。可以把提取结果保存后，换一组校正方式再次计算。骨校正需提前提取同一范围的`Bone_Volume`或`Bone_Area`。
+
+| 方法 | 公式 | 2D单位 | 3D单位 |
+|---|---|---|---|
+| height | 原始面积/体积 ÷ 身高(m)² | cm²/m² | cm³/m² |
+| weight | 原始面积/体积 ÷ 体重(kg) | cm²/kg | cm³/kg |
+| bsa | 原始面积/体积 ÷ BSA(m²) | cm²/m² | cm³/m² |
+| bone | 原始面积/体积 ÷ 同范围骨面积/体积 | 无量纲 | 无量纲 |
+
+2D和3D都使用身高²。默认BSA使用Mosteller公式：`sqrt(height_cm * weight_kg / 3600)`，也可通过`bsa_m2`直接提供已知BSA；提供值优先，来源记录在`normalizer.last_diagnostics`。Mosteller公式参考：[原始论文](https://doi.org/10.1056/NEJM198710223171717)。
+
+身高、体重、BSA需为有限正数；只选择骨校正时不需要身高体重。缺少所选方法需要的参数会抛出明确错误。骨量为0时骨校正输出NaN。CSV校正失败时保留原始特征及失败原因。
+
+若提取全部11个形态特征且启用全部校正，height、weight、bsa各11项，bone对10个非骨组织输出，共43项。与100项基础特征分开存储。骨校正包括CVF和TF两个聚合组织，不输出恒为1的Bone/Bone。实际输出量由所选组织、特征和校正方式决定。
+
+## 可选：校正指数 × 平均HU
+
+从0.1.1开始，校正指数与校正后的复合特征统一由`FeatureNormalizer`管理。使用`include_composite=True`，同一次校正返回“指数”和“指数×同组织平均HU”，每一对相邻排列。两者均属于校正模块，与四类基础特征分开。默认不开启校正复合项。
+
+```python
+from ctbodycomp import BodyCompositionExtractor, FeatureNormalizer
+
+extractor = BodyCompositionExtractor(
+    mode="3D",
+    features={
+        "morphometry": ["SM_Volume", "Bone_Volume"],
+        "firstorder": ["SM_Mean"],
+    },
+)
+raw = extractor.execute("ct.nii.gz", "bc_mask.nii.gz")
+normalizer = FeatureNormalizer(
+    mode="3D", methods=["height", "bone"], tissues=["SM"],
+    include_composite=True,
+)
+corrected = normalizer.execute(raw, height_cm=170)
+# normalization_height_SM_Volume
+# normalized_composite_height_SM_VolumeMean
+# normalization_bone_SM_Volume
+# normalized_composite_bone_SM_VolumeMean
+units = normalizer.get_units(raw)
+```
+
+2D将模式改为`2D`，将第一类特征的`Volume`改为`Area`，输出为`normalized_composite_height_SM_AreaMean`等。
+
+| 方法 | 公式，μ为同组织平均HU | 2D单位 | 3D单位 | 全部组织数量 |
+|---|---|---|---|---:|
+| height | (面积/体积 ÷ 身高(m)²) × μ | cm²·HU/m² | cm³·HU/m² | 11 |
+| weight | (面积/体积 ÷ 体重(kg)) × μ | cm²·HU/kg | cm³·HU/kg | 11 |
+| bsa | (面积/体积 ÷ BSA(m²)) × μ | cm²·HU/m² | cm³·HU/m² | 11 |
+| bone | (面积/体积 ÷ 同范围骨面积/体积) × μ | HU | HU | 10 |
+
+共43项可选校正复合特征，不输出Bone/Bone×HU。每种模式最多有100项基础特征＋43项校正指数＋43项校正复合特征＝186项。2D和3D是两种模式，不合并计数。负平均HU保留符号；指数或均值为NaN/无穷时结果为NaN，不解释为实际组织质量。
+
+通过`methods`选择校正方式，通过`tissues`选择组织；`tissues=None`从输入已有的形态指标中选择组织。开启复合项需要同时提取目标组织的Mean。可用`get_normalized_composite_catalog("3D")`查询完整复合名称、单位、指数键和均值键。
+
+对于已经保存的校正指数字典，仍支持`NormalizedCompositeCalculator(mode, methods, tissues).execute(indices, raw)`单独补算复合项；两个字典需来自同一病例、同一范围。
+
+**2D两层的计算顺序**：先将两层面积与两层平均HU分别等权平均，面积平均值进行校正，再乘HU平均值。因此结果是“校正后的平均面积指数 × 平均HU”，与基础复合类的“逐层面积×HU后平均”定义不同。例如两层面积0.06、0.18 cm²，均值10、30 HU，身高1 m：校正复合为0.12×20＝2.4 cm²·HU/m²，而基础复合为(0.06×10＋0.18×30)/2＝3 cm²·HU。
+
+## 选择类别或单项
+
+```python
+from ctbodycomp import BodyCompositionExtractor, get_feature_catalog
+
+extractor = BodyCompositionExtractor(mode="2D", spine_label=7)
+extractor.disableAllFeatures()
+extractor.enableFeaturesByName(
+    morphometry=["SM_Area", "Bone_Area"],
+    firstorder=["SM_Mean", "SM_P50"],
+    composition=["MFF"],
+)
+raw = extractor.execute("ct.nii.gz", "bc_mask.nii.gz", spine_mask="spine.nii.gz")
+
+# 按整个类别启用：
+extractor.enableFeatureClassByName("firstorder")
+# 查询当前模式下全部可用名称、英文输出键和单位：
+catalog = get_feature_catalog("2D")
+```
+
+构造参数`features=None`默认启用全部四类；`features={}`不启用任何特征。映射中未列出的类别不提取，类别中的`[]`或`None`表示该类全部。`enableFeaturesByName`替换指定类别的选择，其他已启用类别保持不变，因此要只选择几项时先调用`disableAllFeatures()`。支持全部启用`enableAllFeatures()`和单类别关闭`enableFeatureClassByName("firstorder", False)`。
+
+只输出选择的特征，内部依赖按需计算。例如只选Mean不计算分位数，只选形态不计算HU统计；只选一个组成比值时也不输出其内部依赖的组织面积/体积。
+
+## 输入与选层
+
+- 必需：CT与BC mask。接受文件路径或nibabel图像对象，图像需3D且空间匹配，尺寸以mm解释；不重采样。
+- 可选：Spine mask。不提供时3D计算整幅CT，2D在整幅CT全部层中选中间层。
+- 2D有Spine mask时需`spine_label`，例如7或8。仅对该标签实际出现的切片排序，奇数取中间一层，偶数取中间两层。
+- 3D有Spine mask时默认范围`spine_range=(7, 18)`，可配置，取首末层之间的完整范围。新库依据affine识别上下方向，支持数组轴置换。
+- 每个选中切片的组织ROI来自完整BC mask平面，Spine mask仅定位。斜位影像保持原切片平面。
+- 2D两层基础特征先逐层计算再等权平均。独立校正使用这个平均后的形态值；骨校正因此是“平均组织面积/平均骨面积”，不同于旧脚本的“两层骨比值平均”。
+- SD使用ddof=0；分位数为线性插值；非有限CT值不进入HU统计；空组织的面积/体积为0，HU统计为NaN；任一层某基础指标NaN，则两层平均也为NaN。
+
+诊断信息在`extractor.last_diagnostics`，与纯数值特征分开。无Spine mask请传`None`；填写了错误文件路径不会自动退回全图计算。
+
+## CSV分两步运行
+
+新库的CSV使用有意义的列名（区分大小写），不同于旧脚本按列位置读取：
+
+```csv
+ID,Image,Mask,SpineMask,Height_cm,Weight_kg
+001,ct.nii.gz,bc_mask.nii.gz,,170,65
+```
+
+必需`Image`、`Mask`，其他列可选；`SpineMask`可省略或留空。相对路径相对于输入CSV目录。`Height_cm`、`Weight_kg`、可选`BSA_m2`由校正步骤读取，逐病例值优先于命令行公共值。
+
+```bash
+# 查询特征名
+ctbodycomp features --mode 3D
+
+# 仅提取肌肉、皮下脂肪和骨的体积
+ctbodycomp extract cases.csv raw.csv --mode 3D --config examples/morphometry_3d.json
+
+# 对提取结果进行校正，原始列也保留在输出中
+ctbodycomp normalize raw.csv corrected.csv --mode 3D --methods height weight bsa bone --tissues SM SF
+
+# 2D单标签、部分特征
+ctbodycomp extract cases.csv raw_2d.csv --mode 2D --label 7 --config examples/selected_2d.json
+ctbodycomp normalize raw_2d.csv corrected_2d.csv --mode 2D --methods bone --tissues SM
+```
+
+需要校正复合时，提取配置必须包含目标组织的`firstorder_*_Mean`。在同一校正步骤增加`--include-composite`即可：
+
+```bash
+# 示例配置包含肌肉、骨体积和肌肉Mean
+ctbodycomp extract cases.csv raw.csv --mode 3D --config examples/normalized_composite_3d.json
+ctbodycomp normalize raw.csv corrected.csv --mode 3D --methods height weight bsa bone --tissues SM --include-composite
+
+# 查询校正复合特征及所需输入
+ctbodycomp features --mode 3D --normalized-composite
+```
+
+校正CSV保留基础特征，按“校正指数、对应复合项”的顺序追加列，使用统一的`normalization_status`、`normalization_error`记录结果。缺少所需Mean列时记录失败；Mean数值为空时对应复合项为NaN。影像不存在也不影响已成功提取结果的后续计算。
+
+如需对已有校正CSV补算复合项，也保留单独命令：`ctbodycomp normalized-composite corrected.csv products.csv --mode 3D --methods height bone --tissues SM`。
+
+配置JSON直接写“类别→特征名称列表”。命令返回0表示成功，1表示输出中存在失败病例，参数错误返回2。输出目录需存在，输出不能覆盖输入文件；重复输出路径会替换先前结果。
+
+## 完整使用示例
+
+源码包中的 `examples/reference_usage/README.md` 提供五种完整提取示例：2D T12、2D无脊柱、3D T12、3D T1–T12、3D无脊柱，以及独立校正示例。每种情况同时提供可运行的Python脚本和Markdown教程，不依赖额外本地辅助脚本。
+
+输入使用 `cases.example.csv` 和 `cases_without_spine.example.csv` 通用模板。模板不包含实际病例数据，使用前替换为自己的影像路径。示例计算结果写入示例目录下的 `results/`，不会纳入发布包。
+
+## 测试和构建
+
+在项目根目录运行：
+
+```bash
+python -m pip install -e '.[test]'
+python -m pytest -q -p no:cacheprovider
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/ctbodycomp-0.1.1-py3-none-any.whl dist/ctbodycomp-0.1.1.tar.gz
+```
+
+wheel只包含库模块和安装元数据；源码包另外包含测试与使用教程。虚拟环境、缓存、本地影像、实际病例表和计算结果不纳入发布文件。`PUBLISHING.md` 仅保留在开发目录供维护者参考，不随发布包分发。
+
+作者、邮箱和许可证字段当前未设置，可在后续版本补充。本项目目前没有声明MIT或Apache-2.0授权。

ctbodycomp-0.1.1/examples/morphometry_3d.json

@@ -0,0 +1,3 @@
+{
+  "morphometry": ["SM_Volume", "SF_Volume", "Bone_Volume"]
+}

ctbodycomp-0.1.1/examples/normalized_composite_3d.json

@@ -0,0 +1,4 @@
+{
+  "morphometry": ["SM_Volume", "Bone_Volume"],
+  "firstorder": ["SM_Mean"]
+}

ctbodycomp-0.1.1/examples/reference_usage/01_2d_t12.md

@@ -0,0 +1,107 @@
+# 2D T12 单标签特征提取
+
+脊柱 mask 的标签 7 对应 T12。候选切片是实际含标签 7 的切片；奇数取中间一层，偶数取中间两层，分别计算各项特征后取算术平均。BC mask 决定各组织的区域。
+
+下面是完整示例，直接复制到自己的 Python 脚本或 Notebook 中运行即可。代码独立可运行，只需要安装 `ctbodycomp`。默认提取全部 **100 项基础特征**，本步骤不进行校正。
+
+## 输入和输出
+
+- 输入 CSV：`cases.example.csv`。
+- 必需列：`ID`、`Image`、`Mask`、`SpineMask`。
+- 输出 CSV：`results/01_2d_t12/raw_features.csv`。
+- CT、BC、Spine 的形状和 affine 必须一致。路径可以是绝对路径，也可以相对于输入 CSV 所在目录。
+
+## 完整 Python 代码
+
+对应的 Python 文件已同步为完整代码，可以直接运行：
+
+```bash
+python 01_2d_t12.py
+```
+
+脚本默认读取同目录的通用 CSV 模板。先填写模板中的实际影像路径，再运行；也可以修改代码中的 input_csv。在 Notebook 中运行时，先将工作目录切换到模板所在目录。
+
+```python
+import json
+from pathlib import Path
+
+import pandas as pd
+from ctbodycomp import BodyCompositionExtractor
+
+# 1. 输入路径和输出路径：需要换数据时修改这里。
+example_dir = Path(__file__).resolve().parent if "__file__" in globals() else Path.cwd()
+input_csv = example_dir / "cases.example.csv"
+output_csv = input_csv.parent / "results" / "01_2d_t12" / "raw_features.csv"
+
+# 2. 读取 CSV 路径表。ID 按字符串读取，可保留开头的 0。
+cases = pd.read_csv(
+    input_csv, dtype=str, keep_default_na=False, encoding="utf-8-sig"
+)
+required_columns = {"ID", "Image", "Mask", "SpineMask"}
+if not required_columns.issubset(cases.columns):
+    raise ValueError("本例需要 ID、Image、Mask、SpineMask 四列")
+path_columns = ("Image", "Mask", "SpineMask")
+if cases.empty:
+    raise ValueError("输入 CSV 没有病例")
+
+# 把相对路径转成绝对路径，方便保存后继续处理。
+for column in path_columns:
+    cases[column] = cases[column].map(
+        lambda value: str((input_csv.parent / Path(value.strip()).expanduser()).resolve())
+        if value.strip() else ""
+    )
+
+# 3. 2D 单标签：T12=7。
+# 默认全部 100 项；可参照 README.md 的特征选择部分修改。
+extractor = BodyCompositionExtractor(mode="2D", spine_label=7)
+feature_names = extractor.get_feature_names()
+
+# 4. 逐个病例读取 CT 和 mask，提取基础特征。
+rows = []
+for case in cases.to_dict(orient="records"):
+    row = {
+        **case,
+        **dict.fromkeys(feature_names, float("nan")),
+        "diagnostics_scope": "",
+        "diagnostics_slices": "",
+        "extraction_status": "failed",
+        "extraction_error": "",
+    }
+    try:
+        if not case["Image"] or not case["Mask"]:
+            raise ValueError("Image 和 Mask 不能为空")
+        if not case["SpineMask"]:
+            raise ValueError("本例必须提供 SpineMask；无脊柱请使用 without_spine 教程")
+        # execute 才真正根据路径读取影像文件。
+        features = extractor.execute(
+            image=case["Image"],
+            mask=case["Mask"],
+            spine_mask=case["SpineMask"],
+        )
+        row.update(features)
+        row["diagnostics_scope"] = extractor.last_diagnostics["scope"]
+        row["diagnostics_slices"] = json.dumps(
+            extractor.last_diagnostics["selected_slices"]
+        )
+        row["extraction_status"] = "success"
+    except Exception as error:
+        # 单个病例失败会记入结果，继续处理其余病例。
+        row["extraction_error"] = str(error)
+    rows.append(row)
+
+# 5. 保存结果。原路径列、ID 和可能存在的身高体重列都会保留。
+output_csv.parent.mkdir(parents=True, exist_ok=True)
+results = pd.DataFrame(rows)
+results.to_csv(output_csv, index=False, encoding="utf-8-sig")
+print("基础特征已保存：", output_csv)
+print(results[["ID", "extraction_status", "extraction_error"]].to_string(index=False))
+```
+
+`extraction_status=success` 表示流程完成。某组织没有体素、均值不可计算或比值分母为零时，个别特征仍可能为 0 或 NaN。`diagnostics_slices` 是实际使用的切片索引，从 0 开始。
+
+## 提取后校正
+
+本例的校正模式应为 `2D`。用上面生成的 `raw_features.csv` 作为输入，参考 [提取后独立校正](06_提取后校正.md)，不需要重新提取影像特征。
+
+[返回教程目录](README.md)
+

ctbodycomp-0.1.1/examples/reference_usage/01_2d_t12.py

@@ -0,0 +1,75 @@
+"""2D T12 单标签特征提取：直接读取 CSV、执行计算并保存结果。"""
+
+import json
+from pathlib import Path
+
+import pandas as pd
+from ctbodycomp import BodyCompositionExtractor
+
+# 1. 输入路径和输出路径：需要换数据时修改这里。
+example_dir = Path(__file__).resolve().parent if "__file__" in globals() else Path.cwd()
+input_csv = example_dir / "cases.example.csv"
+output_csv = input_csv.parent / "results" / "01_2d_t12" / "raw_features.csv"
+
+# 2. 读取 CSV 路径表。ID 按字符串读取，可保留开头的 0。
+cases = pd.read_csv(
+    input_csv, dtype=str, keep_default_na=False, encoding="utf-8-sig"
+)
+required_columns = {"ID", "Image", "Mask", "SpineMask"}
+if not required_columns.issubset(cases.columns):
+    raise ValueError("本例需要 ID、Image、Mask、SpineMask 四列")
+path_columns = ("Image", "Mask", "SpineMask")
+if cases.empty:
+    raise ValueError("输入 CSV 没有病例")
+
+# 把相对路径转成绝对路径，方便保存后继续处理。
+for column in path_columns:
+    cases[column] = cases[column].map(
+        lambda value: str((input_csv.parent / Path(value.strip()).expanduser()).resolve())
+        if value.strip() else ""
+    )
+
+# 3. 2D 单标签：T12=7。
+# 默认全部 100 项；可参照 README.md 的特征选择部分修改。
+extractor = BodyCompositionExtractor(mode="2D", spine_label=7)
+feature_names = extractor.get_feature_names()
+
+# 4. 逐个病例读取 CT 和 mask，提取基础特征。
+rows = []
+for case in cases.to_dict(orient="records"):
+    row = {
+        **case,
+        **dict.fromkeys(feature_names, float("nan")),
+        "diagnostics_scope": "",
+        "diagnostics_slices": "",
+        "extraction_status": "failed",
+        "extraction_error": "",
+    }
+    try:
+        if not case["Image"] or not case["Mask"]:
+            raise ValueError("Image 和 Mask 不能为空")
+        if not case["SpineMask"]:
+            raise ValueError("本例必须提供 SpineMask；无脊柱请使用 without_spine 教程")
+        # execute 才真正根据路径读取影像文件。
+        features = extractor.execute(
+            image=case["Image"],
+            mask=case["Mask"],
+            spine_mask=case["SpineMask"],
+        )
+        row.update(features)
+        row["diagnostics_scope"] = extractor.last_diagnostics["scope"]
+        row["diagnostics_slices"] = json.dumps(
+            extractor.last_diagnostics["selected_slices"]
+        )
+        row["extraction_status"] = "success"
+    except Exception as error:
+        # 单个病例失败会记入结果，继续处理其余病例。
+        row["extraction_error"] = str(error)
+    rows.append(row)
+
+# 5. 保存结果。原路径列、ID 和可能存在的身高体重列都会保留。
+output_csv.parent.mkdir(parents=True, exist_ok=True)
+results = pd.DataFrame(rows)
+results.to_csv(output_csv, index=False, encoding="utf-8-sig")
+print("基础特征已保存：", output_csv)
+print(results[["ID", "extraction_status", "extraction_error"]].to_string(index=False))