BGsub Skill — 2D Image & 1D Curve Background Subtraction / 2D图像与1D曲线背景扣除#

BGsub is a self-contained CLI toolkit for background subtraction of X-ray diffraction data. It covers 2D detector image processing (TIFF/EDF/H5) and 1D curve processing (XY/DAT/CSV), with SSRF ionchamber transmission auto-correction. No external BGsub package installation is required — all dependencies are bundled in lib/, though standard scientific Python dependencies are still needed. BGsub 是一套 自包含 的 X 射线衍射数据背景扣除 CLI 工具集，覆盖 2D探测器图像处理(TIFF/EDF/H5)和 1D曲线处理(XY/DAT/CSV)，集成 SSRF 电离室透射率自动校正。 无需安装外部 BGsub 包——所有依赖已打包在 lib/ 中，但仍需标准科学计算 Python 依赖。

Latest 1D highlights / 最新 1D 特性：

• T-背景扣除 为首要模式 / T-background subtraction is the primary mode
• 支持多列文本结构 single / xyxy / xyyy
• 支持 逐一文件 与 合并单文件 导出
• 合并导出支持文本/CSV/HDF5；多列模式下暂不支持电离室自动 T

---

Core Capabilities / 核心能力#

#Capability / 能力Domain / 领域Script / 脚本1Reference-based 2D background subtraction / 有参考2D背景扣除2D Imagebg_subtract.py2Batch 2D processing with ionchamber / 批量2D处理+电离室2D Imagebg_batch.py3Ionchamber stats + sample/background transmission / 电离室统计与样品/背景透过率Sharedionchamber.py41D curve background estimation & T-corrected reference subtraction / 1D曲线算法背景估计与T修正参考扣除1D Curvecurve_process_1d.py5Batch 1D curve processing with unified / per-file / ionchamber T / 批量1D曲线处理（统一T/分别设置/电离室）1D Curvecurve_batch_1d.py6Format conversion (TIFF/EDF/H5) / 格式转换2D Imageformat_convert.py7silx image comparison popup / silx图像对比弹窗2D Imagecompare_images.py

---

Processing Flow / 处理流程#

2D Image Background Subtraction / 2D图像背景扣除#

text

Sample image + Ionchamber file / 样品图像 + 电离室文件
         ↓
    Calculate T = I_sample / I_background / 计算透射率
         ↓
result = sample / T - background
         ↓
    Save result image / 保存结果图像

1D Curve Background Estimation / 1D曲线背景估计#

text

Load 1D curve file (XY/DAT/CSV) / 加载1D曲线文件
         ↓
Choose column layout: single / xyxy / xyyy / 选择列结构
         ↓
    Estimate background using algorithm / 使用算法估计背景
    (Morphological / Polynomial / Rolling Ball)
         ↓
    Subtract: result = curve - background / 扣除背景
         ↓
    Save raw, background, subtracted / 保存原始、背景、扣除结果

1D Reference Background Subtraction / 1D参考背景扣除#

text

Sample curve + background curve / 样品曲线 + 背景曲线
         ↓
Transmission source / 透过率来源
  - manual unified / 手动统一值
  - manual per-file / 手动分别设置
  - ionchamber auto / 电离室自动计算
         ↓
result = sample / (T/100) - background
         ↓
Save raw, background, subtracted / 保存原始、背景、扣除结果

---

Quick Usage / 快速使用#

Run Scripts Directly / 直接运行脚本#

Scripts are self-contained — they import from the bundled lib/ package instead of requiring the BGsub package to be installed. Run from the project root directory. Only standard scientific dependencies are needed: numpy, scipy, fabio, h5py, pandas. 脚本为 自包含可执行文件——从内含的 lib/ 包导入，无需安装 BGsub 包。在项目根目录下运行。仅需标准科学计算依赖： numpy、 scipy、 fabio、 h5py、 pandas。

bash

# 2D: Single file background subtraction / 单文件背景扣除
python BGsub_skills/scripts/bg_subtract.py sample.tif background.tif --ion-dir ./ionchamber -o result.tif

# 2D: Batch processing / 批量处理
python BGsub_skills/scripts/bg_batch.py ./data background.tif --ion-dir ./ionchamber -o ./results

# 2D/1D: Ionchamber analysis / 电离室数据分析
python BGsub_skills/scripts/ionchamber.py sample.Ionchamber

# 2D/1D: Sample-vs-background transmission / 样品-背景透过率
python BGsub_skills/scripts/ionchamber.py sample.Ionchamber --background-ion background.Ionchamber

# 2D: Format conversion / 格式转换
python BGsub_skills/scripts/format_convert.py input.tif -o output.edf --format edf

# 2D: Image comparison (silx popup) / 图像对比(silx弹窗)
python BGsub_skills/scripts/compare_images.py image1.tif image2.tif

# 1D: Single curve processing / 单曲线处理
python BGsub_skills/scripts/curve_process_1d.py curve.xy --method morph --radius 50 -o result.xy

# 1D: Multi-column XYYY merged export / 多列 XYYY 合并导出
python BGsub_skills/scripts/curve_process_1d.py curve.txt --parse-mode xyyy --output-mode merged -o merged_curves.h5

# 1D: Reference background + manual T / 参考背景 + 手动T
python BGsub_skills/scripts/curve_process_1d.py curve.xy --background bg.xy --transmission 87.5 -o result.xy

# 1D: Reference background + ionchamber / 参考背景 + 电离室
python BGsub_skills/scripts/curve_process_1d.py curve.xy --background bg.xy --ion-dir ./ionchamber -o result.xy

# 1D: Batch curve processing / 批量曲线处理
python BGsub_skills/scripts/curve_batch_1d.py ./curves --method morph --radius 50 -o ./output

# 1D: Batch reference background + per-file T / 批量参考背景 + 分别设置T
python BGsub_skills/scripts/curve_batch_1d.py ./curves --background bg.xy --transmission-map transmissions.csv -o ./output

---

SSRF Ionchamber File Format / SSRF电离室文件格式#

Plain text format (extension .Ionchamber or .txt) / 纯文本格式：

text

# Time  Ionchamber0  Ionchamber1  Ionchamber2
2026-01-19 12:34:34.130671238  2.807135e-7  2.388761e-8  9.71103e-10

Channel / 通道Description / 说明Ionchamber0Incident beam intensity / 入射光强度Ionchamber1Transmitted beam (intermediate) / 透射光(中间)Ionchamber2Transmitted beam (primary measurement) / 透射光(主测量)

Transmission / 透射率: T = I_sample / I_background × 100%

Where I_sample and I_background are user-selectable channel statistics (mean / median / trimmed_mean). 其中 I_sample 与 I_background 由用户选择通道和统计方式（mean / median / trimmed_mean）。

File Matching Rules / 文件匹配规则#

Ionchamber files auto-match with images by number / 电离室文件通过编号自动匹配：

text

PBS-sd1-1s_00046.tif  ←→  PBS-sd1-1s_046.Ionchamber
   (auto-match _00046.tif → _046.Ionchamber)

---

1D Curve Processing Details / 1D曲线处理详情#

Supported Input Formats / 支持的输入格式#

Format / 格式Extensions / 扩展名XY / DAT / TXT.xy, .dat, .txt (single XY / xyxy / xyyy)CSV.csv (single XY / xyyy)GR.gr

Background Estimation Methods / 背景估计方法#

Method / 方法Key Parameter / 关键参数Use Case / 适用场景morph (Morphological) / 形态学--radius (default: 50)Broad features, smooth background / 宽衍射峰, 平滑背景poly (Polynomial) / 多项式--degree (default: 4), --quantileAmorphous halo fitting / 非晶晕拟合rolling_ball / 滚球--radius (default: 50)Complex baseline / 复杂基线

1D Output Format / 1D输出格式#

Default batch output is per-file split export. Merged single-file output is also supported / 默认批处理为逐文件拆分导出，也支持合并单文件导出：

text

原始: sample_001.xy
→ sample_001_raw.xy   (raw data / 原始数据)
→ sample_001_bg.xy    (estimated background / 估计背景, optional / 可选)
→ sample_001_sub.xy   (subtracted result / 扣除结果, optional / 可选)

1D Transmission Sources / 1D透过率来源#

• --transmission 85 → unified manual transmission / 手动统一透过率
• --transmission-map transmissions.csv → per-file transmission / 分别设置透过率
• --ion-dir ./ionchamber → auto-match ionchamber files and calculate T / 自动匹配电离室并计算逐文件 T

Multi-column Constraints / 多列约束#

• --parse-mode xyxy：按 (x1,y1)(x2,y2)... 展开多条曲线
• --parse-mode xyyy：按 x,y1,y2,... 展开多条曲线
• 多列模式下若使用 --background，当前 不支持 --ion-dir 自动电离室 T

When --background is provided, BGsub uses the traditional reference formula: 当提供 --background 时，BGsub 使用传统参考扣除公式：

text

result = sample / (T/100) - background

---

Reference Documents / 参考文档#

When the user's request goes beyond the quick usage examples above, read the appropriate reference file for detailed guidance. Each file serves a specific purpose — only read what you need. 当用户的需求超出上方快速使用示例时，请阅读对应的参考文档获取详细指引。每个文件有特定用途——只读你需要的。

When to read / 何时阅读File / 文件Content / 内容User is new to BGsub or needs step-by-step walkthrough / 新手入门或需要分步引导references/quickstart.md5-minute quick start with 4 real scenarios / 5分钟快速入门，含4个实际场景User asks about specific CLI flags, parameters, or default values / 用户询问具体 CLI 参数或默认值references/cli_commands.mdFull CLI command reference for all 7 scripts / 全部 7 个脚本的 CLI 命令参考User provides real data and wants end-to-end processing guidance / 用户提供真实数据需要端到端处理指引references/examples.md9 real-world SSRF PBS processing examples / 9 个 SSRF PBS 实际处理示例

---

Script Reference / 脚本参考#

Directory Structure / 目录结构#

text

BGsub_skills/
├── SKILL.md           # This file / 本文件
├── lib/               # Self-contained library (no external BGsub needed) / 自包含库（无需外部BGsub）
│   ├── __init__.py
│   ├── image_io.py    # Image I/O (TIFF/EDF/H5) / 图像读写
│   ├── common.py      # Ionchamber & transmission utilities / 电离室与透射率工具
│   ├── curve_data.py  # 1D curve data model / 1D曲线数据模型
│   ├── curve_io.py    # 1D curve I/O / 1D曲线读写
│   ├── curve_processor.py  # Background estimation algorithms / 背景估计算法
│   └── task_pipeline.py    # Batch pipeline engine / 批处理管线引擎
├── scripts/           # CLI scripts (import from lib/) / CLI脚本（从lib/导入）
└── references/        # Detailed docs / 详细文档

Scripts / 脚本#

Script / 脚本Function / 功能scripts/bg_subtract.pySingle 2D image background subtraction / 单文件2D背景扣除scripts/bg_batch.pyBatch 2D image processing / 批量2D处理scripts/ionchamber.pyIonchamber data analysis / 电离室数据分析scripts/curve_process_1d.pySingle 1D curve processing / 单曲线1D处理scripts/curve_batch_1d.pyBatch 1D curve processing / 批量1D曲线处理scripts/format_convert.pyTIFF/EDF/H5 format conversion / 格式转换scripts/compare_images.pysilx CompareImages popup / silx图像对比弹窗

Usage / 使用方法: python BGsub_skills/scripts/<script>.py --help