Re-encode an image at a chosen quality to reduce file size, writing the result to a NEW file (source unchanged). Quality is 1-100 (default 80); lower values produce smaller files. The output format defaults to JPEG but can be set via 'format'. Returns the output path plus bytes_before, bytes_after, and saved_percent so you can see how much space was recovered.

Change an image's file format and write it to a NEW file (source unchanged). The target format is inferred from the output file extension (e.g. .webp) unless 'format' is given explicitly; supported targets include PNG, JPEG, WEBP, GIF, BMP, TIFF. When saving to a format without transparency (e.g. JPEG), any alpha channel is flattened onto a white background. Returns the output path and final format.

Extract a rectangular sub-region and write it to a NEW file (source unchanged). The region is defined by its top-left corner (x, y) and size (width, height); coordinates are automatically clamped to the image bounds, so partial/out-of-bounds boxes are safe. Returns the output path and the actual box used.

Apply a single visual effect and write the result to a NEW file (source unchanged). Effects: greyscale, sepia, invert, blur (uses 'radius'), sharpen, contrast (uses 'factor'), brightness (uses 'factor'). Returns the output path and the effect applied. Unknown effect names raise an error.

Mirror an image and write it to a NEW file (source unchanged). 'axis' selects horizontal (left-right mirror) or vertical (top-bottom flip). Returns the output path and the axis used.

Read-only metadata inspector. Returns the image's absolute path, format, width, height, color mode, and file size in bytes. Use it first to learn an image's dimensions or mode before resizing, cropping, or converting. Never writes to or modifies the source file.

Composite one image on top of another and write the result to a NEW file (sources unchanged). The 'overlay' image is placed at offset (x, y) on the 'base' image; its alpha channel is respected, and an 'opacity' of 0-1 lets you fade it in. Use it for logos, badges, or layering. Returns the output path and the offset used.

Generate a brand-new solid-color image (optionally with a centered label) and write it to 'out'. Useful for mockups, spacer images, or test fixtures. Provide width, height, background color, and optional text with its color and font size. Returns the output path and the generated dimensions.

Resize an image and write the result to a NEW file (the source is never overwritten). Provide width and/or height; if only one is given the other is computed to preserve aspect ratio. 'fit' controls how the image maps into the target box: contain fits inside (no crop), cover fills the box and crops the overflow, fill/stretch forces the exact width x height (aspect ratio may change). Returns the output path and resulting dimensions.

Rotate an image clockwise by a number of degrees and write it to a NEW file (source unchanged). With expand=true (the default) the canvas is enlarged so no corners are clipped; set expand=false to keep the original canvas size and crop the overflow. Returns the output path and the angle applied.

Create a downscaled preview whose longest side is at most 'size' pixels (aspect ratio preserved), writing it to a NEW file (source unchanged). Ideal for generating small previews or contact sheets. Returns the output path and the max-side constraint applied.

Burn a text label onto an image and write it to a NEW file (source unchanged). Configure placement (position), color (hex, e.g. #ffffff), opacity (0-1, default 0.6), font size, and padding. The label is drawn with an alpha channel so it blends over the image. Returns the output path and the effective position.