genielabsopensource 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.
#!/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()
#!/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()
#!/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 rig
…(truncated)