anitty 0.1.0

Anime character animation rendering for terminals
Documentation
# CLI 示例

命令从仓库根目录执行。示例用于测试库的渲染与协议输出,不是需要全局安装的播放器。
日常播放使用 `--release`;`--help` 列出完整参数。

## 不需要外部素材的体验

```sh
# 内置角色;在 Unix 上自动探测并选择 backend。
cargo run --release --example sprite

# 单独探测终端,默认等待最多 300ms,不播放动画。
cargo run --example probe
cargo run --example probe -- --timeout-ms 1000

# 仓库自带的微型 Spine 测试素材。
cargo run --release --features spine-38 --example spine -- tests/fixtures/spine/sample.skel --list
cargo run --release --features spine-38 --example spine -- tests/fixtures/spine/sample.skel --animation move
```

Spine fixture 用于检验网格与裁剪,不是完整角色素材。使用真实角色时替换骨骼与 atlas 路径。
`probe` 当前支持 Unix,可通过重定向 stdout 保存文字报告;查询本身通过控制终端传输。

## 自定义 Sprite 图集

`character.webp` 是你提供的规则图集。以下示例假定单元格为 64 × 64 像素:

```sh
cargo run --release --example sprite -- character.webp --frame-width 64 --frame-height 64 --row 0 --frame-ms 100
```

PNG 和 WebP 均可。必须明确区分切图尺寸和输出画布尺寸:

| 参数 | 含义与默认值 |
| --- | --- |
| `--frame-width`/`--frame-height` | 图集单元格尺寸,默认 **192 × 208**,不是自动推断 |
| `--row` | 从零开始的动作行,默认 0 |
| `--frames` | 该行从左开始取前 N 格;省略时只去掉行尾全透明格 |
| `--frame-ms` | 默认每帧 100ms,同时作为绘制间隔 |
| `--width`/`--height` | 输出画布像素尺寸,默认各自等于单元格尺寸 |

显式 `--frames` 保留所选范围中的透明格;省略时仍保留中间透明帧。
例如一行只有前 6 格有内容,指定 8 帧会周期性播放两张空白帧。
库本身不自动裁掉透明帧,这个选择规则由 CLI 实现。

仓库自带的小图集也可用于检查参数:

```sh
cargo run --release --example sprite -- tests/fixtures/sheet.png --frame-width 2 --frame-height 2 --width 64 --height 64
```

## 命名动作

使用可重复的 `--clip NAME:ROW[:FRAMES[:MS]]` 将不同行定义为动作:

```sh
cargo run --release --example sprite -- character.webp --frame-width 64 --frame-height 64 --clip idle:0 --clip walk:1 --list
cargo run --release --example sprite -- character.webp --frame-width 64 --frame-height 64 --clip idle:0 --clip walk:1 --animation walk
```

`--clip` 需要图集路径,不能与 `--row`/`--frames` 混用。省略 FRAMES 时去掉该行尾部空格;
省略 MS 时使用 `--frame-ms`。独立指定 MS 时必须同时提供 FRAMES,如 `--clip idle:0:6:140`。
每个动作的帧时长可不同,但示例绘制间隔始终由 `--frame-ms` 决定。

`--list` 打印动作与时长后退出,不探测终端;`--animation NAME` 选择初始动作。
不定义片段时 Sprite 的动作名为 `default`。Spine 的动作名来自素材,大小写必须匹配。

## Spine 素材

```sh
cargo run --release --features spine-38 --example spine -- character.skel --list
cargo run --release --features spine-38 --example spine -- character.skel --animation walk --width 256 --height 256
cargo run --release --features spine-38 --example spine -- character.skel --atlas textures/character.atlas --pma
```

默认读取同名 `.atlas`,纹理相对 atlas 目录加载。仅支持配套的 Spine 3.8 二进制资源。
`--pma` 表示纹理已预乘 alpha,应与导出设置一致。画布默认 256 × 256,绘制间隔默认 80ms。
不指定动作时使用第一个导出动作;它可能是静态姿势。更多限制见 [Spine 指南](spine.md)。

## 通用播放与变换

两个动画示例的交互键相同:

| 按键 | 行为 |
| --- | --- |
| `[`/`]` | 按列表切换动作并从头播放 |
| `r` | 当前动作从头重播 |
| `q`/`Esc`/`Ctrl+C` | 退出并恢复终端会话 |

`--play-once` 播放一次后保持最后一帧,直到手动退出;切换或重播后再次从头播放。
以下参数同时适用于 Sprite 和 Spine:

| 参数 | 含义 |
| --- | --- |
| `--flip-x`/`--flip-y` | 水平/垂直镜像 |
| `--scale X,Y` | 基础适配后的缩放,负值可镜像,不能为零 |
| `--rotate DEGREES` | 顺时针旋转,单位是度;Rust API 使用弧度 |
| `--translate X,Y` | 输出画布内的像素偏移 |
| `--pivot X,Y` | 画布中的变换中心,默认画布中心 |
| `--view X,Y,W,H` | 固定来源取景矩形 |
| `--opacity N` | 整体透明度,范围 0–1 |

```sh
cargo run --release --example sprite -- --width 128 --height 128 --flip-x --rotate 15 --opacity 0.7
```

字段按参数出现顺序赋值,后面的 `--scale` 会覆盖前面镜像参数设置的缩放。
变换顺序与坐标单位见 [渲染指南](rendering.md)。示例使用固定的输出尺寸,不自动响应窗口尺寸变化。

## Backend 与背景

两个示例都支持 `--backend auto|iterm2|kitty|sixel`,默认 `auto`。
Unix 交互模式优先选择已知 Konsole/iTerm2 的 PNG 路径,其次已确认的 Kitty,再次 SIXEL;
无法确定时返回错误,可显式指定 backend。

```sh
cargo run --release --example sprite -- --backend kitty
cargo run --release --example sprite -- --backend sixel
cargo run --release --example sprite -- --backend sixel --sixel-background '#242828'
```

显式 iTerm2/Kitty 跳过探测。SIXEL 的背景默认 `auto`,Unix 交互模式仍会尝试查询终端默认背景;
未知时提示并使用黑色。指定 `#RRGGBB` 可跳过背景探测。非 Unix 平台需要手动选择 backend,
并自行指定需要的 SIXEL 背景。

`--sixel` 是 `--backend sixel` 的别名,重复选择时最后一项生效。
Kitty 示例固定使用图像 ID 1、2,运行时应保证它们未被同一屏幕上的其他程序占用。

## 单帧导出

`--once` 导出时间零的一帧协议数据,不进入交互模式、不探测、不切换终端模式。
它与 `--play-once` 不同。`auto` 在导出模式固定使用 iTerm2 PNG:

```sh
cargo run --release --example sprite -- --once > /tmp/anitty.ansi
cargo run --release --example sprite -- --backend sixel --sixel-background '#242828' --once > /tmp/anitty.sixel
```

这些文件包含终端控制序列,不是独立 PNG;只能在支持对应协议的终端中显示。
SIXEL 导出未指定 RGB 时使用黑色。Kitty 导出保留所显示的图像,不自动 `finish`;
要管理它的完整生命周期,应使用 Rust API。

## 显示问题排查

- **黑色矩形**:SIXEL 默认黑底。指定背景色,或在支持的终端改用保留 alpha 的 backend。
- **周期性消失**:检查帧范围是否包含空白格,尤其是显式指定 `--frames` 时。
- **闪烁或残影**:避免逐帧清屏,保持画布位置和尺寸固定,并检查终端的图像替换能力。
- **滚屏或底部条纹**:确保视口能容纳输出;SIXEL 高度向上补齐到 6 的倍数。
- **CPU 占用高**:使用 release 构建,按实际需求设置画布尺寸与绘制间隔。
- **auto 无法识别**:运行 `probe` 查看证据状态,增加探测等待时间,或显式选择协议。

`probe --timeout-ms` 只设置独立探测命令的等待时间,播放示例的探测上限固定为 300ms。
I/O 成功不代表终端支持;协议透传、远程带宽和宿主输出冲突也会影响结果。