diffraction-scatter-background-substract

BGsub — X-ray diffraction (SAXS/WAXS/XRD) background subtraction toolkit for 2D images and 1D curves. X射线衍射(SAXS/WAXS/XRD)数据背景扣除工具，覆盖2D图像处理和1D曲线处理。 Use this skill whenever the user's task involves ANY of the following, even if they don't explicitly mention "BGsub" or "background subtraction": 请在以下场景触发此 skill，即使用户未明确提及 "BGsub" 或 "背景扣除"： - "背景扣除", "background subtraction", "扣除背景", "去掉背景", "减背景" - "基线校正", "基线扣除", "基线拟合", "baseline correction", "baseline subtraction", "subtract background", "background estimation" - "SAXS", "WAXS", "XRD", "GIWAXS", "散射", "衍射", "小角散射背景扣除", "small-angle scattering background subtraction", "diffraction pattern" - "SSRF电离室", "电离室", "ionchamber", "ion chamber", "ionchamber file", "透射率校正", "透射率修正", "transmission correction", "transmission", "透过率", "T-背景", "T-background", "T修正", "T-correction" - "批量处理TIFF/EDF/H5文件", "batch process images", "batch background subtraction", "批量背景扣除", "格式转换", "图像格式转换", "file format conversion", "convert TIFF to EDF" - "PBS数据", "生物SAS", "biological SAS", "蛋白散射", "protein scattering", "生物样品散射" - "1D曲线处理", "1D curve processing", "曲线背景扣除", "XY曲线", "XY data", "积分曲线", "integrated curve", "curve smoothing", "基线拟合" - "形态学背景", "morphological background", "形态学", "多项式拟合", "polynomial fit", "滚球算法", "rolling ball" - User uploaded .Ionchamber files and needs X-ray data processing - User wants to subtract a known background image from signal images - User wants to estimate and subtract background from 1D diffraction curves - User mentions "T-背景", "T-background", "透射率修正", or asks how to correct for transmission in XRD data

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 / 脚本
1	Reference-based 2D background subtraction / 有参考2D背景扣除	2D Image	bg_subtract.py
2	Batch 2D processing with ionchamber / 批量2D处理+电离室	2D Image	bg_batch.py
3	Ionchamber stats + sample/background transmission / 电离室统计与样品/背景透过率	Shared	ionchamber.py
4	1D curve background estimation & T-corrected reference subtraction / 1D曲线算法背景估计与T修正参考扣除	1D Curve	curve_process_1d.py
5	Batch 1D curve processing with unified / per-file / ionchamber T / 批量1D曲线处理（统一T/分别设置/电离室）	1D Curve	curve_batch_1d.py
6	Format conversion (TIFF/EDF/H5) / 格式转换	2D Image	format_convert.py
7	silx image comparison popup / silx图像对比弹窗	2D Image	compare_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 / 说明
Ionchamber0	Incident beam intensity / 入射光强度
Ionchamber1	Transmitted beam (intermediate) / 透射光(中间)
Ionchamber2	Transmitted 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), --quantile	Amorphous 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.md	5-minute quick start with 4 real scenarios / 5分钟快速入门，含4个实际场景
User asks about specific CLI flags, parameters, or default values / 用户询问具体 CLI 参数或默认值	references/cli_commands.md	Full CLI command reference for all 7 scripts / 全部 7 个脚本的 CLI 命令参考
User provides real data and wants end-to-end processing guidance / 用户提供真实数据需要端到端处理指引	references/examples.md	9 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.py	Single 2D image background subtraction / 单文件2D背景扣除
scripts/bg_batch.py	Batch 2D image processing / 批量2D处理
scripts/ionchamber.py	Ionchamber data analysis / 电离室数据分析
scripts/curve_process_1d.py	Single 1D curve processing / 单曲线1D处理
scripts/curve_batch_1d.py	Batch 1D curve processing / 批量1D曲线处理
scripts/format_convert.py	TIFF/EDF/H5 format conversion / 格式转换
scripts/compare_images.py	silx CompareImages popup / silx图像对比弹窗

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