# 分层图像工作台使用说明

在项目根目录运行 `python scripts/serve_web.py`，然后访问
http://127.0.0.1:8765/ 。如果已有服务正在运行，停止旧服务后重新启动。
所有脚本、字体和示例都在本机，文件不会上传。

## 先体验真实原稿

默认载入 David Revoy 为 Capitole du libre 2023 创作的海报插画。
它包含作者原来的 7 个绘画图层和 1 个图层组，保留线稿、底色、修饰、
阴影、隐藏的草稿及粗线稿备选。我们仅转换格式、缩小尺寸、翻译图层名称，
没有从成品图片猜测图层，也没有另加图画内容。来源和授权见左下角及
`LICENSES/capitole-artwork-NOTICE.txt`。

1. 点击“阴影”旁的眼睛，再打开，观察颜色和明暗变化。
2. 隐藏“线稿”，看底色怎样独立存在；重新打开线稿。
3. 选择“线稿”，在蓝色框内拖动，线条会跟随移动，底色保持原位。
   这会让原稿的线条与颜色错位，恰好能看清两者是独立图层。
4. 点击“撤销”，一次撤回整个拖动。可显示草稿，但草稿会与完成稿叠加。

一个绘画层里可能有多个物体，移动时它们会一起移动。
例如这份原稿的线稿层包含多只企鹅，不能仅靠拖动单独移动其中一只。
本项目处理原稿已有的图层，不会自动识别或拆分层内物体。

## 常用操作

| 操作 | 方法 |
| --- | --- |
| 移动整层 | 选择绘画层，拖动蓝色框；也可填写 X、Y 后应用 |
| 撤销 / 重做 | 顶栏按钮，或输入框外按 Ctrl+Z / Ctrl+Shift+Z（也支持 Ctrl+Y） |
| 放大 / 缩小 | 在画布上滚轮，或使用上方的 − / ＋ |
| 查看原始像素大小 | 点击 100% |
| 全图显示 | 点击“适应” |
| 平移画布 | 按住空格拖动、按鼠标中键拖动，或启用“手形”后拖动 |
| 对照导入时的画面 | 勾选“对照原始画面”；此时不显示可拖动选框 |
| 导入 PNG 为图层 | 左侧“导入 PNG”；选中组时放入该组，否则放在当前同级最上方 |
| 替换某层图片 | 选择绘画层后点击“替换 PNG”；保留名称、位置和混合属性 |
| 新建图层组 | 左侧“新建组”；再用右侧“移入图层组”整理现有层 |
| 复制 / 删除 / 排序 | 右侧图层管理和图层顺序按钮；复制支持整个嵌套组 |
| 锁定 | 右侧“锁定图层”；锁定组同时保护其子层 |
| 单层导出 | 右侧“导出此层 PNG” |
| 全部层导出 | 左侧“提取全部层”，下载 PNG 和 `layers.json` 的压缩包 |
| 整图导出 | 顶栏“导出 PNG” |
| 保留分层继续编辑 | 顶栏“保存 ORA”，可在 Krita 中重新打开 |

## 几个容易误会的地方

- “图层名称”只改变列表中的名字，不会更改已经画成像素的文字。
- 实时拖动使用最长边 384 像素的临时预览，和导出共享 MoonBit 的混合与
  图层组规则。预览中的缩放取样和坐标取整可能与全尺寸不同；松手后使用
  完整分辨率重新合成，导出不使用临时预览。
- 一次拖动只占一个撤销步骤。按 Esc、取消触摸或窗口失去焦点时放弃这次拖动。
- 撤销最多 20 步，并按图层像素内存自动缩短，超过范围的旧步骤会释放。
  重新导入文档或重载示例后历史清空；撤销后做新编辑会清空重做分支。
- 锁定只影响这次网页编辑，不写入 ORA；结构操作、撤销和重做后会清除锁定。
- 单层导出提取的是图层本身，保留该层尺寸和原始像素，不把整层透明度、
  位置、混合方式烘焙进去。压缩包清单记录这些属性和原始图层路径。
- 浏览器最多导入 32 MiB 文件。高位深、需色彩管理的输入等可能仅能查看原始
  预览；不能可靠重新计算的文件不开放编辑，可原样保存。

## 如何检查修改成功

先移动线稿，保存 ORA，再用“打开 ORA”载入刚保存的文件，检查位置、图层和
画面。再用 Krita 打开该文件，确认依然是独立图层。

开发者验证：

```sh
moon test --target js
python scripts/build_web.py
node scripts/check_bridge.mjs
node scripts/check_editor.mjs
python scripts/check_artwork.py
```

浏览器完整操作回归：在 `tests/browser` 下运行 `npm ci`，安装 Playwright 的
Chromium（`npx playwright install chromium`），然后在项目根目录运行
`node tests/browser/check.mjs`。截图写入 `_build/editor-test/workbench.png`。


## 样例库与四步练习

点击顶栏“样例与练习”。每份作品都有“查看原稿”和“开始练习”两个入口。
原稿保持导出后的原始状态；练习有意调整了部分图层，供你修改，不能把练习起点当作作者的原稿。

| 样例 | 练习目标 |
| --- | --- |
| 自由之都 | 对齐线稿、隐藏草稿、用提供的原稿白底 PNG 替换浅绿背景，再导出 |
| 花间少女 | 隐藏完成稿补绘与预设色彩，保留明暗底稿，调整铅笔线条，制作素描变体 |
| 林间小屋 | 关闭透视辅助组、修复前景错位、恢复后期气氛，再导出 |
| 雨城 | 关闭黑白构图检查与透视线，把雨幕不透明度调到 20%–35%，制作小雨版本 |

练习区会自动检查当前图层状态。“定位图层”帮你选中要操作的层；你可以用
右侧属性、眼睛按钮或拖动完成，也可以使用指引提供的参考值按钮。
“参考成图”可对照练习前后的效果。“更换背景”步骤还提供可下载的原稿 PNG，
无需另找图片。需要替换的是整层图片，而不是画面里的某一个物体。

一次练习有三个改图步骤和一个导出步骤。前三步完成后，点击“导出 PNG”，
也可以用顶栏保存 ORA，保留图层结构。任务按参考条件检查，不妨碍你随时自由导出。

完成状态会随文档变化：撤销可能使任务重新变成待完成；更改已经导出的图像后，
需要再次导出。重新练习会清空这次进度。切换样例、重置或打开其他文件前，
若改动尚未保存为 ORA，页面会让你选择保留当前编辑或放弃后切换。
重开导出的 ORA 会按普通本地文件处理，不会自动恢复练习身份。

新增样例保留原始图层与转换说明。雨城原 KRA 的两项调整效果由 Krita 烘焙为
可交换的栅格结果，网页不承诺重新编辑这些 KRA 调整器。来源见每份作品左下角。

样例与练习的额外验证：

```sh
node scripts/check_samples.mjs
python scripts/check_sample_pixels.py
node tests/browser/samples.mjs
```

完整浏览器验证需要先安装前文列出的 Playwright 环境。原始源文件的哈希、
原名称与译名、Krita 像素对照记录在 `fixtures/sample-validation.json`。
