# ark-pd **Repository Path**: guluzz/ark-pd ## Basic Information - **Project Name**: ark-pd - **Description**: 明日方舟 - 奇象巡展拼豆工具 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 5 - **Forks**: 0 - **Created**: 2026-08-09 - **Last Updated**: 2026-08-12 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 奇象巡展拼豆工具 一个完全在浏览器中运行的图片转拼豆工具。它会将任意图片裁剪为正方形，并使用固定的方舟标准色卡生成一张 `24 × 24`、共 576 颗拼豆的像素图。 所有图片读取、裁剪、取样、颜色匹配、编辑和导出均在当前浏览器本地完成，不需要后端服务，也不会主动上传图片。 ## 功能概览 - 保持原图比例裁剪为 `1:1`，只裁切、不拉伸、不变形。 - 固定输出 `24 × 24` 拼豆图。 - 使用 40 色方舟标准色卡进行颜色匹配。 - 一次生成 10 种本地算法效果，可随时重新选择。 - 支持显示或隐藏网格线。 - 默认开启“高亮所有同色格”。 - 点击任意格子可查看当前颜色位置；再次点击该格或其他同色格即可取消。 - 可选显示画布计数坐标；数字对准每个方块中心，并以中心十字线为 0 向四周递增。 - 通过竖向滑杆缩放画布，通过导航缩略图移动视口。 - 编辑模式支持单格填色、按住拖动连续填色、从画布取色、撤销、前进和恢复初始状态。 - 自动缓存最后一次画作，刷新或重新打开网页后可继续编辑。 - 退出编辑模式前会二次确认，避免误操作。 - 下载 `1200 × 1200` PNG 图片。 - 支持 PC 与移动端响应式布局；移动端色卡保持每行 4 列。 ## 支持的图片格式 - PNG - JPEG / JPG - WebP - GIF GIF 会按照浏览器当前解码出的画面进行静态处理，本工具不会导出动画。 ## 使用方法 ### 1. 上传图片 点击左侧栏或空画布中的“上传图片”，选择本地图片。 图片只会被当前浏览器读取。关闭或刷新页面后，尚未下载的工作内容不会自动保存。 ### 2. 裁剪为正方形 上传后会进入裁剪窗口： 1. 拖动图片，调整正方形区域中的构图。 2. 使用“图片缩放”滑杆放大或缩小图片。 3. 点击“使用此区域”。 裁剪始终保持原图比例，不会发生横向或纵向拉伸。 生成结果后，可以点击左侧栏中的“重新裁剪”再次调整。 ### 3. 选择生成算法 裁剪后会同时生成以下 10 种效果： | 算法 | 适用场景 | | --- | --- | | 平衡推荐 | 兼顾轮廓、色块和五官细节，适合作为默认选择。 | | 轮廓清晰 | 加强深色线条和角色外形。 | | 色块平滑 | 合并近似颜色，减少零散杂点。 | | 细节保留 | 优先保留眼睛和小面积装饰。 | | 经典取样 | 按每格占比最高的颜色直接生成。 | | 柔和过渡 | 降低明暗反差，保留柔和层次。 | | 鲜明色彩 | 提高色彩浓度和主体表现力。 | | 高对比度 | 强化明暗关系和视觉识别度。 | | 主色优先 | 优先采用格内占比最大的颜色。 | | 中心采样 | 优先采用每格中心区域的颜色。 | 点击算法卡片可以查看预览，点击“使用”确认。生成后仍可通过左侧栏的“选择其他效果”随时切换算法。 所有算法均为纯前端本地计算，不依赖 AI 服务。算法效果会受到原图构图、背景复杂度、线条粗细和固定 40 色色卡的影响，建议实际比较后选择最合适的一版。 ### 4. 查看和移动画布 左侧“画布导航”包含： - 拼豆图缩略图。 - 当前可视区域框。 - `100%` 至 `300%` 的竖向缩放滑杆。 放大后，在导航缩略图中按住并拖动即可移动当前画布视口。为了减少误操作，PC 和移动端都不使用滚轮或双指手势缩放。 ### 5. 网格、高亮和坐标 右侧控制区提供三个开关： #### 显示网格 控制画布和下载图片中的网格线。关闭后下载的 PNG 也不会包含网格。 #### 高亮所有同色格 默认开启。点击一个格子后，所有相同颜色的格子都会显示高亮描边。 - 再次点击最初的格子，会取消高亮。 - 点击当前高亮组中的任意其他同色格，也会立即取消整组高亮。 - 关闭该开关后，只高亮单个格子。 高亮只是浏览器中的辅助效果，不会写入下载图片。 #### 显示单元格坐标 默认关闭。开启后，每个格子内部会显示坐标： - 坐标采用 `列,行` 的 0 基格式。 - 左上角为 `0,0`。 - 右上角为 `23,0`。 - 左下角为 `0,23`。 - 右下角为 `23,23`。 - 浅色块使用纯黑文字，深色块使用纯白文字。 坐标仅用于制作辅助，不会写入下载图片。移动端空间较小时，可以配合画布缩放查看。 ### 6. 编辑拼豆图 点击右侧“进入编辑模式”。进入编辑模式后： 1. 从方舟标准色卡中选择一种颜色。 2. 点击单元格进行单格填色。 3. 按住并拖过多个单元格，可连续填充经过的位置。 点击编辑工具栏中的吸管按钮，再点击任意单元格，可以立即选中该格对应的标准色卡颜色。 再次点击当前选中的色卡，可以取消颜色选择。 编辑工具栏包含四个图标按钮： - **回退**：撤销上一步操作。 - **前进**：恢复刚刚撤销的操作。如果撤销后进行了新的编辑，前进记录会被清空。 - **恢复初始状态**：恢复到本次进入编辑模式时的画面。该恢复动作本身仍可撤销。 - **取色**：点击后从画布单元格吸取颜色，并自动选中对应色卡。 一次点击算一步操作；一次按住拖动无论经过多少格，都只算一步操作。 点击“退出编辑模式”时必须确认。选择“继续编辑”会返回编辑状态；选择“确认退出”会保留当前修改并退出编辑模式。 ### 7. 下载图片 点击左侧栏底部的“下载图片”，浏览器会保存： - 文件名：`奇象巡展拼豆图-24x24.png` - 尺寸：`1200 × 1200` - 格式：PNG - 内容：当前颜色矩阵，以及当前的网格显示状态 同色高亮、单元格坐标、缩放比例和导航视口不会写入下载图片。 ## PC 与移动端 ### PC - 左侧为上传、画布导航和下载区域。 - 中间为拼豆画布。 - 右侧为显示控制、编辑工具和 40 色方舟标准色卡。 ### 移动端 - 画布优先显示。 - 上传和导航区域位于画布下方。 - 色卡始终保持每行 4 列，颜色顺序与 PC 端一致。 - 使用导航缩略图移动视口，使用竖向滑杆缩放。 ## 隐私与数据 - 项目没有图片上传接口。 - 图片不会主动发送到服务器。 - 图片处理使用浏览器的 Canvas API 完成。 - 项目不会自动保存图片、编辑历史或生成结果。 - 刷新或关闭页面前，请先下载需要保留的结果。 如果将本项目部署到第三方平台，平台自身可能记录常规访问日志；这与本工具的图片处理逻辑无关。 ## 本地开发 ### 环境要求 - Node.js 20 或更高版本（推荐） - npm 10 或更高版本（推荐） - 支持现代 Canvas、Pointer Events 和 CSS Grid 的浏览器 ### 安装依赖 ```bash npm install ``` ### 启动开发服务器 ```bash npm run dev ``` 根据终端显示的本地地址在浏览器中打开项目，默认通常为： ```text http://localhost:5173 ``` ### 生产构建 ```bash npm run build ``` 构建结果位于 `dist/` 目录。 ### 本地预览生产构建 ```bash npm run preview ``` ## 静态部署 本项目为纯前端 Vite 应用，不需要数据库或后端服务。执行 `npm run build` 后，可以将 `dist/` 目录部署到任意静态网站服务。 部署时请确保： - `index.html` 与 `assets/` 目录保持原有相对结构。 - 服务器能正确返回静态资源。 - 如果放在子路径下，按部署平台要求配置 Vite 的 `base`。 - 部署和使用行为符合本项目的非商业许可要求。 ## 技术栈 - React - TypeScript - Vite - Lucide React - Canvas API - Pointer Events ## 项目结构 ```text ark-pd/ ├─ src/ │ ├─ App.tsx # 页面状态与主要工作流 │ ├─ components.tsx # 画布、导航、色卡、裁剪和弹窗组件 │ ├─ image.ts # 24 × 24 取样、颜色匹配、算法和导出 │ ├─ palette.ts # 40 色方舟标准色卡 │ ├─ styles.css # PC 与移动端样式 │ └─ main.tsx # React 入口 ├─ LICENSE ├─ README.md └─ package.json ``` ## 贡献 欢迎在非商业目的下： - 提交问题和改进建议。 - 修复界面或算法问题。 - 增加测试和文档。 - Fork、修改并重新分发项目。 重新分发时必须同时保留本项目的许可条款或官方许可链接。贡献代码前，请确认你的贡献可以在相同许可条件下发布。 ## 许可 本项目采用 [Apache License 2.0](./LICENSE)。 简单来说： - 允许个人学习、研究、实验、娱乐和其他非商业用途。 - 允许在非商业目的下修改和创建衍生作品。 - 允许在非商业目的下复制和分发，并须保留许可条款。 - 允许慈善组织、教育机构、公共研究机构、公共安全或健康组织、环保组织和政府机构按许可条款使用。 - **禁止任何商业用途或预期用于商业应用的用途。** - 商业使用、商业部署、收费服务、广告变现、企业业务使用或其他商业场景，必须事先取得版权所有者的单独书面授权。 由于禁止商业用途，该许可不符合 OSI 对“开源软件”的严格定义；更准确的说法是“源码可用、非商业许可”。完整、具有法律效力的条款以 [`LICENSE`](./LICENSE) 中的英文原文为准。 本说明只是便于理解的摘要，不构成法律意见。