feat: splitsprite 增加白底移除、固定网格拆分与帧居中功能

- 新增 RemoveWhiteBg：纯白色背景(#FFFFFF)像素半透明化
- 新增 fixedGridSplit：GridRows×GridCols 固定网格拆分
- 新增 CenterAlign：帧内容居中对齐，确保人物不跳帧
- Options 新增 WhiteBg/GridRows/GridCols/GridPadding/CenterAlign
- 默认模式从绿幕切换为白底
- 新增 tools/test_prompt_to_gif.go 端到端测试脚本
- .gitignore 忽略 test_output 目录

.gitignore

@@ -26,3 +26,4 @@ backend/main
 
 # Generated output
 generation/
+backend/test_output/

backend/pkg/splitsprite/splitsprite.go

@@ -1,6 +1,6 @@
 // Package splitsprite provides PNG sprite sheet splitting utilities.
 //
-// Pipeline: green screen removal → projection-based gap detection →
+// Pipeline: white/green background removal → projection-based gap detection →
 // split into tiles → filter out low-fill tiles → trim transparent edges.
 package splitsprite
 
@@ -15,11 +15,23 @@ import (
 
 // Options configures the sprite sheet splitting pipeline.
 type Options struct {
+	// WhiteBg enables white background removal.
+	WhiteBg bool
+	// WhiteThreshold is the max distance from pure white (0–255, default 40).
+	WhiteThreshold uint8
+
 	// GreenScreen enables green background removal.
 	GreenScreen bool
 	// GreenTolerance controls how aggressively green pixels are removed (0–1, default 0.2).
 	GreenTolerance float64
 
+	// GridRows / GridCols enable fixed-grid splitting (overrides projection detection).
+	// When >0, the image is divided equally into Rows×Cols cells.
+	GridRows int
+	GridCols int
+	// GridPadding is the gap between cells in pixels (default 2).
+	GridPadding int
+
 	// GapThreshold is the max fraction of non-transparent pixels a row/column
 	// can have to be considered a gap (0–1, default 0.03).
 	GapThreshold float64
@@ -32,12 +44,27 @@ type Options struct {
 
 	// Trim removes transparent borders from output tiles.
 	Trim bool
+	// CenterAlign centers content across all frames so characters stay in place.
+	// All output frames get the same dimensions with content centered.
+	CenterAlign bool
 	// OutW / OutH specify the output tile size (0 = keep original).
 	OutW, OutH int
 }
 
-// DefaultOptions returns sensible default splitting options.
+// DefaultOptions returns sensible default splitting options (white background mode).
 func DefaultOptions() *Options {
+	return &Options{
+		WhiteBg:        true,
+		WhiteThreshold: 40,
+		GapThreshold:   0.03,
+		MinGapWidth:    2,
+		MinFillRatio:   0.3,
+		Trim:           true,
+	}
+}
+
+// DefaultGreenOptions returns options tuned for green screen sprite sheets.
+func DefaultGreenOptions() *Options {
 	return &Options{
 		GreenScreen:    true,
 		GreenTolerance: 0.2,
@@ -49,7 +76,8 @@ func DefaultOptions() *Options {
 }
 
 // Process splits a sprite sheet image into individual cleaned tile images.
-// It runs the full pipeline: green screen removal → split → trim → resize.
+// It runs the full pipeline: background removal → split → trim → resize.
+// When GridRows/GridCols > 0, fixed-grid splitting is used instead of projection detection.
 func Process(img image.Image, opts *Options) ([]image.Image, error) {
 	if opts == nil {
 		opts = DefaultOptions()
@@ -57,13 +85,20 @@ func Process(img image.Image, opts *Options) ([]image.Image, error) {
 
 	src := toRGBA(img)
 
-	if opts.GreenScreen {
+	if opts.WhiteBg {
+		src = removeWhiteBg(src, opts.WhiteThreshold)
+	} else if opts.GreenScreen {
 		src = removeGreenScreen(src, opts.GreenTolerance)
 	}
 
-	tiles := projectionSplit(src, opts.GapThreshold, opts.MinGapWidth, opts.MinFillRatio)
+	var tiles []tile
+	if opts.GridRows > 0 && opts.GridCols > 0 {
+		tiles = fixedGridSplit(src, opts.GridRows, opts.GridCols, opts.GridPadding, opts.MinFillRatio)
+	} else {
+		tiles = projectionSplit(src, opts.GapThreshold, opts.MinGapWidth, opts.MinFillRatio)
+	}
 	if len(tiles) == 0 {
-		return nil, fmt.Errorf("no tiles detected — try lowering GapThreshold or adjusting GreenTolerance")
+		return nil, fmt.Errorf("no tiles detected — try lowering GapThreshold or setting GridRows/GridCols")
 	}
 
 	results := make([]image.Image, len(tiles))
@@ -79,9 +114,98 @@ func Process(img image.Image, opts *Options) ([]image.Image, error) {
 		}
 		results[i] = sub
 	}
+
+	if opts.CenterAlign && len(results) > 1 {
+		results = alignCenter(results)
+	}
+
 	return results, nil
 }
 
+// RemoveWhiteBg removes near-white background pixels, making them transparent.
+func RemoveWhiteBg(img image.Image, threshold uint8) image.Image {
+	return removeWhiteBg(toRGBA(img), threshold)
+}
+
+// CenterFrames centers the content of each frame within a uniform canvas so
+// characters stay in place across frames.
+func CenterFrames(frames []image.Image) []image.Image {
+	return alignCenter(frames)
+}
+
+// alignCenter finds the content bounding box per frame, computes the max
+// dimensions, then pads each frame so content is centered uniformly.
+func alignCenter(frames []image.Image) []image.Image {
+	type contentBox struct {
+		minX, minY, maxX, maxY int
+	}
+	boxes := make([]contentBox, len(frames))
+	maxW, maxH := 0, 0
+
+	for i, f := range frames {
+		b := f.Bounds()
+		minX, minY := b.Max.X, b.Max.Y
+		maxX, maxY := b.Min.X, b.Min.Y
+		hasContent := false
+		for y := b.Min.Y; y < b.Max.Y; y++ {
+			for x := b.Min.X; x < b.Max.X; x++ {
+				_, _, _, a := f.At(x, y).RGBA()
+				if a > 0 {
+					hasContent = true
+					if x < minX {
+						minX = x
+					}
+					if x > maxX {
+						maxX = x
+					}
+					if y < minY {
+						minY = y
+					}
+					if y > maxY {
+						maxY = y
+					}
+				}
+			}
+		}
+		if !hasContent {
+			boxes[i] = contentBox{0, 0, b.Dx(), b.Dy()}
+		} else {
+			boxes[i] = contentBox{minX, minY, maxX, maxY}
+		}
+		w := boxes[i].maxX - boxes[i].minX + 1
+		h := boxes[i].maxY - boxes[i].minY + 1
+		if w > maxW {
+			maxW = w
+		}
+		if h > maxH {
+			maxH = h
+		}
+	}
+
+	// Pad by 10% to avoid edge cropping
+	maxW = maxW * 11 / 10
+	maxH = maxH * 11 / 10
+
+	out := make([]image.Image, len(frames))
+	for i, f := range frames {
+		cb := boxes[i]
+		cw := cb.maxX - cb.minX + 1
+		ch := cb.maxY - cb.minY + 1
+		ox := (maxW - cw) / 2
+		oy := (maxH - ch) / 2
+
+		canvas := image.NewRGBA(image.Rect(0, 0, maxW, maxH))
+		draw.Draw(canvas,
+			image.Rect(ox, oy, ox+cw, oy+ch),
+			f,
+			image.Point{cb.minX, cb.minY},
+			draw.Src,
+		)
+		out[i] = canvas
+	}
+	return out
+}
+
 // RemoveGreenScreen removes green-dominant background pixels, making them transparent.
 func RemoveGreenScreen(img image.Image, tol float64) image.Image {
 	return removeGreenScreen(toRGBA(img), tol)
@@ -105,6 +229,34 @@ type tile struct {
 	x, y, w, h int
 }
 
+// removeWhiteBg removes pixels close to pure white (R,G,B all above threshold).
+func removeWhiteBg(rgba *image.RGBA, threshold uint8) *image.RGBA {
+	if threshold == 0 {
+		threshold = 40
+	}
+	b := rgba.Bounds()
+	dst := image.NewRGBA(b)
+	draw.Draw(dst, b, rgba, b.Min, draw.Src)
+
+	for y := b.Min.Y; y < b.Max.Y; y++ {
+		for x := b.Min.X; x < b.Max.X; x++ {
+			r, g, bl, a := rgba.At(x, y).RGBA()
+			if a == 0 {
+				continue
+			}
+			r8, g8, b8 := uint8(r>>8), uint8(g>>8), uint8(bl>>8)
+			// Pixel is "white" when all channels are near 255
+			if int(255-r8) < int(threshold) && int(255-g8) < int(threshold) && int(255-b8) < int(threshold) {
+				// Calculate alpha: closer to white = more transparent
+				dist := max(int(255-r8), max(int(255-g8), int(255-b8)))
+				alpha := float64(dist) / float64(threshold)
+				dst.SetRGBA(x, y, color.RGBA{R: r8, G: g8, B: b8, A: uint8(alpha * 255)})
+			}
+		}
+	}
+	return dst
+}
+
 func removeGreenScreen(rgba *image.RGBA, tol float64) *image.RGBA {
 	b := rgba.Bounds()
 	dst := image.NewRGBA(b)
@@ -132,6 +284,36 @@ func removeGreenScreen(rgba *image.RGBA, tol float64) *image.RGBA {
 	return dst
 }
 
+// fixedGridSplit divides the image into Rows×Cols equally-sized cells,
+// accounting for a fixed padding between cells.
+func fixedGridSplit(rgba *image.RGBA, rows, cols, padding int, minFill float64) []tile {
+	b := rgba.Bounds()
+	W, H := b.Dx(), b.Dy()
+
+	if padding < 0 {
+		padding = 0
+	}
+	totalPadW := padding * (cols + 1)
+	totalPadH := padding * (rows + 1)
+	cellW := (W - totalPadW) / cols
+	cellH := (H - totalPadH) / rows
+	if cellW <= 0 || cellH <= 0 {
+		return nil
+	}
+
+	var tiles []tile
+	for r := 0; r < rows; r++ {
+		for c := 0; c < cols; c++ {
+			x := padding + c*(cellW+padding)
+			y := padding + r*(cellH+padding)
+			if tileFillRatio(rgba, x, y, cellW, cellH) >= minFill {
+				tiles = append(tiles, tile{x: x, y: y, w: cellW, h: cellH})
+			}
+		}
+	}
+	return tiles
+}
+
 func projectionSplit(rgba *image.RGBA, gapThreshold float64, minGap int, minFill float64) []tile {
 	bounds := rgba.Bounds()
 	W, H := bounds.Dx(), bounds.Dy()

backend/tools/test_prompt_to_gif.go

@@ -0,0 +1,184 @@
+//go:build ignore
+
+package main
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"image"
+	"image/color"
+	"image/draw"
+	"image/gif"
+	"image/png"
+	"os"
+
+	"gen2d/internal/config"
+	"gen2d/internal/service"
+	"gen2d/pkg/splitsprite"
+)
+
+func main() {
+	cfg := config.Load()
+	service.InitLLMConfig(cfg.LLM)
+	service.InitImageGenConfig(cfg.ImageGen)
+
+	ctx := context.Background()
+
+	// 1. PromptAgent 优化提示词
+	fmt.Println("=== Step 1: Optimize prompt via PromptAgent ===")
+	agentIn := service.PromptAgentInput{
+		Tags:      []string{"像素", "战士", "持剑", "精灵表"},
+		AssetType: "sprite",
+		Prompt:    "生成一个像素风持剑战士的4方向行走精灵表",
+		UserNote:  "需要4方向（上下左右），每方向4帧行走动画",
+	}
+	out, err := service.RunPromptAgent(ctx, agentIn)
+	if err != nil {
+		fatalf("PromptAgent failed: %v", err)
+	}
+	fmt.Printf("Optimized prompt:\n%s\n\n", out.Prompt)
+
+	// 2. 调用文生图 API
+	fmt.Println("=== Step 2: Generate sprite sheet via image API ===")
+	params := service.AssetParams{
+		Resolution: 1024,
+		Format:     "spritesheet",
+	}
+	images, err := service.GenerateImages(ctx, out.Prompt, params)
+	if err != nil {
+		fatalf("GenerateImages failed: %v", err)
+	}
+	if len(images) == 0 {
+		fatalf("no images generated")
+	}
+	fmt.Printf("Generated %d image(s), size=%dx%d\n", len(images), images[0].Width, images[0].Height)
+
+	os.MkdirAll("test_output", 0755)
+
+	// 保存原始精灵表
+	sheetPath := "test_output/sprite_sheet.png"
+	if err := os.WriteFile(sheetPath, images[0].Data, 0644); err != nil {
+		fatalf("save sheet: %v", err)
+	}
+	fmt.Printf("Saved sprite sheet → %s (%d bytes)\n", sheetPath, len(images[0].Data))
+
+	// 3. splitsprite 拆分精灵表
+	fmt.Println("\n=== Step 3: Split sprite sheet ===")
+	sheetImg, err := decodePNG(images[0].Data)
+	if err != nil {
+		fatalf("decode sheet: %v", err)
+	}
+	opts := splitsprite.DefaultOptions()
+	opts.GridRows = 4
+	opts.GridCols = 4
+	opts.GridPadding = 2
+	opts.CenterAlign = true
+	frames, err := splitsprite.Process(sheetImg, opts)
+	if err != nil {
+		fatalf("split failed: %v", err)
+	}
+	fmt.Printf("Detected %d frames\n", len(frames))
+
+	// 保存单帧
+	for i, f := range frames {
+		fn := fmt.Sprintf("test_output/frame_%03d.png", i)
+		if err := savePNG(fn, f); err != nil {
+			fatalf("save frame %d: %v", i, err)
+		}
+	}
+	fmt.Printf("Saved %d frames → test_output/frame_*.png\n", len(frames))
+
+	// 4. 生成 GIF 预览
+	fmt.Println("\n=== Step 4: Generate GIF preview ===")
+	gifPath := "test_output/preview.gif"
+	if err := genGIF(gifPath, frames, 12); err != nil {
+		fatalf("generate GIF: %v", err)
+	}
+	fmt.Printf("GIF preview → %s (%d frames)\n", gifPath, len(frames))
+
+	fmt.Println("\n=== Done ===")
+	fmt.Println("Output files:")
+	fmt.Println("  test_output/sprite_sheet.png  — original sprite sheet")
+	fmt.Println("  test_output/frame_*.png       — individual frames")
+	fmt.Println("  test_output/preview.gif       — animated GIF preview")
+}
+
+func genGIF(path string, frames []image.Image, delay int) error {
+	f, err := os.Create(path)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+
+	pal := buildPalette(frames)
+	anim := &gif.GIF{}
+	for _, frame := range frames {
+		b := frame.Bounds()
+		paletted := image.NewPaletted(b, pal)
+		draw.Draw(paletted, b, frame, b.Min, draw.Src)
+		anim.Image = append(anim.Image, paletted)
+		anim.Delay = append(anim.Delay, delay)
+	}
+	anim.LoopCount = 0 // loop forever
+	return gif.EncodeAll(f, anim)
+}
+
+func buildPalette(frames []image.Image) color.Palette {
+	hist := make(map[color.RGBA]int)
+	sampleStep := max(1, len(frames)/8)
+	for i := 0; i < len(frames); i += sampleStep {
+		b := frames[i].Bounds()
+		step := max(1, (b.Dx()*b.Dy())/4096)
+		n := 0
+		for y := b.Min.Y; y < b.Max.Y; y++ {
+			for x := b.Min.X; x < b.Max.X; x++ {
+				if n%step != 0 {
+					n++
+					continue
+				}
+				n++
+				r, g, bl, a := frames[i].At(x, y).RGBA()
+				if a > 0 {
+					c := color.RGBA{R: uint8(r >> 8), G: uint8(g >> 8), B: uint8(bl >> 8), A: uint8(a >> 8)}
+					hist[c]++
+				}
+			}
+		}
+	}
+	pal := make(color.Palette, 0, 256)
+	for c := range hist {
+		pal = append(pal, c)
+		if len(pal) >= 240 {
+			break
+		}
+	}
+	pal = append(pal,
+		color.RGBA{0, 0, 0, 0},
+		color.RGBA{0, 0, 0, 255},
+		color.RGBA{255, 255, 255, 255},
+	)
+	return pal
+}
+
+func decodePNG(data []byte) (image.Image, error) {
+	img, _, err := image.Decode(bytes.NewReader(data))
+	if err != nil {
+		return nil, err
+	}
+	return img, nil
+}
+
+func savePNG(path string, img image.Image) error {
+	f, err := os.Create(path)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+	return png.Encode(f, img)
+}
+
+func fatalf(format string, args ...interface{}) {
+	fmt.Fprintf(os.Stderr, format+"\n", args...)
+	os.Exit(1)
+}