# QuickShakePic

**Repository Path**: chiyoooo/quick-shake-pic

## Basic Information

- **Project Name**: QuickShakePic
- **Description**: 一个面向墨水屏、低色深屏幕和小尺寸显示设备的图片裁剪与抖动处理工具。  
它可以把任意图片快速整理成固定分辨率，并导出为适合设备侧使用的 BMP 文件。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-27
- **Last Updated**: 2026-03-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QuickShakePic

一个面向墨水屏、低色深屏幕和小尺寸显示设备的图片裁剪与抖动处理工具。  
它可以把任意图片快速整理成固定分辨率，并导出为适合设备侧使用的 BMP 文件。

开源地址：[https://gitee.com/chiyoooo/quick-shake-pic](https://gitee.com/chiyoooo/quick-shake-pic)

## 项目简介

QuickShakePic 是一个无需构建的前端小工具，核心流程很直接：

`导入图片 -> 选择目标尺寸 -> 调整构图/色彩 -> 选择调色板 -> 导出 BMP`

适合这些场景：

- 墨水屏相册、桌面摆件、电子价签、电子纸标签图制作
- 将普通彩色图片转换为 1bit / 双色 / 多色近似显示效果
- 为固定分辨率屏幕生成可直接使用的 BMP 资源

## 功能特性

- 固定尺寸裁剪，支持预设分辨率和手动输入尺寸
- 中心裁剪框构图，支持缩放、拖动、旋转、翻转
- 曝光、对比度、饱和度调节
- 可设置画布填充色
- 支持 ACT 调色板加载
- 支持 Floyd-Steinberg 抖动量化
- 支持导出 `24bit BMP` 或 `8bit indexed BMP`
- 支持拖拽导入、文件选择、剪贴板粘贴导入
- 支持撤销 / 重做
- 自定义尺寸预设管理，支持新增、编辑、删除、拖拽排序
- 用户设置和预设自动保存在浏览器本地

## 界面流程

1. 导入图片
2. 选择预设尺寸，或手动输入宽高
3. 通过拖动、缩放、旋转、翻转完成构图
4. 按需调整曝光 / 对比度 / 饱和度
5. 选择背景色与 ACT 调色板
6. 在预览视图中检查抖动结果
7. 导出 BMP

## 导出说明

### 1. 24bit BMP

当调色板选择为“`不使用调色板`”时，导出结果为 24 位真彩 BMP。

适合场景：

- 目标设备支持 RGB BMP
- 暂时不需要做索引色压缩
- 想保留完整颜色信息

### 2. 8bit Indexed BMP

当选择任意 `.act` 调色板时，图片会先按选定色板进行量化，并使用 Floyd-Steinberg 抖动算法生成 8 位索引 BMP。

适合场景：

- 墨水屏 / 电子纸等低色深显示设备
- 需要严格限制输出颜色集合
- 希望减少色阶断层、提升视觉过渡效果

默认可选调色板位于 [`act/`](./act/) 目录，例如：

- `4-color.act`
- `6-color.act`
- `Black-White.act`
- `Black-White-Red.act`
- `Black-White-Yellow.act`
- `N-color.act`

导出文件名会自动带上尺寸、导出模式和时间戳，便于区分不同版本。

## 运行方式

### 方式一：Windows 一键启动

仓库根目录下已提供：

- [`start-local.bat`](./start-local.bat)

双击后会：

- 在本地启动静态服务器
- 自动打开浏览器访问 `http://127.0.0.1:5173/`

### 方式二：Node.js 启动

项目自带一个零依赖本地静态服务器 [`server.js`](./server.js)。

```bash
node server.js
```

启动后访问：

```text
http://127.0.0.1:5173/
```

### 方式三：任意静态服务器

本项目本质上是静态网页，也可以放到任意静态服务器中运行，例如：

- Nginx
- Apache
- VS Code Live Server
- `python -m http.server`

注意：**不建议直接双击打开 `index.html`**。  
项目会通过 `fetch` 读取 `act/palettes.json` 和 `.act` 文件，同时使用 ES Module 脚本；直接以 `file://` 方式打开时，浏览器通常会因为安全策略导致功能异常。

## 环境要求

- 现代浏览器，建议使用 Chrome / Edge 最新版本
- 如需本地启动，安装 Node.js 即可

说明：

- 吸管取色依赖浏览器 `EyeDropper` API
- 若浏览器不支持吸管，仍可使用颜色输入框手动选色

## 使用说明

### 导入图片

支持三种方式：

- 点击“导入或粘贴图片”
- 将图片拖拽到编辑区域
- 直接粘贴剪贴板中的图片

### 设置裁剪尺寸

- 可直接选择内置预设
- 可手动输入宽高
- 可使用“横竖互换”快速交换宽高
- 可进入“预设尺寸管理”新增、编辑、删除、排序常用尺寸

### 调整图片

支持以下操作：

- 左旋 / 右旋 90°
- 水平翻转 / 垂直翻转
- 鼠标拖动移动图片
- 滚轮或快捷键缩放
- 双击编辑区让图片自动铺满裁剪框

### 调整色彩

支持：

- 曝光
- 对比度
- 饱和度
- 背景填充色

背景色会用于裁剪区域中空白部分的填充，也会参与最终导出结果。

### 预览模式

提供两种预览方式：

- `编辑视图`：以编辑态查看整体构图
- `预览视图`：更接近最终输出尺寸和抖动效果

当启用调色板时，界面会显示浮动预览窗口，便于观察量化后的细节。

## 快捷键

| 快捷键             | 功能         |
| ------------------ | ------------ |
| `Ctrl + S`         | 导出 BMP     |
| `Ctrl + N`         | 清除当前图片 |
| `Ctrl + Z`         | 撤销         |
| `Ctrl + Y`         | 重做         |
| `Ctrl + Shift + Z` | 重做         |
| `Ctrl + B`         | 启动背景取色 |
| `Ctrl + R`         | 重置图片变换 |
| `+` / `=`          | 放大         |
| `-`                | 缩小         |
| `方向键`           | 微调图片位置 |
| `Space + 拖动`     | 平移工作区   |

## 内置尺寸预设

当前默认预设如下：

| 名称    | 分辨率      |
| ------- | ----------- |
| `1.54"` | `200 x 200` |
| `2.13"` | `122 x 250` |
| `2.66"` | `152 x 296` |
| `2.9"`  | `296 x 128` |
| `3.5"`  | `184 x 384` |
| `3.97"` | `800 x 480` |
| `4.2"`  | `400 x 300` |
| `5.8"`  | `648 x 480` |
| `7.5"`  | `800 x 480` |
| `9.7"`  | `960 x 672` |

这些预设可在运行时自行修改，修改结果保存在当前浏览器本地。

## 本地存储

项目会把用户设置保存到浏览器 `localStorage`，包括：

- 当前选中的尺寸或手动宽高
- 背景色
- 调色板选择
- 预览模式
- 曝光 / 对比度 / 饱和度参数
- 自定义尺寸预设及其排序

如果想重置这些内容，可以手动清除浏览器站点存储。

## 目录结构

```text
QuickShakePic/
├─ act/                  # ACT 调色板与 palettes.json 清单
├─ assets/
│  ├─ css/               # 样式文件
│  └─ js/                # 核心逻辑：编辑、导出、状态、预设管理
├─ font/                 # 字体资源
├─ icon/                 # 图标资源
├─ index.html            # 页面入口
├─ server.js             # 本地静态服务器
├─ start-local.bat       # Windows 一键启动脚本
└─ README.md
```

## 新增调色板

如果你想扩展新的 ACT 调色板：

1. 将新的 `.act` 文件放入 [`act/`](./act/) 目录
2. 在 [`act/palettes.json`](./act/palettes.json) 中追加文件名
3. 刷新页面

程序会在启动时自动读取清单并预加载对应调色板。

## 开发说明

- 项目无打包流程、无 npm 依赖
- 页面主入口为 [`index.html`](./index.html)
- 交互主逻辑位于 [`assets/js/main.js`](./assets/js/main.js)
- 图片导出与抖动逻辑位于 [`assets/js/image-processing.js`](./assets/js/image-processing.js)
- 本地服务由 [`server.js`](./server.js) 提供

如果你准备继续开发，建议优先阅读：

- [`assets/js/main.js`](./assets/js/main.js)
- [`assets/js/editor.js`](./assets/js/editor.js)
- [`assets/js/image-processing.js`](./assets/js/image-processing.js)
- [`assets/js/preset-manager.js`](./assets/js/preset-manager.js)

## 常见问题

### 页面打开后无法正常加载调色板

通常是因为直接用 `file://` 打开了页面。  
请改用本地静态服务器启动，例如运行 `node server.js` 或双击 `start-local.bat`。

### 吸管取色无法使用

这是浏览器兼容性问题。  
请优先使用最新版 Chrome / Edge；如果仍不可用，可以直接通过颜色选择器手动设置背景色。

### 修改的预设为什么只在当前浏览器可见

因为预设保存在浏览器本地存储中，不会自动同步到仓库文件。

## 后续可扩展方向

- 批量处理多张图片
- 支持 PNG / JPG / WebP 导出
- 支持更多抖动算法
- 支持自定义命名模板
- 支持导入用户自定义调色板文件
- 增加设备模板说明和示例图

## License

当前仓库未附带正式 `LICENSE` 文件。  
如果你计划公开分发或允许他人复用，建议补充对应协议，例如 MIT。