loadimg

Gemfile

@@ -2,9 +2,8 @@ source "https://rubygems.org/"
 gem "jekyll-remote-theme"
 gem "webrick"
 gem "csv"
-gem "github-pages", group: :jekyll_plugins
 
 group :jekyll_plugins do
+    gem "github-pages"
     gem 'jekyll-commonmark-ghpages'
 end
-

dev/README.md

@@ -6,4 +6,5 @@ sort: 6
 
 1. [开发环境](./environment)
 2. [版本与分支](./branch)
-3. [文档的编写与构建](./doc)
+3. [文档](./doc)
+4. [图像处理基础函数](./image)

dev/branch.md

@@ -4,7 +4,7 @@ sort: 2
 
 # 版本与分支
 
-Mower 同时维护两个分支：测试版与稳定版。新功能的开发以及 bug 修复都测试分支上进行。然而，对代码的改动可能引入新的 bug，功能的变动也需要用户不断地学习和适应，使用测试版可能不时遇到新的 bug。对于没有精力跟踪 mower 开发进度，或希望获得稳定体验的用户，稳定版也是必不可少的。
+Mower 同时维护两个分支：测试版与稳定版。新功能的开发以及 bug 修复在测试分支上进行。然而，对代码的改动可能引入新的 bug，功能的变动也需要用户不断地学习和适应，使用测试版可能不时遇到新的 bug。对于没有精力跟踪 mower 开发进度，或希望获得稳定体验的用户，稳定版也是必不可少的。
 
 ## 版本号
 
@@ -22,12 +22,12 @@ Mower 使用 GitHub Actions 自动为 Windows 平台打包。打包过程中，
   if: github.event.head_commit.message != '发版'
   shell: bash
   run: |
-    sed -i 's/__version__ = "\(.*\)"/__version__ = "\1+${GITHUB_SHA::7}"/g' ./arknights_mower/__init__.py
+    sed -i "s/__version__ = \"\(.*\)\"/__version__ = \"\1+${GITHUB_SHA::7}\"/g" ./arknights_mower/__init__.py
 ```
 
 当提交信息是“发版”时，CI 不会修改版本号；反之，CI 会把 commit id 的前 7 位附加到版本号后面，使用加号分隔。
 
-- 测试版使用滚动更新，版本号格式为 `YYYY.MM+<commit id>`，其中 `YYYY` 为四位年份，`MM` 为两位月份，`<commit id>` 为 commit id 的前 7 位。测试版代码的 `__version__` 中只写 `YYYY.MM` 的部分，靠 CI 自动添加 commit id。
+- 测试版使用滚动更新，版本号格式为 `YYYY.MM+<commit id>`，其中 `YYYY` 为四位年份，`MM` 为两位月份，`<commit id>` 为 commit id 的前 7 位。测试版代码的 `__version__` 中只写 `YYYY.MM` 的部分，由 CI 自动添加 commit id。
 - 稳定版使用定点更新，版本号格式为 `YYYY.MM.X`，其中 `X` 为小版本号。创建分支时 `X` 为 1，以后每次发版时，需手动增加 `X`，并将提交信息设为“发版”。
 
 ## 日志页背景

dev/doc.md

@@ -2,11 +2,11 @@
 sort: 3
 ---
 
-# 文档的编写与构建
+# 文档
 
-文档使用 Jekyll 框架，源码在 [doc-pages 分支](https://github.com/ArkMowers/arknights-mower/tree/doc-pages)。
+文档使用 Jekyll 框架，源码在 [doc-pages 分支](https://github.com/ArkMowers/arknights-mower/tree/doc-pages)，使用 [Publishing from a branch](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-from-a-branch) 的方式自动部署到 GitHub Pages。
 
-预览与构建文档，需要安装 Ruby 3.3 和 Bundler。
+在本地预览与构建文档，需要安装 Ruby 3.3 和 Bundler。
 
 ## 安装依赖
 
@@ -27,3 +27,28 @@ bundle exec jekyll build -b /docs
 ```
 
 将生成的 `_site` 复制到 `<mower 文件夹>/dist/docs`，就可以在 mower 中看到文档了。
+
+GitHub Actions 为 Windows 打包 mower 时，会构建文档，随 mower 分发。
+
+## 嵌入 Jupyter Notebook
+
+```bash
+jupyter nbconvert notebook.ipynb --to html --template basic
+```
+
+将转换得到的 html 文件移至 `_includes/` 文件夹下。
+
+在 Markdown 中引入：
+
+```liquid
+{% raw %}{% include notebook.html %}{% endraw %}
+```
+
+如果内容较长，可以放在 `<details>` 标签中：
+
+```liquid
+<details>
+<summary>使用示例</summary>
+{% raw %}{% include notebook.html %}{% endraw %}
+</details>
+```

dev/image.md

@@ -0,0 +1,39 @@
+---
+sort: 4
+---
+
+# 图像处理基础函数
+
+Mower 使用 OpenCV 处理图像，颜色通道顺序为 RGB。
+
+## 加载与显示图像
+
+### `loadimg()`
+
+`arknights_mower/utils/image.py` 中提供了用于读取图像的函数 `loadimg()`。`loadimg()` 接受两个参数，第一个参数 `filename` 是图片文件名，第二个参数 `gray` 为 `True` 时返回灰度图像，否则返回 RGB 顺序的彩色图像。`gray` 默认为 `False`。
+
+`loadimg()` 使用 `lru_cache` 以避免反复加载相同的文件。可使用 `loadimg.cache_clear()` 清除 LRU 缓存。
+
+### `loadres()`
+
+Mower 用于识别的图像素材全部位于 `arknights_mower/resources` 以及热更新目录 `tmp/hot_update` 下。使用 `loadimg()` 加载这些图片时，需要拼接出完整的路径，较为繁琐。`loadres()` 函数可简化从上述位置加载图片的过程。它接受两个参数，第一个参数 `res` 是图片资源名，第二个参数 `gray` 与 `loadimg()` 中保持一致。
+
+图片资源名的规则如下：
+
+1. 对于 `arknights_mower/resources` 下的 png 文件，只需写出相对 `resources` 的路径，并省略扩展名；
+2. 以 `@hot/` 表示热更新目录 `tmp/hot_update`；
+3. 对于 jpg 文件，在资源名中需要保留 `.jpg` 后缀。
+
+| 资源名                             | 文件名                                             |
+| ---------------------------------- | -------------------------------------------------- |
+| `ope_select_start`                 | `arknights_mower/resources/ope_select_start.png`   |
+| `navigation/episode`               | `arknights_mower/resources/navigation/episode.png` |
+| `@hot/dragon_boat_festival/banner` | `tmp/hot_update/dragon_boat_festival/banner.png`   |
+| `@hot/hortus/terminal.jpg`         | `tmp/hot_update/hortus/terminal.jpg`               |
+
+`loadimg()` 与 `loadres()` 加载的图像，可直接用 `matplotlib` 显示。
+
+<details>
+<summary>使用示例</summary>
+{% include loadimg.html %}
+</details>

start/riic.md

@@ -6,7 +6,7 @@ sort: 2
 
 基建是 mower 的核心功能。然而，用 mower ≠ 产出高，玩家只有提高自身的基建理解，才能充分发挥 mower 的作用，取得更高的收益。因此，本篇文档先讲解必要的基建知识，然后说明 mower 的各项基建功能对于提高产出的作用。
 
-新手建议阅读《[Mower 简明教程](https://blog.zhaozuohong.vip/2024/05/10/mower-guide/tutorial/)》，加入 QQ 频道 [ArkMower（频道号：2r118jwue4）](https://pd.qq.com/s/5t91c3gx9)交流基建心得。
+新手建议阅读《[Mower 简明教程](https://blog.zhaozuohong.vip/2024/05/10/mower-guide/tutorial/)》，加入 QQ 频道 [ArkMower（频道号：2r118jwue4）](https://pd.qq.com/s/5t91c3gx9)交流基建。
 
 ## 产出计算教程