Documentation
¶
Overview ¶
Package imageutil normalizes images before they are persisted and inlined into model prompts: EXIF orientation is applied, transparency is flattened onto white, and the result is re-encoded as JPEG so prompt bytes stay predictable regardless of the source format.
Decoding runs on github.com/disintegration/imaging (pure Go, no cgo). TIFF and BMP are decoded because that library imports golang.org/x/image/{tiff,bmp} for registration; a test here holds that implicit dependency in place, and the entry points name the formats they accept so a reader does not have to guess.
Nothing in core calls these functions yet: the consumers are hosts (persisting an attachment, previewing one) and the model-facing tools that read images, which arrive in their own change. Until then the budgets below and the tests that pin them are the package's reason to exist under core/media.
Index ¶
Constants ¶
const ( // DefaultPromptImageEdge is the longest-edge target in pixels. DefaultPromptImageEdge = 1568 // DefaultPromptImageBytes is the raw-byte target; the marshalled // image part stays under the default 1 MiB part budget. DefaultPromptImageBytes = 786_000 )
Prompt-side downscale targets. A tool result is replayed in every later turn's context, so an image handed to the model is bounded on both axes: longest edge in pixels and size in bytes. The edge target matches what the wire providers document (~1568 px).
The byte target is raw JPEG size, while the part budget applied to non-text tool output is metered on the canonical wire encoding (message.MarshalPart): an inline image spends base64-expanded bytes (~4/3 of the raw size) plus a small JSON envelope. DefaultPromptImageBytes is therefore the raw size that still fits the default 1 MiB part budget (core/tool/middleware.DefaultResultPartBudget); a wiring test in this package pins the two constants against each other.
const JPEGQuality = 90
JPEGQuality is the quality used for normalized attachment images.
const MaxDecodePixels = 40_000_000
MaxDecodePixels bounds the pixel budget of images that are fully decoded for normalization. Decoding a huge-but-compressed image (a decompression bomb) would otherwise allocate hundreds of MB per working buffer. Comparisons are made in int64 so the bound also holds where int is 32 bits wide.
const MaxInlineImageBytes = 10 << 20
MaxInlineImageBytes is the per-image inline budget: one image carried into a prompt, persisted as an attachment, or previewed as a data URL stays under it. The media.attachments prepare hook applies the same number to every attachment kind (core/media/hook.DefaultMaxInlineBytes), so an image that survived persistence also survives the trip into a prompt; hosts and tools that cap an image on their own use this constant.
Variables ¶
This section is empty.
Functions ¶
func DownscaleToJPEG ¶
func DownscaleToJPEG( r io.Reader, maxEdge, maxBytes int, ) (out []byte, width, height int, err error)
DownscaleToJPEG decodes r (same formats and EXIF handling as NormalizeToJPEG) and re-encodes it as a JPEG that fits both maxEdge (longest side, pixels; <= 0 keeps the source size) and maxBytes (encoded size; <= 0 applies no byte budget and returns the first ladder step, quality 90). Quality is stepped down first and the image is scaled further only when the lowest quality still does not fit, so a normal screenshot keeps its resolution and a huge one still arrives.
The returned dimensions always describe the returned bytes. When the byte budget is out of reach even at the smallest size the ladder produces, the smallest encoding it made is returned instead of an error: callers use this to fit a preview, and an oversized preview beats a failed read.
func JPEGUpright ¶
JPEGUpright reports whether path is a JPEG whose EXIF orientation requires no transform: orientation 1, an orientation value outside 1..8 that imaging rejects as well, an APP1 segment that is not EXIF, or no APP1 segment at all. Such a file can be persisted and served byte-for-byte; a file that needs a transform falls back to full decode + JPEG normalization.
The reader mirrors imaging's, because imaging is what re-encodes a file reported as needing a transform: it looks at the first APP1 segment only, and takes the orientation from the first two bytes of the tag's value field whatever type and count the entry declares. Where this reader cannot follow a malformed stream — truncated EXIF data, marker fill bytes imaging misreads — it reports "needs a transform" instead of guessing: a needless re-encode costs quality, a missed rotation ships a sideways image.
func NormalizeFileToJPEG ¶
NormalizeFileToJPEG is NormalizeToJPEG for a local path. It checks the pixel budget before decoding, so a sparse image with enormous dimensions is rejected without a full-size allocation.
func NormalizeToJPEG ¶
NormalizeToJPEG decodes r (JPEG/PNG/GIF/TIFF/BMP with EXIF orientation applied), flattens transparency onto white, and re-encodes the result as a JPEG at JPEGQuality. Formats the decoder does not understand (for example WebP/AVIF) return an error so callers can fall back to the original bytes. The pixel budget guard lives in NormalizeFileToJPEG, which is the production entry point; this reader variant is used by tests and by callers that already validated the input, and checking the header is their responsibility.
Types ¶
This section is empty.