| name | fennec-image-compression |
| description | Use this skill when asked to compress, resize, or analyze images in Go using the Fennec library, or when modifying the Fennec codebase itself. |
Fennec Image Compression Skill
Fennec is a pure-Go image compression library that uses SSIM-guided optimization to find the smallest file size that
preserves visual quality.
Core Architecture & Rules
- Pure Go: Fennec has zero external dependencies and does not use cgo. Do not introduce third-party packages.
- SSIM-Guided: Fennec binary-searches for the lowest JPEG quality that meets a target SSIM, rather than using
arbitrary quality numbers.
- Format Auto-Selection: Fennec automatically selects between JPEG and PNG based on factors like alpha transparency,
color count, and edge density.
Usage Examples
1. Basic File Compression (Quality-based)
When a user wants to compress an image with a quality preset (Lossless, Ultra, High, Balanced, Aggressive, Maximum):
import "github.com/shamspias/fennec"
opts := fennec.DefaultOptions()
opts.Quality = fennec.Balanced
result, err := fennec.CompressFile("input.jpg", "output.jpg", opts)
2. Target File Size Compression
When hitting a specific file size target in bytes, Fennec uses a multi-strategy engine (JPEG quality search, color
quantization, scaling):
opts := fennec.DefaultOptions()
opts.TargetSize = 100 * 1024
opts.Format = fennec.Auto
result, err := fennec.CompressFile("input.png", "output.jpg", opts)
3. Resizing and Compressing
Fennec uses Lanczos-3 interpolation with pre-multiplied alpha to prevent dark fringing on transparent edges:
opts := fennec.DefaultOptions()
opts.MaxWidth = 1920
opts.MaxHeight = 1080
result, err := fennec.CompressFile("huge.jpg", "web.jpg", opts)
4. Image Analysis
To analyze an image's characteristics without compressing it:
img, err := fennec.Open("photo.jpg")
stats := fennec.Analyze(img)
Contributor Guidelines
If you are tasked with modifying the Fennec codebase:
- Test Fixtures: Fennec's integration tests rely on real image files in
testdata/. If tests fail with "testdata
missing", you must run make fixtures first to generate the synthetic deterministic images.
- Performance: When modifying files like
compress.go or targetsize.go, run make bench to check for memory
allocation and performance regressions.
- SSIM Checks: The
SSIM() and SSIMFast() functions require *image.NRGBA inputs. Always ensure images are
converted using toNRGBA() before comparison.
