Communitygithub.com

动漫伪3D技能引擎

将2D动漫/角色图像转化为高分辨率(160层)、24帧/秒的伪3D角色:多视角生成与无缝对齐、GPU SDF雕刻、任意动作的FK/IK动画、可复用像素艺术UI工具包、.ap3d二进制包导出/加载/合并,以及零依赖的单HTML WebGL 双通道查看器。

动漫伪3D技能引擎 是什么?

该技能提供了一个完整的端到端流水线,用于从2D图像创建360°可旋转的24帧/秒动漫风格伪3D角色。它采用严格的四层架构:多视角生成与无缝3D对齐层、模型雕刻与24帧/秒动画工具包、便携式.ap3d二进制格式,以及角色无关的WebGL双通道引擎和可复用像素UI工具包。这允许开发者将一个或多个2D输入图像转换为一个完整的3D角色,包含任意数量的动作、一个可导出的二进制包,以及一个零依赖的独立HTML查看器,支持拖放加载。该流水线确保无缝连接、倾斜的脸部投影、像素完美的质量以及稳健的QA验证,所有操作均符合声明的架构规则。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/kuraneko1/anime-pseudo-3d/tree/HEAD

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

动漫伪3D技能引擎(anime-pseudo-3d)

从参考图像创建清晰的、360°可旋转的、24帧/秒动漫风格伪3D角色,采用严格解耦的四层架构:

  1. 多视角生成与无缝3D对齐层(toolkit/multiview_fitter.py、references/multiview_3d_reconstruction_guide.md):对生成的正面 / 侧面 / 背面 / 顶部正交图像进行外部洪水填充分割,对齐精确的Z坐标地标,计算3D视觉外壳 + 基于法线的无缝六视角颜色合成,并通过正交轮廓IoU质量保证叠加验证雕刻的3D贴合度。
  2. 模型雕刻与24帧/秒动画工具包(toolkit/gpu_sdf.py、toolkit/anime_face_kit.py、toolkit/rig_contracts.py、toolkit/pixel_fx_kit.py、toolkit/qa_validator.py、toolkit/record_gif.py):CuPy GPU / NumPy CPU SDF基础体、倾斜原始角色脸部投影(6.5°–14.5°)、统一的FK + 3D IK PoseFrame约束、任意周期运动以及自动裁切/接缝质量保证。
  3. 便携式.ap3d二进制格式(toolkit/ap3d_format.py、engine/ap3d_codec.js):零依赖跨平台二进制容器(AP3D v1),存储清单 + 原始二进制WebP/PNG资产(比base64小约33%)。支持CLI pack / unpack / inspect / merge,以及实时浏览器导出、加载、+MOTION合并,以及在file://协议下的Canvas拖放。
  4. 角色无关的WebGL双通道引擎与可复用像素UI工具包(engine/anime_stack_engine.js、engine/anime_ui_kit.js、engine/anime_ui_theme.css、engine/viewer_shell.html、engine/bundle_standalone.py):
    • 真正的3D正交投影视图:y = rot.y * sin(pitch) - z * cos(pitch) * spacing(PITCH 15°–90°,默认20°,无垂直拉伸,俯仰不变相机缩放)。
    • 可复用模块化UI(AnimeUIKit):适用于任意数量的动画(1个静态模型,2个、9个、16个、24个、50+个),通过动态网格布局、可滚动的像素动作架、可选类别过滤标签(motion.category)、PREV / NEXT快捷键([ / ]),以及热重载运行时API(engine.loadScene(...)、engine.addMotions(...))。

鸣谢与灵感:


1. 严格分离规则

  • 切勿在engine/中硬编码角色或动作名称。所有内容通过motion_pack.json(schema v1.1:engine/motion_pack.schema.json)或.ap3d包以声明方式驱动。
  • 保持UI模块化:复用window.AnimeUIKit(mountStudioUI或单个小部件createMotionShelf、createPixelSlider、createTimelineScrubber、createFileIOControls)和window.AnimeStackEngine.create(...),而不是复制粘贴原始HTML/CSS。
  • 切勿仅凭单张裁剪像盲目雕刻:务必先执行第一阶段(多视角生成)和第二阶段(multiview_fitter.py对齐 + Z坐标地标)!

2. 可靠六阶段端到端工作流程(新会话标准操作程序)

在编写前请阅读相关参考指南:

阶段 1:生成全身多视角正交图像(必须执行!)

  1. 根据用户的输入图像,调用image-generator创建一个统一的三视图全身旋转图像(正面 | 侧面 | 背面),背景为纯#FFFFFF,正交投影,标准A姿态,所有三个视图的地平线基线一致。
  2. 如果角色有复杂的顶部发型/头饰或不对称的左右道具,还需生成一个90° 顶部俯视图和/或**右侧面视图**。
  3. 视觉关卡:使用read_file检查生成的图像,确认头身比匹配、地标对齐、头发/脚部未裁剪以及背景干净白色,方可继续。

阶段 2:分割、对齐与测量蓝图(toolkit/multiview_fitter.py)

  1. 运行split_multiview_sheet(...) + align_and_measure_views(..., grid_xy=112, grid_z=160, z_height=140, qa_out_path="out/qa_multiview_align.png")。
  2. 视觉检查out/qa_multiview_align.png,确认水平Z坐标标尺(z_crown、z_head_mid、z_neck、z_shoulders、z_waist、z_soles)在正面 | 侧面 | 背面视图间对齐整洁。
  3. 使用reconstruct_visual_hull(bp) + project_6view_colors(occ, bp)获取快速的无缝静态原型,或使用bp["landmarks"] + 基于法线的六视角颜色投影来指导骨骼绑定的SDF角色。

阶段 3:雕刻基础3D角色 + 受保护倾斜脸部并验证轮廓IoU

  1. 构建与bp["landmarks"]匹配的骨骼驱动SDF几何体(toolkit/gpu_sdf.py)(规范:+X右,+Y前,+Z上)。
  2. 提取干净的前脸区域(toolkit/anime_face_kit.py),并使用project_tilted_face(..., tilt_deg=6.5..14.5)进行投影。切勿将黑色轮廓烘焙进切片中;严格限制眼白增强仅在冷白区域(b >= r - 6)。
  3. 3D合成质量关卡:运行render_multiview_fit_qa(vol_neutral, bp, "out/qa_3d_fit_overlay.png"),并视觉验证轮廓IoU(目标>= 72%)以及无缝合成(眼镜腿、衣领盖过肩膀、发冠),之后才能烘焙动画!

阶段 4:编写任意多个24帧/秒动作(PoseFrame)并烘焙

  1. 使用toolkit/rig_contracts.py编写任意数量的动作(1个静态、2个、9个、16个、24+个)(ArmPose(mode="fk"|"ik")、volume_preserving_sx、periodic_lag)。可选地添加category标签(例如"BASE"、"POSE"、"ATTACK"、"SPECIAL"),以便AnimeUIKit自动激活类别标签页。
  2. 当躯干前倾时(torso_pitch > 0),头部需反向仰起(head_pitch < 0),以保持脸部可见。
  3. 烘焙前运行validate_motion_poses(poses)验证动作姿势,对每个烘焙帧断言assert_no_border_clipping(vol, check_bottom=False),保存无损WebP图集(save_tiled_webp),并视觉检查render_animation_sheet。

阶段 5:审计、打包.ap3d并生成独立HTML

  1. 通过toolkit/pixel_fx_kit.py生成像素特效精灵和16×16 UI图标,并编写motion_pack.json。
  2. 审计模块化HTML + CSS + JS的100%像素纯度,导出便携式.ap3d包,并打包零依赖的file://独立HTML:
    python3 engine/audit_pixel_build.py \
      --html engine/viewer_shell.html \
      --css engine/anime_ui_theme.css \
      --js engine/ap3d_codec.js engine/anime_ui_kit.js engine/anime_stack_engine.js
    
    python3 engine/bundle_standalone.py \
      --html engine/viewer_shell.html \
      --js engine/anime_stack_engine.js \
      --pack your_char/motion_pack.json \
      --assets-root your_char \
      --export-ap3d dist/your-char.ap3d \
      --out dist/your-char-standalone.html
    
    • 构建轻量级通用.ap3d播放器(约65 KB,可通过拖放加载/合并/导出任意.ap3d):
      python3 engine/bundle_standalone.py \
        --html engine/viewer_shell.html \
        --js engine/anime_stack_engine.js \
        --empty-player \
        --out dist/ap3d-player.html
      
    • 将额外动画合并到现有.ap3d中,无需重新烘焙:
      python3 toolkit/ap3d_format.py merge --base char.ap3d --extra dlc_motions.ap3d --out char_expanded.ap3d
      

阶段 6:浏览器验证与GIF展示导出

  1. 通过Playwright(--use-gl=angle --use-angle=swiftshader --enable-webgl)在桌面端(1280×800)和移动端(390×844,has_touch=True)的无头Chrome中验证,断言0个控制台/页面错误,并视觉检查多个角度(0°、24°、90°、180°)和仰角俯仰(20°、48°、90°)。
  2. 通过toolkit/record_gif.py录制确定性的无缝README GIF。

相关技能