X-Ray Spectrum Plotter 用户手册

wangsy 发布于 2026-1-21 20:15 阅读：81 linux

X-Ray Spectrum Plotter 用户手册

1. 简介 (Introduction)

X-Ray Spectrum Plotter 是一个专为处理和可视化 X 射线光谱（如 XAS, NEXAFS 等）设计的 Python 工具。它能够读取原始计算数据（棒状图），对其进行不同线型的展宽（Broadening），并生成高质量的 2D 堆叠图 和 3D 演化图（热力图/曲面图）。

主要功能

双区间展宽: 支持将光谱分为两个能量区间，分别应用不同的展宽参数（HWHM）和函数（高斯/洛伦兹/Stieltjes）。
自动化批处理: 自动扫描文件夹内的光谱文件，根据文件名自动归类。
3D 可视化: 支持生成随条件（如温度、时间、距离）变化的 3D 等高线图或曲面图。
高度可定制: 支持自定义颜色、字体、刻度方向、标签偏移及输出分辨率（DPI）。
实验谱对比: 支持将实验数据与计算光谱叠加对比。

2. 环境要求与安装 (Installation)

这一部分不想看文字，可以点击看图文版本

本程序依赖 Anaconda3 环境运行。请严格按照以下步骤完成环境配置和软件安装。

2.1 第一步：下载并安装 Anaconda3

本程序使用 Anaconda3 来管理 Python 环境，省去配置依赖库的麻烦。

下载安装包:
- 访问清华大学开源软件镜像站下载最新版 Anaconda3 (64-bit)。
- 下载地址: https://mirrors.tuna.tsinghua.edu.cn/anaconda/archive/
- 推荐版本: 选择 Windows x86_64 版本（如 Anaconda3-2024.10-1-Windows-x86_64.exe）。
安装向导设置:
- 运行安装包，点击 Next 直到出现 Select Installation Type。
- Install for: 选择 Just Me (recommended)。
- Destination Folder: 建议使用默认路径或简单的自定义路径（如 C:\Software\anaconda3），请记住此路径，后续配置环境变量需要用到。
- Advanced Installation Options (高级选项):
- [x] Add Anaconda3 to my PATH...: 勾选 (推荐)。
- [x] Register Anaconda3 as my default Python 3.12: 勾选 (推荐)。
- [x] Clear the package cache upon completion: 勾选 (推荐，节省空间)。

安装完成后，取消勾选 "Launch Anaconda Navigator" 和 "Getting Started"，点击 Finish。

2.2 第二步：配置环境变量 (关键步骤)

安装完成后，必须手动将 Anaconda 的路径添加到系统环境变量中，否则无法在终端直接运行命令。

打开环境变量设置:
- 按键盘 Win 键，输入“高级”，选择 查看高级系统设置。
- 在弹出的“系统属性”窗口中，点击右下角的 环境变量(N)...。
编辑 Path 变量:
- 在 系统变量(S) (或用户变量) 区域中，找到并选中 Path，点击 编辑(E)...。
添加路径:
- 如果不存在如下环境，需要点击 新建(N)，依次添加以下 5 条路径（假设安装路径为 C:\Software\anaconda3，如果您的安装路径不同，请相应修改盘符和文件夹名）：
C:\Software\anaconda3
C:\Software\anaconda3\Library\mingw-w64\bin
C:\Software\anaconda3\Library\usr\bin
C:\Software\anaconda3\Library\bin
C:\Software\anaconda3\Scripts

重要: 添加完成后，使用右侧的 上移(U) 按钮，将这 5 条路径移动到列表的最顶部。
依次点击确定保存所有设置并关闭窗口。

2.3 第三步：安装 plotterxray 程序

打开终端:
- 进入存放 plotterxray-5.7.2-py3-none-any.whl 安装包的文件夹。
- 按住键盘 Shift 键，同时在文件夹空白处点击 鼠标右键。
- 在菜单中选择 在此处打开 Powershell 窗口 (或 "在终端中打开")。
执行安装命令:
- 在终端窗口中输入以下命令并回车： plotterxray下载地址
```
pip install plotterxray-5.7.2-py3-none-any.whl
```


* **注意**: 请确保命令中的文件名与实际文件完全一致（支持按 `Tab` 键自动补全文件名）。
* 当显示 `Successfully installed ...` 即表示安装成功。

### 2.4 程序更新与卸载

* **卸载旧版本**:
在终端输入 `pip uninstall plotterxray`，出现提示时输入 `Y` 确认。
* **安装新版本**:
卸载后，参照“第三步”，使用 `pip install XXXXX.whl` 安装新版安装包即可。

---

## 3. 快速开始 (Quick Start)

1. **准备数据**: 将你的光谱数据文件（例如 `.dat` 或 `.txt`，格式为两列：能量 强度）放入任意工作文件夹。
2. **准备配置**: 复制 `plot_detailed.ini` 到该文件夹并重命名为 `plot.ini`（或者使用简单版 `plot_simple.ini`）。
3. **运行程序**:
* 进入数据文件夹，**Shift + 右键** 打开终端。
* 运行以下命令：
```bash
plotterxray plot.ini

查看结果: 程序运行结束后，会在当前目录下生成 spectrum/ 文件夹，里面包含生成的 .pdf 和 .jpg 图片。

4. 配置文件详解 (Configuration Guide)

配置文件是控制绘图行为的核心。以下是各部分的详细说明。

4.1 [auto] - 自动扫描设置

用于控制程序是否自动读取当前目录下的文件。

参数	说明	示例值
mode	开关。`True` 开启自动扫描；`False` 仅使用 `[spectra]` 中的手动列表。	`True`
suffix	待扫描文件的后缀名。	`dat`
category	分类策略。`auto` 会尝试从文件名提取数字作为类别；指定字符串则强制归类。	`auto`
weight	默认强度权重。	`0.02`
shift	默认能量平移量 (eV)。	`-3.5`
color	绘图颜色。`auto` 自动循环颜色；指定 hex 码 (如 `#FF0000`) 则固定颜色。	`#808080`

注意: 自动模式下生成的列表会缓存到 plot_list.cache 文件中。如果新增了文件，请删除该缓存或在提示时选择重新生成。

4.2 [calculation] - 光谱计算与展宽核心

程序支持将光谱分为两个区间进行不同程度的展宽（例如：Pre-edge 区间使用较小的展宽，EXAFS 区间使用较大的展宽）。

参数	格式 / 说明
hwhm1	`Start End HWHM` (例如 `500 541 0.8`)。

定义区间1的起始能量、结束能量和半高宽。 |
| hwhm2 | Start End HWHM (例如 541 600 1.5)。

支持的展宽函数代码:

G: 高斯函数 (Gaussian)
L: 洛伦兹函数 (Lorentzian)
S: Stieltjes 函数 (适用于连续态展宽)

4.3 [general] - 画布通用设置

控制图片的外观、尺寸和坐标轴。

figure_width / figure_height: 图片尺寸（英寸）。
dpi: 输出分辨率，出版级图像建议设为 300 或更高。
font_family / font_size: 字体（如 Arial）和字号。
xlim: X轴能量显示范围 (例如 520 550)。
plot_order: 堆叠顺序。
bottom_up: 类别从小到大，从下往上堆叠。
top_down: 类别从小到大，从上往下堆叠。
tick_direction: 刻度朝向 (in 或 out)。
mirror_ticks: 是否在顶部和右侧显示镜像刻度。

4.4 [plot_2d] - 2D 堆叠图设置

用于绘制传统的瀑布图/堆叠图。

show: 是否生成 2D 图。
vertical_spacing: 各条光谱之间的垂直间距。设为 auto 则自动根据画幅计算，也可指定具体数值。
show_total: 是否将所有类别的光谱加和，绘制一条总谱（黑色曲线）。
show_sticks: 是否在曲线下方绘制原始的棒状图（Stick plot），用于分析具体跃迁贡献。
info_label: 图内标注文字（如 "O K-edge"）。

4.5 [plot_3d] - 3D 演化图设置

用于绘制随参数连续变化的光谱图（例如随温度变化）。

参数	说明
show	是否生成 3D 图。
type	图表类型：`contour` (等高线/热力图) 或 `surf` (3D 立体曲面)。
cmap	颜色映射表 (Colormap)，如 `seismic`, `jet`, `viridis`。
sampling_y	Y轴（类别轴）插值倍数。数值越大，类别间的过渡越平滑。
sampling_x	X轴（能量轴）插值倍数。
colorbar_range	颜色条数值范围。`auto` 或指定范围（如 `0 1.5`），用于统一不同图片的色阶。
rasterize_content	`T`。是否对绘图内容进行栅格化（保留矢量文字）。强烈建议开启，否则 PDF 文件会非常巨大且卡顿。

4.6 [spectra] - 手动文件列表

当 [auto] mode = False 时，程序读取此列表。

格式:

; 文件名      权重   类别   个体位移   颜色
file1.dat    1.0   CatA   0.0       red
file2.dat    1.0   CatB   0.2       blue

shift: 全局手动平移量，会叠加在个体位移上。

4.7 [exp_spectra] - 实验谱数据

用于加载实验数据进行对比。

格式:

; 文件名      缩放   图例标签   颜色
exp_data.txt  0.5   Experiment black

5. 数据准备 (Data Preparation)

5.1 计算数据文件

格式: 纯文本文件。
内容: 至少包含两列数据。
第1列: 激发能量 (eV)
第2列: 振子强度 (Oscillator Strength) 或强度
注释: 支持 # 或 ! 开头的注释行。

5.2 实验数据文件

同上，通常为两列 (Energy, Intensity)。程序会自动扣除 Y 轴的最小值（Baseline subtraction）。

6. 高级用法与技巧 (Tips & Tricks)

6.1 缓存机制 (Cache System)

程序在 [auto] 模式下运行时，会生成 plot_list.cache 文件。

作用: 记录了扫描到的文件列表、分类和颜色。
技巧: 你可以直接编辑 plot_list.cache 文件来微调某个特定文件的颜色或位移，而无需关闭自动模式。
坑点: 如果你添加了新文件但程序没读到，请删除该缓存文件，程序下次运行时会重新扫描。

6.2 混合展宽策略 (Hybrid Broadening)

在 XAS 模拟中，边前峰（Pre-edge）通常寿命较长，展宽较小；而边后（Post-edge）受连续态影响，展宽较大。

推荐设置：
hwhm1 (边前): 使用 0.5 - 0.8 eV，配合 Gaussian (G) 函数。
hwhm2 (边后): 使用 1.0 - 2.0 eV，配合 Stieltjes (S) 或 Lorentzian (L) 函数。

6.3 3D图去噪

如果 3D 热力图背景很脏，可以调整 [plot_3d] 中的 background_threshold。

设置为 0.001 或更高，可以将低强度的底噪强制归零，使图面更干净。

6.4 批量修改颜色

在 [auto] 模块中：

设置 color = auto: 程序会自动给不同类别分配不同颜色。
设置 color = #FF0000: 所有线条都变为红色（适合用于生成单一色调的对比图）。

7. 常见问题 (Troubleshooting)

Q: 运行后报错 ValueError: Cannot read config file?
A: 请检查 .ini 文件的编码。建议使用 UTF-8 编码保存。同时确保文件名输入正确。

Q: 生成的 PDF 文件打开极慢？
A: 请确保 [plot_3d] 中的 rasterize_content = T。这会将复杂的纹理光栅化为像素图，而保留坐标轴文字为矢量，大大减小文件体积。

Q: 为什么我的 3D 图看起来也是一条条的，不平滑？
A: 增加 [plot_3d] 中的 sampling_y 值（例如设为 20 或 50），程序会在不同文件的数据之间进行插值，使其看起来连续。

Q: 如何让某些特定的线突出显示（例如加粗或变色）？
A: 建议先运行一次生成 plot_list.cache，然后手动编辑该缓存文件，修改特定行的颜色代码，最后再次运行程序。

8. 输出示例

程序将在 spectrum/ 目录下生成以下文件：

spectrum_stack_2d.jpg / .pdf: 2D 堆叠图。
spectrum_evolution_contour.jpg / .pdf: 3D 热力图（如果启用）。
*_broad.txt: 如果开启了 keep_intermediate，这里保存了展宽后的具体数据点。

绘图