spine-animation-ai
AI-powered Claude skill for Spine 2D skeletal animation — auto-rig, animate, and preview characters
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/genielabsopensource--spine-animation-ai)HTML
<a href="/listings/genielabsopensource--spine-animation-ai"><img src="/api/listings/genielabsopensource--spine-animation-ai/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Option A: Claude Projects (Recommended)
The easiest way — works with any Claude account, no extra software needed.
1. Go to [claude.ai](https://claude.ai) → create a new **Project** 2. Open **Project Knowledge** → **Add content** 3. Copy the full contents of [`SKILL.md`](SKILL.md) and paste it in 4. Save — Claude now has the full skill baked in, **including all scripts embedded inline** 5. Upload your character assets and describe what you want:
"I have separated body part PNGs for my character. Create idle and walk animations."
Claude will write the scripts to disk, run the pipeline, and deliver `skeleton.json` + `preview.html`.
> **Why it works:** `SKILL.md` is auto-generated with all 4 Python scripts embedded inside it — Claude extracts and runs them without needing to clone the repo.
---
Option B: Claude Custom Skill (`/mnt/skills/` environments)
For Claude environments that support mounted skill directories:
git clone https://github.com/GenielabsOpenSource/spine-animation-ai.git /mnt/skills/user/spine-animation
Claude will automatically discover and load the skill on next session start.
---
Option C: Manual Pipeline (no Claude needed)
**Step 0: Split a Full Character Into Parts (New!)**
If you only have a single character image (not separated body parts), `split_character.py` uses Google Gemini to generate a deconstructed sprite atlas and then segments it into individual transparent PNGs via OpenCV connected-components analysis.
Prerequisites: - `GEMINI_API_KEY` environment variable — get a free key at https://aistudio.google.com/app/apikey - `pip install google-generativeai`
GEMINI_API_KEY=your_key python3 scripts/split_character.py character.png \ --output-dir parts/
Skip this step if you already have separated body-part PNGs.
**1. Auto-position parts from a reference image**
python3 scripts/position_parts.py \ --reference assembled_character.png \ --parts parts/ \ --output layout.json \ --debug debug/
**2. Build the Spine JSON**
python3 scripts/build_spine_json.py \ --config layout.json \ --output skeleton.json
**3. Pack a texture atlas**
python3 scripts/make_atlas.py \ --parts parts/ \ --output atlas/ \ --name skeleton
**4. Generate a self-contained HTML preview**
python3 scripts/generate_spine_player.py \ --skeleton skeleton.json \ --atlas skeleton.atlas \ --atlas-image skeleton.png \ --output preview.html
Open `preview.html` in any browser — no server needed.
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 1,995 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: spine-animation
- description: >
- Create Spine 2D skeletal animations from pre-existing character assets (separated body-part PNGs,
- atlas spritesheet, or a full character image). Use this skill whenever the user wants to animate
- a 2D character, create Spine JSON from existing art assets, rig a character with bones, build
- walk/idle/run/attack animations, produce an interactive Spine Web Player preview, or generate
- Spine-compatible export files (.json + .atlas + .png). Also trigger when the user mentions
- "Spine animation", "2D rigging", "skeletal animation", "bone animation", "cutout animation",
- "animate this character", "make this walk", "create walk cycle", or uploads separated character
- body parts and wants them animated. This skill handles the full pipeline: asset analysis,
- skeleton rigging, animation keyframing, Spine JSON export, and interactive HTML5 preview.
- ---
- <!-- ⚠️ AUTO-GENERATED FILE — DO NOT EDIT DIRECTLY
- Edit SKILL.template.md instead, then push to trigger rebuild.
- Scripts are embedded automatically by build_skill.py via GitHub Actions. -->
- # Spine Animation Skill
- Turn pre-existing 2D character assets into fully animated, interactive Spine animations.
- ## Step 0: Set Up Scripts
- This skill includes Python scripts that do the heavy lifting. Claude MUST write them to disk
- before use. Each script is embedded below — Claude should save them to `/home/claude/spine-scripts/`
- at the start of every session.
- ```bash
- mkdir -p /home/claude/spine-scripts
- pip install opencv-python Pillow numpy google-generativeai --break-system-packages -q
- ```
- ### Embedded Scripts
- The following scripts are auto-injected from the repository's `scripts/` directory.
- **Claude: read these carefully, then write each one to `/home/claude/spine-scripts/`**
- before running the pipeline.
- <!-- EMBED:scripts/split_character.py -->
- <details>
- <summary>📄 <code>scripts/split_character.py</code> (231 lines)</summary>
- ```python
- #!/usr/bin/env python3
- """
- split_character.py — Generate a sprite-sheet atlas from a full character image
- using Google Gemini image generation, then segment individual body parts via
- OpenCV connected-components analysis.
- Usage:
- python split_character.py <input_image> [--output-dir output_parts]
- [--atlas-out atlas.png] [--min-area 500] [--padding 12]
- [--bg-threshold 240]
- Requires:
- pip install google-generativeai opencv-python Pillow numpy
- Environment variable GEMINI_API_KEY must be set.
- """
- import argparse
- import os
- import sys
- import cv2
- import numpy as np
- from PIL import Image
- def get_gemini_client():
- """Initialise the Gemini generative-AI client, or exit with a helpful
- error if the API key is missing."""
- api_key = os.environ.get("GEMINI_API_KEY")
- if not api_key:
- print(
- "ERROR: GEMINI_API_KEY environment variable is not set.\n"
- "Get a free API key at: https://aistudio.google.com/app/apikey\n"
- "Then run:\n"
- " export GEMINI_API_KEY=your_key_here",
- file=sys.stderr,
- )
- sys.exit(1)
- from google import genai
- client = genai.Client(api_key=api_key)
- return client
- POSITIVE_PROMPT = (
- "A complete 2D game sprite sheet texture atlas for Spine animation of the "
- "exact character in the reference image. The character is completely "
- "deconstructed into separated, isolated body parts. Separated individual "
- "parts laid out flatly: isolated head, isolated torso, isolated upper arms, "
- "lower arms, hands, upper legs, lower legs, and feet. Spread out with clear "
- "space between every single body part. No overlapping parts. Clean solid "
- "white background. CRITICAL: Maintain the exact same art style, exact same "
- "shading, exact face, and exact color palette as the reference image. "
- "Identical style match, 2D game asset, flat layout, character design sheet."
- )
- NEGATIVE_PROMPT = (
- "3D, realistic, altered style, different art style, different face, "
- "redesign, overlapping parts, connected limbs, full body standing, dynamic "
- "pose, background scenery, shadows, gradients on background, messy layout, "
- "missing limbs, merged layers, text, watermarks."
- )
- def generate_atlas(client, input_image_path: str, atlas_out: str) -> str:
- """Send the reference image to Gemini and save the generated atlas PNG."""
- from google.genai import types
- ref_image = Image.open(input_image_path)
- response = client.models.generate_content(
- model="gemini-3.1-flash-image-preview",
- contents=[
- POSITIVE_PROMPT,
- f"Negative prompt: {NEGATIVE_PROMPT}",
- ref_image,
- ],
- config=types.GenerateContentConfig(
- response_modalities=["IMAGE", "TEXT"],
- ),
- )
- # Extract the generated image from the response parts
- for part in response.candidates[0].content.parts:
- if part.inline_data is not None:
- image_data = part.inline_data.data
- with open(atlas_out, "wb") as f:
- f.write(image_data)
- return atlas_out
- print("ERROR: Gemini did not return an image in its response.", file=sys.stderr)
- sys.exit(1)
- def segment_parts(
- atlas_path: str,
- output_dir: str,
- min_area: int = 500,
- padding: int = 12,
- bg_threshold: int = 240,
- ) -> list[str]:
- """Detect individual parts in the atlas using connected-components analysis.
- Returns a list of saved part file paths.
- """
- img = cv2.imread(atlas_path, cv2.IMREAD_UNCHANGED)
- if img is None:
- print(f"ERROR: Could not read atlas image: {atlas_path}", file=sys.stderr)
- sys.exit(1)
- # Convert to RGBA if needed
- if img.shape[2] == 3:
- img = cv2.cvtColor(img, cv2.COLOR_BGR2BGRA)
- # Build a foreground mask: pixels whose RGB channels are all below the
- # background threshold are considered foreground.
- bgr = img[:, :, :3]
- gray = cv2.cvtColor(bgr, cv2.COLOR_BGR2GRAY)
- _, mask = cv2.threshold(gray, bg_threshold, 255, cv2.THRESH_BINARY_INV)
- # Connected-components analysis (8-connectivity)
- num_labels, labels, stats, _ = cv2.connectedComponentsWithStats(
- mask, connectivity=8
- )
- os.makedirs(output_dir, exist_ok=True)
- saved: list[str] = []
- part_idx = 0
- h_img, w_img = img.shape[:2]
- for label_id in range(1, num_labels): # skip background (label 0)
- area = stats[label_id, cv2.CC_STAT_AREA]
- if area < min_area:
- continue
- x = stats[label_id, cv2.CC_STAT_LEFT]
- y = stats[label_id, cv2.CC_STAT_TOP]
- w = stats[label_id, cv2.CC_STAT_WIDTH]
- h = stats[label_id, cv2.CC_STAT_HEIGHT]
- # Apply padding (clamped to image bounds)
- x1 = max(x - padding, 0)
- y1 = max(y - padding, 0)
- x2 = min(x + w + padding, w_img)
- y2 = min(y + h + padding, h_img)
- # Crop the RGBA region
- crop = img[y1:y2, x1:x2].copy()
- # Zero-out pixels that don't belong to this component (make transparent)
- label_region = labels[y1:y2, x1:x2]
- component_mask = label_region == label_id
- crop[~component_mask] = [0, 0, 0, 0]
- out_path = os.path.join(output_dir, f"part_{part_idx:02d}.png")
- cv2.imwrite(out_path, crop)
- saved.append(out_path)
- part_idx += 1
- return saved
- def main():
- parser = argparse.ArgumentParser(
- description="Generate a sprite atlas from a character image using "
- "Gemini, then segment into individual body parts."
- )
- parser.add_argument("input_image", help="Path to the character reference image")
- parser.add_argument(
- "--output-dir",
- default="output_parts",
- help="Directory for cropped part PNGs (default: output_parts)",
- )
- parser.add_argument(
- "--atlas-out",
- default="atlas.png",
- help="Output path for the generated atlas PNG (default: atlas.png)",
- )
- parser.add_argument(
- "--min-area",
- type=int,
- default=500,
- help="Minimum component area in pixels to keep (default: 500)",
- )
- parser.add_argument(
- "--padding",
- type=int,
- default=12,
- help="Padding in pixels around each cropped part (default: 12)",
- )
- parser.add_argument(
- "--bg-threshold",
- type=int,
- default=240,
- help="Grayscale threshold above which pixels are treated as background (default: 240)",
- )
- args = parser.parse_args()
- if not os.path.isfile(args.input_image):
- print(f"ERROR: Input image not found: {args.input_image}", file=sys.stderr)
- sys.exit(1)
- # --- Step 1: Generate atlas ---
- print("[1/3] Generating atlas …")
- client = get_gemini_client()
- generate_atlas(client, args.input_image, args.atlas_out)
- print(f" Atlas saved to {args.atlas_out}")
- # --- Step 2: Segment parts ---
- print("[2/3] Segmenting parts …")
- parts = segment_parts(
- args.atlas_out,
- args.output_dir,
- min_area=args.min_area,
- padding=args.padding,
- bg_threshold=args.bg_threshold,
- )
- print(f" Found {len(parts)} parts → {args.output_dir}/")
- for p in parts:
- print(f" • {os.path.basename(p)}")
- # --- Step 3: Done ---
- print("[3/3] Done ✓")
- print(f"\nParts are in: {args.output_dir}/")
- print("You can now feed them into position_parts.py (Step 1 of the Spine pipeline).")
- if __name__ == "__main__":
- main()
- ```
- </details>
- <!-- EMBED:scripts/position_parts.py -->
- <details>
- <summary>📄 <code>scripts/position_parts.py</code> (492 lines)</summary>
- ```python
- #!/usr/bin/env python3
- """
- position_parts.py — Part positioning via SIFT + RANSAC homography, z-order via occlusion.
- Given a fully assembled character image and individual body-part PNGs,
- determines where each part goes (x, y, scale, rotation) and the draw order.
- Algorithm:
- Phase 1 — SIFT keypoint matching + RANSAC homography
- - Extract SIFT features from each part (alpha-masked) and the reference
- - Match descriptors via FLANN (knnMatch + Lowe's ratio test)
- - Estimate homography via RANSAC → extract position, scale, rotation
- - For small/low-texture parts that fail SIFT: fall back to template matching
- Phase 2 — Pairwise occlusion voting for z-order
- - Sample overlap pixels, compare to reference → occlusion graph → topo sort
- Usage:
- python3 position_parts.py \
- --reference character.png \
- --parts parts_folder/ \
- --output layout.json \
- [--min-matches 4] \
- [--ratio 0.80] \
- [--debug debug_folder/]
- """
- import argparse, json, os, sys, math
- from pathlib import Path
- from collections import defaultdict
- import cv2
- import numpy as np
- from PIL import Image
- def load_rgba(path):
- return np.array(Image.open(path).convert("RGBA"))
- def create_foreground_mask(rgba, bg_color=(255,255,255), bg_threshold=30):
- alpha = rgba[:, :, 3]
- is_opaque = alpha > 128
- rgb = rgba[:, :, :3].astype(float)
- dist = np.sqrt(np.sum((rgb - np.array(bg_color, dtype=float)) ** 2, axis=2))
- mask = (is_opaque & (dist > bg_threshold)).astype(np.uint8) * 255
- k = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))
- return cv2.morphologyEx(cv2.morphologyEx(mask, cv2.MORPH_CLOSE, k), cv2.MORPH_OPEN, k)
- # ─────────────────────────────────────────────────────────────────
- # Phase 1: SIFT + RANSAC
- # ─────────────────────────────────────────────────────────────────
- def sift_match_part(ref_gray, ref_kp, ref_des, part_rgba,
- sift, ratio_thresh=0.80, min_matches=4):
- """
- Match a part to the reference using SIFT + FLANN + RANSAC affine transform.
- Uses estimateAffinePartial2D (4 DOF: translate + scale + rotation) instead
- of full homography — much more robust with sparse matches on game art.
- Returns dict with position/scale/rotation/score, or None.
- """
- part_h, part_w = part_rgba.shape[:2]
- part_gray = cv2.cvtColor(part_rgba[:, :, :3], cv2.COLOR_RGB2GRAY)
- part_mask = (part_rgba[:, :, 3] > 128).astype(np.uint8) * 255
- part_kp, part_des = sift.detectAndCompute(part_gray, part_mask)
- if part_des is None or len(part_kp) < 2:
- return None
- # FLANN matching
- flann = cv2.FlannBasedMatcher(dict(algorithm=1, trees=5), dict(checks=150))
- try:
- matches = flann.knnMatch(part_des, ref_des, k=2)
- except cv2.error:
- return None
- # Lowe's ratio test
- good = []
- for pair in matches:
- if len(pair) == 2 and pair[0].distance < ratio_thresh * pair[1].distance:
- good.append(pair[0])
- if len(good) < min_matches:
- return None
- src_pts = np.float32([part_kp[m.queryIdx].pt for m in good]).reshape(-1, 1, 2)
- dst_pts = np.float32([ref_kp[m.trainIdx].pt for m in good]).reshape(-1, 1, 2)
- # RANSAC similarity transform (4 DOF: translate + uniform scale + rotation)
- # This is much more constrained than homography (8 DOF) and needs only 2 points
- M, inliers_mask = cv2.estimateAffinePartial2D(
- src_pts, dst_pts, method=cv2.RANSAC, ransacReprojThreshold=5.0)
- if M is None or inliers_mask is None:
- return None
- inliers = int(inliers_mask.sum())
- if inliers < min_matches:
- return None
- # Extract scale and rotation from 2x3 affine matrix
- # M = [[s*cos(θ), -s*sin(θ), tx], [s*sin(θ), s*cos(θ), ty]]
- scale = np.sqrt(M[0,0]**2 + M[1,0]**2)
- rotation = math.degrees(math.atan2(M[1,0], M[0,0]))
- # Sanity: game parts should be ~0.5–2.0x scale, ~0° rotation
- if scale < 0.3 or scale > 3.0:
- return None
- if abs(rotation) > 20:
- return None
- # Transform corners via the affine matrix
- corners = np.float32([[0,0],[part_w,0],[part_w,part_h],[0,part_h]]).reshape(-1,1,2)
- transformed = cv2.transform(corners, M).reshape(-1, 2)
- x_min, y_min = transformed[:, 0].min(), transformed[:, 1].min()
- x_max, y_max = transformed[:, 0].max(), transformed[:, 1].max()
- out_w, out_h = x_max - x_min, y_max - y_min
- if out_w < 5 or out_h < 5:
- return None
- inlier_ratio = inliers / len(good) if good else 0
- return {
- "x": int(round(x_min)), "y": int(round(y_min)),
- "width": int(round(out_w)), "height": int(round(out_h)),
- "original_width": part_w, "original_height": part_h,
- "scale": round(scale, 4), "rotation": round(rotation, 2),
- "score": round(inlier_ratio, 4),
- "n_matches": inliers, "n_good": len(good),
- "n_keypoints": len(part_kp), "method": "sift",
- }
- def template_match_fallback(ref_bgr, ref_fg_mask, part_bgra,
- scales=None):
- """Fallback for parts too small/featureless for SIFT."""
- if scales is None:
- scales = (0.85, 0.9, 0.95, 1.0, 1.05, 1.1, 1.15)
- ref_h, ref_w = ref_bgr.shape[:2]
- best = None
- for scale in scales:
- sw = max(1, int(part_bgra.shape[1] * scale))
- sh = max(1, int(part_bgra.shape[0] * scale))
- if sw >= ref_w - 2 or sh >= ref_h - 2:
- continue
- interp = cv2.INTER_AREA if scale < 1 else cv2.INTER_LINEAR
- scaled = cv2.resize(part_bgra, (sw, sh), interpolation=interp)
- tmpl_bgr = cv2.cvtColor(scaled, cv2.COLOR_BGRA2BGR)
- mask = (scaled[:, :, 3] > 128).astype(np.uint8) * 255
- opaque = np.count_nonzero(mask)
- if opaque < 20:
- continue
- try:
- result = cv2.matchTemplate(ref_bgr, tmpl_bgr, cv2.TM_CCORR_NORMED, mask=mask)
- except cv2.error:
- continue
- _, max_val, _, max_loc = cv2.minMaxLoc(result)
- fg_region = ref_fg_mask[max_loc[1]:max_loc[1]+sh, max_loc[0]:max_loc[0]+sw]
- fg_ratio = 0.0
- if fg_region.shape == (sh, sw):
- fg_ratio = np.count_nonzero(fg_region[mask > 128] > 128) / max(1, opaque)
- combined = max_val * (0.3 + 0.7 * fg_ratio)
- if best is None or combined > best["score"]:
- best = {
- "x": int(max_loc[0]), "y": int(max_loc[1]),
- "width": sw, "height": sh,
- "original_width": part_bgra.shape[1], "original_height": part_bgra.shape[0],
- "scale": round(scale, 4), "rotation": 0.0,
- "score": round(combined, 4),
- "n_matches": 0, "n_good": 0, "n_keypoints": 0,
- "method": "template",
- }
- return best
- def find_all_positions(reference_path, parts_folder, ratio_thresh, min_matches):
- ref_rgba = load_rgba(reference_path)
- ref_gray = cv2.cvtColor(ref_rgba[:, :, :3], cv2.COLOR_RGB2GRAY)
- ref_bgra = cv2.cvtColor(ref_rgba, cv2.COLOR_RGBA2BGRA)
- ref_bgr = cv2.cvtColor(ref_bgra, cv2.COLOR_BGRA2BGR)
- fg_mask = create_foreground_mask(ref_rgba)
- # Tuned SIFT: lower contrast threshold to find more features on game art
- sift = cv2.SIFT_create(nfeatures=0, contrastThreshold=0.02, edgeThreshold=20)
- print("Computing SIFT on reference...")
- ref_kp, ref_des = sift.detectAndCompute(ref_gray, None)
- print(f" Reference: {ref_gray.shape[1]}x{ref_gray.shape[0]}, {len(ref_kp)} keypoints\n")
- part_files = sorted([f for f in os.listdir(parts_folder) if f.lower().endswith(('.png','.webp'))])
- # First pass: try SIFT on all parts
- sift_results = {}
- failed_parts = []
- for fname in part_files:
- name = Path(fname).stem
- part_rgba = load_rgba(os.path.join(parts_folder, fname))
- if np.count_nonzero(part_rgba[:,:,3] > 128) / part_rgba[:,:,3].size < 0.01:
- print(f" SKIP {name}: <1% opaque")
- continue
- result = sift_match_part(ref_gray, ref_kp, ref_des, part_rgba,
- sift, ratio_thresh, min_matches)
- if result:
- sift_results[name] = result
- print(f" SIFT {name:>20}: pos=({result['x']},{result['y']}) "
- f"scale={result['scale']:.3f} rot={result['rotation']:.1f}° "
- f"inliers={result['n_matches']}/{result['n_good']} "
- f"score={result['score']:.3f}")
- else:
- failed_parts.append((name, part_rgba))
- # Derive template matching scales from SIFT results
- tmpl_scales = (0.85, 0.9, 0.95, 1.0, 1.05, 1.1, 1.15)
- if sift_results:
- sift_scales = [r["scale"] for r in sift_results.values()]
- median_scale = float(np.median(sift_scales))
- # Generate scale range around the SIFT median: ±20%
- tmpl_scales = tuple(round(median_scale * f, 4)
- for f in (0.80, 0.85, 0.90, 0.95, 1.0, 1.05, 1.10, 1.15, 1.20))
- print(f"\n SIFT median scale: {median_scale:.3f} → template range: "
- f"{tmpl_scales[0]:.3f}–{tmpl_scales[-1]:.3f}")
- # Second pass: template matching for failed parts using SIFT-derived scales
- positions = dict(sift_results)
- for name, part_rgba in failed_parts:
- part_bgra = cv2.cvtColor(part_rgba, cv2.COLOR_RGBA2BGRA)
- result = template_match_fallback(ref_bgr, fg_mask, part_bgra, scales=tmpl_scales)
- if result:
- positions[name] = result
- print(f" TMPL {name:>20}: pos=({result['x']},{result['y']}) "
- f"scale={result['scale']:.3f} score={result['score']:.3f}")
- else:
- print(f" FAIL {name:>20}: no match")
- return positions, fg_mask
- # ─────────────────────────────────────────────────────────────────
- # Phase 2: Z-Order via Occlusion
- # ─────────────────────────────────────────────────────────────────
- def compute_z_order(reference_path, parts_folder, positions):
- reference = load_rgba(reference_path)
- ref_h, ref_w = reference.shape[:2]
- part_images = {}
- for name, pos in positions.items():
- fp = None
- for ext in ['.png','.webp']:
- c = os.path.join(parts_folder, name+ext)
- if os.path.exists(c): fp = c; break
- if not fp: continue
- img = load_rgba(fp)
- tw, th = pos["width"], pos["height"]
- if (tw, th) != (img.shape[1], img.shape[0]):
- img = np.array(Image.fromarray(img).resize((tw, th), Image.LANCZOS))
- part_images[name] = img
- names = list(part_images.keys())
- n = len(names)
- wins = defaultdict(lambda: defaultdict(int))
- print(f"\nZ-order analysis ({n} parts):")
- for i in range(n):
- for j in range(i+1, n):
- a, b = names[i], names[j]
- ap, bp = positions[a], positions[b]
- ai, bi = part_images[a], part_images[b]
- ox1 = max(ap["x"], bp["x"])
- oy1 = max(ap["y"], bp["y"])
- ox2 = min(ap["x"]+ap["width"], bp["x"]+bp["width"])
- oy2 = min(ap["y"]+ap["height"], bp["y"]+bp["height"])
- if ox1 >= ox2 or oy1 >= oy2: continue
- step = max(1, int(math.sqrt((ox2-ox1)*(oy2-oy1)/500)))
- aw, bw, tot = 0, 0, 0
- for sy in range(oy1, oy2, step):
- for sx in range(ox1, ox2, step):
- if sy >= ref_h or sx >= ref_w: continue
- rp = reference[sy, sx]
- if rp[3] < 128: continue
- aly, alx = sy-ap["y"], sx-ap["x"]
- bly, blx = sy-bp["y"], sx-bp["x"]
- if not (0<=alx<ai.shape[1] and 0<=aly<ai.shape[0]): continue
- if not (0<=blx<bi.shape[1] and 0<=bly<bi.shape[0]): continue
- apx, bpx = ai[aly, alx], bi[bly, blx]
- if apx[3] < 128 or bpx[3] < 128: continue
- ad = np.sqrt(np.sum((rp[:3].astype(float)-apx[:3].astype(float))**2))
- bd = np.sqrt(np.sum((rp[:3].astype(float)-bpx[:3].astype(float))**2))
- tot += 1
- if ad < bd - 5: aw += 1
- elif bd < ad - 5: bw += 1
- if tot > 5:
- if aw > bw * 1.2:
- wins[a][b] += aw
- print(f" {a} OVER {b} ({aw}/{tot})")
- elif bw > aw * 1.2:
- wins[b][a] += bw
- print(f" {b} OVER {a} ({bw}/{tot})")
- depth = {nm: 0.0 for nm in names}
- for a in names:
- for b in names:
- if a != b and wins[a][b] > 0:
- depth[b] -= wins[a][b]
- depth[a] += wins[a][b]
- result = sorted(names, key=lambda nm: depth[nm])
- print(f"\nDraw order (back -> front):")
- for i, nm in enumerate(result):
- print(f" z={i:>2}: {nm} (depth={depth[nm]:.0f}, {positions[nm]['method']})")
- return result, depth
- # ─────────────────────────────────────────────────────────────────
- # Debug Visualization
- # ─────────────────────────────────────────────────────────────────
- def generate_debug(ref_path, parts_folder, positions, z_order, fg_mask, debug_dir):
- os.makedirs(debug_dir, exist_ok=True)
- ref = load_rgba(ref_path)
- rh, rw = ref.shape[:2]
- # Composite
- comp = np.zeros((rh, rw, 4), dtype=np.uint8)
- comp[:,:,:3] = 255; comp[:,:,3] = 255
- for name in z_order:
- if name not in positions: continue
- pos = positions[name]
- fp = None
- for ext in ['.png','.webp']:
- c = os.path.join(parts_folder, name+ext)
- if os.path.exists(c): fp = c; break
- if not fp: continue
- img = load_rgba(fp)
- tw, th = pos["width"], pos["height"]
- if (tw, th) != (img.shape[1], img.shape[0]):
- img = np.array(Image.fromarray(img).resize((tw, th), Image.LANCZOS))
- x, y = pos["x"], pos["y"]
- ph, pw = img.shape[:2]
- sx1, sy1 = max(0,-x), max(0,-y)
- dx1, dy1 = max(0,x), max(0,y)
- sx2, sy2 = min(pw, rw-x), min(ph, rh-y)
- dx2, dy2 = dx1+(sx2-sx1), dy1+(sy2-sy1)
- if sx2<=sx1 or sy2<=sy1: continue
- pr = img[sy1:sy2, sx1:sx2]
- a = pr[:,:,3:4].astype(float)/255.0
- cr = comp[dy1:dy2, dx1:dx2, :3].astype(float)
- comp[dy1:dy2, dx1:dx2, :3] = (pr[:,:,:3].astype(float)*a + cr*(1-a)).astype(np.uint8)
- Image.fromarray(comp).save(os.path.join(debug_dir, "composite.png"))
- # Side-by-side
- gap = 10
- sb = np.zeros((rh, rw*2+gap, 4), dtype=np.uint8)
- sb[:,:,:3]=40; sb[:,:,3]=255
- sb[:rh,:rw] = ref; sb[:rh,rw+gap:rw*2+gap] = comp
- Image.fromarray(sb).save(os.path.join(debug_dir, "comparison.png"))
- # Bboxes
- rv = ref.copy()
- colors = [(255,80,80),(80,255,80),(80,80,255),(255,255,80),(255,80,255),
- (80,255,255),(200,140,80),(140,80,200),(80,200,140),
- (255,160,120),(120,255,160),(160,120,255),(200,200,100)]
- for i, (name, pos) in enumerate(positions.items()):
- c = colors[i % len(colors)]
- m = pos["method"][0].upper()
- x1, y1 = pos["x"], pos["y"]
- x2, y2 = x1+pos["width"], y1+pos["height"]
- cv2.rectangle(rv, (x1,y1), (x2,y2), c+(255,), 2)
- label = f"{name} [{m}] s={pos['scale']:.2f} m={pos.get('n_matches',0)}"
- cv2.putText(rv, label, (x1, y1-5),
- cv2.FONT_HERSHEY_SIMPLEX, 0.33, c+(255,), 1)
- Image.fromarray(rv).save(os.path.join(debug_dir, "bboxes.png"))
- # FG mask
- Image.fromarray(cv2.cvtColor(fg_mask, cv2.COLOR_GRAY2RGBA)).save(
- os.path.join(debug_dir, "fg_mask.png"))
- # Per-part SIFT match visualizations
- sift = cv2.SIFT_create(nfeatures=0, contrastThreshold=0.02, edgeThreshold=20)
- ref_gray = cv2.cvtColor(ref[:,:,:3], cv2.COLOR_RGB2GRAY)
- ref_kp, ref_des = sift.detectAndCompute(ref_gray, None)
- for name, pos in positions.items():
- if pos["method"] != "sift": continue
- fp = None
- for ext in ['.png','.webp']:
- c = os.path.join(parts_folder, name+ext)
- if os.path.exists(c): fp = c; break
- if not fp: continue
- prgba = load_rgba(fp)
- pgray = cv2.cvtColor(prgba[:,:,:3], cv2.COLOR_RGB2GRAY)
- pmask = (prgba[:,:,3] > 128).astype(np.uint8) * 255
- pkp, pdes = sift.detectAndCompute(pgray, pmask)
- if pdes is None: continue
- flann = cv2.FlannBasedMatcher(dict(algorithm=1, trees=5), dict(checks=150))
- matches = flann.knnMatch(pdes, ref_des, k=2)
- good = [m for m, n in matches if len([m,n])==2 and m.distance < 0.8*n.distance]
- if len(good) >= 4:
- src = np.float32([pkp[m.queryIdx].pt for m in good]).reshape(-1,1,2)
- dst = np.float32([ref_kp[m.trainIdx].pt for m in good]).reshape(-1,1,2)
- H, hmask = cv2.estimateAffinePartial2D(src, dst, method=cv2.RANSAC, ransacReprojThreshold=5.0)
- if hmask is not None:
- draw_p = dict(matchColor=(0,255,0), singlePointColor=(255,0,0),
- matchesMask=hmask.ravel().tolist(),
- flags=cv2.DrawMatchesFlags_NOT_DRAW_SINGLE_POINTS)
- pbgr = cv2.cvtColor(prgba[:,:,:3], cv2.COLOR_RGB2BGR)
- rbgr = cv2.cvtColor(ref[:,:,:3], cv2.COLOR_RGB2BGR)
- vis = cv2.drawMatches(pbgr, pkp, rbgr, ref_kp, good, None, **draw_p)
- cv2.imwrite(os.path.join(debug_dir, f"sift_{name}.jpg"), vis,
- [cv2.IMWRITE_JPEG_QUALITY, 70])
- print(f"\nDebug saved to {debug_dir}/")
- # ─────────────────────────────────────────────────────────────────
- # Main
- # ─────────────────────────────────────────────────────────────────
- def main():
- p = argparse.ArgumentParser(
- description="Position parts via SIFT+RANSAC homography + occlusion z-order")
- p.add_argument("--reference", required=True)
- p.add_argument("--parts", required=True)
- p.add_argument("--output", default="layout.json")
- p.add_argument("--min-matches", type=int, default=4,
- help="Min RANSAC inliers (default: 4)")
- p.add_argument("--ratio", type=float, default=0.80,
- help="Lowe's ratio threshold (default: 0.80)")
- p.add_argument("--debug", default=None)
- args = p.parse_args()
- print("=" * 60)
- print("PHASE 1: SIFT + RANSAC Homography")
- print("=" * 60)
- positions, fg_mask = find_all_positions(
- args.reference, args.parts, args.ratio, args.min_matches)
- if not positions:
- print("ERROR: No parts matched!"); sys.exit(1)
- sift_n = sum(1 for p in positions.values() if p["method"] == "sift")
- tmpl_n = sum(1 for p in positions.values() if p["method"] == "template")
- print(f"\nResult: {sift_n} SIFT, {tmpl_n} template fallback")
- print(f"\n{'='*60}")
- print("PHASE 2: Z-Order (Occlusion Analysis)")
- print("="*60)
- z_order, depth = compute_z_order(args.reference, args.parts, positions)
- for i, name in enumerate(z_order):
- if name in positions:
- positions[name]["z_index"] = i
- positions[name]["depth_score"] = depth[name]
- ref_img = Image.open(args.reference)
- output = {
- "reference_image": os.path.basename(args.reference),
- "canvas_width": ref_img.width, "canvas_height": ref_img.height,
- "parts": positions, "z_order": z_order,
- }
- with open(args.output, "w") as f:
- json.dump(output, f, indent=2)
- print(f"\nLayout saved: {args.output}")
- if args.debug:
- generate_debug(args.reference, args.parts, positions, z_order, fg_mask, args.debug)
- if __name__ == "__main__":
- main()
- ```
- </details>
- <!-- EMBED:scripts/build_spine_json.py -->
- <details>
- <summary>📄 <code>scripts/build_spine_json.py</code> (562 lines)</summary>
- ```python
- #!/usr/bin/env python3
- """
- build_spine_json.py — Generate a complete Spine-compatible JSON skeleton with animations.
- Accepts a config describing bones, slots, attachments, and desired animations,
- then outputs a valid Spine 4.2 JSON file.
- Usage:
- python3 build_spine_json.py --config config.json --output skeleton.json
- Config JSON format:
- {
- "skeleton": {
- "name": "my-character",
- "width": 400,
- "height": 600
- },
- "bones": [
- { "name": "root" },
- { "name": "hip", "parent": "root", "x": 0, "y": 200, "length": 30 },
- { "name": "torso", "parent": "hip", "length": 120 },
- ...
- ],
- "slots": [
- { "name": "torso", "bone": "torso", "attachment": "torso" },
- ...
- ],
- "attachments": {
- "torso": { "width": 120, "height": 200, "x": 0, "y": 60 },
- ...
- },
- "animations": ["idle", "walk", "wave", "jump", "run", "attack"],
- "custom_animations": {
- "my-custom": { "bones": { "head": { "rotate": [...] } } }
- }
- }
- """
- import argparse
- import json
- import hashlib
- import sys
- # ─── Bezier curve presets ────────────────────────────────────────────────────
- EASE = [0.25, 0, 0.75, 1] # Standard ease in-out (most common)
- EASE_IN = [0.42, 0, 1, 1] # Accelerate from rest
- EASE_OUT = [0, 0, 0.58, 1] # Decelerate to rest
- EASE_BOUNCE = [0.34, 1.56, 0.64, 1] # Slight overshoot
- EASE_FAST = [0.4, 0, 0.2, 1] # Quick but smooth
- def _has(bone_names, *names):
- """Check if any of the given bone names exist."""
- return any(n in bone_names for n in names)
- def _kf(time, angle=None, x=None, y=None, curve=EASE):
- """Build a keyframe dict, omitting None values.
- This is the authoring shorthand used by the generators below: rotations go
- under "angle", and `curve` is a single normalized bezier describing the
- segment that ends at this keyframe. `_to_spine_42` rewrites both into the
- wire format before the skeleton is serialized.
- """
- kf = {"time": round(time, 4)}
- if angle is not None:
- kf["angle"] = round(angle, 2)
- if x is not None:
- kf["x"] = round(x, 2)
- if y is not None:
- kf["y"] = round(y, 2)
- if curve:
- kf["curve"] = curve
- return kf
- # ─── Spine 4.2 wire format ──────────────────────────────────────────────────
- # Timeline type -> the properties it animates, with their default values.
- _TIMELINE_PROPERTIES = {
- "rotate": (("value", 0.0),),
- "translate": (("x", 0.0), ("y", 0.0)),
- "scale": (("x", 1.0), ("y", 1.0)),
- "shear": (("x", 0.0), ("y", 0.0)),
- "translatex": (("value", 0.0),),
- "translatey": (("value", 0.0),),
- "scalex": (("value", 1.0),),
- "scaley": (("value", 1.0),),
- "shearx": (("value", 0.0),),
- "sheary": (("value", 0.0),),
- }
- def _convert_timeline(kind, frames):
- """Rewrite one bone timeline in place into the Spine 4.2 wire format.
- Three things differ from the 3.8-era shorthand the generators author in:
- 1. Rotation values live under "value", not "angle". A 4.x runtime that
- finds "angle" reads every rotation as 0, so nothing turns.
- 2. A bezier is stored per ANIMATED PROPERTY, not per keyframe. `rotate`
- drives one property and needs 4 numbers, but `translate`, `scale` and
- `shear` drive two (x and y) and need 8. Given only 4, the runtime
- indexes past the end of the array, reads undefined, and NaN spreads
- through the bone transforms until the skeleton stops rasterizing
- entirely -- it renders the setup pose for one frame, then vanishes.
- 3. Control points are absolute, in the same units as `time` and `value`,
- not normalized to the segment. From Animation.js in spine-core:
- let dx = (cx1 - time1) * 0.3 + ...; let x = time1 + dx;
- Normalized points land outside the segment they belong to, which makes
- the interpolation lurch instead of ease.
- A keyframe's curve also governs the segment that STARTS at it, so curves
- shift one frame earlier: what the generators attach to frame i describes
- the segment i-1 -> i.
- """
- properties = _TIMELINE_PROPERTIES.get(kind)
- if not properties or len(frames) < 2:
- return
- if kind == "rotate":
- for kf in frames:
- if "angle" in kf:
- kf["value"] = kf.pop("angle")
- authored = [kf.pop("curve", None) for kf in frames]
- for i in range(len(frames) - 1):
- curve = authored[i + 1]
- if curve is None:
- continue
- if curve == "stepped":
- frames[i]["curve"] = "stepped"
- continue
- if not isinstance(curve, list) or len(curve) < 4:
- continue
- cx1, cy1, cx2, cy2 = curve[:4]
- time1, time2 = frames[i]["time"], frames[i + 1]["time"]
- span = time2 - time1
- absolute = []
- for name, default in properties:
- value1 = frames[i].get(name, default)
- value2 = frames[i + 1].get(name, default)
- delta = value2 - value1
- absolute += [
- round(time1 + span * cx1, 6), round(value1 + delta * cy1, 6),
- round(time1 + span * cx2, 6), round(value1 + delta * cy2, 6),
- ]
- frames[i]["curve"] = absolute
- def _to_spine_42(animations):
- """Convert every bone timeline in `animations` to the Spine 4.2 format."""
- for animation in animations.values():
- for timelines in animation.get("bones", {}).values():
- for kind, frames in timelines.items():
- _convert_timeline(kind, frames)
- # ─── Animation Generators ───────────────────────────────────────────────────
- def gen_idle(B):
- """Idle breathing/sway. Subtle, loopable. ~1.6s"""
- bones = {}
- D = 1.6
- for name, angle_amp, phase in [
- ("torso", 1.5, 0.5), ("neck", 1.0, 0.55), ("head", -2.0, 0.6)
- ]:
- if name in B:
- bones[name] = {"rotate": [
- _kf(0, 0, curve=None),
- _kf(D * phase, angle_amp),
- _kf(D, 0),
- ]}
- # Subtle torso lift
- if "torso" in B:
- bones.setdefault("torso", {})["translate"] = [
- _kf(0, x=0, y=0, curve=None),
- _kf(D * 0.5, x=0, y=1.5),
- _kf(D, x=0, y=0),
- ]
- # Gentle arm sway
- for side in ["left", "right"]:
- s = 1 if side == "left" else -1
- for part, amp, ph in [
- (f"{side}-upper-arm", s * 1.5, 0.5),
- (f"{side}-lower-arm", s * 1.0, 0.55),
- ]:
- if part in B:
- bones[part] = {"rotate": [
- _kf(0, 0, curve=None), _kf(D * ph, amp), _kf(D, 0),
- ]}
- return {"bones": bones} if bones else {}
- def gen_walk(B):
- """Walk cycle. Opposing arm-leg motion, hip bob. ~0.8s"""
- bones = {}
- D = 0.8
- Q = D / 4 # quarter
- if "hip" in B:
- bones["hip"] = {
- "translate": [
- _kf(0, x=0, y=0, curve=None),
- _kf(Q, x=0, y=3), _kf(Q*2, x=0, y=0),
- _kf(Q*3, x=0, y=3), _kf(D, x=0, y=0),
- ],
- "rotate": [
- _kf(0, 0, curve=None),
- _kf(Q, -2), _kf(Q*2, 0), _kf(Q*3, 2), _kf(D, 0),
- ],
- }
- if "torso" in B:
- bones["torso"] = {"rotate": [
- _kf(0, 0, curve=None),
- _kf(Q, 3), _kf(Q*2, 0), _kf(Q*3, -3), _kf(D, 0),
- ]}
- if "head" in B:
- bones["head"] = {"rotate": [
- _kf(0, 0, curve=None),
- _kf(Q, -1.5), _kf(Q*2, 0), _kf(Q*3, 1.5), _kf(D, 0),
- ]}
- # Legs: left forward at t=0, right forward at t=D/2
- for side, phase_shift in [("left", 0), ("right", 0.5)]:
- p = phase_shift * D
- upper = f"{side}-upper-leg"
- lower = f"{side}-lower-leg"
- foot = f"{side}-foot"
- if upper in B:
- bones[upper] = {"rotate": [
- _kf(0, -25 if phase_shift == 0 else 25, curve=None),
- _kf(Q, 0), _kf(Q*2, 25 if phase_shift == 0 else -25),
- _kf(Q*3, 0), _kf(D, -25 if phase_shift == 0 else 25),
- ]}
- if lower in B:
- # Back leg straight, front leg bent
- bones[lower] = {"rotate": [
- _kf(0, 5 if phase_shift == 0 else 35, curve=None),
- _kf(Q, 35), _kf(Q*2, 35 if phase_shift == 0 else 5),
- _kf(Q*3, 5), _kf(D, 5 if phase_shift == 0 else 35),
- ]}
- # Arms: oppose legs
- for side, phase_shift in [("left", 0.5), ("right", 0)]:
- upper = f"{side}-upper-arm"
- lower = f"{side}-lower-arm"
- if upper in B:
- bones[upper] = {"rotate": [
- _kf(0, -20 if phase_shift == 0 else 20, curve=None),
- _kf(Q, 0), _kf(Q*2, 20 if phase_shift == 0 else -20),
- _kf(Q*3, 0), _kf(D, -20 if phase_shift == 0 else 20),
- ]}
- if lower in B:
- bones[lower] = {"rotate": [
- _kf(0, -10 if phase_shift == 0 else -30, curve=None),
- _kf(Q, -20), _kf(Q*2, -30 if phase_shift == 0 else -10),
- _kf(Q*3, -20), _kf(D, -10 if phase_shift == 0 else -30),
- ]}
- return {"bones": bones} if bones else {}
- def gen_run(B):
- """Run cycle. Exaggerated walk, forward lean, bigger bounce. ~0.5s"""
- bones = {}
- D = 0.5
- Q = D / 4
- if "hip" in B:
- bones["hip"] = {
- "translate": [
- _kf(0, x=0, y=0, curve=None),
- _kf(Q, x=0, y=6), _kf(Q*2, x=0, y=-2),
- _kf(Q*3, x=0, y=6), _kf(D, x=0, y=0),
- ],
- "rotate": [
- _kf(0, 0, curve=None),
- _kf(Q, -3), _kf(Q*2, 0), _kf(Q*3, 3), _kf(D, 0),
- ],
- }
- if "torso" in B:
- bones["torso"] = {"rotate": [
- _kf(0, 8, curve=None), # Constant forward lean
- _kf(Q, 12), _kf(Q*2, 8), _kf(Q*3, 12), _kf(D, 8),
- ]}
- if "head" in B:
- bones["head"] = {"rotate": [
- _kf(0, -6, curve=None), # Compensate for torso lean
- _kf(Q, -8), _kf(Q*2, -6), _kf(Q*3, -8), _kf(D, -6),
- ]}
- for side, ph in [("left", 0), ("right", 0.5)]:
- upper = f"{side}-upper-leg"
- lower = f"{side}-lower-leg"
- if upper in B:
- bones[upper] = {"rotate": [
- _kf(0, -35 if ph == 0 else 40, curve=None),
- _kf(Q, 0), _kf(Q*2, 40 if ph == 0 else -35),
- _kf(Q*3, 0), _kf(D, -35 if ph == 0 else 40),
- ]}
- if lower in B:
- bones[lower] = {"rotate": [
- _kf(0, 10 if ph == 0 else 50, curve=None),
- _kf(Q, 50), _kf(Q*2, 50 if ph == 0 else 10),
- _kf(Q*3, 10), _kf(D, 10 if ph == 0 else 50),
- ]}
- for side, ph in [("left", 0.5), ("right", 0)]:
- upper = f"{side}-upper-arm"
- lower = f"{side}-lower-arm"
- if upper in B:
- bones[upper] = {"rotate": [
- _kf(0, -30 if ph == 0 else 30, curve=None),
- _kf(Q, 0), _kf(Q*2, 30 if ph == 0 else -30),
- _kf(Q*3, 0), _kf(D, -30 if ph == 0 else 30),
- ]}
- if lower in B:
- bones[lower] = {"rotate": [
- _kf(0, -20 if ph == 0 else -50, curve=None),
- _kf(Q, -35), _kf(Q*2, -50 if ph == 0 else -20),
- _kf(Q*3, -35), _kf(D, -20 if ph == 0 else -50),
- ]}
- return {"bones": bones} if bones else {}
- def gen_wave(B):
- """Waving greeting. Raise right arm, oscillate forearm. ~1.2s"""
- bones = {}
- D = 1.2
- if "right-upper-arm" in B:
- bones["right-upper-arm"] = {"rotate": [
- _kf(0, 0, curve=None),
- _kf(0.2, -130, curve=EASE_OUT),
- _kf(D - 0.2, -130, curve=None),
- _kf(D, 0, curve=EASE_IN),
- ]}
- if "right-lower-arm" in B:
- bones["right-lower-arm"] = {"rotate": [
- _kf(0, 0, curve=None),
- _kf(0.2, -30, curve=EASE_OUT),
- _kf(0.4, 20), _kf(0.6, -20), _kf(0.8, 20), _kf(1.0, -20),
- _kf(D, 0, curve=EASE_IN),
- ]}
- if "torso" in B:
- bones["torso"] = {"rotate": [
- _kf(0, 0, curve=None),
- _kf(0.2, -3), _kf(D - 0.2, -3, curve=None), _kf(D, 0),
- ]}
- if "head" in B:
- bones["head"] = {"rotate": [
- _kf(0, 0, curve=None),
- _kf(0.3, 5), _kf(D - 0.2, 5, curve=None), _kf(D, 0),
- ]}
- return {"bones": bones} if bones else {}
- def gen_jump(B):
- """Jump: anticipation squat → launch → air → land → settle. ~1.0s"""
- bones = {}
- D = 1.0
- if "hip" in B:
- bones["hip"] = {"translate": [
- _kf(0, x=0, y=0, curve=None),
- _kf(0.15, x=0, y=-20, curve=EASE_IN), # squat
- _kf(0.35, x=0, y=70, curve=EASE_OUT), # launch
- _kf(0.55, x=0, y=65, curve=None), # float
- _kf(0.80, x=0, y=-10, curve=EASE_IN), # land impact
- _kf(D, x=0, y=0, curve=EASE_OUT), # settle
- ]}
- if "torso" in B:
- bones["torso"] = {"rotate": [
- _kf(0, 0, curve=None),
- _kf(0.15, 8, curve=EASE_IN), # lean forward in squat
- _kf(0.35, -5, curve=EASE_OUT), # extend in air
- _kf(0.80, 5, curve=EASE_IN), # absorb landing
- _kf(D, 0, curve=EASE_OUT),
- ]}
- if "head" in B:
- bones["head"] = {"rotate": [
- _kf(0, 0, curve=None),
- _kf(0.15, 5), _kf(0.35, -8), _kf(0.80, 3), _kf(D, 0),
- ]}
- for side in ["left", "right"]:
- s = 1 if side == "left" else -1
- arm = f"{side}-upper-arm"
- if arm in B:
- bones[arm] = {"rotate": [
- _kf(0, 0, curve=None),
- _kf(0.15, s*10), _kf(0.35, s*-50, curve=EASE_OUT),
- _kf(0.80, s*8, curve=EASE_IN), _kf(D, 0),
- ]}
- upper = f"{side}-upper-leg"
- lower = f"{side}-lower-leg"
- if upper in B:
- bones[upper] = {"rotate": [
- _kf(0, 0, curve=None),
- _kf(0.15, 20), # squat bend
- _kf(0.35, -15), # extend
- _kf(0.55, 10), # tuck in air
- _kf(0.80, 15), # absorb
- _kf(D, 0),
- ]}
- if lower in B:
- bones[lower] = {"rotate": [
- _kf(0, 0, curve=None),
- _kf(0.15, -30), _kf(0.35, 10), _kf(0.55, -15),
- _kf(0.80, -20), _kf(D, 0),
- ]}
- return {"bones": bones} if bones else {}
- def gen_attack(B):
- """Melee attack: wind-up → strike → follow-through. ~0.6s"""
- bones = {}
- D = 0.6
- if "right-upper-arm" in B:
- bones["right-upper-arm"] = {"rotate": [
- _kf(0, 0, curve=None),
- _kf(0.1, 40, curve=EASE_IN), # wind up (pull back)
- _kf(0.25, -80, curve=EASE_FAST), # strike forward
- _kf(0.4, -60, curve=None), # follow through
- _kf(D, 0, curve=EASE_OUT),
- ]}
- if "right-lower-arm" in B:
- bones["right-lower-arm"] = {"rotate": [
- _kf(0, 0, curve=None),
- _kf(0.1, -40, curve=EASE_IN),
- _kf(0.25, 10, curve=EASE_FAST),
- _kf(0.4, -5, curve=None),
- _kf(D, 0, curve=EASE_OUT),
- ]}
- if "torso" in B:
- bones["torso"] = {"rotate": [
- _kf(0, 0, curve=None),
- _kf(0.1, -8, curve=EASE_IN), # lean back
- _kf(0.25, 12, curve=EASE_FAST), # lunge forward
- _kf(0.4, 5, curve=None),
- _kf(D, 0, curve=EASE_OUT),
- ]}
- if "hip" in B:
- bones["hip"] = {"translate": [
- _kf(0, x=0, y=0, curve=None),
- _kf(0.1, x=-5, y=-5, curve=EASE_IN),
- _kf(0.25, x=10, y=2, curve=EASE_FAST),
- _kf(D, x=0, y=0, curve=EASE_OUT),
- ]}
- return {"bones": bones} if bones else {}
- PRESETS = {
- "idle": gen_idle,
- "walk": gen_walk,
- "run": gen_run,
- "wave": gen_wave,
- "jump": gen_jump,
- "attack": gen_attack,
- }
- # ─── Spine JSON Builder ──────────────────────────────────────────────────────
- def build_spine_json(config):
- """Build a complete Spine JSON structure from config."""
- bone_names = {b["name"] for b in config["bones"]}
- skel_meta = config.get("skeleton", {})
- data_hash = hashlib.md5(json.dumps(config, sort_keys=True).encode()).hexdigest()[:20]
- spine = {
- "skeleton": {
- "hash": data_hash,
- "spine": "4.2.0",
- "x": -(skel_meta.get("width", 400) // 2),
- "y": 0,
- "width": skel_meta.get("width", 400),
- "height": skel_meta.get("height", 600),
- "images": "./images/",
- },
- "bones": config["bones"],
- "slots": config.get("slots", []),
- "skins": [{"name": "default", "attachments": {}}],
- "animations": {},
- }
- # Build attachments for default skin
- attachments = config.get("attachments", {})
- for slot in config.get("slots", []):
- att_name = slot.get("attachment", slot["name"])
- if att_name in attachments:
- spine["skins"][0]["attachments"][slot["name"]] = {
- att_name: attachments[att_name]
- }
- # Generate preset animations
- for anim_name in config.get("animations", ["idle"]):
- if anim_name in PRESETS:
- data = PRESETS[anim_name](bone_names)
- if data:
- spine["animations"][anim_name] = data
- else:
- print(f" WARNING: Unknown animation preset '{anim_name}', skipping")
- # Merge custom animations
- for name, data in config.get("custom_animations", {}).items():
- spine["animations"][name] = data
- # Presets and custom animations alike are authored in the shorthand above;
- # the file declares "spine": "4.2.0", so emit what a 4.x runtime expects.
- _to_spine_42(spine["animations"])
- return spine
- def main():
- parser = argparse.ArgumentParser(description="Build Spine JSON skeleton with animations")
- parser.add_argument("--config", required=True, help="Skeleton configuration JSON")
- parser.add_argument("--output", default="skeleton.json", help="Output Spine JSON")
- args = parser.parse_args()
- with open(args.config) as f:
- config = json.load(f)
- print(f"Building: {config.get('skeleton', {}).get('name', 'unnamed')}")
- spine_json = build_spine_json(config)
- with open(args.output, "w") as f:
- json.dump(spine_json, f, indent=2)
- print(f"Saved: {args.output}")
- print(f" Bones: {len(spine_json['bones'])}")
- print(f" Slots: {len(spine_json['slots'])}")
- print(f" Animations: {list(spine_json['animations'].keys())}")
- if __name__ == "__main__":
- main()
- ```
- </details>
- <!-- EMBED:scripts/make_atlas.py -->
- <details>
- <summary>📄 <code>scripts/make_atlas.py</code> (102 lines)</summary>
- ```python
- #!/usr/bin/env python3
- """
- make_atlas.py — Pack individual body part PNGs into a Spine-compatible texture atlas.
- Usage:
- python3 make_atlas.py --parts parts/ --output atlas/ --name skeleton
- Input: Directory of individual .png files (head.png, torso.png, etc.)
- Output: skeleton.png (spritesheet) + skeleton.atlas (Spine atlas metadata)
- """
- import argparse
- import json
- import math
- import os
- import sys
- from pathlib import Path
- try:
- from PIL import Image
- except ImportError:
- print("ERROR: Pillow required. Install: pip install Pillow --break-system-packages")
- sys.exit(1)
- def next_pow2(v):
- v -= 1
- v |= v >> 1; v |= v >> 2; v |= v >> 4; v |= v >> 8; v |= v >> 16
- return max(v + 1, 1)
- def pack(images, padding=2):
- """Row-based bin packing. Returns (width, height, placements dict)."""
- sorted_imgs = sorted(images.items(), key=lambda x: -x[1].height)
- total_area = sum(img.width * img.height for img in images.values())
- est = int(math.sqrt(total_area) * 1.3)
- atlas_w = next_pow2(est)
- placements = {}
- rx, ry, rh, max_w = padding, padding, 0, 0
- for name, img in sorted_imgs:
- if rx + img.width + padding > atlas_w:
- rx = padding
- ry += rh + padding
- rh = 0
- placements[name] = (rx, ry, img.width, img.height)
- max_w = max(max_w, rx + img.width + padding)
- rh = max(rh, img.height)
- rx += img.width + padding
- return next_pow2(max_w), next_pow2(ry + rh + padding), placements
- def main():
- parser = argparse.ArgumentParser(description="Pack PNGs into a Spine texture atlas")
- parser.add_argument("--parts", required=True, help="Directory with part PNG files")
- parser.add_argument("--output", default=".", help="Output directory")
- parser.add_argument("--name", default="skeleton", help="Base filename for atlas")
- parser.add_argument("--padding", type=int, default=2, help="Pixel padding between regions")
- args = parser.parse_args()
- images = {}
- for f in sorted(os.listdir(args.parts)):
- if f.lower().endswith(".png"):
- name = Path(f).stem
- images[name] = Image.open(os.path.join(args.parts, f)).convert("RGBA")
- print(f" {name}: {images[name].width}x{images[name].height}")
- if not images:
- print("ERROR: No PNGs found in", args.parts)
- sys.exit(1)
- aw, ah, placements = pack(images, args.padding)
- print(f"Atlas: {aw}x{ah} ({len(images)} regions)")
- # Compose atlas image
- atlas = Image.new("RGBA", (aw, ah), (0, 0, 0, 0))
- for name, (x, y, w, h) in placements.items():
- atlas.paste(images[name], (x, y))
- os.makedirs(args.output, exist_ok=True)
- img_path = os.path.join(args.output, f"{args.name}.png")
- atlas.save(img_path)
- # Write .atlas file
- lines = [f"{args.name}.png", f"size: {aw},{ah}",
- "format: RGBA8888", "filter: Linear,Linear", "repeat: none"]
- for name, (x, y, w, h) in placements.items():
- lines += [name, " rotate: false", f" xy: {x}, {y}",
- f" size: {w}, {h}", f" orig: {w}, {h}",
- " offset: 0, 0", " index: -1"]
- atlas_path = os.path.join(args.output, f"{args.name}.atlas")
- with open(atlas_path, "w") as f:
- f.write("\n".join(lines) + "\n")
- print(f"Saved: {img_path}, {atlas_path}")
- if __name__ == "__main__":
- main()
- ```
- </details>
- <!-- EMBED:scripts/generate_spine_player.py -->
- <details>
- <summary>📄 <code>scripts/generate_spine_player.py</code> (292 lines)</summary>
- ```python
- #!/usr/bin/env python3
- """
- generate_spine_player.py — Generate a self-contained HTML preview using the official Spine Web Player.
- Embeds the skeleton JSON, atlas text, and atlas PNG as base64 data URIs via the
- rawDataURIs configuration, so the resulting HTML file works standalone — no server needed.
- Uses the official @esotericsoftware/spine-player from UNPKG CDN.
- Usage:
- python3 generate_spine_player.py \
- --skeleton skeleton.json \
- --atlas skeleton.atlas \
- --atlas-image skeleton.png \
- --output preview.html \
- [--animation idle] \
- [--background "#1a1a2eff"] \
- [--skin default]
- If no --atlas and --atlas-image are given but a --parts directory is provided,
- the script will pack the parts into an atlas automatically.
- """
- import argparse
- import base64
- import json
- import os
- import sys
- from pathlib import Path
- def file_to_base64(path):
- """Read a file and return its base64-encoded contents."""
- with open(path, "rb") as f:
- return base64.b64encode(f.read()).decode("ascii")
- def json_to_base64(path):
- """Read a JSON file and return it as base64."""
- with open(path, "r") as f:
- content = f.read()
- return base64.b64encode(content.encode("utf-8")).decode("ascii")
- def text_to_base64(path):
- """Read a text file and return it as base64."""
- with open(path, "r") as f:
- content = f.read()
- return base64.b64encode(content.encode("utf-8")).decode("ascii")
- def find_atlas_images(atlas_path):
- """Parse an atlas file to find all referenced PNG filenames."""
- atlas_dir = os.path.dirname(os.path.abspath(atlas_path))
- images = []
- with open(atlas_path, "r") as f:
- lines = f.readlines()
- # The first line (or lines before the first region entry) contain page image filenames
- # Atlas format: image filename is a line that ends with .png (or other image ext)
- # followed by size:, format:, filter:, repeat: lines
- i = 0
- while i < len(lines):
- line = lines[i].strip()
- # A page image is the first non-empty line, or any line ending with an image extension
- # that is followed by "size:" on the next line
- if line and not line.startswith(" ") and not ":" in line:
- # Check if next line starts with "size:" indicating this is a page name
- if i + 1 < len(lines) and lines[i + 1].strip().startswith("size:"):
- img_path = os.path.join(atlas_dir, line)
- if os.path.exists(img_path):
- images.append((line, img_path))
- else:
- print(f" WARNING: Atlas references '{line}' but file not found at {img_path}")
- i += 1
- return images
- def generate_html(skeleton_path, atlas_path, atlas_images,
- animation=None, skin=None, bg_color="#1a1a2eff",
- show_controls=True, title="Spine Animation Preview"):
- """Generate the complete HTML file with embedded Spine Web Player."""
- # Get filenames for rawDataURIs keys
- skel_filename = os.path.basename(skeleton_path)
- atlas_filename = os.path.basename(atlas_path)
- # Determine if JSON or binary
- is_json = skel_filename.lower().endswith(".json")
- skel_mime = "application/json" if is_json else "application/octet-stream"
- # Encode all assets
- skel_b64 = file_to_base64(skeleton_path)
- atlas_b64 = file_to_base64(atlas_path)
- # Build rawDataURIs object
- raw_data_entries = []
- raw_data_entries.append(
- f' "{skel_filename}": "data:{skel_mime};base64,{skel_b64}"'
- )
- raw_data_entries.append(
- f' "{atlas_filename}": "data:application/octet-stream;base64,{atlas_b64}"'
- )
- for img_name, img_path in atlas_images:
- img_ext = Path(img_path).suffix.lower()
- img_mime = "image/png" if img_ext == ".png" else "image/jpeg"
- img_b64 = file_to_base64(img_path)
- raw_data_entries.append(
- f' "{img_name}": "data:{img_mime};base64,{img_b64}"'
- )
- raw_data_uris_js = ",\n".join(raw_data_entries)
- # Build config options
- config_lines = []
- config_lines.append(f' skeleton: "{skel_filename}"')
- config_lines.append(f' atlas: "{atlas_filename}"')
- if animation:
- config_lines.append(f' animation: "{animation}"')
- if skin and skin != "default":
- config_lines.append(f' skin: "{skin}"')
- config_lines.append(f' backgroundColor: "{bg_color}"')
- config_lines.append(f' showControls: {"true" if show_controls else "false"}')
- config_lines.append(f' premultipliedAlpha: false')
- config_lines.append(f' rawDataURIs: {{\n{raw_data_uris_js}\n }}')
- # Error/success callbacks
- config_lines.append(""" success: function(player) {
- document.getElementById('status').textContent = 'Loaded successfully';
- document.getElementById('status').style.color = '#4ade80';
- // Log available animations
- var anims = player.skeleton.data.animations.map(function(a) { return a.name; });
- console.log('Available animations:', anims);
- var skins = player.skeleton.data.skins.map(function(s) { return s.name; });
- console.log('Available skins:', skins);
- }""")
- config_lines.append(""" error: function(player, reason) {
- document.getElementById('status').textContent = 'Error: ' + reason;
- document.getElementById('status').style.color = '#ef4444';
- console.error('Spine Player error:', reason);
- }""")
- config_js = ",\n".join(config_lines)
- html = f"""<!DOCTYPE html>
- <html lang="en">
- <head>
- <meta charset="UTF-8">
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
- <title>{title}</title>
- <!-- Official Spine Web Player -->
- <script src="https://unpkg.com/@esotericsoftware/spine-player@4.2.*/dist/iife/spine-player.js"></script>
- <link rel="stylesheet" href="https://unpkg.com/@esotericsoftware/spine-player@4.2.*/dist/spine-player.css">
- <style>
- * {{ margin: 0; padding: 0; box-sizing: border-box; }}
- body {{
- background: #0f0f1a;
- color: #e0e0e0;
- font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
- display: flex;
- flex-direction: column;
- align-items: center;
- min-height: 100vh;
- padding: 20px;
- }}
- h1 {{
- font-size: 1.5em;
- margin-bottom: 10px;
- color: #a8b2d1;
- letter-spacing: 0.04em;
- }}
- #status {{
- font-size: 0.85em;
- margin-bottom: 15px;
- color: #6b7da0;
- transition: color 0.3s;
- }}
- #player-container {{
- width: 700px;
- height: 600px;
- max-width: 95vw;
- border-radius: 12px;
- overflow: hidden;
- box-shadow: 0 8px 32px rgba(0,0,0,0.5);
- }}
- .info {{
- margin-top: 15px;
- font-size: 0.8em;
- color: #4a5568;
- text-align: center;
- max-width: 600px;
- line-height: 1.5;
- }}
- .info a {{ color: #6b8aad; text-decoration: none; }}
- .info a:hover {{ text-decoration: underline; }}
- </style>
- </head>
- <body>
- <h1>{title}</h1>
- <div id="status">Loading Spine Player...</div>
- <div id="player-container"></div>
- <div class="info">
- Rendered with the official
- <a href="https://en.esotericsoftware.com/spine-player" target="_blank">Spine Web Player</a>.
- Use the controls to switch animations, adjust speed, and toggle debug views.
- </div>
- <script>
- new spine.SpinePlayer("player-container", {{
- {config_js}
- }});
- </script>
- </body>
- </html>"""
- return html
- def main():
- parser = argparse.ArgumentParser(
- description="Generate a self-contained HTML preview using the official Spine Web Player"
- )
- parser.add_argument("--skeleton", required=True, help="Spine JSON or binary (.skel) file")
- parser.add_argument("--atlas", required=True, help="Spine .atlas file")
- parser.add_argument("--atlas-image", default=None,
- help="Atlas PNG image (auto-detected from atlas if omitted)")
- parser.add_argument("--output", default="preview.html", help="Output HTML file")
- parser.add_argument("--animation", default=None, help="Default animation to play")
- parser.add_argument("--skin", default=None, help="Default skin")
- parser.add_argument("--background", default="#1a1a2eff", help="Background color (hex RGBA)")
- parser.add_argument("--title", default="Spine Animation Preview", help="Page title")
- parser.add_argument("--no-controls", action="store_true", help="Hide player controls")
- args = parser.parse_args()
- # Verify files exist
- for path, name in [(args.skeleton, "Skeleton"), (args.atlas, "Atlas")]:
- if not os.path.exists(path):
- print(f"ERROR: {name} file not found: {path}")
- sys.exit(1)
- # Find atlas images
- atlas_images = []
- if args.atlas_image:
- img_name = os.path.basename(args.atlas_image)
- atlas_images.append((img_name, args.atlas_image))
- else:
- atlas_images = find_atlas_images(args.atlas)
- if not atlas_images:
- print("ERROR: No atlas images found. Specify --atlas-image or ensure atlas references valid PNGs.")
- sys.exit(1)
- print(f"Skeleton: {args.skeleton}")
- print(f"Atlas: {args.atlas}")
- for img_name, img_path in atlas_images:
- print(f"Atlas image: {img_name} ({os.path.getsize(img_path) / 1024:.1f} KB)")
- # Generate HTML
- print("Generating HTML with embedded Spine Web Player...")
- html = generate_html(
- skeleton_path=args.skeleton,
- atlas_path=args.atlas,
- atlas_images=atlas_images,
- animation=args.animation,
- skin=args.skin,
- bg_color=args.background,
- show_controls=not args.no_controls,
- title=args.title,
- )
- with open(args.output, "w") as f:
- f.write(html)
- size_kb = os.path.getsize(args.output) / 1024
- print(f"\nPreview saved: {args.output} ({size_kb:.1f} KB)")
- print("Open in a browser to see your animation (requires internet for the Spine Player CDN).")
- if __name__ == "__main__":
- main()
- ```
- </details>
- After writing the scripts, verify:
- ```bash
- ls /home/claude/spine-scripts/
- # Should show: split_character.py position_parts.py build_spine_json.py make_atlas.py generate_spine_player.py
- ```
- ---
- ## What You Need From the User
- At minimum, one of these asset sets:
- | Asset Set | What to Expect |
- |-----------|---------------|
- | **Separated body part PNGs** | Individual transparent PNGs for head, torso, arms, legs, etc. |
- | **Separated PNGs + reference image** | Parts + an assembled character image → enables auto-positioning |
- | **Texture atlas + atlas PNG** | A `.atlas` file + spritesheet `.png` (standard Spine export) |
- | **Full character image** | A single image — Claude will help define part regions |
- | **Existing Spine JSON** | An existing `.json` to add/modify animations |
- The user should also say what animations they want (idle, walk, run, attack, wave, jump, etc.)
- ## Full Pipeline
- ```
- User Assets → Analyze Parts → [Auto-Position if reference] → Build Skeleton → Animate → Preview
- ```
- ### Step 0.5: Generate Parts From a Full Character Image (Optional)
- If the user only has a **single full character image** (not separated body parts), use
- `split_character.py` to generate a deconstructed sprite atlas via Google Gemini and then
- automatically segment it into individual part PNGs.
- **Requires:** `GEMINI_API_KEY` environment variable (free key at https://aistudio.google.com/app/apikey).
- ```bash
- GEMINI_API_KEY=your_key python /home/claude/spine-scripts/split_character.py character.png \
- --output-dir parts/
- ```
- This sends the character image to Gemini, which generates a flat sprite-sheet atlas with
- all body parts separated. OpenCV connected-components analysis then crops each part into
- its own transparent PNG. The resulting `parts/` directory can be fed directly into
- **Step 1** (`position_parts.py`).
- ### Step 1: Analyze the Assets
- Look at the uploaded files:
- 1. **If separated PNGs**: Use Claude's vision to identify each part (head, torso, left-arm, etc.)
- and note their dimensions. Determine the bone hierarchy from the part names and visual layout.
- 2. **If atlas + spritesheet**: Parse the `.atlas` file to extract region names, positions, and sizes.
- 3. **If full image only**: Use Claude's vision to identify body parts, then crop into separate PNGs.
- 4. **If existing Spine JSON**: Parse it, understand the skeleton, and add new animations.
- 5. **If separated PNGs + assembled reference image**: Run `position_parts.py` for auto-layout.
- ### Step 1.5: Auto-Position Parts (when reference image is available)
- If the user provides both separated body-part PNGs **and** an assembled reference image:
- ```bash
- python3 /home/claude/spine-scripts/position_parts.py \
- --reference assembled_character.png \
- --parts parts_folder/ \
- --output layout.json \
- --debug debug/ \
- --min-matches 4 \
- --ratio 0.80
- ```
- **Algorithm — SIFT + RANSAC similarity transform:**
- 1. Extracts SIFT keypoints from each part (alpha-masked) and the reference image
- 2. Matches via FLANN with Lowe's ratio test (default 0.80)
- 3. Estimates similarity transform (4 DOF: translate + scale + rotation) via
- `cv2.estimateAffinePartial2D` — more robust than full homography for game art
- 4. SIFT tuning for stylized art: `contrastThreshold=0.02, edgeThreshold=20`
- 5. Template matching fallback for tiny/featureless parts, using SIFT-derived median scale
- 6. Z-order via pairwise occlusion voting
- After running, **check `debug/comparison.png`** to verify positioning accuracy.
- Per-part SIFT match visualizations: `debug/sift_<partname>.jpg`.
- **Limitations:** Heavily occluded parts (e.g., thighs behind a belt) may need manual correction.
- Compare composite vs reference with Claude's vision and adjust layout JSON offsets.
- ### Step 2: Build Bone Hierarchy
- Standard humanoid skeleton:
- ```
- root
- └── hip
- ├── torso
- │ ├── neck → head → hat/hair
- │ ├── left-shoulder → left-upper-arm → left-lower-arm → left-hand
- │ └── right-shoulder → right-upper-arm → right-lower-arm → right-hand
- ├── left-upper-leg → left-lower-leg → left-foot
- └── right-upper-leg → right-lower-leg → right-foot
- ```
- **Coordinate system:** Spine uses Y-up, origin at character's feet center.
- - `spine_x = pixel_x - center_x`
- - `spine_y = bottom_y - pixel_y`
- **Bone positions** are RELATIVE to parent:
- - `relative_pos = child_world_pos - parent_world_pos`
- **Attachment offsets** are relative to their bone:
- - `att_offset = image_center_world_pos - bone_world_pos`
- ### Step 3: Build Spine JSON
- Spine JSON v4.2 structure:
- ```json
- {
- "skeleton": { "hash": "...", "spine": "4.2", "width": 500, "height": 950 },
- "bones": [
- { "name": "root", "x": 0, "y": 0, "length": 0 },
- { "name": "hip", "parent": "root", "x": 0, "y": 410, "length": 30 }
- ],
- "slots": [
- { "name": "back-arm", "bone": "left-arm-bone", "attachment": "back-arm" }
- ],
- "skins": [{
- "name": "default",
- "attachments": {
- "slot-name": {
- "attachment-name": { "x": 5, "y": -10, "width": 100, "height": 200 }
- }
- }
- }],
- "animations": {
- "idle": {
- "bones": {
- "hip": {
- "translate": [
- { "time": 0, "x": 0, "y": 0, "curve": [0.25, 0, 0.75, 1] },
- { "time": 1.0, "x": 0, "y": 3 },
- { "time": 2.0, "x": 0, "y": 0 }
- ]
- }
- }
- }
- }
- }
- ```
- **Slots** define draw order — first slot is drawn first (back), last is front.
- ### Step 4: Create Animations
- **Keyframe format:**
- ```json
- { "time": 0.0, "value": 0, "curve": [0.25, 0, 0.75, 1] }
- ```
- The `curve` is a cubic bezier `[cx1, cy1, cx2, cy2]`. Use `[0.25, 0, 0.75, 1]` for ease-in-out.
- **Animation presets:**
- | Preset | Duration | Key Technique |
- |--------|----------|---------------|
- | idle | 2.0s loop | Hip ±3px translate, torso ±1° rotate, head ±1.5° counter-sway |
- | walk | 0.8s loop | Opposing arm-leg swing, hip ±5px bob, torso ±3° lean |
- | run | 0.5s loop | Exaggerated walk + 5° forward lean + ±8px bounce |
- | wave | 1.2s | Shoulder -45°, forearm oscillate ±15° |
- | jump | 1.0s | Squat → launch → air → land (4 phases) |
- | attack | 0.6s | Windup → strike → follow-through (3 phases) |
- **Key principles:**
- - Offset timing between related bones (head peaks 0.1s after torso = follow-through)
- - Larger movements on larger bones (hip > torso > head)
- - All loops must return to starting values
- ### Step 5: Build Atlas
- ```bash
- python3 /home/claude/spine-scripts/make_atlas.py \
- --parts parts_folder/ \
- --output . \
- --name character_name
- ```
- Outputs: `character_name.png` (spritesheet) + `character_name.atlas` (metadata).
- ### Step 6: Generate Preview
- For a **self-contained HTML Canvas preview** (recommended):
- Build the HTML directly in Python with base64-embedded images, bone system, bezier interpolation,
- and animation loop. No external dependencies needed.
- For an **official Spine Web Player preview**:
- ```bash
- python3 /home/claude/spine-scripts/generate_spine_player.py \
- --skeleton character.json \
- --atlas character.atlas \
- --atlas-image character.png \
- --output preview.html
- ```
- ### Step 7: Interactive Editor (Optional)
- Build an HTML editor that allows the user to fine-tune part positions:
- - Click to select parts (purple dashed border + glow)
- - Drag to reposition in real-time
- - Arrow keys for 1px nudge (Shift for 10px)
- - Side panel with numeric X/Y/rotation inputs
- - Draggable z-order list
- - Export button producing layout corrections JSON:
- ```json
- {
- "adjustments": {
- "part-name": {
- "original_offset": { "x": 0, "y": 0 },
- "user_offset": { "dx": 5.2, "dy": -3.1, "drot": 0 },
- "final_offset": { "x": 5.2, "y": -3.1 }
- }
- },
- "draw_order": ["back-part", "...", "front-part"]
- }
- ```
- This JSON can be fed back to Claude to apply corrections to the skeleton.
README.md · README · 394 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 🎭 Spine Animation AI
- > An AI-powered Claude skill for creating, rigging, and refining Spine 2D skeletal animations — from raw assets to interactive previews.
- [](LICENSE)
- [](http://esotericsoftware.com)
- [](SKILL.md)
- [](https://openclaw.ai)
- ---
- <p align="center">
- <img src="demo/flow.gif" alt="Spine Animation AI demo" width="50%"/>
- </p>
- <p align="center">
- <a href="https://GenielabsOpenSource.github.io/spine-animation-ai/demo/sombrero_idle.html"><strong>▶ Live Animation Preview</strong></a>
- ·
- <a href="https://GenielabsOpenSource.github.io/spine-animation-ai/demo/sombrero_editor.html"><strong>🎛 Interactive Part Editor</strong></a>
- </p>
- ---
- ## ✨ New: Reskin Studio
- **Restyle any rigged Spine character with a single sentence.** Open a Spine project, describe the look you want — *"emerald and silver royal robes"* — and Reskin Studio repaints the whole character with Gemini, slices the result back into clean per-slot textures, and drops the new skin straight onto the live rig. Retouch any part, refine masks, then export back to Spine. No redraw, no re-rig.
- <!-- TODO: drop the reskin demo gif at demo/reskin.gif -->
- <p align="center">
- <img src="demo/reskin.gif" alt="Reskin Studio demo" width="50%"/>
- </p>
- <p align="center">
- <a href="reskin-app/"><strong>→ Explore Reskin Studio</strong></a>
- </p>
- ---
- <div align="center">
- # 🔬 Genielabs — Pioneering AI Animation Research
- ## We are actively researching AI-driven animation pipelines.
- **[Genielabs](https://genielabs.tech)** is at the forefront of AI-powered 2D animation — using machine learning to automate character rigging, motion generation, and asset positioning for game production.
- This repository is a direct product of that research: an open-source skill that brings industrial-grade animation automation into Claude.
- ### 📬 Want to collaborate, license, or learn more?
- ## 👉 [**genielabs.tech**](https://genielabs.tech) 👈
- *Reach out — we'd love to hear from you.*
- </div>
- ---
- ## What Is This?
- **Spine Animation AI** is a [Claude agent skill](SKILL.md) that lets AI handle the tedious parts of Spine 2D animation production:
- - **Auto-position** body parts from reference images using SIFT + RANSAC
- - **Build skeleton JSON** with proper bone hierarchy and draw order
- - **Generate animations** (idle, walk, run, attack, wave, jump) using the 12 principles of animation
- - **Produce interactive HTML5 previews** using the official Spine Web Player
- - **Correct and refine** existing skeletons with AI-assisted offset adjustments
- Think of it as a Spine rigging co-pilot. You provide the art assets; Claude does the math.
- ---
- ## Quick Start
- ### Option A: Claude Projects (Recommended)
- The easiest way — works with any Claude account, no extra software needed.
- 1. Go to [claude.ai](https://claude.ai) → create a new **Project**
- 2. Open **Project Knowledge** → **Add content**
- 3. Copy the full contents of [`SKILL.md`](SKILL.md) and paste it in
- 4. Save — Claude now has the full skill baked in, **including all scripts embedded inline**
- 5. Upload your character assets and describe what you want:
- ```
- "I have separated body part PNGs for my character.
- Create idle and walk animations."
- ```
- Claude will write the scripts to disk, run the pipeline, and deliver `skeleton.json` + `preview.html`.
- > **Why it works:** `SKILL.md` is auto-generated with all 4 Python scripts embedded inside it — Claude extracts and runs them without needing to clone the repo.
- ---
- ### Option B: Claude Custom Skill (`/mnt/skills/` environments)
- For Claude environments that support mounted skill directories:
- ```bash
- git clone https://github.com/GenielabsOpenSource/spine-animation-ai.git /mnt/skills/user/spine-animation
- ```
- Claude will automatically discover and load the skill on next session start.
- ---
- ### Option C: Manual Pipeline (no Claude needed)
- **Step 0: Split a Full Character Into Parts (New!)**
- If you only have a single character image (not separated body parts), `split_character.py`
- uses Google Gemini to generate a deconstructed sprite atlas and then segments it into
- individual transparent PNGs via OpenCV connected-components analysis.
- Prerequisites:
- - `GEMINI_API_KEY` environment variable — get a free key at https://aistudio.google.com/app/apikey
- - `pip install google-generativeai`
- ```bash
- GEMINI_API_KEY=your_key python3 scripts/split_character.py character.png \
- --output-dir parts/
- ```
- Skip this step if you already have separated body-part PNGs.
- **1. Auto-position parts from a reference image**
- ```bash
- python3 scripts/position_parts.py \
- --reference assembled_character.png \
- --parts parts/ \
- --output layout.json \
- --debug debug/
- ```
- **2. Build the Spine JSON**
- ```bash
- python3 scripts/build_spine_json.py \
- --config layout.json \
- --output skeleton.json
- ```
- **3. Pack a texture atlas**
- ```bash
- python3 scripts/make_atlas.py \
- --parts parts/ \
- --output atlas/ \
- --name skeleton
- ```
- **4. Generate a self-contained HTML preview**
- ```bash
- python3 scripts/generate_spine_player.py \
- --skeleton skeleton.json \
- --atlas skeleton.atlas \
- --atlas-image skeleton.png \
- --output preview.html
- ```
- Open `preview.html` in any browser — no server needed.
- ---
- ## AI Adjustment Format
- When Claude analyzes a skeleton and recommends corrections, it outputs adjustments in this format:
- ```json
- {
- "adjustments": {
- "right-arm": {
- "original_offset": { "x": -1.5, "y": 0 },
- "user_offset": { "dx": -29.4, "dy": -84.1, "drot": 0 },
- "final_offset": { "x": -30.9, "y": -84.1 }
- },
- "head": {
- "original_offset": { "x": 3, "y": 20.5 },
- "user_offset": { "dx": -18.3, "dy": -2, "drot": 0 },
- "final_offset": { "x": -15.3, "y": 18.5 }
- }
- },
- "draw_order": [
- "right-arm", "left-leg", "right-thigh", "right-leg",
- "left-thigh", "waist", "left-hand", "torso", "hat", "head"
- ]
- }
- ```
- Each entry tracks the original offset, the AI-suggested correction delta, and the applied final value.
- This makes adjustments **reviewable, revertible, and composable**.
- See [docs/adjustment-format.md](docs/adjustment-format.md) for full specification.
- ---
- ## Included Example: Sombrero Character
- The `examples/sombrero/` directory contains a complete, working example:
- | File | Description |
- |------|-------------|
- | `sombrero.json` | Full Spine skeleton with idle animation |
- | `sombrero.atlas` | Texture atlas metadata |
- | `sombrero.png` | Packed atlas spritesheet (10 parts) |
- | `skeleton.json` | Skeleton-only version (no animation) |
- The sombrero character has **10 body parts**, **16 bones**, and a 2-second idle loop with:
- - Hip breathing bob
- - Torso sway
- - Head gentle rotation
- - Hat follow-through
- - Arm natural drift
- Open [`demo/sombrero_idle.html`](demo/sombrero_idle.html) to see it in action.
- Open [`demo/sombrero_editor.html`](demo/sombrero_editor.html) to interactively adjust part positions and export layout JSON.
- ---
- ## Project Structure
- ```
- spine-animation-ai/
- ├── SKILL.md ← Auto-generated (don't edit directly)
- ├── SKILL.template.md ← Human-editable source (edit this)
- ├── build_skill.py ← Builds SKILL.md from template + scripts
- ├── scripts/
- │ ├── position_parts.py ← SIFT+RANSAC auto-positioning
- │ ├── build_spine_json.py ← Spine JSON builder
- │ ├── make_atlas.py ← Texture atlas packer
- │ └── generate_spine_player.py ← HTML preview generator
- ├── .github/workflows/
- │ └── build-skill.yml ← Auto-rebuilds SKILL.md on push
- ├── references/
- │ └── spine-json-spec.md ← Spine format reference
- ├── examples/
- │ └── sombrero/ ← Full working example
- │ ├── sombrero.json
- │ ├── sombrero.atlas
- │ └── sombrero.png
- ├── demo/
- │ ├── sombrero_idle.html ← Idle animation preview
- │ ├── sombrero_editor.html ← Interactive part editor
- │ └── spine_animation_preview.html
- └── docs/
- ├── getting-started.md
- ├── adjustment-format.md
- └── claude-prompting-guide.md
- ```
- ---
- ## How the Auto-Positioning Works
- The `position_parts.py` script uses a two-phase algorithm:
- ### Phase 1: SIFT + RANSAC (primary)
- 1. Extract **SIFT keypoints** from each body part (alpha-masked to visible pixels)
- 2. Extract keypoints from the **assembled reference image**
- 3. Match with **FLANN** matcher + Lowe's ratio test
- 4. Estimate a **similarity transform** (translate + scale + rotate) via RANSAC
- 5. Accept if 4+ inlier matches are found; fall back otherwise
- This is more robust than full homography for stylized game art with sparse features.
- ### Phase 2: Z-Order via Occlusion Analysis
- For every overlapping pair of positioned parts:
- 1. Sample pixels in the overlap region
- 2. Compare each pixel to the reference image
- 3. The part whose color is closer to the reference is "on top"
- 4. Build a directed occlusion graph → topological sort → draw order
- ### Fallback: Template Matching
- Parts too small for SIFT (accessories, tiny objects) fall back to
- alpha-masked `TM_CCORR_NORMED` at multiple scales with background penalty scoring.
- ---
- ## Requirements
- ```
- Python 3.9+
- opencv-python >= 4.8
- Pillow >= 10.0
- numpy >= 1.24
- ```
- Install dependencies:
- ```bash
- pip install opencv-python Pillow numpy
- ```
- ---
- ## Claude Prompting Tips
- The best prompts for this skill are specific about assets and intent:
- ✅ **Good:**
- ```
- "I have separated body part PNGs for a robot character (head.png, torso.png,
- left-arm.png, right-arm.png, left-leg.png, right-leg.png) and a reference
- image showing the assembled character. Create idle and walk animations."
- ```
- ✅ **Also good:**
- ```
- "Here's my Spine JSON. The right arm is positioned wrong — it should be
- lower and more to the left. Also add a wave animation."
- ```
- ❌ **Too vague:**
- ```
- "Animate this character"
- ```
- See [docs/claude-prompting-guide.md](docs/claude-prompting-guide.md) for more examples.
- ---
- ## Animation Presets
- | Preset | Duration | Technique |
- |--------|----------|-----------|
- | `idle` | 2.0s loop | Overlapping sine waves on hip/torso/head |
- | `walk` | 0.8s loop | Opposing arm-leg swing with hip bob |
- | `run` | 0.5s loop | Exaggerated walk + forward lean + bounce |
- | `wave` | 1.2s | Raise arm, oscillate forearm |
- | `jump` | 1.0s | Anticipation squat → launch → land |
- | `attack` | 0.6s | Windup → strike → follow-through |
- All presets use **bezier easing** (`[0.25, 0, 0.75, 1]`) following the
- [12 principles of animation](https://en.wikipedia.org/wiki/Twelve_basic_principles_of_animation).
- ---
- ## How SKILL.md Stays in Sync
- `SKILL.md` is **auto-generated** — don't edit it directly. Instead:
- 1. Edit `SKILL.template.md` (the prose and instructions)
- 2. Edit scripts in `scripts/` (the actual code)
- 3. Push to `main` — GitHub Actions runs `build_skill.py` which:
- - Reads `SKILL.template.md`
- - Finds all `<!-- EMBED:scripts/filename.py -->` markers
- - Injects the actual script contents into collapsible `<details>` blocks
- - Commits the updated `SKILL.md` automatically
- This means `SKILL.md` is always a **self-contained document** — when someone pastes it into Claude Projects, Claude has the actual script code right there, no cloning needed.
- To build locally:
- ```bash
- python build_skill.py
- ```
- ---
- ## Contributing
- PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
- Ideas for contributions:
- - New animation presets (dance, swim, fly, cast spell...)
- - Support for non-humanoid rigs (animals, vehicles, abstract)
- - Better occlusion detection for heavily layered characters
- - Blender / Aseprite asset pipeline integration
- - Spine Runtimes integration examples (Unity, Godot, Phaser)
- ---
- ## License
- [PolyForm Noncommercial 1.0.0](LICENSE) — free for all non-commercial use. Commercial use requires a separate license — contact us at [genielabs.tech](https://genielabs.tech).
- ---
- ## Credits
- Built with:
- - [Spine by Esoteric Software](http://esotericsoftware.com) — the industry-standard 2D animation tool
- - [OpenCV](https://opencv.org) — SIFT feature detection and RANSAC
- - [Claude AI](https://anthropic.com/claude) — the brain
- - [OpenClaw](https://openclaw.ai) — the agent runtime
- ---
- <p align="center">Made with ✨ by the community · Star if useful!</p>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.