Documentation
¶
Overview ¶
Package imageopt provides a single, reusable image normalization pipeline used before images are sent to LLM providers, both for user attachments and for tool-result images (e.g. browser screenshots).
The optimization is intentionally provider-agnostic: it decodes the image, resizes it down to the model's vision long-side limit, and recompresses it (with progressive shrinking) so the encoded payload stays within a byte budget. Sending a 4K photo untouched gives the model no extra detail because the provider rescales it anyway — it only costs bandwidth and latency.
Index ¶
Constants ¶
const ( MIMEJPEG = "image/jpeg" MIMEPNG = "image/png" MIMEWEBP = "image/webp" MIMEGIF = "image/gif" )
Supported MIME types (decode). Animations use only the first frame.
const ( // DefaultLongSidePx is the long-side pixel cap for standard vision models. DefaultLongSidePx = 1568 // HighTierLongSidePx is the long-side pixel cap for the newest, highest // resolution vision models (Opus 4.8, Sonnet 5, Fable 5, Mythos 5). HighTierLongSidePx = 2576 )
Vision resolution tiers.
Cost of an image for a vision model is driven by pixels, not bytes: the provider rescales anything larger than its long-side limit before encoding. Resizing locally to that limit saves upload bandwidth and latency with no loss of detail the model could have used.
Variables ¶
This section is empty.
Functions ¶
func Crop ¶
Crop returns the given rectangular region of the source image, re-encoded in the source format (PNG stays PNG; other formats become JPEG). The region is clamped to the image bounds. Used for the overview+zoom reading pattern.
func DetectMIME ¶
DetectMIME returns the image MIME type by inspecting magic bytes, not the file extension. Returns "" when the bytes are not a recognized image.
func ImageDimensions ¶
ImageDimensions decodes just the header to return the image's pixel size.
Types ¶
type Meta ¶
type Meta struct {
Width int
Height int
Bytes int // decoded output byte length
Base64Bytes int // base64-encoded length
Resized bool // true if the image was decoded and re-encoded
MIMEType string
}
Meta describes the result of a Normalize call, for placeholders and logging.
func Normalize ¶
func Normalize(data []byte, mime string, opts Options) (out []byte, outMIME string, meta Meta, err error)
Normalize resizes and recompresses data according to opts. When the image is already within all limits (or AutoResize is false), the original bytes are returned unchanged. The returned MIME type may differ from the input (an oversized PNG photo is re-encoded as JPEG to hit the byte budget).
type Options ¶
type Options struct {
// AutoResize enables the resize/recompress pipeline. When false, Normalize
// returns the input unchanged.
AutoResize bool
// MaxLongSidePx caps the longest image side in pixels. When 0, DefaultLongSidePx.
MaxLongSidePx int
// MaxWidth / MaxHeight are optional additional pixel caps (0 = unbounded).
MaxWidth int
MaxHeight int
// MaxBase64Bytes caps the base64-encoded payload size. 0 = unbounded.
MaxBase64Bytes int
// Quality is the JPEG quality used when recompressing (1-100). 0 => 85.
Quality int
}
Options controls how an image is normalized. A zero value disables all work (AutoResize false), returning the input untouched.
type Region ¶
type Region struct {
X, Y, W, H int
}
Region is a rectangular area of an image, in pixels.
type Tile ¶
Tile is one piece of a tiled image, encoded and labeled by grid position.
Source Files