PPM Image Preview

---

📖 插件简介

PPM Image Preview 是一款专为 VS Code 开发者设计的轻量级、高性能 PPM (Portable Pixmap) 图像预览工具。无论是查看计算机图形学作业输出、调试图像处理算法，还是分析渲染结果，本插件都能提供流畅、专业的查看体验。

采用 Rust + WebAssembly + TypeScript 混合架构，将 Rust 的极致性能与 Web 技术的跨平台优势完美结合，支持 P3/P6 格式及 8-bit/16-bit 色彩深度。

什么是 PPM 格式？
PPM (Portable Pixmap) 是一种简单、通用的图像文件格式，常用于教学、科研和图像处理领域。它支持 ASCII (P3) 和二进制 (P6) 两种存储方式。

✨ 功能特性

🎯 核心功能

• ✅ 全格式支持 - 完整支持 P3 (ASCII) 和 P6 (二进制) 格式,兼容 8-bit 和 16-bit 色彩深度
• ⚡ 高性能渲染 - 基于 Rust + WASM 的图像解析引擎,加载速度较纯 JS 提升 10 倍以上
• 🔍 智能缩放 - 鼠标滚轮缩放 (0.01x - 100x),以光标为中心平滑缩放
• ✋ 画布平移 - 左键拖拽平移图像,支持触摸屏双指缩放
• 🎯 像素检查器 - 实时显示鼠标位置的坐标和 RGB 颜色值 (0-255 + 0.0-1.0 双精度显示)

🎨 交互体验

• ➕ 十字准星 - 虚线十字线跟随鼠标,精准定位像素坐标
• 🎨 颜色预览 - 28×28px 实时颜色色块显示
• 🪟 毛玻璃面板 - 半透明红色主题信息面板,不遮挡图像主体
• 📋 一键复制 - 快速复制坐标和颜色信息 (RGB + Hex 格式)
• 💾 导出 PNG - 将当前 PPM 图像导出并保存为 PNG 格式
• 🔄 视图控制 - 放大 (+) / 缩小 (-) / 重置 (Reset) 快捷按钮

📱 设备兼容

• 🖱️ 鼠标键盘 - 完整的键盘快捷键支持
• 📱 触摸设备 - 支持单指平移和双指捏合缩放
• 🖥️ 高分屏 - 自动适配 Retina 等高 DPI 显示器

⌨️ 快捷键支持

默认快捷键

当前版本可通过界面按钮完成所有操作。为提升使用体验,建议在 package.json 中添加以下快捷键配置：

推荐的快捷键配置

在 package.json 的 contributes 字段中添加 keybindings：

{
  "contributes": {
    "keybindings": [
      {
        "command": "ppmPreview.zoomIn",
        "key": "ctrl+equal",
        "mac": "cmd+equal",
        "when": "activeCustomEditorId == 'ppmPreview.editor'",
        "title": "放大图像"
      },
      {
        "command": "ppmPreview.zoomOut",
        "key": "ctrl+minus",
        "mac": "cmd+minus",
        "when": "activeCustomEditorId == 'ppmPreview.editor'",
        "title": "缩小图像"
      },
      {
        "command": "ppmPreview.resetView",
        "key": "ctrl+0",
        "mac": "cmd+0",
        "when": "activeCustomEditorId == 'ppmPreview.editor'",
        "title": "重置视图"
      },
      {
        "command": "ppmPreview.copyPixelInfo",
        "key": "ctrl+shift+c",
        "mac": "cmd+shift+c",
        "when": "activeCustomEditorId == 'ppmPreview.editor'",
        "title": "复制像素信息"
      },
      {
        "command": "ppmPreview.saveAsPng",
        "key": "ctrl+s",
        "mac": "cmd+s",
        "when": "activeCustomEditorId == 'ppmPreview.editor'",
        "title": "导出为 PNG"
      }
    ]
  }
}

📝 注意: 当前版本暂未实现上述命令,需要扩展开发者在 extension.ts 中注册对应命令并实现与 Webview 的通信。

鼠标操作

操作	功能	说明
滚轮	缩放图像	以光标为中心,每次缩放 1.1 倍
左键拖拽	平移画布	按住左键拖动图像
悬停	查看像素	在信息面板显示坐标和颜色

触摸操作 (移动设备)

操作	功能
单指拖拽	平移图像
双指捏合	缩放图像

🚀 技术架构

┌─────────────────────────────────────────────────────────┐
│                    VS Code Extension                     │
├─────────────────────────────────────────────────────────┤
│  TypeScript (Extension Host)                             │
│  ├── CustomEditorProvider  - 注册自定义编辑器           │
│  ├── File Watcher          - 监听文件变化               │
│  └── Message Broker        - Extension ↔ Webview 通信   │
├─────────────────────────────────────────────────────────┤
│  Webview (Browser Context)                               │
│  ├── Canvas Rendering Engine - 离屏 Canvas 预渲染       │
│  ├── Zoom/Pan Controller     - 缩放/平移控制器          │
│  ├── Pixel Inspector UI      - 像素信息面板             │
│  └── Web Worker              - 后台线程解析 (可选)      │
├─────────────────────────────────────────────────────────┤
│  WebAssembly Module (ppm_parser_bg.wasm)                │
│  └── Rust PPM Parser                                    │
│      ├── P3 ASCII 解析                                  │
│      ├── P6 Binary 解析                                 │
│      └── 8-bit/16-bit 色彩处理                          │
└─────────────────────────────────────────────────────────┘

技术栈详情

层级	技术	版本	说明
平台	VS Code	^1.74.0	扩展运行宿主
语言	TypeScript	^5.9.3	扩展主语言
语言	Rust	latest	WASM 源码
构建	Webpack	^5.108.4	双 target 打包 (node + web)
WASM 工具链	wasm-pack	latest	Rust → WASM 编译
渲染	Canvas 2D API	native	离屏 Canvas 预渲染
UI	HTML + CSS	native	原生 DOM + CSS3

📦 安装与使用指南

安装方法

方法一：从 VS Code 扩展市场安装 (推荐)

1. 打开 VS Code
2. 点击左侧活动栏的扩展图标 (或按 Ctrl+Shift+X)
3. 搜索 PPM Image Preview
4. 点击 安装 按钮
5. 重启 VS Code (如有提示)

方法二：从 VSIX 文件安装

1. 下载最新版本的 ppm-preview-x.x.x.vsix 文件
2. 打开 VS Code
3. 按 Ctrl+Shift+P (Windows/Linux) 或 Cmd+Shift+P (macOS) 打开命令面板
4. 输入 Extensions: Install from VSIX...
5. 选择下载的 .vsix 文件
6. 点击 安装,重启 VS Code

使用指南

自动预览

安装扩展后,直接点击任意 .ppm 文件即可自动启动预览编辑器。

手动打开

如果默认未使用 PPM Preview 打开：

1. 右键点击 .ppm 文件
2. 选择 打开方式... (Open With...)
3. 选择 PPM Preview

或者通过命令面板：

1. 打开 .ppm 文件
2. 按 Ctrl+Shift+P 打开命令面板
3. 输入 PPM: Open Preview

界面说明

┌─────────────────────────────────────────────────────────┐
│  PPM Preview                                    [-][□][x]│
├─────────────────────────────────────────────────────────┤
│ ┌─────────────────────┐                                 │
│ │ 📊 Image Info       │                                 │
│ │ Type: P6            │      🖼️ 图像显示区域            │
│ │ Width: 1920px       │                                 │
│ │ Height: 1080px      │      (支持缩放、平移)           │
│ │ Scale: 45%          │                                 │
│ ├─────────────────────┤                                 │
│ │ 🎯 Mouse Pixel      │                                 │
│ │ X: 960   Y: 540     │                                 │
│ │ R: 0.8784 (224)     │                                 │
│ │ G: 0.4510 (115)     │                                 │
│ │ B: 0.2314 (59)      │                                 │
│ │ [████] #E0733B      │                                 │
│ ├─────────────────────┤                                 │
│ │ [＋] [－] [Reset]   │                                 │
│ │ [📋 Copy] [💾 Save] │                                 │
│ └─────────────────────┘                                 │
└─────────────────────────────────────────────────────────┘

左侧信息面板说明

📊 Image Info (图像信息)

• Type: PPM 文件类型 (P3 = ASCII 格式, P6 = 二进制格式)
• Width: 图像宽度 (像素)
• Height: 图像高度 (像素)
• Scale: 当前缩放比例 (点击 Reset 可重置为适应窗口大小)

🎯 Mouse Pixel (鼠标像素)

• X / Y: 当前鼠标所在位置的图像坐标
• R / G / B: 红绿蓝通道值,显示格式为 浮点值 (整数)：
  • 浮点值: 0.0 - 1.0 范围,用于着色器计算
  • 整数: 0 - 255 范围,标准 RGB 值
• [████]: 28×28px 颜色预览色块
• #E0733B: Hex 颜色代码

控制按钮说明

按钮	功能	说明
＋	放大	每次放大 1.25 倍
－	缩小	每次缩小 1.25 倍
Reset	重置视图	将图像缩放至适合窗口大小并居中
📋 Copy	复制信息	复制当前像素的坐标、RGB 值和 Hex 代码到剪贴板
💾 Save	导出 PNG	将当前 PPM 图像保存为 PNG 格式文件

项目结构

ppmtool/
├── rust/                      # Rust WASM 模块
│   ├── Cargo.toml
│   └── src/
│       └── lib.rs            # PPM 解析核心
├── src/
│   ├── extension.ts          # VS Code 扩展入口
│   ├── webview/
│   │   ├── main.ts          # Webview 渲染逻辑
│   │   ├── styles.css       # UI 样式
│   │   ├── tsconfig.json    # Webview TS 配置
│   │   └── vscode.d.ts      # VS Code API 类型声明
│   └── wasm/
│       └── ppm_parser.d.ts  # WASM 模块类型声明
├── pkg/                      # WASM 构建产物 (自动生成)
├── dist/                     # Webpack 构建产物 (自动生成)
├── package.json              # 扩展清单
├── tsconfig.json             # TypeScript 配置
├── webpack.config.js         # Webpack 双目标配置
└── .vscodeignore             # VSIX 打包忽略规则

🛠️ 本地开发与构建指南

环境要求

在开始之前,请确保你的系统已安装以下工具：

工具	版本要求	说明
Node.js	^18.0.0	JavaScript 运行时
VS Code	^1.74.0	扩展宿主环境
Rust	最新稳定版	WASM 编译后端
wasm-pack	最新稳定版	Rust → WASM 构建工具

安装 Rust 和 wasm-pack

Windows (使用 rustup):

# 安装 Rust (包括 rustc 和 cargo)
irm https://win.rustup.rs/x86_64 -OutFile rustup-init.exe
.\rustup-init.exe

# 配置国内镜像 (可选,加速下载)
$env:RUSTUP_DIST_SERVER="https://rsproxy.cn"
$env:RUSTUP_UPDATE_ROOT="https://rsproxy.cn/rustup"

# 安装 stable 工具链
rustup install stable
rustup default stable

macOS / Linux:

# 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 配置环境变量 (添加到 ~/.bashrc 或 ~/.zshrc)
source "$HOME/.cargo/env"

安装 wasm-pack:

# 方法一：使用安装脚本
curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

# 方法二：使用 cargo install
cargo install wasm-pack

# 验证安装
wasm-pack --version

从源码构建

1. 克隆仓库

git clone https://github.com/your-repo/ppmtool.git
cd ppmtool

2. 安装 Node.js 依赖

# 如果遇到网络问题,可使用国内镜像
npm config set registry https://registry.npmmirror.com

# 安装依赖
npm install

3. 编译 Rust 为 WASM

# 生产构建 (优化,体积更小)
npm run build:wasm

# 开发构建 (包含调试信息,编译更快)
npm run build:wasm:dev

编译成功后,会在 pkg/ 目录生成以下文件：

• ppm_parser.js - WASM 模块的 JavaScript 绑定
• ppm_parser_bg.wasm - 编译后的 WebAssembly 二进制文件
• ppm_parser.d.ts - TypeScript 类型声明

4. 编译 TypeScript 扩展

# 开发模式 (监听文件变化)
npm run watch

# 或者单次编译
npm run compile

5. 调试扩展

1. 在 VS Code 中打开项目：

code .

2. 按 F5 启动调试 (会自动运行 .vscode/launch.json 中的配置)
3. 在打开的扩展开发宿主窗口中,打开任意 .ppm 文件测试

6. 打包为 VSIX

# 安装 vsce 工具 (如果尚未安装)
npm install -g @vscode/vsce

# 打包扩展
vsce package --no-dependencies
或者
npx vsce package --no-dependencies

打包完成后会生成 ppm-preview-x.x.x.vsix 文件,可分发给其他用户安装。

项目结构

ppmtool/
├── rust/                      # 🦀 Rust WASM 模块
│   ├── Cargo.toml            # Rust 依赖配置
│   └── src/
│       └── lib.rs            # PPM 解析核心 (P3/P6, 8/16-bit)
├── src/                       # 📘 TypeScript 源码
│   ├── extension.ts          # VS Code 扩展入口 (CustomEditorProvider)
│   ├── webview/              # Webview 前端
│   │   ├── main.ts          # 渲染逻辑、交互处理
│   │   ├── styles.css       # UI 样式
│   │   ├── tsconfig.json    # Webview TS 配置
│   │   └── vscode.d.ts      # VS Code API 类型声明
│   └── wasm/                 # WASM 类型声明
│       └── ppm_parser.d.ts  
├── pkg/                       # 📦 WASM 构建产物 (自动生成)
│   ├── ppm_parser.js
│   ├── ppm_parser_bg.wasm
│   └── ppm_parser.d.ts
├── dist/                      # 📦 Webpack 构建产物 (自动生成)
│   └── extension.js
├── package.json              # 扩展清单文件
├── tsconfig.json             # TypeScript 配置
├── webpack.config.js         # Webpack 双目标配置 (node + web)
├── .vscode/                  # VS Code 调试配置
│   ├── launch.json
│   └── tasks.json
└── .vscodeignore             # VSIX 打包忽略规则

构建命令速查表

命令	说明	输出目录
npm run build:wasm	编译 Rust → WASM (生产模式)	pkg/
npm run build:wasm:dev	编译 Rust → WASM (开发模式)	pkg/
npm run compile	Webpack 开发模式打包	dist/
npm run watch	监听模式,自动重新编译	dist/
npm run package	Webpack 生产模式打包	dist/
vsce package	打包为 .vsix 安装文件	项目根目录

开发技巧

热重载开发

同时监听 TypeScript 和 Rust 代码变化：

# 终端 1: 监听 TypeScript
npm run watch

# 终端 2: 监听 Rust 代码 (需要 cargo-watch)
cargo install cargo-watch
cd rust && cargo watch -i .gitignore -i "pkg/*" -s "wasm-pack build --target web --out-dir ../pkg --dev"

查看 WASM 编译日志

# 设置 RUST_LOG 环境变量
export RUST_LOG=info  # Linux/macOS
$env:RUST_LOG="info"  # PowerShell

npm run build:wasm

调试 WASM

1. 使用 npm run build:wasm:dev 编译调试版本
2. 在 Chrome DevTools 中打开 Webview 调试 (帮助 → 切换开发人员工具)
3. 在 Sources 面板可查看和调试 Rust 源码 (需启用 Source Maps)

功能演示

像素信息面板

左上角半透明红色面板显示：

• Image Info: 文件类型 (P3/P6)、宽度、高度、当前缩放比例
• Mouse Pixel: X/Y 坐标、R/G/B 值 (0-1 浮点 + 0-255 整数双显示)
• Color Swatch: 28x28px 颜色预览色块

十字准星

虚线十字线 (4px 间隔) 跟随鼠标位置，精准定位像素坐标。

缩放控制

• 鼠标滚轮: 以光标为中心平滑缩放
• 缩放范围: 0.01x - 100x
• 动画帧率: 60fps (requestAnimationFrame)

⚡ 性能优化

本插件采用多项优化技术,确保大尺寸图像也能流畅查看：

• 🎨 离屏 Canvas 预渲染 - 图像解码后先绘制到离屏 Canvas,缩放时只需变换绘制参数,无需重复解码
• ⚙️ WASM 原生解析 - Rust 编译为 WebAssembly,解析速度接近原生 C/C++,较纯 JS 提升 10 倍以上
• 🔄 requestAnimationFrame - 使用 RAF 进行渲染调度,保持 60fps 流畅动画,避免高频重绘
• 🎯 智能图像平滑 - 缩小时启用 imageSmoothingEnabled 抗锯齿,放大时关闭以保持像素边缘清晰
• 📦 零拷贝数据传输 - WASM 返回的像素数组直接创建 ClampedArray 视图,避免内存拷贝
• 🧵 Worker 线程解析 (可选) - 大文件可切换至 Web Worker 后台解析,不阻塞 UI 线程

❓ 常见问题 (FAQ)

Q: 支持哪些 PPM 格式？

A: 完整支持标准 PPM 格式：

• P3: ASCII 编码,人类可读,文件较大
• P6: 二进制编码,紧凑高效,常用格式
• 色彩深度: 8-bit (max_val ≤ 255) 和 16-bit (max_val > 255,自动归一化为 8-bit 显示)

Q: 大文件性能如何？

A: 使用离屏 Canvas 预渲染 + WASM 原生解析,即使 4K+ 分辨率图像也能流畅缩放和平移。实测 3840×2160 的 P6 文件加载时间 < 500ms。

Q: 如何导出为其他格式？

A: 目前仅支持导出为 PNG。如需其他格式,可先导出 PNG 后使用在线工具或 ImageMagick 转换。

Q: 支持触摸设备吗？

A: 是的,完整支持：

• 单指拖拽: 平移图像
• 双指捏合: 缩放图像
• 可在 Surface、iPad 等平板设备上流畅使用

Q: 为什么有时打开 PPM 文件显示空白？

A: 可能原因：

1. 文件头部格式不正确 (需以 P3 或 P6 开头)
2. 文件编码错误 (P3 应为 ASCII,P6 应为二进制)
3. 注释位置错误 (注释 # 只能在头部或空白处)

按 Ctrl+Shift+I 打开开发者工具查看 Console 错误信息。

Q: 可以调整背景颜色吗？

A: 当前版本背景色固定为 VS Code 默认深色主题色 #1e1e1e。如需自定义,可修改 src/webview/styles.css 中的 body 背景色。

Q: 如何查看 16-bit PPM 文件？

A: 插件会自动将 16-bit 色彩值归一化为 8-bit 显示 (除以 256)。信息面板会同时显示归一化后的 8-bit 值和原始浮点值。

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

开发流程

1. Fork 本仓库
2. 创建特性分支: git checkout -b feature/AmazingFeature
3. 提交更改: git commit -m 'Add some AmazingFeature'
   • 请遵循 Conventional Commits 规范
4. 推送到分支: git push origin feature/AmazingFeature
5. 开启 Pull Request: 描述你的改动和测试情况

代码规范

• TypeScript: 遵循 ESLint 配置 (npm run lint)
• Rust: 使用 cargo fmt 格式化,cargo clippy 检查
• 提交信息: 使用语义化提交信息

报告 Bug

使用 GitHub Issues 报告 Bug,请包含：

• VS Code 版本
• 插件版本
• 操作系统
• 复现步骤
• 示例 PPM 文件 (如有)

功能建议

同样通过 Issues 提出,标注为 enhancement,说明：

• 功能描述
• 使用场景
• 实现思路 (可选)

📄 许可证

本项目采用 MIT License 开源协议。

🙏 致谢

• wasm-pack - 优秀的 Rust WASM 工具链
• vsce - VS Code 扩展打包工具
• PPM 格式规范 - Netpbm 项目
• Canvas API - MDN Web Docs
• 所有 贡献者

🔗 相关链接

• VS Code 扩展开发文档
• Rust and WebAssembly
• WebAssembly
• PPM 格式详解

---