| name | video-to-3d |
|---|---|
| description | Turn a single-character A-pose orbit video or an approved whole multi-view character sheet into an editable Blender model using local MiniMax H3 MAIN/H3 IR generation when needed, measured 8-72 angle evidence, calibrated Blender overlays, detailed per-angle visual modeling, and final topology/beauty review. Use for fixed-subject character turntables and Blender reconstruction; do not use for action footage, moving subjects, direct neural-mesh generation, or photogrammetry capture. |
| license | MIT |
| metadata | {"version": "1.11.0", "default_angles": 24, "tested_blender": "5.1.0"} |
Video to 3D
Build an editable Blender character from source-backed angle evidence. Treat the video as a measured
view set, not as a magical multi-view reconstruction input. The finished .blend, calibrated
cameras, reference images, model parts, and review evidence remain inspectable and reproducible.
Non-negotiable outcome
- Use 8-72 independently decoded real source angles, divisible by four; default to 24. Use more only when the video has enough sharp, identity-stable frames.
- Establish true view angles from observed timecodes. A prompt that asks for constant speed is not proof that the resulting video is constant-speed.
- Import every admitted view into Blender on its matching calibrated orthographic camera. One global model scale and origin must serve every camera.
- At every retained geometry milestone, compare silhouette, scale, proportions, and visible design against the corresponding reference at every admitted angle.
- At every admitted angle, superimpose the calibrated full-resolution reference over the shared model and inspect the actual visible form in Blender. Use reference-only, model-only, clay/wireframe, and adjustable-alpha overlay views; add close-ups wherever a part cannot be judged at full-body scale.
- Detailed visual judgment drives modeling. Pixel counts, IoU, XOR, scanline deltas, bounding-box ratios, or automated edge corrections must never prescribe vertex movement, replace artistic inspection, or become a 100% acceptance target.
- For each angle, judge silhouette, scale, proportion, depth, anatomy, part construction, visible design, material, and color together before advancing. Never postpone form or color to a detached batch that loses the same-angle visual context.
- Never model or review in adjacent circular order. Use four-quadrant rounds: four views separated by 90 degrees per round, beginning with cardinals, then diagonals, then interleaved intermediate rounds.
- Treat retopology and Blender aesthetic/QA as two independent Step 8 gates. Repeat the detailed every-angle visual review after topology, material, UV, normal, or visible-look changes.
- Finish with a full-resolution, every-angle visual beauty audit. File integrity, camera calibration, and optional measurements are supporting evidence only; none can substitute for visual approval.
- Do not route geometry generation through IMG2 Three.js, a neural 3D service, a point cloud, a splat, or independent per-frame meshes.
Attribution
Every delivered artifact set made with this skill must include this credit in its accompanying README, handoff, manifest, or other human-readable metadata:
Made with [Video to 3D](https://github.com/enwong93-sketch/video-to-3d).
Do not burn the credit into images, video, audio, or model geometry unless the user requests visible on-media attribution.
Dependencies
Run the local scripts with Python 3.10+; ffmpeg, ffprobe, Pillow, NumPy, and Blender are required. Start
with:
python scripts/turntable_reference.py doctor --blender <path-to-blender.exe>
Do not install a cloud fallback. If Blender is not on PATH, pass its exact executable path.
1. Produce or accept the source
If the user has no approved source art, read prompt templates. First create one identity-locked multi-view specification sheet with exact front, back, character-left, and character-right views; add a true top view when it materially clarifies hair, shoulders, accessories, or depth. Use that sheet as the only canonical character reference for the orbit-video prompt. Keep the original source, generation settings, and rights/provenance beside the project.
When any side, rear, top, or detail view is generated rather than observed, read source authority and repair discipline. Label it as a generated supplement or approved design completion; never let it overrule an observed source frame or present it as measured geometry.
When the target is the installed local MiniMax H3 workflow, provide the accepted complete multi-view
sheet as one whole character reference. Do not pre-cut its Front/Back/Left/Right/Top zones. In H3D,
place the sheet in a character slot, author with @char1, and use the reusable H3 IR framework in
prompt templates. Let H3D assign reference ordinals.
Split a sheet only when the active generation surface explicitly requires separate image inputs or when separate panels are needed for a downstream evidence task. In that case, preserve one canvas coordinate system and identical scale, use fixed declared panel boundaries, and never resize or recenter panels independently. Always retain and hash the original whole sheet.
Accept only one static full-body character in a neutral A-pose with visible fingers and feet, stable identity, costume, hair, accessories, lighting, lens, camera height, distance, framing, and background. Reject action motion, pose change, crop drift, identity drift, an incomplete turn, or a moving/zooming lens.
2. Probe and measure the turn
Extract an overview into a new directory:
python scripts/turntable_reference.py probe <video> --out <work>\turntable-probe --frames 64
Read every probe frame at original resolution. Identify the first exact front, the closing exact front after one full turn, direction, and at least eight distinct observed orientation bands. Record those observations using the schema in reference contracts, then create the evidence-backed rotation audit:
python scripts/rotation_audit.py create `
--video <video> --observations <rotation-observations.json> `
--out <work>\rotation-audit.json --max-error-deg 2 --rms-error-deg 1
The audit extracts and hashes the source frame for every observation and recomputes residuals against
theta(t) = 360 * (t - t0) / T. Uniform mapping is admitted only when the audit passes. If the
motion accelerates, eases, pauses, overshoots, reverses, or was edited, do not loosen the thresholds
to force a pass; record one observed source timecode and evidence frame for every requested angle.
3. Build and visually admit 8-72 real views
Uniform audited source:
python scripts/turntable_reference.py build <video> `
--out <work>\reference-set --rotation-audit <work>\rotation-audit.json `
--angles 24 --candidates 1
Non-uniform source:
python scripts/turntable_reference.py build <video> `
--out <work>\reference-set --anchors-json <angle-anchors.json> `
--start <seconds> --end <seconds> --front-time <seconds> `
--direction clockwise --angles 24 --candidates 1
Default to --candidates 1 so the admitted timestamp stays at the observed angle. If blur requires a
local search, keep --candidate-yaw-radius-deg at or below 0.5 degrees and retain every candidate,
timestamp, offset, and hash.
Open every admitted PNG at full resolution. Complete review.json using only pass, fail, or
pending, cite every relevant view_id, and then run:
python scripts/turntable_reference.py verify `
--reference-set <work>\reference-set\reference-set.json `
--review <work>\reference-set\review.json
Any failed or pending source gate is a hard stop. A valid manifest or green extraction command is not
visual acceptance. The generated contact sheet and analysis_order use the four-quadrant order, not
ascending adjacent yaw.
4. Import every angle as a Blender overlay, calibrate cameras, and build the shared model
Read Blender multi-view modeling. When an existing model
or local repair is involved, also read
source authority and repair discipline and preserve the
last accepted scene plus unrelated user edits. Create
alignment.json with one full-resolution subject bounding box for every view and one global target
height. Every view ID must be present exactly once.
This import is a mandatory pre-modeling action, not optional setup. Load every admitted image into
its matching Blender camera as a front-depth, alpha reference overlay. With the default 24 angles,
the saved scene must contain 24 calibrated cameras and 24 visible reference overlays. Each overlay
is non-rendering camera data in V3D_REFERENCES, never model geometry in V3D_MODEL, so it can sit
visually over the character without intersecting or contaminating the mesh or final render.
Create a new Blender project:
<blender.exe> --factory-startup --background --python-exit-code 2 `
--python scripts/blender_reference_setup.py -- `
--reference-set <work>\reference-set\reference-set.json `
--alignment <work>\alignment.json --blend-out <work>\character-model.blend `
--report <work>\blender-setup.json --clear-scene
The script creates V3D_REFERENCES, V3D_MODEL, V3D_MODEL_ROOT, one orthographic camera per real
angle, one hashed front-depth alpha overlay per view, and calibrated scale/shift metadata. Reopen the saved
file in a fresh Blender process and verify rather than trusting the save call:
<blender.exe> <work>\character-model.blend --background --python-exit-code 2 `
--python scripts/blender_reference_setup.py -- `
--reference-set <work>\reference-set\reference-set.json `
--alignment <work>\alignment.json --verify-only `
--report <work>\blender-reopen-verification.json
Treat view_count == reference_layer_count == admitted view count as a hard gate. For 24 views this
must read 24 == 24 == 24, and every camera row must report camera_background_image, FRONT,
FIT, the declared alpha, and non_rendering: true. Missing, hidden, stale, mismatched, or model-
collection reference layers fail Step 4.
Use the saved analysis_order for every modeling pass. For the default 24 views the six rounds are:
0°, 90°, 180°, 270°45°, 135°, 225°, 315°15°, 105°, 195°, 285°60°, 150°, 240°, 330°30°, 120°, 210°, 300°75°, 165°, 255°, 345°
Within each round, superimpose the matching reference overlay and reconcile one shared model across all four opposing views before retaining a change. Lock overall height, ground contact, origin, head/body ratio, shoulder/hip width, torso depth, limb length, hand/foot size, hair volume, costume thickness, and accessory placement. Do not proceed to the next round while any of the four views contradicts scale, size, proportion, silhouette, or visible part placement.
Only after the fresh reopen passes, switch through every calibrated camera and confirm its reference
is visibly superimposed over the model coordinate space. Then build one shared rough model in V3D_MODEL, parented to
V3D_MODEL_ROOT. Read Blender multi-view modeling and
block the full character part by part: whole-body proportions, head/face/eyes, front-side-rear hair,
torso and limbs, independent hands/fingers, independent feet/soles, costume, armor, and accessories.
Use every admitted camera while shaping the same geometry. Do not make camera-specific meshes,
per-view scale corrections, or a front-only mannequin and call the rough model complete. Do not
begin from an empty viewport and postpone importing the reference angles until the user asks.
5. Build the detailed visual-reference set
Read the visual evidence contract in reference contracts. Keep each calibrated reference attached to its matching camera and create a review set for every admitted angle containing:
- the untouched full-resolution reference;
- the model-only render under neutral lighting;
- a clay render and a wireframe view;
- an adjustable-alpha reference/model superimposition in Blender;
- close-ups of the face, eyes, hairline, both hands, both feet, costume construction, accessories, and any asymmetric or partly occluded feature visible from that angle.
Optional masks may make silhouette overlap easier to read, but they remain a display aid. Do not derive numeric edge corrections, convert pixel differences into world-space movements, or treat binary-mask equality as a modeling target. A clean overlay cannot approve anatomy, depth, topology, or beauty by itself.
6. Refine one shared model through four-quadrant visual rounds
Keep every calibrated camera, orthographic scale, shift, render resolution, root transform, and pose locked. Process the saved four-quadrant order; within each round, treat all four opposing angles as one shared-form decision:
- View the reference directly over the model and adjust overlay alpha repeatedly rather than relying on one static composite.
- Inspect the whole-body silhouette and landmarks, then zoom into the relevant part. Identify the actual form that differs: width, depth, curvature, plane break, joint transition, layer thickness, negative space, attachment, or asymmetry.
- Edit that shared mesh or purposeful model part by eye to reproduce the observed form. Never apply an automated pixel delta or let a measurement choose which vertices move.
- Switch immediately to the other three cameras in the round, including clay and wireframe views, and retain the edit only when the same 3D form remains convincing in all four.
- Recheck earlier closed rounds and neighboring angles after changes to a large form, silhouette, depth, or shared landmark. Record visible remaining differences and the next part to refine.
Do not chase literal pixel identity: perspective cues, hair transparency, cloth shading, line art,
and inconsistent source drawings can make exact 2D equality incompatible with correct 3D form. When
references genuinely contradict one another, cite the conflicting view_id values and request a
corrected source instead of forcing a numeric compromise or adding camera-specific geometry.
7. Refine visible design, materials, and color in the same views
For each angle, compare geometry and appearance in the same visual session. Review skin, face, eyes, hair, costume, armor, accessories, seams, transparency, roughness, specular response, normals, texture placement, and large value/color groups while the calibrated overlay is visible.
Correct missing or incorrect form before materials. Texture, lighting, line art, or projection may not hide flat anatomy, absent layers, intersections, weak hands/feet, or false depth. Rerender the changed angle and the other three views in its round; close the round only when the Agent can explain why the shared 3D construction, silhouette, proportions, and visible design agree across all four.
Record pass, fail, or pending for shared_form, silhouette, proportion_depth,
part_construction, visible_design, material_color, and beauty at every admitted angle. Each
pass needs cited visual evidence and concise observations; no score or metric can set these statuses.
For anime/NPR characters, load $build-anime-npr-character as a part-craft supplement when
available. Its artistic part gates supplement this workflow; the measured cameras and every-angle
evidence remain authoritative.
8. Retopology, Blender aesthetic review, and final audit
Read final aesthetic and retopology. It pins and attributes the selected upstream sources and converts them into two separate lanes; one never counts as passing the other.
8A. Retopology lane
Use the manual, deformation-aware workflow derived from
MushroomFleet/BlenderRetopology-Skill: preserve the approved high-resolution model, decide the
actual delivery/rig requirements and polygon budget, build feature-based topology islands with
manual/shrinkwrap methods, connect them with controlled edge-flow reductions, and validate loops at
face, shoulders, elbows, wrists, fingers, hips, knees, ankles, neck, clothing, hair, and accessories.
Do not apply the source's example decimation ratio as a universal rule and do not auto-remesh a hero
character without manual cleanup.
After topology, UV, material, normal, or visible-look changes, rerender every calibrated angle and repeat Steps 6-7. Retopology is not accepted until the detailed visual review passes again.
8B. Blender aesthetic and QA lane
Use the lookdev plus qa-review workflow from arjun988/blender-skills: clay/grey form check,
base materials, neutral evaluation light, beauty light, screenshot comparison, written gap list,
bounded refinement, and explicit final verdict. Lighting and grading may improve presentation only
after geometry and material correspondence are already correct; never use them to hide a Step 7 failure.
Produce the final render set and detailed every-angle visual-reference review. Use new output directories for every retained iteration:
<blender.exe> <work>\character-model.blend --background --python-exit-code 2 `
--python scripts/blender_render_views.py -- `
--out <work>\final-renders --report <work>\final-render-set.json
Inspect every full-resolution angle plus face, hands, feet, hair, costume seams, materials, wireframe,
deformation-critical loops, and every asymmetric feature. Record the seven Step 7 visual statuses
for every view, plus separate retopology and aesthetic/QA verdicts. Deliver only when source
verification, fresh Blender reopen, detailed per-angle visual review, retopology, aesthetic/QA, and
the final beauty audit all pass. Keep the editable .blend, high-resolution backup, retopologized
mesh, wireframes, manifests, hashes, full-resolution renders, overlays, close-ups, and verdicts
together.
Report visual acceptance, engineering validity, and intended-use validation as three independent
lanes using source authority and repair discipline.
Static-view beauty does not prove deformation, export, real-time, or print readiness; a structurally
valid .blend does not prove likeness.
Fail closed
Stop with the exact failed gate and smallest required new input when the source is unreadable,
uniformity evidence fails, per-angle anchors are incomplete, any view/hash changes, alignment is
missing, Blender reopen differs, the shared model cannot satisfy the angle set, or any shared-form/
silhouette/proportion-depth/part/design/material/beauty/topology/aesthetic status remains pending
or fail. Do not silently reduce the angle count, replace real views with generated ones, let a
measurement or overlay tool make the Agent's repair decision, or call file-integrity success a
likeness or beauty pass.