Clone URL: https://github.com/moses-y/AniGen

The Problem

Generating a fully rigged, animate‑ready 3D asset from a single image requires tightly coupled shape, skeleton, and skinning fields, but the repository’s codebase suffers from import cycles, duplicated logic, and no automated test or CI gate, making reliable iteration and production deployment risky.

What This Does

AniGen models shape, skeleton and skin as mutually consistent S³ Fields defined over a shared spatial domain. The two‑stage flow‑matching pipeline first synthesises a sparse structural scaffold (anigen/pipelines/anigen_image_to_3d.py:332 → run reaches 160 functions) and then generates dense geometry and articulation in a structured latent space (anigen/models/structured_latent_vae/anigen_decoder.py). Key entry points are run (anigen/pipelines/anigen_image_to_3d.py:332), main (example.py:17) and image_to_3d (app.py:74), each driving filesystem writes via os.makedirs and network loads of pretrained flow‑matching models.

How It Is Wired

Execution starts at run in anigen/pipelines/anigen_image_to_3d.py:332, which calls snapshot → to → cuda → reshape and finally writes a PLY/GLB via os.makedirs. main in example.py:17 follows a similar path, reaching 87 functions and invoking os.makedirs for output directories. The internal call graph shows float called from 57 places, to from 51, and reshape from 50, indicating these utilities are pervasive. A notable hub is anigen/modules/sparse/__init__.py (17 importers, 7 out‑going edges, instability 0.29) that participates in a 20‑module import cycle; any change here ripples across many modules. Circular imports also appear in anigen/pipelines/__init__.py and anigen/modules/sparse/basic.py, requiring careful import‑ordering or extraction of shared types.

How To Use It

  • Setup (Linux, NVIDIA GPU ≥ 18 GB): ``bash git clone https://github.com/moses-y/AniGen cd AniGen pip install -e . # installs core package cd extensions/CUBVH && pip install . # builds the CUBVH C++/CUDA extension ` The requirements.txt and extensions/CUBVH/pyproject.toml` declare pip‑installable dependencies; no lockfile is committed, so repeatable builds require committing the generated lockfile after the first install.
  • Configuration: Config JSON lives in configs/ (e.g., configs/ss_flow_duet.json). Environment variables for CUDA are handled by the system; no extra keys are required beyond the GPU driver.
  • Running it: ``bash # generate from a single image python app.py --image assets/cond_images/brickbob.png --output out_dir ` or use the CLI entry point: `bash python -m anigen.pipelines.anigen_image_to_3d --image assets/cond_images/brickbob.png --out out_dir ` The image_to_3d function (app.py:74`) produces a rigged mesh, skeleton and skinning weights.

Real‑World Use

A downstream embodied‑AI pipeline can ingest the generated .glb asset, drive it with motion clips from a motion‑capture dataset, and immediately simulate physics. Example workflow:

from anigen.pipelines.anigen_image_to_3d import image_to_3d
mesh, skeleton, weights = image_to_3d("input.jpg")
mesh.export("output.glb")          # compatible with Unity/Unreal
skeleton.animate(clip)            # off‑the‑shelf runtime

The produced asset carries a coherent skeleton and per‑vertex skinning weights, ready for animation rigs.

Code Health & Issues

  • HIGH – Add a test suite; repository has 114 source files, no test files. Any change ships with no signal that existing behaviour still holds.
  • HIGH – Commit a lockfile beside the manifest (extensions/CUBVH/pyproject.toml). Without a lockfile the artifact tested and the artifact shipped can diverge.
  • HIGH – Add a CI workflow that builds and tests the repository on push and pull_request.
  • MEDIUM – Enable Dependabot or Renovate to keep manifests up‑to‑date; currently no update bot is configured.

The Bottom Line

The framework delivers a novel S³‑field approach to single‑image 3D avatar generation and ships working inference pipelines, but the absence of tests, CI, and a lockfile makes production‑grade changes fragile. Teams that can invest in a test harness and lockfile management will gain the most stability; others can safely experiment on isolated branches.