Image

Image preparation and T-pose generation Skill

Use this Skill when a game plan needs a single-subject concept image, a character reference cleaned for image-to-3D, or a front-facing transparent T-pose image for downstream character reconstruction. T-pose generation is an image-generation and image-editing task; it is not a separate asset category.

Scope and handoff

Do not use multi-view sheets, collages, multiple characters, busy scenery, watermarks, floor shadows, or cropped limbs as input to an image-to-3D workflow. They tend to become fused geometry, baked texture, or missing body parts.

Models and pipeline

The default T-pose route is Qwen Image Edit Qwen/Qwen-Image-Edit-2511 plus RMBG briaai/RMBG-1.4. The generation backend can be changed to Seedream doubao-seedream-5-0-260128 while keeping the same RMBG mask stage, shared T-pose prompt, operator, task JSONL, and output contract. Local model weights are downloaded on first use unless checkpoint flags point to local paths. A CUDA GPU is strongly recommended for Qwen Edit and RMBG; Seedream itself runs through the Ark API, but the RMBG stage still uses the local runtime.

Prefer the Seedream cloud route when the user permits paid generation; local Qwen Image Edit is the offline/declined fallback. Seedream is paid, so before the first call pause and follow Paid cloud backend in <REPO_PATH>/agent_skills/asset_qa/README.md: send the purchase/API-key page (https://console.volcengine.com/ark), state the estimated cost for the planned image count including retries, ask the user to buy access and supply ARK_API_KEY, and wait for an explicit answer.

Install the image environment

Install Qwen Image Edit and the local RMBG / Depth Anything mask runtime. This environment is also required when Seedream generation is followed by real RMBG:

bash scripts/asset_env_setup/image/qwen_image_install.sh
conda activate qwen_image

Install only the shared HTTP and smoke-test dependencies for cloud wrappers:

bash scripts/asset_env_setup/image/cloud_api_install.sh

Plan the image before generating

For each requested image, record the asset role, visual style, camera/view, intended downstream use, desired silhouette, material cues, and acceptance criteria. For a T-pose input, provide one clearly visible character reference and a description of appearance, costume, colors, and important accessories.

The T-pose editor preserves the input appearance while requesting this fixed result: upright character, arms horizontal at shoulder height, directly facing forward, flat white background, no scenery, no cast shadow, and clean game-art presentation. The pipeline then removes the background, crops the foreground, pads it to a square, and resizes it for reconstruction.

Generate concept art for 3D reconstruction

SDXLTurboModel is for fast single-object concept art, not final game art. It defaults to a square 512 px image and a negative prompt that excludes turnarounds, duplicate subjects, crops, ground planes, shadows, text, and busy backgrounds—details that harm 3D reconstruction.

from models.gen_image.sdxl_turbo import SDXLTurboModel

model = SDXLTurboModel(model_path="stabilityai/sdxl-turbo", device="cuda")
image = model.generate(
    prompt="a single stylized brass-and-wood treasure chest, centered, full object visible",
    seed=42,
)
image.save("/absolute/path/chest.png")
model.unload()

Keep only one subject in frame. If the result will be converted to 3D, review it before calling the 3D-object Skill rather than trying to repair bad geometry later.

Generate a T-pose image

Single image

Run from the repository root:

python pipeline/assets_gen/gen_tpose_image/run.py \
  --game gameA_cyberpunk_shooter \
  --run-id auto \
  --image /absolute/path/character_reference.png \
  --task-id character_tpose_001 \
  --description "Full-body cyberpunk scout, teal jacket, red utility belt, boots, and visor." \
  --seed 42 \
  --steps 40 \
  --target-size 1024

JSONL batch

Use --tasks for an explicit task file or --game to resolve that game's task list. A task supports image_path (or an in-memory PIL image for Python callers), game_id, task_id, description, seed, steps, target_size, and save_intermediate.

{"game_id":"gameA_cyberpunk_shooter","task_id":"luffy_tpose_001","image_path":"test_data/test_samples/gameA_cyberpunk_shooter/tpose/ref_images/luffy.jpg","description":"Monkey D. Luffy wearing his iconic red vest and straw hat.","seed":42,"steps":40,"target_size":1024}

python pipeline/assets_gen/gen_tpose_image/run.py \
  --tasks /absolute/path/tpose_tasks.jsonl \
  --run-id auto

Optional backend/model overrides and segmentation choice:

# Local Qwen Image Edit (default)
python pipeline/assets_gen/gen_tpose_image/run.py \
  --gen-backend qwen_edit \
  --gen-ckpt Qwen/Qwen-Image-Edit-2511 \
  --mask-ckpt briaai/RMBG-1.4 \
  --mask-type rmbg \
  --device cuda \
  --tasks test_data/test_samples/tpose_gen_collect.jsonl \
  --run-id auto

# Seedream API generation with the same local RMBG stage
export ARK_API_KEY="your-key"
python pipeline/assets_gen/gen_tpose_image/run.py \
  --gen-backend seedream \
  --gen-ckpt doubao-seedream-5-0-260128 \
  --mask-ckpt briaai/RMBG-1.4 \
  --mask-type rmbg \
  --device cuda \
  --tasks test_data/test_samples/tpose_gen_collect.jsonl \
  --run-id auto

Use --mask-type depth --mask-ckpt LiheYoung/depth-anything-small-hf only when the Depth Anything backend is intentionally selected. --out-dir is legacy flat-output mode for debugging; do not use it for game deliverables.

Outputs and metadata

The current registered task kind remains tpose, so standard artifacts are:

test_data/outputs/<game_id>/<run_id>/assets/tpose/<task_id>/
├── tpose_fg.png   # transparent-background deliverable
├── tpose.png      # white-background intermediate, unless save_intermediate=false
└── meta.json       # source, models, seed, steps, size, and task metadata

Use <REPO_PATH>/pipeline/common/paths.py and preserve this task-kind layout. The Skill is named image for agent routing; it does not rename existing pipeline APIs or artifact paths.

Validation and QA

Run free contract checks before loading production checkpoints or spending API credits:

python test/harness/smoke.py --kind tpose
python test/harness/smoke.py --kind tpose --backend seedream

The smoke harness uses stub models, requires only pillow, numpy, and scipy, and leaves no production output after success. Run the local checkpoint integration test when Qwen and RMBG weights plus a GPU are intentionally available:

QWEN_EDIT_CKPT=Qwen/Qwen-Image-Edit-2511 \
RMBG_CKPT=briaai/RMBG-1.4 \
python -m unittest test.test_gen_tpose_image -v

Run the paid Seedream integration against the same canonical task JSONL and the same RMBG stage only when explicitly requested:

export ARK_API_KEY="your-key"
export AAAGF_RUN_SEEDREAM_LIVE=1
export SEEDREAM_MODEL="doubao-seedream-5-0-260128"
export RMBG_CKPT="briaai/RMBG-1.4"
python -m unittest test.test_api_gen_tpose_image -v

Review every production image at full size before handoff:

1. Pose and framing: upright full body; both arms horizontal; feet, hands, head, and accessories visible; no crop or duplicate body parts.
2. Facing and identity: direct front view; readable facial/body orientation; costume, colors, and key accessories retained from the reference.
3. Background and alpha: no scenery, floor shadow, halo, or opaque white rectangle; inspect the transparent PNG on both light and dark backgrounds.
4. Reconstruction readiness: one centered subject with a clear silhouette; avoid excessive pose asymmetry, motion blur, text, watermarks, and tiny props.
5. Style: image must follow the planned game style before it is consumed by 3D or motion generation.

If any check fails, improve the source image or description, change the seed, regenerate, and re-review. Do not compensate for a reversed or malformed image only through downstream mesh rotations or gameplay code.