动漫伪3D技能引擎(anime-pseudo-3d)
从参考图像创建清晰的、360°可旋转的、24帧/秒动漫风格伪3D角色,采用严格解耦的四层架构:
- 多视角生成与无缝3D对齐层(toolkit/multiview_fitter.py、references/multiview_3d_reconstruction_guide.md):对生成的
正面 / 侧面 / 背面 / 顶部正交图像进行外部洪水填充分割,对齐精确的Z坐标地标,计算3D视觉外壳 + 基于法线的无缝六视角颜色合成,并通过正交轮廓IoU质量保证叠加验证雕刻的3D贴合度。 - 模型雕刻与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 IKPoseFrame约束、任意周期运动以及自动裁切/接缝质量保证。 - 便携式
.ap3d二进制格式(toolkit/ap3d_format.py、engine/ap3d_codec.js):零依赖跨平台二进制容器(AP3Dv1),存储清单 + 原始二进制WebP/PNG资产(比base64小约33%)。支持CLIpack / unpack / inspect / merge,以及实时浏览器导出、加载、+MOTION合并,以及在file://协议下的Canvas拖放。 - 角色无关的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(...))。
- 真正的3D正交投影视图:
鸣谢与灵感:
- 深受**SpriteCook — 用于假3D像素艺术汽车和道具的精灵堆叠**的启发。
- 扩展了sprite-stacking-3d的工作流程,用于24帧/秒动漫角色与WebGL双通道渲染。
- 旗舰展示项目:kuraneko1/deepseek-chan-3d。
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. 可靠六阶段端到端工作流程(新会话标准操作程序)
在编写前请阅读相关参考指南:
- 多视角生成与3D合成:references/multiview_3d_reconstruction_guide.md
- 模型与倾斜脸部投影:references/anime_model_guide.md
- 24帧/秒动作与IK绑定:references/animation_24fps_guide.md
- WebGL引擎、UI工具包与
.ap3dAPI:references/webgl_engine_guide.md
阶段 1:生成全身多视角正交图像(必须执行!)
- 根据用户的输入图像,调用
image-generator创建一个统一的三视图全身旋转图像(正面 | 侧面 | 背面),背景为纯#FFFFFF,正交投影,标准A姿态,所有三个视图的地平线基线一致。 - 如果角色有复杂的顶部发型/头饰或不对称的左右道具,还需生成一个90°
顶部俯视图和/或**右侧面视图**。 - 视觉关卡:使用
read_file检查生成的图像,确认头身比匹配、地标对齐、头发/脚部未裁剪以及背景干净白色,方可继续。
阶段 2:分割、对齐与测量蓝图(toolkit/multiview_fitter.py)
- 运行
split_multiview_sheet(...)+align_and_measure_views(..., grid_xy=112, grid_z=160, z_height=140, qa_out_path="out/qa_multiview_align.png")。 - 视觉检查
out/qa_multiview_align.png,确认水平Z坐标标尺(z_crown、z_head_mid、z_neck、z_shoulders、z_waist、z_soles)在正面 | 侧面 | 背面视图间对齐整洁。 - 使用
reconstruct_visual_hull(bp)+project_6view_colors(occ, bp)获取快速的无缝静态原型,或使用bp["landmarks"]+ 基于法线的六视角颜色投影来指导骨骼绑定的SDF角色。
阶段 3:雕刻基础3D角色 + 受保护倾斜脸部并验证轮廓IoU
- 构建与
bp["landmarks"]匹配的骨骼驱动SDF几何体(toolkit/gpu_sdf.py)(规范:+X右,+Y前,+Z上)。 - 提取干净的前脸区域(
toolkit/anime_face_kit.py),并使用project_tilted_face(..., tilt_deg=6.5..14.5)进行投影。切勿将黑色轮廓烘焙进切片中;严格限制眼白增强仅在冷白区域(b >= r - 6)。 - 3D合成质量关卡:运行
render_multiview_fit_qa(vol_neutral, bp, "out/qa_3d_fit_overlay.png"),并视觉验证轮廓IoU(目标>= 72%)以及无缝合成(眼镜腿、衣领盖过肩膀、发冠),之后才能烘焙动画!
阶段 4:编写任意多个24帧/秒动作(PoseFrame)并烘焙
- 使用toolkit/rig_contracts.py编写任意数量的动作(
1个静态、2个、9个、16个、24+个)(ArmPose(mode="fk"|"ik")、volume_preserving_sx、periodic_lag)。可选地添加category标签(例如"BASE"、"POSE"、"ATTACK"、"SPECIAL"),以便AnimeUIKit自动激活类别标签页。 - 当躯干前倾时(
torso_pitch > 0),头部需反向仰起(head_pitch < 0),以保持脸部可见。 - 烘焙前运行
validate_motion_poses(poses)验证动作姿势,对每个烘焙帧断言assert_no_border_clipping(vol, check_bottom=False),保存无损WebP图集(save_tiled_webp),并视觉检查render_animation_sheet。
阶段 5:审计、打包.ap3d并生成独立HTML
- 通过toolkit/pixel_fx_kit.py生成像素特效精灵和16×16 UI图标,并编写
motion_pack.json。 - 审计模块化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展示导出
- 通过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°)。 - 通过toolkit/record_gif.py录制确定性的无缝README GIF。