feat: add autoZoom param to GIF/MP4 renderers

devilr33f · devilr33f · commit fcc495c06fff · 2026-01-23T01:51:07.000+06:00
Adjusts camera distance multiplier from 1.5 to 1.25 when enabled,
reducing empty space around character while leaving room for cosmetics.
diff --git a/internal/api/handlers.go b/internal/api/handlers.go
@@ -66,7 +66,7 @@ func (h *Handlers) HandlePNG(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	pngBytes, err := render.RenderPNG(result.GLBBytes, result.Atlas, req.Rotation, req.Background, req.Width, req.Height)
+	pngBytes, err := render.RenderPNG(result.GLBBytes, result.Atlas, req.Rotation, req.Background, req.Width, req.Height, true)
 	if err != nil {
 		writeError(w, http.StatusInternalServerError, "render failed: "+err.Error())
 		return
@@ -103,7 +103,7 @@ func (h *Handlers) HandleGIF(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	gifBytes, err := render.RenderGIF(result.GLBBytes, result.Atlas, req.Background, req.Frames, req.Width, req.Height, req.Delay, *req.Dithering)
+	gifBytes, err := render.RenderGIF(result.GLBBytes, result.Atlas, req.Background, req.Frames, req.Width, req.Height, req.Delay, *req.Dithering, *req.AutoZoom)
 	if err != nil {
 		writeError(w, http.StatusInternalServerError, "render failed: "+err.Error())
 		return
@@ -140,7 +140,7 @@ func (h *Handlers) HandleMP4(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	mp4Bytes, err := render.RenderMP4(result.GLBBytes, result.Atlas, req.Background, req.Frames, req.Width, req.Height, req.FPS)
+	mp4Bytes, err := render.RenderMP4(result.GLBBytes, result.Atlas, req.Background, req.Frames, req.Width, req.Height, req.FPS, *req.AutoZoom)
 	if err != nil {
 		writeError(w, http.StatusInternalServerError, "render failed: "+err.Error())
 		return
diff --git a/internal/api/openapi.go b/internal/api/openapi.go
@@ -238,7 +238,8 @@ const OpenAPISpec = `{
           "width": {"type": "integer", "default": 512, "description": "Image width in pixels"},
           "height": {"type": "integer", "default": 512, "description": "Image height in pixels"},
           "delay": {"type": "integer", "default": 5, "description": "Centiseconds between frames"},
-          "dithering": {"type": "boolean", "default": true, "description": "Enable Floyd-Steinberg dithering (disable for faster rendering)"}
+          "dithering": {"type": "boolean", "default": true, "description": "Enable Floyd-Steinberg dithering (disable for faster rendering)"},
+          "autoZoom": {"type": "boolean", "default": true, "description": "Auto-zoom camera to fit character tightly in frame"}
         }
       },
       "MP4Request": {
@@ -250,7 +251,8 @@ const OpenAPISpec = `{
           "frames": {"type": "integer", "default": 36, "description": "Number of frames (36 = 10° per frame)"},
           "width": {"type": "integer", "default": 512, "description": "Video width in pixels"},
           "height": {"type": "integer", "default": 512, "description": "Video height in pixels"},
-          "fps": {"type": "integer", "default": 12, "description": "Frames per second"}
+          "fps": {"type": "integer", "default": 12, "description": "Frames per second"},
+          "autoZoom": {"type": "boolean", "default": true, "description": "Auto-zoom camera to fit character tightly in frame"}
         }
       },
       "ErrorResponse": {
diff --git a/internal/api/types.go b/internal/api/types.go
@@ -20,6 +20,7 @@ type GIFRequest struct {
 	Height     int             `json:"height"`     // default 512
 	Delay      int             `json:"delay"`      // centiseconds between frames, default 5
 	Dithering  *bool           `json:"dithering"`  // Floyd-Steinberg dithering, default true
+	AutoZoom   *bool           `json:"autoZoom"`   // auto-zoom to fit character, default true
 }
 
 // MP4Request represents a request to render a character as MP4 video
@@ -30,6 +31,7 @@ type MP4Request struct {
 	Width      int             `json:"width"`      // default 512
 	Height     int             `json:"height"`     // default 512
 	FPS        int             `json:"fps"`        // frames per second, default 12
+	AutoZoom   *bool           `json:"autoZoom"`   // auto-zoom to fit character, default true
 }
 
 // ErrorResponse represents an error returned by the API
@@ -71,6 +73,10 @@ func (r *GIFRequest) ApplyDefaults() {
 		defaultDithering := true
 		r.Dithering = &defaultDithering
 	}
+	if r.AutoZoom == nil {
+		defaultAutoZoom := true
+		r.AutoZoom = &defaultAutoZoom
+	}
 }
 
 // ApplyDefaults fills in default values for MP4Request
@@ -90,4 +96,8 @@ func (r *MP4Request) ApplyDefaults() {
 	if r.Background == "" {
 		r.Background = "#FFFFFF"
 	}
+	if r.AutoZoom == nil {
+		defaultAutoZoom := true
+		r.AutoZoom = &defaultAutoZoom
+	}
 }
diff --git a/internal/render/gif.go b/internal/render/gif.go
@@ -14,7 +14,7 @@ import (
 )
 
 // RenderGIF renders a GLB model to an animated GIF rotating 360 degrees
-func RenderGIF(glbBytes []byte, atlas *texture.Atlas, background string, frames, width, height, delay int, dithering bool) ([]byte, error) {
+func RenderGIF(glbBytes []byte, atlas *texture.Atlas, background string, frames, width, height, delay int, dithering, autoZoom bool) ([]byte, error) {
 	// Parse background color
 	bgColor, err := ParseHexColor(background)
 	if err != nil {
@@ -41,7 +41,7 @@ func RenderGIF(glbBytes []byte, atlas *texture.Atlas, background string, frames,
 		go func(frameIdx int) {
 			defer wg.Done()
 			rotation := float64(frameIdx) * rotationPerFrame
-			renderedFrames[frameIdx] = RenderScene(mesh, atlasImage, rotation, width, height, bgColor)
+			renderedFrames[frameIdx] = RenderScene(mesh, atlasImage, rotation, width, height, bgColor, autoZoom)
 		}(i)
 	}
 	wg.Wait()
diff --git a/internal/render/mp4.go b/internal/render/mp4.go
@@ -12,7 +12,7 @@ import (
 )
 
 // RenderMP4 renders a GLB model to an MP4 video rotating 360 degrees
-func RenderMP4(glbBytes []byte, atlas *texture.Atlas, background string, frames, width, height, fps int) ([]byte, error) {
+func RenderMP4(glbBytes []byte, atlas *texture.Atlas, background string, frames, width, height, fps int, autoZoom bool) ([]byte, error) {
 	// Parse background color
 	bgColor, err := ParseHexColor(background)
 	if err != nil {
@@ -47,7 +47,7 @@ func RenderMP4(glbBytes []byte, atlas *texture.Atlas, background string, frames,
 		go func(frameIdx int) {
 			defer wg.Done()
 			rotation := float64(frameIdx) * rotationPerFrame
-			img := RenderScene(mesh, atlasImage, rotation, width, height, bgColor)
+			img := RenderScene(mesh, atlasImage, rotation, width, height, bgColor, autoZoom)
 
 			// Write frame to temp file
 			framePath := filepath.Join(tempDir, fmt.Sprintf("frame_%04d.png", frameIdx))
diff --git a/internal/render/png.go b/internal/render/png.go
@@ -9,7 +9,7 @@ import (
 )
 
 // RenderPNG renders a GLB model to PNG with the given parameters
-func RenderPNG(glbBytes []byte, atlas *texture.Atlas, rotation float64, background string, width, height int) ([]byte, error) {
+func RenderPNG(glbBytes []byte, atlas *texture.Atlas, rotation float64, background string, width, height int, autoZoom bool) ([]byte, error) {
 	// Parse background color
 	bgColor, err := ParseHexColor(background)
 	if err != nil {
@@ -26,7 +26,7 @@ func RenderPNG(glbBytes []byte, atlas *texture.Atlas, rotation float64, backgrou
 	}
 
 	// Render the scene
-	img := RenderScene(mesh, atlasImage, rotation, width, height, bgColor)
+	img := RenderScene(mesh, atlasImage, rotation, width, height, bgColor, autoZoom)
 
 	// Encode to PNG
 	var buf bytes.Buffer
diff --git a/internal/render/software.go b/internal/render/software.go
@@ -313,7 +313,7 @@ func quaternionToMatrix(x, y, z, w float64) fauxgl.Matrix {
 }
 
 // RenderScene renders a mesh with the given parameters
-func RenderScene(mesh *fauxgl.Mesh, atlasImage image.Image, rotationY float64, width, height int, bgColor color.Color) image.Image {
+func RenderScene(mesh *fauxgl.Mesh, atlasImage image.Image, rotationY float64, width, height int, bgColor color.Color, autoZoom bool) image.Image {
 	context := fauxgl.NewContext(width, height)
 	context.Cull = fauxgl.CullNone
 	context.AlphaBlend = false
@@ -342,7 +342,11 @@ func RenderScene(mesh *fauxgl.Mesh, atlasImage image.Image, rotationY float64, w
 	far := 100.0
 
 	maxDim := math.Max(modelSize.X, math.Max(modelSize.Y, modelSize.Z))
-	cameraDistance := maxDim / (2 * math.Tan(fauxgl.Radians(fovy/2))) * 1.5
+	multiplier := 1.5
+	if autoZoom {
+		multiplier = 1.25
+	}
+	cameraDistance := maxDim / (2 * math.Tan(fauxgl.Radians(fovy/2))) * multiplier
 
 	eye := fauxgl.V(modelCenter.X, modelCenter.Y, modelCenter.Z+cameraDistance)
 	center := modelCenter

Original file line number	Diff line number	Diff line change
`@@ -20,6 +20,7 @@ type GIFRequest struct {`
`20`	`20`	Height int `json:"height"` // default 512
`21`	`21`	Delay int `json:"delay"` // centiseconds between frames, default 5
`22`	`22`	Dithering *bool `json:"dithering"` // Floyd-Steinberg dithering, default true
	`23`	+ AutoZoom *bool `json:"autoZoom"` // auto-zoom to fit character, default true
`23`	`24`	`}`
`24`	`25`
`25`	`26`	`// MP4Request represents a request to render a character as MP4 video`
`@@ -30,6 +31,7 @@ type MP4Request struct {`
`30`	`31`	Width int `json:"width"` // default 512
`31`	`32`	Height int `json:"height"` // default 512
`32`	`33`	FPS int `json:"fps"` // frames per second, default 12
	`34`	+ AutoZoom *bool `json:"autoZoom"` // auto-zoom to fit character, default true
`33`	`35`	`}`
`34`	`36`
`35`	`37`	`// ErrorResponse represents an error returned by the API`
`@@ -71,6 +73,10 @@ func (r *GIFRequest) ApplyDefaults() {`
`71`	`73`	`defaultDithering := true`
`72`	`74`	`r.Dithering = &defaultDithering`
`73`	`75`	`}`
	`76`	`+ if r.AutoZoom == nil {`
	`77`	`+ defaultAutoZoom := true`
	`78`	`+ r.AutoZoom = &defaultAutoZoom`
	`79`	`+ }`
`74`	`80`	`}`
`75`	`81`
`76`	`82`	`// ApplyDefaults fills in default values for MP4Request`
`@@ -90,4 +96,8 @@ func (r *MP4Request) ApplyDefaults() {`
`90`	`96`	`if r.Background == "" {`
`91`	`97`	`r.Background = "#FFFFFF"`
`92`	`98`	`}`
	`99`	`+ if r.AutoZoom == nil {`
	`100`	`+ defaultAutoZoom := true`
	`101`	`+ r.AutoZoom = &defaultAutoZoom`
	`102`	`+ }`
`93`	`103`	`}`
Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@ import (`
`9`	`9`	`)`
`10`	`10`
`11`	`11`	`// RenderPNG renders a GLB model to PNG with the given parameters`
`12`		`-func RenderPNG(glbBytes []byte, atlas *texture.Atlas, rotation float64, background string, width, height int) ([]byte, error) {`
	`12`	`+func RenderPNG(glbBytes []byte, atlas *texture.Atlas, rotation float64, background string, width, height int, autoZoom bool) ([]byte, error) {`
`13`	`13`	`// Parse background color`
`14`	`14`	`bgColor, err := ParseHexColor(background)`
`15`	`15`	`if err != nil {`
`@@ -26,7 +26,7 @@ func RenderPNG(glbBytes []byte, atlas *texture.Atlas, rotation float64, backgrou`
`26`	`26`	`}`
`27`	`27`
`28`	`28`	`// Render the scene`
`29`		`- img := RenderScene(mesh, atlasImage, rotation, width, height, bgColor)`
	`29`	`+ img := RenderScene(mesh, atlasImage, rotation, width, height, bgColor, autoZoom)`
`30`	`30`
`31`	`31`	`// Encode to PNG`
`32`	`32`	`var buf bytes.Buffer`