# cph

**Repository Path**: blake-john/cph

## Basic Information

- **Project Name**: cph
- **Description**: 分子图像分类课设程序
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-07
- **Last Updated**: 2026-07-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AtomClass - 原子图像分类应用

AtomClass 是用于原子图像分类的跨平台桌面应用，利用神经网络对分子图像进行分类。

## 目录

- [功能特性](#功能特性)
- [架构设计](#架构设计)
- [安装方法](#安装方法)
- [使用指南](#使用指南)
- [模型支持](#模型支持)
- [开发指南](#开发指南)
- [技术栈](#技术栈)
- [许可证](#许可证)

## 功能特性

- **单张图像分类**: 上传并分类单独的原子图像，显示详细的概率结果。
- **批量图像处理**: 处理整个文件夹中的原子图像，高效批量处理。
- **可视化结果叠加**: 直接在图像上查看分类结果。
- **灵活的模型支持**: 支持自定义 ONNX 模型和动态切换模型。
- **跨平台支持**: 支持 Windows、macOS 和 Linux 平台。
- **用户友好界面**: 使用 React 和 Tailwind CSS 构建的简洁现代界面。

## 架构设计

AtomClass 应用采用 Tauri 架构:

```
┌─────────────────┐
│   front         │
│  (React/Tail-   │
│   wind CSS)     │
├─────────────────┤
│  Tauri bridge   │
│  (Safe IPC)     │
├─────────────────┤
│   Backend       │
│   (Rust)        │
└─────────────────┘
```

**前端**
- React 配合 TypeScript
- Tailwind CSS 和 DaisyUI 样式
- Tauri 用于系统集成

**后端**
- Rust 配合 Tauri 进行系统集成
- ONNX Runtime 用于机器学习模型执行
- OpenCV 用于图像处理
- Image-rs 用于图像操作

## 安装方法

### 直接安装

通过安装程序 `atomclass-setup.exe` (Windows) 进行安装。

### 源码编译

#### 环境依赖

- Node.js 18.0+
- Rust 1.80.0+
- ONNX Runtime 1.23.1
- OpenCV 4.12.0
- MSVC latest
- LLVM 20.0.0+
- 可选：CUDA 12.6+

#### 编译步骤

1. 环境配置

确保 [Rust](https://rust-lang.org/zh-CN/) 以及 [Node.js](https://nodejs.cn/download/) 两大基础环境正常安装。

然后，需要下载 [OpenCV 4.12.0](https://github.com/opencv/opencv) 用于图像处理以及 [ONNX Runtime 1.23.1](https://github.com/microsoft/onnxruntime) 用于模型推理后端。

> 注意：对于 ONNX Runtime ， Windows 上可选 `x64-1.23.1` 或 `x64-gpu-1.23.1`，如果需要 GPU 加速，请选择 gpu 版本并确保 [CUDA](https://developer.nvidia.com/cuda-toolkit) 12.6+ 已正确安装并配置。

接着，我们需要确保 [MSVC](https://aka.ms/vs/stable/vs_BuildTools.exe) 正确安装，因为在 Windows 上开发程序基本绕不开微软的生成工具。

此外，由于我们在 `rust` 中使用 `OpenCV` , `onnxruntime` 等库，需要 `clang` 来编译，因此还要确保 [LLVM](https://releases.llvm.org/) 正确安装。

最后，我们需要为我们的程序指定安装的库，由于通过 `rust` 使用 `onnxruntime` 时会自动下载，与 OpenCV 冲突，因此我们还需要配置使用自己下载的 `onnxruntime` 来解决冲突，在 `src-tauri/.cargo/config.toml` 中配置：

```toml
[env]
# OpenCV 相关
OPENCV_DIR = "path_to_your_opencv/x64/vc16/"
OPENCV_LINK_LIBS = "opencv_world4120"
OPENCV_LINK_PATHS = "path_to_your_opencv/x64/vc16/lib/"
OPENCV_INCLUDE_PATHS = "path_to_your_opencv/include/"

# onnxruntime 相关
ORT_LIB_LOCATION="path_to_your_onnxruntime/"

# Clang 相关
# 可以先检查系统环境中有没有该变量，如果有，则无需设置
LIBCLANG_PATH = "path_to_your_llvm/bin/"
```

2. 安装依赖:

在项目根目录下：

```bash
npm install # 要求环境安装有 npm 和 node.js
npm fund
cargo install tauri-cli --version "^2.0.0" --locked # 要求环境安装有 Rust
```

3. 使用 cargo 运行开发版本:

```bash
cargo tauri dev
```

4. 使用 cargo 构建安装程序版本:
```bash
cargo tauri build
```

打包的应用程序将被创建在 `src-tauri/target/release/bundle/` 目录中，格式为对应平台的可执行文件(Windows为 `EXE/MSI`，macOS为 `DMG`，Linux为 `DEB/TAR`)。

## 使用指南

### 快速开始

1. 启动应用程序
2. 通过设置菜单(左下角 `※` 图标)加载 ONNX 模型(程序自带默认模型，可直接使用，也可训练自己的模型用于推理)
3. 在 `Single` 和 `Group` 选项卡之间切换，使用不同的工作流程

### 单张图像分类

1. 点击 `Load Image` 选择单张原子图像
2. 点击 "Infer" 进行推理
3. 在 `Prediction` 一栏中查看结果
4. 点击 `Save Result` 保存带有结果的图像

![单张图像界面](./src-tauri/public/single_tab.png)

### 批量图像处理

1. 点击 `Load Imgs From Folder` 选择包含原子图像的文件夹
2. 点击 `Infer` 使用当前模型处理所有图像
3. 在结果面板中查看处理后的图像
4. 点击 `Save Result` 将处理后的图像保存到文件夹

![批量处理界面](./src-tauri/public/group_tab.png)

### 设置和模型配置

1. 点击左下角的设置图标(※)
2. 设置 ONNX 模型文件的路径
3. 验证模型参数是否匹配预期的输入/输出形状
4. 保存配置

![模型设置界面](./src-tauri/public/model_select.png)

## 模型支持

AtomClass 使用 ONNX 模型进行原子分类：

- **输入要求**: `112x112` 像素的图像，RGB 通道，按照 `ImageNet` 的均值/标准差归一化
- **输出期望**: 分类张量，包含各个类别的概率分布
- **文件格式**: ONNX (`.onnx`) 模型文件
- **默认模型**: `public/r18_dyn_4cls.onnx`

> `mean: [0.485, 0.456, 0.406]`
> `std: [0.229, 0.224, 0.225]`

### 模型参数

模型必须支持：
- 输入形状: [Batch, 3, 112, 112]
- 输出形状: [Batch, classes]

要验证自定义模型，请在设置面板中检查模型元数据。

## 开发指南

### 项目结构

```
atomclass/
├── src/                        # 前端源代码
│   ├── components/             # React 组件
│   │   ├── single.tsx          # 单图像界面
│   │   ├── group.tsx           # 批量处理界面
│   │   └── ModelSelector.tsx   # 模型配置界面
│   └── App.tsx                 # 主应用程序组件
├── src-tauri/                  # 后端源代码 (Rust)
│   ├── .cargo/                 # Rust 项目编译配置，需要自己补充
│   ├── src/
│   │   ├── main.rs             # Tauri 初始化
│   │   ├── lib.rs              # Tauri 命令设置
│   │   ├── model.rs            # 机器学习模型操作
│   │   └── imgp.rs             # 图像处理功能
│   ├── Cargo.toml              # Rust 依赖
│   ├── public/                 # 公共资源 (模型，静态文件)
│   ├── icons/                  # 图标
│   └── tauri.conf.json         # Tauri 项目配置文件
├── package.json                # npm 项目元数据
└── README.md                   # 这个文件
```

### 可用命令

```bash
# 开发模式
npm run dev

# 构建生产版本
npm run build

# 使用 cargo 启动开发服务器 (推荐)
cargo tauri dev

# 使用 cargo 构建 Tauri 应用程序包
cargo tauri build

# 预览构建版本
npm run preview
```

### 后端命令

以下几个（不止这几个） Tauri 命令可供 TypeScript 访问：

- `infer_from_path`: 对给定路径的单张图像进行分类
- `infer_from_bytes_batch`: 对批量 base64 图像数据进行分类
- `read_img2base64_from_file`: 将图像文件转换为 base64
- `read_img_folder2base64_vec`: 从文件夹获取批量图像
- `write_result_on_img`: 在单张图像上叠加结果文本
- `write_result_on_imgs_bytes`: 在多张图像上叠加文本
- `set_model` / `get_model`: 模型管理命令

## 技术栈

- **前端框架**: React 19, TypeScript
- **样式**: Tailwind CSS, DaisyUI
- **桌面框架**: Tauri 2.0
- **后端语言**: Rust
- **机器学习运行时**: ONNX Runtime with Ort crate
- **图像处理**: OpenCV 和 Image-rs Rust crates
- **构建工具**: Vite 用于前端打包
- **并发处理**: Rayon crate 用于并行图像操作
- **数据处理**: Ndarray crate 用于 n 维数组操作
- **编码**: Base64 crate 用于编码/解码图像数据

## 许可证

本项目在 `Apache-2.0` 下获得许可 (详情请查看 [LICENSE](./LICENSE) 文件)。