imageutil

package
v0.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 27, 2026 License: MIT Imports: 10 Imported by: 0

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

View Source
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.

View Source
const JPEGQuality = 90

JPEGQuality is the quality used for normalized attachment images.

View Source
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.

View Source
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

func JPEGUpright(path string) (upright bool)

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

func NormalizeFileToJPEG(path string) (out []byte, err error)

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

func NormalizeToJPEG(r io.Reader) ([]byte, error)

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址