| 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.
|
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.
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.
📄 scripts/split_character.py (231 lines)
#!/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()
📄 scripts/position_parts.py (492 lines)
#!/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()
📄 scripts/build_spine_json.py (562 lines)
#!/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()
📄 scripts/make_atlas.py (102 lines)
#!/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()
📄 scripts/generate_spine_player.py (292 lines)
#!/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()
After writing the scripts, verify:
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).
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:
-
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.
-
If atlas + spritesheet: Parse the .atlas file to extract region names, positions, and sizes.
-
If full image only: Use Claude's vision to identify body parts, then crop into separate PNGs.
-
If existing Spine JSON: Parse it, understand the skeleton, and add new animations.
-
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:
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:
- Extracts SIFT keypoints from each part (alpha-masked) and the reference image
- Matches via FLANN with Lowe's ratio test (default 0.80)
- Estimates similarity transform (4 DOF: translate + scale + rotation) via
cv2.estimateAffinePartial2D — more robust than full homography for game art
- SIFT tuning for stylized art:
contrastThreshold=0.02, edgeThreshold=20
- Template matching fallback for tiny/featureless parts, using SIFT-derived median scale
- 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_xspine_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:
{
"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:
{ "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
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:
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:
{
"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.
