Anime Pseudo-3D Skill & Engine (anime-pseudo-3d)
Create crisp, 360°-rotatable, 24-FPS anime-style pseudo-3D characters from reference images using a strictly decoupled 4-Layer Architecture:
- Multi-View Generation & Seam-Free 3D Alignment Layer (toolkit/multiview_fitter.py, references/multiview_3d_reconstruction_guide.md): Split generated
FRONT / SIDE / BACK / TOPorthographic sheets with exterior flood-fill, align exact Z-landmarks, compute 3D Visual Hulls + normal-weighted seam-free 6-view color joining, and validate sculpted 3D fits with orthographic Silhouette IoU QA overlays. - Model Sculpting & 24-FPS Animation Toolkit (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 primitives, tilted original-artwork face projection (
6.5°–14.5°), unified FK + 3D IKPoseFramecontracts, arbitrary-N periodic motions, and automated clipping/seam QA. - Portable
.ap3dBinary Format (toolkit/ap3d_format.py, engine/ap3d_codec.js): Zero-dependency cross-platform binary container (AP3Dv1) storing manifest + raw binary WebP/PNG assets (~33% smaller than base64). Supports CLIpack / unpack / inspect / mergeAND live browser Export, Load,+MOTIONMerge, and Canvas Drag-and-Drop overfile://. - Character-Agnostic WebGL 2-Pass Engine & Reusable Pixel UI Kit (engine/anime_stack_engine.js, engine/anime_ui_kit.js, engine/anime_ui_theme.css, engine/viewer_shell.html, engine/bundle_standalone.py):
- True 3D Orthographic Elevation:
y = rot.y * sin(pitch) - z * cos(pitch) * spacing(PITCH 15°–90°, default20°, zero vertical stretching, pitch-invariant camera scale). - Reusable Modular UI (
AnimeUIKit): Works with ANY number of animations (1static model,2,9,16,24,50+) via dynamic grid layout, scrollable pixel motion shelf, optional category filter tabs (motion.category),PREV / NEXT([/]), and hot-reloadable runtime API (engine.loadScene(...),engine.addMotions(...)).
- True 3D Orthographic Elevation:
Credits & Inspiration:
- Greatly inspired by SpriteCook — Sprite stacking for fake 3D pixel art cars and props.
- Extends workflows from sprite-stacking-3d for 24-FPS anime characters & WebGL 2-Pass rendering.
- Live flagship showcase: kuraneko1/deepseek-chan-3d.
1. Strict Separation Rules
- Never hardcode character or motion names inside
engine/. Drive everything declaratively viamotion_pack.json(schema v1.1 in engine/motion_pack.schema.json) or.ap3dpackages. - Keep UI modular: Reuse
window.AnimeUIKit(mountStudioUIor individual widgetscreateMotionShelf,createPixelSlider,createTimelineScrubber,createFileIOControls) andwindow.AnimeStackEngine.create(...)instead of copy-pasting raw HTML/CSS. - Never sculpt blind from a single cropped portrait: Always execute Stage 1 (Multi-View Generation) & Stage 2 (
multiview_fitter.pyalignment + Z-landmarks) first!
2. Bulletproof 6-Stage End-to-End Workflow (Fresh Session SOP)
Read the relevant reference guides before authoring:
- Multi-View Generation & 3D Joining: references/multiview_3d_reconstruction_guide.md
- Model & Tilted Face Projection: references/anime_model_guide.md
- 24-FPS Motion & IK Rigging: references/animation_24fps_guide.md
- WebGL Engine, UI Kit &
.ap3dAPI: references/webgl_engine_guide.md
Stage 1: Generate Full-Body Multi-View Orthographic Sheets (Mandatory!)
- From the user's input image(s), invoke
image-generatorto create a unified 3-View Full-Body Turnaround Sheet (FRONT | SIDE | BACK) on pure#FFFFFFbackground, flat orthographic projection, neutral A-pose, identical floor baseline across all 3 views. - If the character has complex top hair/headdress or asymmetric left/right props, also generate a 90°
TOPoverhead view and/orRIGHT SIDEview. - Visual Gate: Inspect the generated sheet(s) with
read_fileto verify matched head-to-body ratio, aligned landmarks, uncropped hair/feet, and clean white background before proceeding.
Stage 2: Split, Align & Measure Blueprint (toolkit/multiview_fitter.py)
- Run
split_multiview_sheet(...)+align_and_measure_views(..., grid_xy=112, grid_z=160, z_height=140, qa_out_path="out/qa_multiview_align.png"). - Visually inspect
out/qa_multiview_align.pngto confirm horizontal Z-rulers (z_crown,z_head_mid,z_neck,z_shoulders,z_waist,z_soles) line up cleanly acrossFRONT | SIDE | BACK. - Use
reconstruct_visual_hull(bp)+project_6view_colors(occ, bp)for fast seam-free static prototypes, OR usebp["landmarks"]+ normal-weighted 6-view color projection to guide your bone-rigged SDF character.
Stage 3: Sculpt Base 3D Character + Protected Tilted Face & Verify Silhouette IoU
- Build bone-driven SDF geometry (
toolkit/gpu_sdf.py) matchingbp["landmarks"](canonical+Xright,+Yforward,+Zup). - Extract clean front face patch (
toolkit/anime_face_kit.py) and project withproject_tilted_face(..., tilt_deg=6.5..14.5). Never bake black outlines into slices; restrict eye-white boosts strictly to cool whites (b >= r - 6). - 3D Joining QA Gate: Run
render_multiview_fit_qa(vol_neutral, bp, "out/qa_3d_fit_overlay.png")and visually verify Silhouette IoU (target>= 72%) and seam-free joins (glasses temples, collar over traps, hair crown) BEFORE baking animations!
Stage 4: Author Arbitrary-N 24-FPS Motions (PoseFrame) & Bake
- Author any number of motions (
1static,2,9,16,24+) using toolkit/rig_contracts.py (ArmPose(mode="fk"|"ik"),volume_preserving_sx,periodic_lag). Optionally tagcategory(e.g."BASE","POSE","ATTACK","SPECIAL") to activate category tabs inAnimeUIKitautomatically. - Counter-pitch head upward (
head_pitch < 0) whenever leaning torso forward (torso_pitch > 0) so the face stays visible. - Run
validate_motion_poses(poses)pre-bake, assertassert_no_border_clipping(vol, check_bottom=False)on every baked frame, save lossless WebP atlases (save_tiled_webp), and visually inspectrender_animation_sheet.
Stage 5: Audit, Pack .ap3d, and Bundle Standalone HTML
- Generate pixel FX sprites & 16×16 UI icons via toolkit/pixel_fx_kit.py and write
motion_pack.json. - Audit 100% pixel purity across modular HTML + CSS + JS, export a portable
.ap3dpackage, AND bundle a zero-dependencyfile://standalone 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- Build a lightweight Universal
.ap3dPlayer (~65 KB, load/merge/export any.ap3dvia drag-and-drop):python3 engine/bundle_standalone.py \ --html engine/viewer_shell.html \ --js engine/anime_stack_engine.js \ --empty-player \ --out dist/ap3d-player.html - Merge extra animations into an existing
.ap3dwithout re-baking:python3 toolkit/ap3d_format.py merge --base char.ap3d --extra dlc_motions.ap3d --out char_expanded.ap3d
- Build a lightweight Universal
Stage 6: Browser Verification & GIF Showcase Export
- Verify in headless Chrome via Playwright (
--use-gl=angle --use-angle=swiftshader --enable-webgl) on Desktop (1280×800) and Mobile (390×844,has_touch=True), asserting 0 console/page errors and visually checking multiple angles (0°,24°,90°,180°) and elevation pitches (20°,48°,90°). - Record deterministic seamless README GIFs via toolkit/record_gif.py.