企业官网建设流程全解析

AnimatedDrawings 排错手册：5 个阶段 16 种报错一次讲清，从第一次运行崩溃到成功导出视频

【免费下载链接】AnimatedDrawingsCode to accompany "A Method for Animating Children's Drawings of the Human Figure"项目地址: https://gitcode.com/GitHub_Trending/an/AnimatedDrawings

这是一份面向 AnimatedDrawings（AI 动画化儿童简笔画）的故障排除与错误处理实操指南，覆盖环境安装、TorchServe 标注服务、图像自动标注、BVH 动作重定向、视频导出五个阶段中最常踩的坑，每条都给出报错现场、判断特征、修复步骤和验证方法，帮你 10 分钟内独立定位并修好问题。

阶段 0｜把安装环境一次装对

conda create 直接报架构错

• 报错现场：M 系列芯片的 Mac 上建环境，输出里出现一堆osx-64版本的包，随后安装失败或运行时报 architecture 相关错误。
• 快速判断：只有 Apple Silicon 用户会中招；看conda create的 NEW packages 列表，装的是osx-64而不是osx-arm64就是它。
• 修复路径：
  1. 编辑~/.condarc，把subdirs里的osx-64删掉，只留osx-arm64和noarch
  2. 执行conda clean --all清缓存后重建环境
• 验证通过：再次conda create，NEW packages 列表全部是osx-arm64。

pip install -e . 卡在 libGL

• 报错现场：终端弹出一串ImportError: libGL.so.1: cannot open shared object file或 OpenGL 相关编译错误。
• 快速判断：常见于没装图形库的 Ubuntu 服务器和全新系统。本项目依赖 setup.py 锁定的PyOpenGL==3.1.6和 glfw，缺系统库就会炸。
• 修复路径：
  1. 先补系统依赖：sudo apt-get install libgl1-mesa-dev freeglut3-dev（macOS 则brew install freeglut）
  2. 重新执行pip install -e .
• 验证通过：python -c "import OpenGL, glfw"无报错输出。

render.start 不弹窗口或直接崩溃

• 报错现场：粘进两行render.start(...)后屏幕无窗口，或进程直接挂掉。
• 快速判断：九成是控制器模式和渲染后端冲突——mvc_base_cfg.yaml 里interactive模式与USE_MESA: True互斥。
• 修复路径：
  1. 本地看窗口：确认controller.MODE: interactive且view.USE_MESA: False
  2. SSH 远程无显示环境：改MODE: video_render并设USE_MESA: True走无头渲染
• 验证通过：本地能弹出交互窗口，空格暂停、方向键倒带、q 退出。

阶段 1｜把 TorchServe 标注服务拉起来

curl (52) Empty reply from server

• 报错现场：docker run之后curl http://localhost:8080/ping返回curl: (52) Empty reply from server。
• 快速判断：两种可能——服务还在初始化，或 Docker 内存不足。用docker logs docker_torchserve区分：日志正常滚动就是前者，出现 OOM 就是后者。
• 修复路径：
  1. 等 10 秒重试（镜像构建本身要 5-7 分钟，属正常）
  2. 日志显示内存不足时，把 Docker Desktop 的容器内存调到 16GB 后重启容器
• 验证通过：ping 返回{"status": "Healthy"}。

Could not detect any drawn humanoids

• 报错现场：跑image_to_animation.py时 assert 抛出Could not detect any drawn humanoids in the image. Aborting。
• 快速判断：检测器只认"人形简笔画"——复杂背景、背面朝向、遮挡严重的图容易检不到。
• 修复路径：
  1. 先用仓库自带的蒜宝宝示例图 examples/drawings/garlic.png 跑一遍，确认服务链路本身没问题
  2. 换成正面朝向、背景干净的图，尺寸控制在 512-1024 像素
• 验证通过：日志出现Detected 1 humanoids in image。

检测请求返回 404

• 报错现场：报错里提到drawn_humanoid_detector.mar，响应体带code: 404。
• 快速判断：torchserve/model-store/里缺 .mar 模型文件，手动装 torchserve 时跳过了模型下载步骤。
• 修复路径：
  1. 确认model-store/下同时有drawn_humanoid_detector.mar和drawn_humanoid_pose_estimator.mar
  2. Mac 本地方案直接补跑 torchserve/setup_macos.sh，它会 wget 这两个文件
• 验证通过：重跑标注命令，检测请求不再 404。

8080 端口被占用

• 报错现场：本地起 torchserve 时提示 address already in use。
• 快速判断：上一个容器或残留进程还占着 8080。注意 examples/image_to_annotations.py 把http://localhost:8080写死在请求里，所以换端口不如腾端口。
• 修复路径：
  1. lsof -i :8080找到 PID 后杀掉
  2. 重启 torchserve
• 验证通过：ping 返回 Healthy，且占端口的进程列表里只剩 torchserve。

阶段 2｜让标注结果正确

mask 有洞，角色残缺或背景没分离

• 报错现场：生成的动画里角色缺胳膊少腿，或白色背景被贴到身上。
• 快速判断：打开输出目录（如garlic_out/）里的mask.png——角色区域应为纯白、背景纯黑，模型偶发漏分割。
• 修复路径：
  1. 用任意图像编辑工具把 mask 涂成角色纯白、背景纯黑
  2. 重跑python annotations_to_animation.py garlic_out/
• 验证通过：输出视频中角色轮廓完整、背景透明。

关节点没标对，肢体乱飞

• 报错现场：角色动起来后手臂"脱臼"、头部位置飘忽。
• 快速判断：char_cfg.yaml里 skeleton 各关节的像素坐标（loc）与画面不符，用joint_overlay.png叠上去一眼就能看出来。
• 修复路径：
  1. python fix_annotations.py garlic_out/启动网页工具
  2. 浏览器打开http://127.0.0.1:5050，把关节拖到正确位置后 Submit
• 验证通过：重新渲染，肢体跟随骨架不再断裂。

标注目录缺文件

• 报错现场：FileNotFoundError或 YAML 解析失败。
• 快速判断：char_cfg.yaml 约定 texture.png 和 mask.png 必须与它同目录，且 skeleton 里必须有且仅有一个root（parent 为 null）。
• 修复路径：
  1. 对照 examples/characters/char1/ 的完整文件结构补齐缺失文件
  2. 确保 texture.png 尺寸与 char_cfg 里的 width/height 一致
• 验证通过：python -c "import yaml; yaml.safe_load(open('garlic_out/char_cfg.yaml'))"无报错。

阶段 3｜让 BVH 动作对得上角色

换自定义 BVH 直接 KeyError

• 报错现场：加载自己的 BVH 后报关节名找不到的错误。
• 快速判断：示例配置全是按 Mixamo 骨架写的（见 examples/config/retarget/fair1_spf.yaml 的char_joint_bvh_joints_mapping），换一套 BVH 关节名全变了。
• 修复路径：
  1. head -n 50 你的.bvh看 Hierarchy 段，记下真实关节名
  2. 新建 motion 配置（填forward_perp_joint_vectors、groundplane_joint、up）和 retarget 配置（把每个角色关节映射到一对 BVH 关节），可参考 Rokoko 导出示例 examples/config/motion/jesse_dance.yaml
• 验证通过：渲染无缺失关节，动作连续平滑。

蝌蚪人掉头

• 报错现场：头身一体的角色，做某些动作时脸朝下翻面。
• 快速判断：画里 neck 朝下，被旋转去对齐人体骨架时整张脸就翻了。
• 修复路径：
  1. 在 retarget 配置里加char_runtime_checks：当 neck 不在两肩连线上方时，自动跳过 neck 的映射（写法直接抄 fair1_spf.yaml 末尾那几行）
• 验证通过：动画全程脸部保持朝上。

想动四足动物

• 报错现场：非人形角色跑自动标注必然失败，因为检测器只认人形。
• 快速判断：标准管线只支持人形；四足、多臂等骨架必须手动搭。
• 修复路径：
  1. 参考 examples/quadruped/ 目录，手动写 char_cfg.yaml 并配专门的 four_legs retarget 配置，区分前后腿关节
  2. 用 examples/config/mvc/four_legs_example.yaml 这类 mvc 配置验证效果
• 验证通过：四足角色原地跑动，腿不穿模。

阶段 4｜把视频导出来

渲染跑完却没有视频文件

• 报错现场：命令正常结束，但目标目录空空如也。
• 快速判断：mvc 配置里controller.MODE还是interactive——这个模式下OUTPUT_VIDEO_PATH会被直接忽略。
• 修复路径：
  1. 改成MODE: video_render并指定OUTPUT_VIDEO_PATH（如./video.gif）
  2. 远程 SSH 执行时同时设view.USE_MESA: True
• 验证通过：指定目录出现 video.gif，浏览器能打开播放。

透明背景导不出来

• 报错现场：期望透明底，结果 MP4 背景是一整块白色。
• 快速判断：这个项目里透明通道只有 .gif 支持，MP4 按OUTPUT_VIDEO_CODEC（示例值为avc1）编码，必然不透明。
• 修复路径：
  1. 要透明底就把输出改成.gif
  2. 要高清就用.mp4，OUTPUT_VIDEO_CODEC可按需调整
• 验证通过：gif 放到白底页面显示镂空，mp4 在播放器正常播放。

多角色叠在一起

• 报错现场：场景里两个角色站同一位置互相遮挡。
• 快速判断：每个角色的落点由各自 retarget 配置的char_starting_location决定，默认都在原点。
• 修复路径：
  1. 照 examples/config/mvc/multiple_characters_example.yaml 的方式，给每个角色用单独的 retarget 配置，把 x 坐标错开（例如 -0.5 / +0.5）
• 验证通过：导出的 gif 中两角色并排不遮挡。

自检清单｜从头到尾走一遍

排不动的时候按顺序跑，哪一步先失败就去修哪一步：

• conda activate animated_drawings成功，且python -c "import animated_drawings"无报错
• curl http://localhost:8080/ping返回{"status": "Healthy"}
• python image_to_animation.py examples/drawings/garlic.png garlic_out输出 "Detected N humanoids"
• garlic_out/里 char_cfg.yaml、mask.png、texture.png 齐全，mask 角色纯白背景纯黑
• python -c "import yaml; yaml.safe_load(open('garlic_out/char_cfg.yaml'))"通过
• render.start('./examples/config/mvc/interactive_window_example.yaml')弹窗正常
• MODE: video_render+USE_MESA: True能在无窗口环境下产出 gif
• 换 BVH 时已新建 joint 名匹配的 motion/retarget 配置

两个顺手的小工具：所有脚本的错误详情都写到./logs/log.txt，修 bug 前先翻它比盯终端快；配置改乱了就用python -c "import yaml; yaml.safe_load(open('xxx.yaml'))"先验证语法再跑渲染。

【免费下载链接】AnimatedDrawingsCode to accompany "A Method for Animating Children's Drawings of the Human Figure"项目地址: https://gitcode.com/GitHub_Trending/an/AnimatedDrawings