# HImage

![HImage 应用图标](assets/icon.png)

应用图标源文件为 `assets/icon.svg`，PNG 用于窗口图标，多尺寸 ICO 用于 Windows EXE 和安装器。修改 SVG 后，在 PowerShell 中执行以下命令重新生成：

```powershell
$env:HIMAGE_GENERATE_ICON = '1'
cargo run --example generate_icon
Remove-Item Env:HIMAGE_GENERATE_ICON
```

随后正常构建即可将图标嵌入程序。`build.rs` 仅在 Windows 构建时编译图标资源。

HImage 是一款使用 Rust、egui/eframe 和 wgpu 构建的桌面图片浏览器。当前首版面向 Windows 10/11 x64。核心目录、解码和视图逻辑不依赖 Windows API。

## 功能

- 打开单张图片或文件夹，也可以将图片或文件夹拖入窗口。
- 仅浏览当前目录，按文件名自然排序，并支持首尾循环切换；按 `F5` 重新扫描目录。
- 支持 JPEG（含 EXIF 方向）、PNG、BMP、WebP、TIFF、ICO、GIF 和 SVG。
- GIF 按帧延时和循环设置播放。TIFF、APNG 和动画 WebP 当前仅显示首幅。
- SVG 按静态图像渲染；缩放时在后台重新栅格化，不执行脚本，也不获取网络资源。
- 解码在后台运行，并隔离已取消的请求；GIF 帧队列容量为 1。
- 解码器分配预算为 128 MiB，最多同时执行一个解码任务。预留合成、帧队列和显示缓冲空间后，目标峰值预算为 512 MiB（不含图形驱动和字体）。位图单边最大 16384 像素，SVG 源文件最大 16 MiB。上传纹理尺寸受设备上限与 8192 像素限制，超出时会缩小显示；超出其他限制时会显示错误。

## 使用方法

直接打开图片、打开文件夹、拖入图片或文件夹，或从命令行传入路径：

```powershell
HImage.exe "图片路径或文件夹路径"
```

| 操作 | 功能 |
| --- | --- |
| 鼠标滚轮 | 以鼠标位置为锚点缩放 |
| 左键拖动 | 平移图片 |
| 左右方向键 | 切换上一张/下一张 |
| 窗口两侧半透明三角按钮 | 切换上一张/下一张 |
| `+` / `-` | 放大 / 缩小 |
| `0` | 适应窗口 |
| `1` | 显示原始尺寸 |
| `Ctrl+O` | 打开图片 |
| `Ctrl+Shift+O` | 打开文件夹 |
| `F5` | 重新扫描当前目录 |

## 构建

需要安装 Rust（项目固定使用 `rust-toolchain.toml` 中的工具链）以及 Visual Studio 2022 Build Tools 的“使用 C++ 的桌面开发”组件和 Windows SDK。

```powershell
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
cargo build --release --locked
```

开发运行示例：

```powershell
cargo run -- "图片或目录路径"
```

本项目优先使用全局 Rust，不需要 `.tools` 下的 Rust 工具链。

## 打包

使用 Inno Setup 6.6 或更新版本编译安装程序：

```powershell
./scripts/package.ps1 -Iscc "C:/Program Files (x86)/Inno Setup 6/ISCC.exe"
```

打包输出为 `dist/HImage.exe` 和 `dist/HImage-Setup.exe`。全用户安装需要管理员权限，程序日常运行不需要。安装器会创建开始菜单和卸载入口，并可选注册“打开方式”；不会更改默认图片应用。程序当前未签名。

## 项目结构

- `src/browser.rs`：目录浏览和文件排序
- `src/decode.rs`：图片解码和动画帧队列
- `src/view.rs`：缩放和视图状态
- `src/main.rs`：应用界面与入口
- `platform/windows`：Windows 安装配置

Linux/macOS 仅预留源码结构，尚未完成实机验证或打包。未来 Linux 构建还需要启用 eframe 的 X11/Wayland 后端和文件对话框依赖。

## 许可

项目内置 Noto Sans SC 字体，许可证见 `assets/fonts/OFL.txt`。依赖版本由 `Cargo.lock` 锁定；发布包附带第三方许可证目录。

## 验证记录

截至 2026-11-02，在 Windows x64、全局 stable Rust 1.99.1 / Cargo 1.99.1 和 Visual Studio 2022 Build Tools 环境中：

- 11 项单元测试通过，覆盖自然排序、空目录、循环、缩放锚点、中文字体渲染、静态解码、EXIF 旋转、GIF 循环/延时/帧处置、SVG 和分配限制。
- 格式检查、Clippy（警告视为错误）和 Release 构建通过。
- 实际窗口检查覆盖中文界面、文件对话框、中文及空格路径、SVG 显示和自然排序切图。
- 安装器已在隔离目录完成全用户安装、覆盖升级和卸载测试，均返回 0；卸载后程序和测试用“打开方式”注册项均已清理。
- 尚未在其他 DPI、Windows 10、Linux 或 macOS 实机验证。拖放和快速连续切图已实现，尚未完成 UI 自动化验证。

## 仓库

[https://git.honulla.com/hokori/HImage](https://git.honulla.com/hokori/HImage)