# FPM_Study

**Repository Path**: narcijie/FPM_study

## Basic Information

- **Project Name**: FPM_Study
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-23
- **Last Updated**: 2026-02-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FPM (Fourier Ptychographic Microscopy) 仿真项目

本项目提供一维和二维傅立叶叠层显微术 (FPM) 的仿真程序，用于教育和研究目的。

## 项目结构

```
.
├── src/                        # 源代码目录
│   ├── __init__.py             # 包初始化文件
│   ├── 1d_fpm.py              # 一维FPM基础仿真（非交互）
│   ├── fpm_interactive.py     # 一维FPM交互式GUI（带参数滑块）
│   ├── fpm_2d_corrected.py    # 二维FPM基础算法（直接拼接）
│   ├── fpm_2d_algorithms.py   # 二维FPM高级算法（直接、迭代、ePIE）
│   └── fpm_image_processor.py # 基于图片的FPM仿真处理器
├── examples/                   # 示例和演示程序
│   ├── demo_fpm_2d.py         # 二维完整演示程序
│   ├── verify_fpm_2d.py       # 二维算法验证脚本
│   └── example_usage.py       # 二维使用示例
├── tests/                      # 测试脚本
│   ├── test_image_fpm.py      # 图片处理器测试脚本
│   └── test_quick.py          # 快速功能测试
├── docs/                       # 文档
│   └── 1d_fpm_explanation.md  # 一维FPM算法详细解释
├── dist/                       # 可执行文件（Windows）
│   ├── 1d_fpm.exe             # 一维基础程序
│   ├── fpm_interactive.exe    # 一维交互程序  
│   ├── demo_fpm_2d.exe        # 二维完整演示程序
│   ├── verify_fpm_2d.exe      # 二维算法验证程序
│   ├── example_usage.exe      # 二维使用示例程序
│   └── fpm_image_processor.exe # 基于图片的FPM仿真处理器
├── *.spec                      # PyInstaller打包配置文件
├── requirements.txt            # Python依赖包
└── README.md                   # 本文档
```
## 安装为Python包

本项目已打包为Python包，可通过pip安装。

### 安装方法

```bash
pip install -e .
```

### 命令行工具

安装后可使用以下命令行工具：

- `fpm-demo-2d` - 运行完整的2D FPM演示
- `fpm-verify-2d` - 运行2D算法验证测试
- `fpm-example-usage` - 运行2D使用示例
- `fpm-image-processor` - 基于图片的FPM仿真处理器（支持 `--demo` 参数）
- `fpm-1d` - 运行一维FPM基础仿真
- `fpm-interactive` - 运行一维FPM交互式GUI

> **注意**：在Windows系统上，命令行工具会安装到Python的`Scripts`目录（例如 `C:\Users\用户名\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.10_qbz5n2kfra8p0\LocalCache\local-packages\Python310\Scripts\`），请将该目录添加到PATH环境变量中，或使用完整路径运行。

### 作为Python模块使用

```python
from src.fpm_2d_algorithms import compute_fpm_2d_direct, compute_fpm_2d_epie
from src.fpm_image_processor import process_custom_image, demo_with_sample_image
```

## 一维FPM仿真

### 快速开始

1. **运行交互式程序**（推荐）：
   ```bash
    python -m src.fpm_interactive
   ```
   或直接双击 `fpm_interactive.exe`（无需Python环境）。

2. **运行基础演示**：
   ```bash
    python -m src.1d_fpm
   ```
   或双击 `1d_fpm.exe`。

### 一维程序特点

- **交互式GUI**：实时调节12个参数：
  - 系统参数：采样点数、像素尺寸、波长、数值孔径、LED距离/范围/数量
  - 物体参数：两个物体的位置/宽度、相位调制周期/幅度
- **实时可视化**：显示物体、频谱、低分辨率图像、重建结果
- **合成NA计算**：实时显示FPM合成的等效数值孔径
- **优化布局**：避免文本重叠，改善视觉体验

### 算法解释

详细算法说明见 [1d_fpm_explanation.md](1d_fpm_explanation.md)，包含：
- FPM物理原理
- 数学公式推导
- 代码逐行解释
- 参数含义说明

## 二维FPM仿真

### 算法概述

二维FPM仿真实现了以下算法：

1. **直接频谱拼接算法** (`compute_fpm_2d_direct`)：
   - 模拟每个LED照明下的低分辨率图像
   - 提取频域子带并中心化
   - 拼接子带得到高分辨率频谱
   - 反傅里叶变换得到重建图像
   - 支持两种重叠处理：最大模值(`max`)或平均(`avg`)

2. **迭代恢复算法** (`compute_fpm_2d_iterative`)：
   - 基于Gerchberg-Saxton类型的迭代算法
   - 在空间域（强度约束）和频域（支持约束）间交替
   - 支持多次迭代逐步优化

3. **ePIE算法** (`compute_fpm_2d_epie`)：
   - 扩展的ptychographic迭代引擎（业界标准）
   - 同时恢复物体复振幅和瞳孔函数（系统像差）
   - 支持噪声模型、LED位置误差和照明强度误差
   - 自适应步长更新，收敛更稳定

### 快速开始

1. **运行完整演示**：
   ```bash
    python examples/demo_fpm_2d.py
   ```
   或直接双击 `dist/demo_fpm_2d.exe`（无需Python环境）。
   程序将展示多个预设场景，比较不同算法的性能。

2. **使用核心算法**：
   ```python
    from src.fpm_2d_algorithms import compute_fpm_2d_direct
   
   params = {
       "N": 128,                    # 图像尺寸 (N×N 像素)
       "dx": 0.3,                   # 像素尺寸 (μm)
       "wavelength": 0.532,         # 波长 (μm)
       "NA_obj": 0.15,              # 物镜数值孔径
       "LED_dist": 40,              # LED阵列距离 (mm)
       "LED_grid_shape": (5, 5),    # LED网格 (行, 列)
       "LED_spacing": 6,            # LED间距 (mm)
   }
   
   result = compute_fpm_2d_direct(**params, overlap_method='max')
   ```

3. **验证算法正确性**：
   ```bash
    python examples/verify_fpm_2d.py
   ```
   或双击 `dist/verify_fpm_2d.exe`（显示控制台输出和验证图表）。

4. **运行使用示例**：
   ```bash
    python examples/example_usage.py
   ```
   或双击 `dist/example_usage.exe`（显示控制台输出和示例图表）。

### 基于图片的FPM仿真

新增模块 `fpm_image_processor.py` 支持从任意图片输入进行FPM仿真：

1. **核心功能**：
   - 加载和预处理任意图片（自动转为灰度、调整尺寸、归一化）
   - 从振幅图像创建复数物体（支持多种相位类型：零相位、正弦相位、随机相位、梯度相位）
   - 对复数物体进行完整的FPM前向仿真
   - 从低分辨率图像重建（支持直接算法和ePIE迭代算法）
   - 可视化原始图片、仿真过程、重建结果

2. **使用方法**：
    ```bash
    # 运行演示（使用内置测试图片）
    python -m src.fpm_image_processor --demo
    
    # 处理自定义图片
    python -m src.fpm_image_processor your_image.png
    
    # 指定相位类型和重建方法
    python -m src.fpm_image_processor your_image.png --phase sine --method direct
    ```

3. **可执行程序**：
   - `dist/fpm_image_processor.exe`：独立的可执行程序，无需Python环境
   - 命令行参数与Python脚本相同

4. **测试验证**：
   ```bash
    python tests/test_image_fpm.py
   ```
   运行完整的单元测试验证模块功能。

### 参数说明

| 参数 | 类型 | 描述 | 典型值 |
|------|------|------|--------|
| `N` | int | 高分辨率图像尺寸（正方形） | 128, 256 |
| `dx` | float | 空间采样间隔 (μm/像素) | 0.2-0.5 |
| `wavelength` | float | 照明波长 (μm) | 0.532 (绿光) |
| `NA_obj` | float | 物镜数值孔径 | 0.1-0.3 |
| `LED_dist` | float | LED阵列到样本的距离 (mm) | 30-100 |
| `LED_grid_shape` | tuple | LED网格形状 (行数, 列数) | (5,5), (7,7) |
| `LED_spacing` | float | LED间距 (mm) | 4-10 |

### 输出结果

算法返回包含以下字段的字典：

- `obj_amplitude`, `obj_phase`: 原始物体的振幅和相位
- `recon_amplitude`, `recon_phase`: 重建的振幅和相位
- `spectrum`: 原始高分辨率频谱
- `spectrum_stitched`: 拼接后的频谱
- `low_res_images`: 低分辨率强度图像列表
- `LED_positions`: LED位置坐标 (μm)
- `NA_eff`: 合成后的等效数值孔径
- `pupil_radius_pix`: 瞳孔半径 (像素)

## 物理原理

### FPM基本思想

傅立叶叠层显微术通过以下步骤实现超分辨成像：

1. **多角度照明**：使用LED阵列从不同角度照射样本
2. **低分辨率采集**：每个LED产生一个低分辨率强度图像
3. **频域拼接**：每个低分辨率图像对应频域的一个子带
4. **相位恢复**：利用重叠区域信息恢复丢失的相位
5. **高分辨率重建**：拼接所有子带得到高分辨率复振幅图像

### 分辨率提升

传统显微镜的分辨率受限于物镜数值孔径 (NA_obj)：
```
分辨率 ≈ λ / (2·NA_obj)
```
FPM通过合成多个倾斜照明，将有效NA提升为：
```
NA_eff = NA_obj + sin(θ_max)
```
其中 θ_max 是最大照明角度。

## 性能说明

### 算法精度

- **直接拼接算法**：振幅误差约10-15%，相位误差约2-5%
- **迭代算法（GS）**：振幅误差约30-40%，相位误差较大
- **ePIE算法**：振幅误差约35-40%，但能处理噪声和实验误差
- **合成NA提升**：典型提升3-5倍

### 计算复杂度

- 直接算法复杂度：O(M·N²)，其中M为LED数量，N为图像尺寸
- 推荐尺寸：N ≤ 256 以获得合理计算时间
- 内存需求：约 N² × 8 × 2 字节（复数双精度）

## 扩展开发

### 添加新算法

1. 在 `fpm_2d_algorithms.py` 中添加新函数
2. 遵循现有接口格式
3. 在 `demo_fpm_2d.py` 中集成新算法

### 创建交互式GUI

参考 `fpm_interactive.py` 的设计：
1. 使用 `matplotlib.widgets.Slider` 创建参数控件
2. 使用 `GridSpec` 管理布局
3. 实现 `update()` 函数实时刷新

### 优化建议

1. **算法优化**：
   - 实现更高效的迭代算法（如ADMM）
   - 添加正则化项抑制噪声
   - 支持非均匀照明校正

2. **性能优化**：
   - 使用GPU加速（CuPy）
   - 实现频域操作的向量化
   - 支持并行LED处理

3. **功能扩展**：
   - 支持任意形状LED阵列
   - 添加噪声模型
   - 支持实验数据导入

## 依赖环境

- Python 3.8+
- numpy
- matplotlib
- scipy (用于迭代算法的上采样)

安装依赖：
```bash
pip install -r requirements.txt
```

## 许可证

本项目仅供教育和研究使用。

## 作者

FPM仿真项目 - 用于傅立叶叠层显微术教学和算法验证。

## 参考文献

1. Zheng, G., Horstmeyer, R., & Yang, C. (2013). Wide-field, high-resolution Fourier ptychographic microscopy. *Nature Photonics*, 7(9), 739-745.
2. Tian, L., et al. (2014). Computational illumination for high-speed in vitro Fourier ptychographic microscopy. *Optica*, 1(1), 1-9.
3. Ou, X., Zheng, G., & Yang, C. (2014). Embedded pupil function recovery for Fourier ptychographic microscopy. *Optics Express*, 22(5), 4960-4972.