企业官网建设流程全解析

• 计算机视觉
• 图形学

本指南以仓库中 examples/quadruped/README.md 为核心，系统讲解 AnimatedDrawings 项目中 Quadruped（四足动物）扩展的完整使用流程：从一张儿童画开始，依次完成人物标注生成、人体骨架到四足骨架的自动转换（human_to_animal.py）、MVC 渲染配置编写，最终通过render.start()输出四足角色行走/跳舞动画视频。读完本文，你将掌握四足扩展的端到端操作步骤，并理解其底层关节映射、腿部验证与重配置算法，以及配套的 retarget 配置原理。

一、Quadruped 扩展是什么

AnimatedDrawings 是一套"让儿童画动起来"的开源工具链，其核心流程是：输入一张人物简笔画 → 检测/分割/姿态估计生成角色标注（char_cfg.yaml、texture.png、mask.png）→ 用 BVH 动作数据驱动 2D 角色完成动画渲染。默认管线只支持"两足直立"的人形角色；而Quadruped 扩展（位于examples/quadruped/目录）的目标，是把这一能力延伸到四条腿的动物形态——例如马、狗、恐龙等长着四条腿的涂鸦角色。

从 human_to_animal.py 的源码结构可以推断，该扩展的核心思路并非训练新模型，而是在标注层做一次"骨架重命名 + 拓扑重构"：把人体姿态估计得到的关节（hip、torso、neck、shoulder、elbow、hand 等）映射为四足动物关节（right_hip_f/right_knee_f/right_foot_f、right_hip_b/right_knee_b/right_foot_b等前后腿），再用同一条四足 retarget 配置把 BVH 动作绑到新骨架上。整个过程只需要两个 Python 文件与一个 YAML 配置，不改动渲染内核。

二、整体工作流一览

原始儿童画 │ python image_to_animation.py path/to/your/file ▼ 角色标注目录（char_cfg.yaml + texture.png + mask.png + bounding_box.yaml） │ python human_to_animal.py path/to/your/yaml ▼ animal_config.yaml（四足骨架角色配置） │ 编辑 four_legs_example.yaml，将 character_cfg 指向它 ▼ render.start('./examples/config/mvc/four_legs_example.yaml') ▼ 四足角色动画视频（video.gif / video.mp4）

下文将按照这条链路逐一展开，并在关键节点给出源码级原理说明。

三、第一步：生成角色标注（image_to_animation.py）

四足扩展的输入同样是一张画有人物的图片。原文档给出的启动命令是：

python image_to_animation.py path/to/your/file

在仓库中，该入口脚本位于 examples/image_to_animation.py，它内部做了两件事（见其第 18–22 行的调用链）：

1. 调用 image_to_annotations.py 中的image_to_annotations(img_fn, char_anno_dir)：将图片送入本地运行的 TorchServe 服务（drawn_humanoid_detector与drawn_humanoid_pose_estimator两个模型），完成人物检测、分割与姿态估计；
2. 调用 annotations_to_animation.py 中的annotations_to_animation(...)，把标注结果整理成动画所需的角色配置。

从 image_to_annotations.py 的源码可以看出，该步骤会在输出目录中生成：

• image.png：原始图片副本；
• bounding_box.yaml：检测到的人物包围盒，包含left / top / right / bottom四个像素坐标（源码第 79–85 行直接写入该文件）。仓库中的 examples/characters/char5/bounding_box.yaml 与 examples/characters/char6/bounding_box.yaml 即为其产物示例；
• char_cfg.yaml：角色配置文件，包含height、width与skeleton关节列表；
• texture.png/mask.png：纹理图与分割掩码。

关于char_cfg.yaml的字段，examples/config/README.md 中给出了权威说明：height/width是纹理与掩码的像素尺寸；skeleton是关节列表，每个关节含loc（图像像素坐标，(0,0)为左上角）、name（关节名）、parent（父关节名，唯一例外是root，其parent必须为null）。例如 examples/characters/char6/char_cfg.yaml 中right_hip_b的parent是root，right_knee_b的parent是right_hip_b，构成一条完整骨骼链。

提示：image_to_annotations.py依赖本地 TorchServe 服务（默认地址http://localhost:8080），请先确保docker_torchserve容器处于运行且健康状态，否则会抛出检测失败异常（源码第 52–53 行有明确校验）。

四、第二步：人体骨架转四足骨架（human_to_animal.py）

4.1 运行方式

生成角色标注后，把 human_to_animal.py 放到角色标注所在目录（或确保以可访问路径执行），然后运行：

python human_to_animal.py path/to/your/yaml

原文档特别强调：human_to_animal.py要么与待转换的char_cfg.yaml位于同一目录，要么在输入参数中给出其文件夹路径。从脚本主入口（第 379–386 行）看，第一个参数是角色 YAML 路径，脚本内部会读取该 YAML 的height、width、skeleton三部分，转换完成后在输入文件同目录下写出animal_config.yaml（源码第 372–376 行：output_dir = os.path.dirname(human_yaml_path)），并打印输出路径。

4.2 关节映射表：人体关节 → 四足关节

转换的核心是一张关节映射表（源码第 229–245 行part_mapping）：

同时，四足骨架显式引入一个root关节，四条腿的髋关节（right_hip_f/left_hip_f/right_hip_b/left_hip_b）的parent统一指向root（源码第 248–253 行parent_mapping）。如果原骨架没有root，脚本会以hip的位置补插一个（第 307–314 行）。

颈部位置会被重算：脚本以"髋→躯干"方向向量作为前向参考，把颈部放到躯干前方 30% 的位置（第 262–271 行），使四足动物的头颈比例更自然：

forward_vector = [torso_pos[0] - hip_pos[0], torso_pos[1] - hip_pos[1]] neck_pos = [torso_pos[0] - forward_vector[0] * 0.3, torso_pos[1] - forward_vector[1] * 0.3]

4.3 腿部验证与自动重配置（关键算法）

转换完成后，四条腿（前后各两条）并不保证几何合理。脚本为此实现了validate_leg_group（第 48–113 行）校验函数，从三个维度把关：

1. 段长比例：knee→foot与hip→knee的距离之比不得超过阈值；
2. 膝部关节角：髋、膝、足三点在膝处的夹角必须足够大（腿部不能"反向折叠"）；
3. 垂直次序：在图像坐标系（y 轴向下）中，膝必须位于髋之下、足必须位于膝之下。

前腿使用了更严格的标准（源码第 83–88 行）：比例阈值由默认2.0收紧到1.5，膝角阈值由150°提高到160°。未通过的腿会被送入reconfigure_leg_group（第 143–215 行）进行"候选关节搜索"：以对侧已验证的腿（或默认 20 像素垂直偏移）为参照估算期望的膝/足位置，再回到原始骨架中查找距离该期望位置 30 像素以内的关节作为替代（candidate_search_for_joint，tolerance 默认 30），并做越界钳制（validate_y_within_bounds保证关节 y 坐标不超过图像高度）。

整体转换入口convert_human_to_animal（第 217–356 行）的处理顺序是：先对四组腿(hip, knee, foot)逐一验证，收集通过验证的腿作为对称参照，再对未通过的腿用对侧参照进行重配置。

4.4 输出

脚本通过自定义 YAML representer（第 366–369 行）避免别名引用，将{'height', 'width', 'skeleton'}写为结构清晰、可直接被渲染管线读取的animal_config.yaml。这一步完成后，你的画就"长"出了四条腿。

五、第三步：编辑 MVC 渲染配置

转换得到animal_config.yaml后，需要把它接入渲染管线。原文档给出的方法是编辑 examples/quadruped/four_legs_example.yaml（仓库examples/config/mvc/目录下也有一份同名示例），把character_cfg指向新生成的动物配置：

scene: ANIMATED_CHARACTERS: - character_cfg: path/to/your/new/animal/config motion_cfg: examples/config/motion/zombie.yaml retarget_cfg: examples/config/retarget/four_legs.yaml controller: MODE: video_render OUTPUT_VIDEO_PATH: ./video.gif

各字段含义（依据 examples/config/README.md 的权威说明）：

• scene.ANIMATED_CHARACTERS：场景中的角色列表，每个角色由三个配置组成——
  • character_cfg：角色配置路径（即上一步生成的animal_config.yaml）；
  • motion_cfg：动作配置路径，指定驱动角色的 BVH 动作文件；
  • retarget_cfg：重定向配置路径，定义如何把 BVH 骨架动作绑定到 2D 角色骨骼上。列表中可追加多个字典实现多角色同屏。
• controller.MODE：控制器模式。video_render表示直接渲染视频到文件；interactive则打开可交互窗口（此时不能与view.USE_MESA同时使用）。
• controller.OUTPUT_VIDEO_PATH：输出视频路径，仅video_render模式生效。目前仅支持.gif与.mp4，且透明度仅.gif可用。

仓库自带的 examples/config/mvc/four_legs_example.yaml 完整示例中，character_cfg直接指向了 examples/characters/char6/char_cfg.yaml——从该文件可以看出，char6的角色骨架已经采用right_hip_b/right_hip_f等四足关节命名，是一个预标注好的四足角色，非常适合作为对照样板。

六、第四步：运行四足动画

配置完成后，用 MVC 配置路径调用渲染入口即可。原文档给出的调用方式：

from animated_drawings import render render.start('./examples/config/mvc/four_legs.yaml')

render.start()是仓库统一的渲染入口（核心实现位于 animated_drawings/render.py）。它会读取基础配置 animated_drawings/mvc_base_cfg.yaml，再用你提供的 MVC 配置中的字段覆盖默认值，然后实例化 Model（场景）/ View（渲染视图）/ Controller（视频渲染控制器）三层组件完成动画输出。关于 MVC 配置的更多参数（如view.WINDOW_DIMENSIONS、view.CAMERA_POS、view.USE_MESA无头渲染、scene.ADD_FLOOR地面、scene.ADD_AD_RETARGET_BVH显示原始 BVH 骨架等），可查阅 examples/config/README.md 的 MVC Config File 一节。

七、底层支撑：four_legs.yaml 重定向配置解析

四足扩展之所以"一套配置通吃"，关键在于配套的 examples/config/retarget/four_legs.yaml。这份重定向配置把 BVH 骨架（人形动作数据）与四足角色骨骼桥接起来，其主要结构如下：

1. char_starting_location: [-0.3, -0.2, -0.5]：角色根关节的起始 xzy 位置。
2. bvh_projection_bodypart_groups：将 BVH 关节分组并指定投影平面——手臂组与腿部组使用pca（自动挑选最合适的投影平面），躯干组使用frontal。这是重定向器把 3D 动作投影到 2D 角色平面上的关键机制。
3. char_bodypart_groups：定义 2D 角色各部位（前腿组、后腿组、躯干组）的渲染先后顺序，通过bvh_depth_drivers（如LeftFoot、RightFoot、Hips）在投影平面上的平均深度决定前后遮挡关系。
4. char_bvh_root_offset：处理 BVH 骨架的位移——用Lower Limbs（下肢组）的投影平面承载根偏移，并以 BVH 关节链与角色关节链的长度之比作为尺度启发式，将骨架平移量等比施加到 2D 角色上。
5. char_joint_bvh_joints_mapping：关节对映射表。例如left_foot_b → (LeftLeg, LeftFoot)、left_knee_b → (LeftUpLeg, LeftLeg)，渲染时把角色骨骼旋转到与 BVH 关节对向量一致的方向。四条腿的膝/足关节都映射到 BVH 下肢关节，实现"人形动作 → 四足姿态"的驱动。

同时注意配套的动作配置 examples/config/motion/zombie.yaml：

filepath: examples/bvh/fair1/zombie.bvh start_frame_idx: 0 end_frame_idx: 779 groundplane_joint: LeftFoot forward_perp_joint_vectors: - - LeftShoulder - RightShoulder - - LeftUpLeg - RightUpLeg scale: 0.025 up: +z

其中groundplane_joint: LeftFoot用于把骨架对齐到地面、up: +z指定 BVH 的"上"方向、scale对骨架做整体缩放以适应场景尺度。原文档示例默认使用zombie动作，你也可以把motion_cfg换成 examples/config/motion 下的jumping.yaml、dab.yaml等其他动作配置，让四足角色做出跳跃、摆 pose 等不同表演。

八、注意事项与调优建议

原文档在 Notes 一节明确了两条实操要点，结合源码可以进一步展开：

1. 脚本位置：human_to_animal.py必须与待转换 YAML 同目录，或通过参数指定其所在文件夹。从源码实现看，输出文件animal_config.yaml总是写入输入 YAML 所在目录，与当前执行目录无关，因此推荐把该脚本复制到标注输出目录中运行，便于管理产物。

2. 包围盒（bounding box）调优：原文档指出，为获得最佳四足动画效果，可能需要编辑image_to_animal.py中的包围盒配置。结合 image_to_annotations.py 源码（第 74–85 行），检测器返回的bbox会被四舍五入后直接写入bounding_box.yaml；如果人物在画中的裁剪范围不理想（如手腿被切、留白过大），可以手动调整该文件中的left/top/right/bottom四个值，再配合仓库提供的标注修正工具 examples/fixer_app 与 examples/fix_annotations.py（基于 Flask 的交互式标注网页）修正关节位置，从而让骨架转换与腿部验证获得更合理的输入。

3. 四肢合理性：由于四足骨架是由"手臂当后腿参考的前腿"重构而来，画中人物的站姿与四肢展开程度直接决定转换质量。前腿使用了更严格的验证阈值（段长比 ≤ 1.5、膝角 ≥ 160°），若画面中手臂过短或折叠，可能触发候选关节搜索，此时留意输出日志中Reconfigured leg group: ...的提示（源码第 214 行），必要时重新绘制或调整标注。

九、源码与示例索引

为便于继续深入阅读，本文涉及的仓库关键文件汇总如下：

• 四足扩展说明：examples/quadruped/README.md
• 骨架转换脚本：examples/quadruped/human_to_animal.py
• 四足 MVC 示例：examples/quadruped/four_legs_example.yaml、examples/config/mvc/four_legs_example.yaml
• 四足重定向配置：examples/config/retarget/four_legs.yaml
• 动作配置：examples/config/motion/zombie.yaml
• 预标注四足角色：examples/characters/char6/char_cfg.yaml（骨架已使用*_hip_f/*_hip_b四足关节命名）
• 标注生成管线：examples/image_to_annotations.py、examples/annotations_to_animation.py
• 渲染入口：animated_drawings/render.py
• 配置文件权威说明：examples/config/README.md

按照本指南四步操作，即可让任意一幅画着人物的儿童涂鸦以四足形态在场景中行走、跳跃甚至跳僵尸舞；若要进一步定制，可从human_to_animal.py的关节映射表与four_legs.yaml的关节对映射入手，调整映射关系以适配更多动物形态（如更多腿、更长脖颈）。

• 计算机视觉
• 图形学