ToonComposer 入门与实践：把“补帧+上色”两道工序合并成一键生成

一句话看懂 ToonComposer

传统动画制作要经历“原画→补帧→上色”三步；ToonComposer 把后两步合并成“生成后原画”（Post-Keyframing）——只需一张彩色参考图 + 少量关键帧线稿，就能自动生成完整动画片段，极大减少手工工作量。

它到底解决了什么问题？

痛点 传统做法 ToonComposer 的做法
补帧难 需要多幅关键帧才能插出流畅动作 1 张关键帧也能插，支持任意时序的多张关键帧
上色累 每帧都要完整线稿 仅在关键帧画线稿，其余由模型补全
误差累积 先补帧再上色，前一步错误影响后一步 联合优化，减少跨阶段误差
风格漂移 真人视频模型直接做卡通会失真 专门设计的「空间低秩适配器」保留时间先验，只改外观

技术拆解：三个关键词

  1. 稀疏草图注入（Sparse Sketch Injection）
    在 DiT（Diffusion Transformer）的 token 序列里，把关键帧线稿当作“提示”插到对应时间点，模型就知道“第 7 帧人物手要抬到这里”。

  2. 空间低秩适配器（SLRA）
    冻结原模型的时间注意力，只对空间注意力加两个小矩阵（降维→卡通化→升维），既保留原模型对动作的理解，又把外观调成卡通。

  3. 区域控制（Region-wise Control）
    线稿不需要画满整张图：你想让背景自动生成，只需把背景涂黑，模型会自动补出合理的画面。

实际效果

  • 数据说话
    在作者自建的两个基准上，ToonComposer 的 LPIPS、DISTS、CLIP 等指标全面优于 AniDoc、LVCD、ToonCrafter。
    用户主观投票：71% 认为 ToonComposer 画质最好，69% 认为动作最流畅。

  • 真实场景
    用 B&T Studio 和 Gudong Animation 授权的动画片段做测试，生成结果与原作风格一致，肉眼难以分辨。

快速上手：10 分钟跑通 Demo

硬件/系统要求

  • NVIDIA GPU，显存 ≥ 16 GB
  • Python 3.10，PyTorch 2.6.0
  • CUDA ≥ 11.8

安装步骤

# 1. 克隆仓库
git clone https://github.com/TencentARC/ToonComposer
cd ToonComposer

# 2. 创建环境
conda create -n tooncomposer python=3.10 -y
conda activate tooncomposer
pip install -r requirements.txt
pip install flash-attn==2.8.0.post2 --no-build-isolation

启动界面

python app.py --device cuda:0 --resolution 480p

浏览器打开 http://localhost:7860，即可看到 Gradio 界面。

“

如果模型权重不在本地，第一次运行会自动从 Hugging Face 下载（约 14 GB）。

界面用法（附截图位置）

  1. 文本提示
    例：A girl with long hair waves her hand.

  2. 彩色参考帧
    上传一张 480×480 或 608×608 的彩色图，通常放在第 0 帧。

  3. 关键帧线稿
    在时间轴上点选帧号 → 上传对应线稿。
    支持多次添加，最少 1 张即可运行。

  4. 区域蒙版（可选）
    用黑色笔刷在线稿上涂黑，告诉模型“这块你自由发挥”。

  5. 高级旋钮

    • CFG Scale：提示词强度，默认 7.5。
    • Position-aware Residual Scale：线稿控制力，0 为完全自由，1 为严格遵循。

  6. 点击 Generate
    进度条跑完后，右侧直接播放生成视频，可下载 MP4。

FAQ：你可能想问的 10 个问题

Q1：只能做 2D 日式动画吗？
A：作者额外做了一个小规模 3D 渲染动画微调，效果同样可用，见补充视频。

Q2：没有美术基础，线稿很潦草可以吗？
A：训练时使用了 4 种自动线稿生成器 + 1 个人工线稿混合数据，对潦草线条有一定鲁棒性，但清晰线稿效果最佳。

Q3：能否一次生成 1 分钟以上？
A：当前官方示例最长 69 帧（≈ 3 秒）。长序列可分段生成后人工衔接。

Q4：商用授权？
A：权重放在 Hugging Face，遵循仓库 LICENSE；训练数据已获 B&T Studio 等授权，但用户需确保输入素材合法。

Q5：显存不足怎么办？
A：

  • 用 --resolution 480p
  • 关 flash-attn，改 --no-flash
  • 降低帧数

Q6：如何离线部署？
A：先手动下载
huggingface-cli download TencentARC/ToonComposer
再设置环境变量：

export WAN21_I2V_DIR=/path/Wan2.1-I2V-14B-480P
export TOONCOMPOSER_DIR=/path/TencentARC-ToonComposer

Q7：为什么生成结果和预览不一致？
A：扩散模型本身有随机性，可调 seed、步数或线稿强度重试。

Q8：能否只补帧不上色？
A：把彩色参考帧设为线稿即可，但这不是设计初衷，效果可能一般。

Q9：训练代码会公开吗？
A：论文中已给出完整训练目标与超参，仓库暂未放出训练脚本。

Q10：未来会支持 4K？
A：作者提到受限于 DiT 内存，目前仅 480p/608p，后续会研究分层超分。

深入阅读：论文要点速记

章节 一句话总结
3.1 Post-Keyframing 把补帧和上色合并成单阶段扩散任务
3.2 Sparse Sketch Injection 用 RoPE 位置编码把线稿 token 插到任意时间点
3.3 SLRA 只改空间注意力，不改时间注意力，保住动作流畅度
3.4 Region-wise 训练时随机 mask 部分线稿，让模型学会“补空白”
4.1 PKBench 30 组真人手绘线稿 + 彩色参考，公开基准
4.5 Ablation 去掉 SLRA 或改成 LoRA，指标立刻下降，证明结构有效

结语：把精力还给创意

ToonComposer 并不是要取代动画师，而是把最耗时、最机械的补帧和上色自动化，让创作者把注意力放在故事和关键动作设计上。如果你正被大量中间帧折磨，或者想快速验证分镜，不妨打开浏览器，上传一张彩图、画几根线，十分钟就能看到动画动起来。

项目主页：https://lg-li.github.io/project/tooncomposer
在线体验：Hugging Face Space