spine-animation

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 ()