diffraction-scatter

Use this skill for diffraction / scattering data processing with pyFAI. It covers the full workflow: calibration (generating .poni files), azimuthal integrat...

Security Scan

The skill's code, runtime instructions, and required actions are consistent with its stated purpose (post-PONI pyFAI integration); it installs a Python venv and uses pyFAI to process detector files but does not request unrelated credentials or contact unexpected endpoints.

Purpose & Capability

Name/description (pyFAI post-PONI integration) align with the included scripts and library code: inspecting .poni files, iterating frames from EDF/TIFF/HDF5/NPY, applying masks/corrections, and running pyFAI integration methods. The declared requirements (none) match that the skill is self-contained and implements its own helpers.

Instruction Scope

SKILL.md instructs the agent to use bundled scripts (inspect_poni, install_pyfai_env, integrate_with_poni) and to collect only inputs relevant to diffraction processing (image files, .poni, masks, dark/flat). The instructions do not ask for unrelated files, credentials, or to transmit data to unknown external endpoints. Outputs are written to disk and progress emitted as JSONL to stdout as described.

Install Mechanism

There is no registry 'install' spec, but the included helper (lib/install_env.py) will create a Python virtualenv and call pip to install packages (pyFAI, fabio, h5py, numpy) from package indices. This is expected for a Python-based skill but means network downloads from PyPI will occur and new packages will be written to disk; run in an isolated environment if you want to restrict network/source trust.

Credentials

The skill does not require or read any environment variables, credentials, or config paths beyond standard filesystem access to input/output files. No secrets or unrelated service tokens are requested.

Persistence & Privilege

Flags show no always:true and the skill is user-invocable only. The code creates a virtualenv and writes per-frame outputs/manifest in the working directory — normal behavior for a data-processing tool and limited in scope to its own files.

Assessment

This skill appears to do exactly what it says: inspect .poni files and run pyFAI-based integrations. Before running: (1) review the bundled scripts (install helper calls pip and creates a venv) and run them in a controlled directory or sandbox/VM if you are cautious; (2) be aware the installer will download packages from PyPI (network); (3) the runner will write per-frame CSV/HDF5/NPZ outputs and a manifest.jsonl to disk and print JSONL events to stdout — ensure you run it where that output is acceptable. No credentials or external endpoints are requested by the skill.

pyFAI Post-PONI Integrator / pyFAI PONI 后积分器

This skill is for work after the user already has a .poni geometry file. 本技能面向用户已经获得 .poni 几何文件后的后续积分工作。

It covers: 1D radial, azimuthal/chi, sector 1D, GIWAXS/Fiber 2D, full 2D cake maps, large HDF5 streaming, uncertainty propagation, and Python/pyFAI environment setup. 覆盖：1D 径向、χ/方位角、扇区 1D、GIWAXS Fiber 2D、完整 2D cake/q-χ 图、 大批量 HDF5 流式处理、误差传播、Python/pyFAI 环境安装。

---

Step 0 — Confirm .poni / 先确认 .poni

EN: Confirm the user already has a .poni file. If not, guide them through calibration first (see below).

中文：先确认用户是否已有 .poni 文件。如果没有，先引导完成校准（见下方）。

What if the user does NOT have a .poni yet / 用户还没有 .poni 怎么办

A missing .poni means the user has not completed geometric calibration. Follow this sequence: 没有 .poni 意味着几何校准未完成。按以下顺序引导：

Step 1 / 第一步 — Install pyFAI / 安装 pyFAI

python pyfaiskills/scripts/install_pyfai_env.py --venv .venv-pyfai

If Python itself is missing / 如果连 Python 都没有：

• Windows: Python.org installer or Miniconda
• macOS: Homebrew (brew install python) or Python.org
• Linux: apt install python3 python3-venv or mamba/conda

Step 2 / 第二步 — Learn calibration / 学习校准

• 中文视频：pyFAI 校准教程（B站-个人）
• English: pyFAI Calibration Tutorial (silx.org, 15 min，official)

Once calibration is complete and the user has a .poni file, return to the main workflow below. 校准完成后用户有了 .poni 文件，回到下面的主流程。

---

Step 1 — Identify Mode / 判断积分模式

Identify the integration mode early: 优先判断积分模式：

Mode / 模式	Description / 描述	Core pyFAI call
radial1d	Standard 1D radial → I(q) / I(2θ)	integrate1d_ng
azimuthal1d	I(χ) inside a radial range / 固定 q 范围做 χ 积分	integrate_radial
sector1d	1D in an azimuthal sector / 扇区 1D	integrate1d_ng(..., azimuth_range=...)
cake2d	Full q-χ / 2θ-χ map / 完整 2D cake	integrate2d_ng
fiber2d	GIWAXS q_ip × q_oop / 纤维积分	FiberIntegrator.integrate2d_grazing_incidence

Advanced modes not yet fully scripted / 额外高级模式：

• MultiGeometry.integrate1d() — multi-detector fusion / 多探测器拼接
• sigma_clip_ng() — dynamic masking / 动态 mask
• pyFAI-integrate --no-gui --json — official JSON batch / 官方 JSON 批处理

---

Step 2 — Gather Missing Info / 补齐关键信息

Before executing, confirm: 执行前确认：

• Input format / 输入格式：EDF / TIFF / HDF5 / NPY
• Output format / 输出形式：CSV / HDF5 / NPZ / PNG
• Integration unit / 积分单位 (see rules below / 见下方规则)
• Corrections needed / 需要的修正：mask / dark / flat / polarization / solid-angle
• Streaming needed / 是否流式处理（large HDF5 / Eiger）
• GIWAXS: incident_angle, sample_orientation, units, ranges

---

Step 3 — Use Bundled Scripts / 优先使用脚本

Prefer the bundled scripts instead of rewriting one-off code / 优先调用脚本：

# 1) Inspect .poni and detector inputs / 检查 .poni 与输入数据
python pyfaiskills/scripts/inspect_poni.py --poni geometry.poni sample.h5

# 2) Create a pyFAI-ready environment / 创建 pyFAI 环境
python pyfaiskills/scripts/install_pyfai_env.py --venv .venv-pyfai

# 3) Run streaming integration / 运行流式积分
python pyfaiskills/scripts/integrate_with_poni.py \
  --mode radial1d --poni geometry.poni -i "data/**/*.edf" -o output/radial \
  --unit q_nm^-1 --npt 2000

The runner emits JSONL progress and writes results frame-by-frame to disk. 脚本默认把进度以 JSONL 打到标准输出，逐帧写结果到磁盘。

---

Unit Selection Rules / 单位选择规则

Units matter / 单位很重要 — different experiments have different conventions. 不同实验类型有不同惯例。 按以下规则处理：

1. User specified a unit explicitly / 用户明确指定 → use what the user asked for
2. User mentioned experiment type but not unit / 用户提到了实验类型：
   • WAXS / WAXD / wide-angle / 广角 → 2th_deg (2θ degrees)
   • SAXS / small-angle / 小角 → q_nm^-1 (q, nm⁻¹)
   • GIWAXS / fiber / grazing-incidence / 掠入射 → qip_nm^-1 × qoop_nm^-1(仅限该格式，无其他单位)
3. Nothing specified / 什么都没说 → ask WAXS or SAXS first / 先问是 WAXS 还是 SAXS

Common pyFAI units / 常见单位：

• q_nm^-1 — scattering vector q (nm⁻¹)
• q_A^-1 — scattering vector q (Å⁻¹)
• 2th_deg — scattering angle 2θ (degrees)
• 2th_rad — scattering angle 2θ (radians)
• r_mm — radial distance from beam center (mm)

---

Good Defaults / 推荐默认参数

Mode / 模式	Command / 命令
1D radial (WAXS)	--mode radial1d --unit 2th_deg --npt 1000~4000
1D radial (SAXS)	--mode radial1d --unit q_nm^-1 --npt 1000~4000
χ profile / χ 积分	--mode azimuthal1d --azimuthal-unit chi_deg --npt 360 --npt-rad 100
Sector 1D / 扇区	--mode sector1d --azimuth-min -30 --azimuth-max 30
2D cake	--mode cake2d --unit q_nm^-1 --npt-rad 500 --npt-azim 360
GIWAXS / Fiber	--mode fiber2d --unit-ip qip_nm^-1 --unit-oop qoop_nm^-1
Throughput / 吞吐优先	--method csr
Accuracy / 精度优先	--method splitpixel

---

Command Templates / 常见命令模板

Standard 1D radial / 标准 1D 径向积分

python pyfaiskills/scripts/integrate_with_poni.py \
  --mode radial1d --poni geometry.poni -i sample.edf -o out/1d \
  --unit q_A^-1 --npt 2000 --method splitpixel --polarization 0.95

Azimuthal I(χ) inside a q-range / 固定 q 范围做 χ 积分

python pyfaiskills/scripts/integrate_with_poni.py \
  --mode azimuthal1d --poni geometry.poni -i sample.h5 -o out/chi \
  --radial-unit q_nm^-1 --radial-min 2 --radial-max 18 --azimuthal-unit chi_deg

Sector 1D / 扇区 1D

python pyfaiskills/scripts/integrate_with_poni.py \
  --mode sector1d --poni geometry.poni -i "frames/*.tif" -o out/sector \
  --unit q_nm^-1 --azimuth-min -20 --azimuth-max 20

Full 2D cake / 完整 2D cake

python pyfaiskills/scripts/integrate_with_poni.py \
  --mode cake2d --poni geometry.poni -i sample.edf -o out/cake \
  --unit q_nm^-1 --npt-rad 800 --npt-azim 360

GIWAXS / Fiber 2D

python pyfaiskills/scripts/integrate_with_poni.py \
  --mode fiber2d --poni geometry.poni -i sample.edf -o out/fiber \
  --unit-ip qip_nm^-1 --unit-oop qoop_nm^-1 \
  --incident-angle 0.2 --sample-orientation 1

---

Large-Volume / Streaming Policy / 大批量策略

When the user mentions large HDF5 stacks, tiff, Eiger data, many frames, or memory pressure: 当用户提到"海量 HDF5 / tiff /Eiger / 很多帧 / 不能一次读进内存"时：

1. Process file-by-file and frame-by-frame / 逐文件、逐帧处理
2. For HDF5, prefer explicit dataset path; otherwise /data / HDF5 优先指定 dataset path
3. For 4D Eiger, confirm channel (LowThresholdData, HighThresholdData, DiffData) / 4D Eiger 确认通道
4. Prefer csr for throughput; splitpixel for accuracy / 高吞吐用 csr，高精度用 splitpixel
5. Write outputs incrementally / 边算边写

---

When to Read References / 什么时候读参考文档

• Overview & fast start / 总览 → references/quickstart.md
• Mode selection / 模式选择 → references/modes.md
• Large dataset strategy / 大数据策略 → references/streaming.md

---

Acknowledgments / 致谢

This work is built upon three core open‑source projects:

• pyFAI – The fast azimuthal integration Python library.
  Citation: G. Ashiotis, A. Deschildre, Z. Nawaz, J. P. Wright, D. Karkoulis, F. E. Picca and J. Kieffer; Journal of Applied Crystallography (2015) 48(2), 510‑519.
  DOI: 10.1107/S1600576715004306

• fabio – I/O library for 2D X‑ray detector images.
  Citation: E. B. Knudsen, H. O. Sørensen, J. P. Wright, G. Goret and J. Kieffer; Journal of Applied Crystallography (2013) 46, 537‑539.
  DOI: 10.1107/S0021889813000150

• silx – Collection of Python packages for data assessment, reduction and analysis at synchrotron radiation facilities.
  Citation: silx releases can be cited via their DOI on Zenodo: 10.5281/zenodo.591709

We thank the ESRF and all contributors of these projects for making this work possible.

本技能基于以下三个核心开源项目开发：

• pyFAI – 快速方位角积分库，引用信息同上。
• fabio – 二维X射线探测器图像I/O库，引用信息同上。
• silx – 同步辐射设施数据评估、归约与分析工具包，引用信息同上。

感谢ESRF及上述项目的所有贡献者。

Mandatory Closing / 结束时必须做

1. State which mode, units, corrections, and output formats were used / 明确告知采用的模式、单位、修正项和输出格式

2. If large job, mention streaming / frame-wise processing / 大批量时说明是否采用了流式策略

3. Always credit pyFAI, fabio, and silx / 必须强调 pyFAI、fabio 和 silx 并附带引用：

   [上述致谢与引用内容]

4. This is a personal project, not an official release from ESRF or the pyFAI/silx/fabio teams. / 本技能为个人项目，并非 ESRF 或 pyFAI/silx/fabio 团队的官方发布。

Installation Guide / 安装指南

This skill can be installed on any platform that supports the standard skill directory structure.

本技能可安装在任何支持标准 skill 目录结构的平台上。

Common installation paths / 常见安装路径：

Platform / 平台	Path / 路径
OpenCode (Windows)	C:\Users\<user>\.config\opencode\skills\
OpenCode (macOS/Linux)	~/.config/opencode/skills/
SkillHub (腾讯)	~/.skillhub/skills/（或参考平台文档）
ClawHub	~/.clawhub/skills/
OpenClaw	~/.openclaw/skills/
Generic	AI agent 配置的任意 skill 目录

If your platform is not listed, refer to its documentation for the skills folder location. 如果你的平台未列出，请查阅对应文档确认 skills 目录位置。

Verification / 验证

After installation, trigger the skill by mentioning: 安装后，可通过提到以下内容触发技能：

• 1D integration / 1D 积分
• GIWAXS, sector, cake, HDF5, Eiger

Or run the test script (if supported by your platform): 或运行测试脚本（如果平台支持）：

python <SKILLS_DIR>/diffraction-scatter/scripts/integrate_with_poni.py --help

Notes / 注意事项

• Must preserve directory structure / 必须保留目录结构：lib/ and scripts/ must be in the same parent directory / lib/ 和 scripts/ 必须在同一父目录下
• Do not copy __pycache__ / 不要拷贝 __pycache__
• Minimum install (without pyfaiinfo) is ~12 files / 最小安装约 12 个文件