Image

from blanket import Image exposes the Image class, constructors, image operations, and saving. General processing supports 8-bit L, RGB, and RGBA images. Quantization produces indexed P images with a smaller API. See formats and save options and high bit depth for codec and precision limits.

Create and open

API	Behavior
`Image.open(path_or_stream)`	Open a path or binary stream. Only the first frame or primary image is opened.
`Image.new(mode, size, color=0)`	Create an 8-bit `L`, `RGB`, or `RGBA` image.
`Image.fromarray(array, bit_depth=None)`	Import an array-interface object, including strided uint8 or uint16 arrays.
`Image.frombytes(mode, size, data, ..., bit_depth=8)`	Import packed pixels; samples above 8 bits use little-endian uint16 storage.

Inspect and edit pixels

API	Behavior
`getpixel((x, y))`	Read one pixel; negative coordinates are accepted.
`putpixel((x, y), value)`	Write one 8-bit pixel. Palette images require an index.
`getdata(band=None)`, `get_flattened_data(band=None)`	Return independent flat list or tuple snapshots in row order.
`putdata(data, scale=1.0, offset=0.0)`	Write 8-bit pixels in row order. Short input leaves remaining pixels unchanged. Scale and offset apply to single-band values.
`getbands()`, `getchannel(name_or_index)`, `split()`	Inspect or extract channels as independent `L` images.
`getcolors(maxcolors=256)`	Return unordered `(count, pixel)` pairs, or `None` if the limit is exceeded.
`getextrema()`, `getbbox(alpha_only=True)`	Find sample extrema or a nonzero bounding box. RGBA bounding boxes check alpha by default.
`histogram(mask=None, extrema=None)`, `entropy(mask=None, extrema=None)`	Use 256 bins per channel on 8-bit images. A nonzero `L` mask selects pixels; `extrema` is ignored.

Pixel reads, channel extraction, extrema, bounding boxes, and color counts also support high-bit-depth samples. Pixel mutation requires 8-bit samples.

Transform and resize

API	Behavior
`convert(mode, bit_depth=None)`	Convert among `L`, `RGB`, and `RGBA`; choose 8 bits before unsupported processing.
`copy()`, `crop(box=None)`	Copy pixels; crop pads out-of-bounds regions with zeros.
`resize(size, resample=None, box=None, reducing_gap=None)`	Return a resized copy. Default is BICUBIC; all six `Image.Resampling` filters work. `reducing_gap` must be at least 1.0.
`thumbnail(size, resample=Image.Resampling.BICUBIC, reducing_gap=2.0)`	Shrink in place without enlarging; preserve aspect ratio and return `None`.
`reduce(factor, box=None)`	Average integer blocks; dimensions round up. Indexed images allow only a full-size copy.
`transpose(method)`	Return a flipped or rotated copy; all seven `Image.Transpose` methods work.
`rotate(angle, resample=Image.Resampling.NEAREST, expand=False, center=None, translate=None, fillcolor=None)`	Rotate counterclockwise with NEAREST, BILINEAR, or BICUBIC. Expansion assumes the default center and no translation.
`transform(size, method, data=None, resample=Image.Resampling.NEAREST, fill=1, fillcolor=None)`	Support AFFINE, EXTENT, PERSPECTIVE, QUAD, and MESH with NEAREST, BILINEAR, or BICUBIC; also accepts `getdata()` objects and `ImageTransformHandler` subclasses.
`point(lut, mode=None)`	Apply a 256-entry-per-channel LUT or callable to 8-bit pixels. Output mode conversion is unsupported.

These copy metadata where applicable. Copy, conversion, crop, transpose, and resize retain high-bit-depth samples; most other processing requires 8 bits.

Compose images

Image.blend(im1, im2, alpha) blends equally sized 8-bit images. Alpha outside [0, 1] extrapolates and clips. Image.composite(image1, image2, mask) uses an L mask or the alpha channel of an RGBA mask.

image.paste(source_or_color, box=None, mask=None) clips to the canvas and accepts L or RGBA masks. Image.alpha_composite(background, overlay) and image.alpha_composite(overlay, dest=(0, 0), source=(0, 0)) require RGBA. image.putalpha(alpha) accepts an L image or integer and promotes RGB to RGBA; L and P images cannot gain alpha this way. Image.merge(mode, bands) combines L bands into an L, RGB, or RGBA image. These APIs use 8-bit samples.

Quantize and use palettes

image.quantize(colors=256, method=None, kmeans=0, palette=None, dither=Image.Dither.FLOYDSTEINBERG) returns a P image. Methods are MEDIANCUT, MAXCOVERAGE, and FASTOCTREE (the RGBA default). LIBIMAGEQUANT is unavailable. Generated palettes can differ from Pillow.

Indexed images support palette access and editing, copying, cropping, nearest-neighbor resizing, conversion, PNG saving with palette alpha, and to_pillow(). Convert to L, RGB, or RGBA for general processing. See ImagePalette for palette objects.

Save and metadata

image.save(path, ...) infers the format from the extension. Supply format when saving to a binary stream. See formats and save options for encoder arguments and Compressor for optional save-time optimization.

Opening PNG and JPEG reads EXIF/XMP into image.info; uncompressed EXIF/XMP boxes in JPEG XL are also read. This supports ImageOps.exif_transpose. Saving writes pixels only and does not preserve metadata.

Reference

new

new(mode: str, size: tuple[int, int], color: str | int | tuple[int, ...] | None = 0) -> Image

Create an 8-bit L, RGB, RGBA, or indexed image filled with color.

Parameters:

Name	Type	Description	Default
`mode`	`str`	Image mode, such as `L`, `RGB`, or `RGBA`.	required
`size`	`tuple[int, int]`	Output `(width, height)` in pixels.	required
`color`	`str \| int \| tuple[int, ...] \| None`	Fill value, channel tuple, or CSS color string.	`0`

Examples:

from blanket import Image

image = Image.new("RGB", (64, 64), "navy")

open

open(fp: str | bytes | PathLike[str] | PathLike[bytes] | BinaryIO, mode: str = 'r', formats: list[str] | tuple[str, ...] | None = None) -> Image

Open and eagerly decode a supported image.

Parameters:

Name	Type	Description	Default
`fp`	`str \| bytes \| PathLike[str] \| PathLike[bytes] \| BinaryIO`	Image filename, path-like object, or binary stream. Decoding is eager.	required
`mode`	`str`	Read mode; only `r` is supported.	`'r'`
`formats`	`list[str] \| tuple[str, ...] \| None`	Optional allowlist of format names to attempt.	`None`

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
from io import BytesIO

encoded = BytesIO()
image.save(encoded, format="PNG")
encoded.seek(0)
with Image.open(encoded) as reopened:
    print(reopened.size)

frombytes

frombytes(mode: str, size: tuple[int, int], data: object, *, bit_depth: int = 8) -> Image

Create an image from packed pixels; depths above 8 use little-endian uint16.

Parameters:

Name	Type	Description	Default
`mode`	`str`	Image mode, such as `L`, `RGB`, or `RGBA`.	required
`size`	`tuple[int, int]`	Output `(width, height)` in pixels.	required
`data`	`object`	Contiguous packed pixel buffer; depths above 8 use little-endian uint16 samples.	required
`bit_depth`	`int`	Significant bits per channel: 8, 10, 12, or 16. None retains or infers the depth where supported.	`8`

Examples:

from blanket import Image

image = Image.frombytes("RGB", (2, 1), bytes([255, 0, 0, 0, 255, 0]))

fromarray

fromarray(obj: object, mode: str | None = None, *, bit_depth: int | None = None) -> Image

Create an image from uint8 or uint16 samples exposing the array interface.

Parameters:

Name	Type	Description	Default
`obj`	`object`	Object exposing the array interface with uint8 or uint16 samples.	required
`mode`	`str \| None`	Optional mode matching the array's channel layout.	`None`
`bit_depth`	`int \| None`	Significant bits per channel: 8, 10, 12, or 16. None retains or infers the depth where supported.	`None`

Examples:

import numpy as np
from blanket import Image

pixels = np.zeros((8, 8, 3), dtype=np.uint8)
image = Image.fromarray(pixels)

merge

merge(mode: str, bands: Sequence[Image]) -> Image

Interleave L bands into an independent L, RGB, or RGBA image.

Parameters:

Name	Type	Description	Default
`mode`	`str`	Image mode, such as `L`, `RGB`, or `RGBA`.	required
`bands`	`Sequence[Image]`	Sequence of single-channel L images, one per output band.	required

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
red, green, blue = image.split()
result = Image.merge("RGB", (blue, green, red))

blend

blend(im1: Image, im2: Image, alpha: float) -> Image

Interpolate equal-sized 8-bit images, clipping extrapolated values.

Parameters:

Name	Type	Description	Default
`im1`	`Image`	First image; both inputs must have the same mode and dimensions.	required
`im2`	`Image`	Second image.	required
`alpha`	`float`	Blending weight: 0 selects the first image and 1 the second; values outside this range extrapolate.	required

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
other = Image.new("RGB", image.size, "white")
result = Image.blend(image, other, 0.25)

composite

composite(image1: Image, image2: Image, mask: Image) -> Image

Select between images using an L or RGBA mask through native paste.

Parameters:

Name	Type	Description	Default
`image1`	`Image`	First input image; its mode and dimensions must match the second image.	required
`image2`	`Image`	Second input image.	required
`mask`	`Image`	Optional mask selecting pixels. Histogram operations require an L mask; compositing also accepts RGBA alpha.	required

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
other = Image.new("RGB", image.size, "white")
mask = Image.new("L", image.size, 128)
result = Image.composite(image, other, mask)

alpha_composite

alpha_composite(im1: Image, im2: Image) -> Image

Return im2 composited over im1; both must be equal-sized 8-bit RGBA.

Parameters:

Name	Type	Description	Default
`im1`	`Image`	First image; both inputs must have the same mode and dimensions.	required
`im2`	`Image`	Second image.	required

Examples:

from blanket import Image

background = Image.new("RGBA", (8, 8), "navy")
overlay = Image.new("RGBA", (8, 8), (255, 0, 0, 128))
result = Image.alpha_composite(background, overlay)

Image

An image whose pixels and supported operations live in Rust.

mode `property`

mode: str

Pixel mode of this image.

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
print(image.mode)

bit_depth `property`

bit_depth: int

Significant bits per channel (8, 10, 12, or 16).

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
print(image.bit_depth)

size `property`

size: tuple[int, int]

Image dimensions as (width, height).

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
print(image.size)

width `property`

width: int

Image width in pixels.

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
print(image.width)

height `property`

height: int

Image height in pixels.

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
print(image.height)

format `property`

format: str | None

Detected input format, or None for a newly created image.

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
print(image.format)

info `property`

info: dict[object, object]

Mutable metadata dictionary.

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
print(image.info)

is_animated `property`

is_animated: bool

Blanket exposes a single frame for every supported image.

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
print(image.is_animated)

has_transparency_data `property`

has_transparency_data: bool

Whether alpha or transparency metadata exists, even if opaque.

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
print(image.has_transparency_data)

load

load() -> None

Validate that this eagerly loaded image remains open.

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
image.load()

close

close() -> None

Release the image's pixel buffer.

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
image.close()

convert

convert(mode: str, *, bit_depth: int | None = None) -> Image

Return a new image converted to L, RGB, or RGBA.

Parameters:

Name	Type	Description	Default
`mode`	`str`	Destination mode: `L`, `RGB`, or `RGBA`.	required
`bit_depth`	`int \| None`	Output sample depth, or None to retain the input depth.	`None`

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
result = image.convert("L")

copy

copy() -> Image

Return an independent copy of the pixels, palette, and metadata.

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
result = image.copy()

getpixel

getpixel(xy: tuple[int, int] | list[int]) -> int | tuple[int, ...]

Return a pixel value, accepting negative coordinates as Pillow does.

Parameters:

Name	Type	Description	Default
`xy`	`tuple[int, int] \| list[int]`	Pixel `(x, y)` coordinates. Negative coordinates count from the right or bottom.	required

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
pixel = image.getpixel((0, 0))

getpalette

getpalette(rawmode: str | None = 'RGB') -> list[int] | None

Return interleaved palette entries, or None for non-palette images.

Parameters:

Name	Type	Description	Default
`rawmode`	`str \| None`	Channel layout of the palette data, normally `RGB` or `RGBA`.	`'RGB'`

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
palette = image.quantize(colors=8).getpalette()

putpixel

putpixel(xy: tuple[int, int], value: int | tuple[int, ...]) -> None

Write an 8-bit pixel, accepting negative coordinates and clipping values.

Palette images accept numeric indices, not RGB color allocation.

Parameters:

Name	Type	Description	Default
`xy`	`tuple[int, int]`	Pixel `(x, y)` coordinates. Negative coordinates count from the right or bottom.	required
`value`	`int \| tuple[int, ...]`	Pixel value or channel tuple.	required

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
image.putpixel((0, 0), (255, 0, 0))

getdata

getdata(band: int | None = None) -> list[int | tuple[int, ...]]

Return a flat pixel snapshot, optionally selecting one band.

Parameters:

Name	Type	Description	Default
`band`	`int \| None`	Zero-based channel index, or None for all channels.	`None`

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
pixels = image.getdata()

get_flattened_data

get_flattened_data(band: int | None = None) -> tuple[int | tuple[int, ...], ...]

Return an immutable flat pixel snapshot, as in recent Pillow versions.

Parameters:

Name	Type	Description	Default
`band`	`int \| None`	Zero-based channel index, or None for all channels.	`None`

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
pixels = image.get_flattened_data()

putdata

putdata(data: Sequence[int | float | tuple[int, ...]], scale: float = 1.0, offset: float = 0.0) -> None

Write 8-bit pixels in row order; scale/offset apply to single-band data.

Parameters:

Name	Type	Description	Default
`data`	`Sequence[int \| float \| tuple[int, ...]]`	Pixel values in row order. Short input leaves remaining pixels unchanged.	required
`scale`	`float`	Multiplier for single-band input values.	`1.0`
`offset`	`float`	Offset added after multiplying single-band values.	`0.0`

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
image.putdata([(255, 0, 0)] * 64)

getcolors

getcolors(maxcolors: int = 256) -> list[tuple[int, int | tuple[int, ...]]] | None

Return unordered (count, pixel) pairs, or None above maxcolors.

Parameters:

Name	Type	Description	Default
`maxcolors`	`int`	Maximum number of distinct colors to return; exceeding it returns None.	`256`

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
counts = image.getcolors(maxcolors=256)

putpalette

putpalette(data: Sequence[int] | bytes | ImagePalette, rawmode: str = 'RGB') -> None

Attach an RGB or RGBA palette to an L or P image.

Parameters:

Name	Type	Description	Default
`data`	`Sequence[int] \| bytes \| ImagePalette`	Interleaved palette entries or an ImagePalette object.	required
`rawmode`	`str`	Channel layout of the palette data, normally `RGB` or `RGBA`.	`'RGB'`

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
image = Image.new("P", (8, 8))
image.putpalette([0, 0, 0, 255, 0, 0])

quantize

quantize(colors: int = 256, method: int | None = None, kmeans: int = 0, palette: Image | None = None, dither: Dither = FLOYDSTEINBERG) -> Image

Return an indexed P image using a generated or supplied palette.

MEDIANCUT, MAXCOVERAGE, and FASTOCTREE run in the native backend. LIBIMAGEQUANT is unavailable in this build. Generated palette ordering and color choices may differ from Pillow's implementations.

Parameters:

Name	Type	Description	Default
`colors`	`int`	Maximum palette size, from 1 through 256.	`256`
`method`	`int \| None`	Quantizer from `Image.Quantize`; defaults to FASTOCTREE for RGBA and MEDIANCUT otherwise.	`None`
`kmeans`	`int`	Number of k-means refinement iterations for supported quantizers.	`0`
`palette`	`Image \| None`	Optional indexed image supplying the destination palette.	`None`
`dither`	`Dither`	Dithering mode from `Image.Dither`.	`FLOYDSTEINBERG`

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
result = image.quantize(colors=8)

tobytes

tobytes() -> bytes

Return packed pixels; high-depth samples use little-endian uint16 storage.

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
pixels = image.tobytes()

filter

filter(filter: Filter | type[Filter]) -> Image

Return a filtered image, accepting a filter instance or class.

Parameters:

Name	Type	Description	Default
`filter`	`Filter \| type[Filter]`	Filter instance or filter class from `ImageFilter`.	required

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
from blanket import ImageFilter

result = image.filter(ImageFilter.GaussianBlur(radius=2))

paste

paste(im: Image | str | int | tuple[int, ...], box: Image | tuple[int, ...] | None = None, mask: Image | None = None) -> None

Paste pixels or a color, optionally interpolating through an L/RGBA mask.

Parameters:

Name	Type	Description	Default
`im`	`Image \| str \| int \| tuple[int, ...]`	Source image or fill color.	required
`box`	`Image \| tuple[int, ...] \| None`	Destination origin or rectangle, or a mask image as the second positional argument.	`None`
`mask`	`Image \| None`	Optional mask selecting pixels. Histogram operations require an L mask; compositing also accepts RGBA alpha.	`None`

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
image.paste("red", (0, 0, 4, 4))

alpha_composite

alpha_composite(im: Image, dest: tuple[int, int] = (0, 0), source: tuple[int, ...] = (0, 0)) -> None

Composite an RGBA source region onto this image in place.

Parameters:

Name	Type	Description	Default
`im`	`Image`	RGBA source image.	required
`dest`	`tuple[int, int]`	Destination `(x, y)` position.	`(0, 0)`
`source`	`tuple[int, ...]`	Source `(x, y)` origin or `(left, top, right, bottom)` region.	`(0, 0)`

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
image = image.convert("RGBA")
overlay = Image.new("RGBA", (4, 4), (255, 0, 0, 128))
image.alpha_composite(overlay, dest=(2, 2))

putalpha

putalpha(alpha: Image | int) -> None

Replace alpha in place; RGB images become RGBA.

L and P inputs are unsupported because Blanket does not implement LA/PA.

Parameters:

Name	Type	Description	Default
`alpha`	`Image \| int`	L image matching the image size, or a constant alpha value from 0 through 255.	required

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
image.putalpha(128)

split

split() -> tuple[Image, ...]

Return independent L images for each band, in channel order.

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
red, green, blue = image.split()

getbands

getbands() -> tuple[str, ...]

Return channel names in pixel order.

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
bands = image.getbands()

getchannel

getchannel(channel: int | str) -> Image

Return an independent L image for a channel name or index.

Parameters:

Name	Type	Description	Default
`channel`	`int \| str`	Channel name, such as `R`, or zero-based channel index.	required

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
red = image.getchannel("R")

histogram

histogram(mask: Image | None = None, extrema: tuple[float, float] | None = None) -> list[int]

Return 256 bins per band for 8-bit pixels; extrema is ignored.

Parameters:

Name	Type	Description	Default
`mask`	`Image \| None`	Optional mask selecting pixels. Histogram operations require an L mask; compositing also accepts RGBA alpha.	`None`
`extrema`	`tuple[float, float] \| None`	Accepted for Pillow compatibility; ignored.	`None`

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
counts = image.histogram()

getextrema

getextrema() -> tuple[int, int] | tuple[tuple[int, int], ...] | None

Return the minimum and maximum sample value of each band.

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
extrema = image.getextrema()

getbbox

getbbox(*, alpha_only: bool = True) -> tuple[int, int, int, int] | None

Return the nonzero bounding box, using RGBA alpha by default.

Parameters:

Name	Type	Description	Default
`alpha_only`	`bool`	For RGBA images, inspect only alpha when true; otherwise inspect all channels.	`True`

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
box = image.getbbox()

point

point(lut: Sequence[float] | Callable[[int], float], mode: str | None = None) -> Image

Map 8-bit channels through a table or a function evaluated 256 times.

Parameters:

Name	Type	Description	Default
`lut`	`Sequence[float] \| Callable[[int], float]`	256 entries per input channel, or a callable evaluated for each possible 8-bit value.	required
`mode`	`str \| None`	Optional output mode; must match the input mode.	`None`

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
result = image.point(lambda value: 255 - value)

thumbnail

thumbnail(size: tuple[float, float], resample: int = BICUBIC, reducing_gap: float | None = 2.0) -> None

Shrink in place to fit size, preserving aspect ratio without upscaling.

Parameters:

Name	Type	Description	Default
`size`	`tuple[float, float]`	Output `(width, height)` in pixels.	required
`resample`	`int`	Resampling filter from `Image.Resampling`; supported filters depend on the operation.	`BICUBIC`
`reducing_gap`	`float \| None`	Optional pre-reduction optimization threshold; must be at least 1.0.	`2.0`

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
image.thumbnail((4, 4))

reduce

reduce(factor: int | tuple[int, int], box: tuple[int, int, int, int] | None = None) -> Image

Average integer blocks, rounding the output dimensions up.

factor can specify horizontal and vertical factors separately. box selects a nonempty source rectangle within the image.

Parameters:

Name	Type	Description	Default
`factor`	`int \| tuple[int, int]`	Positive integer reduction factor, or separate `(x, y)` factors.	required
`box`	`tuple[int, int, int, int] \| None`	Optional source `(left, top, right, bottom)` rectangle.	`None`

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
result = image.reduce(2)

entropy

entropy(mask: Image | None = None, extrema: tuple[float, float] | None = None) -> float

Return Shannon entropy over all channel histogram bins.

An L mask selects pixels with nonzero values. As in Pillow, extrema is ignored for the supported 8-bit modes.

Parameters:

Name	Type	Description	Default
`mask`	`Image \| None`	Optional mask selecting pixels. Histogram operations require an L mask; compositing also accepts RGBA alpha.	`None`
`extrema`	`tuple[float, float] \| None`	Accepted for Pillow compatibility; ignored.	`None`

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
entropy = image.entropy()

transpose

transpose(method: int) -> Image

Return a flipped or right-angle rotated copy using Transpose.

Parameters:

Name	Type	Description	Default
`method`	`int`	Flip or right-angle rotation from `Image.Transpose`.	required

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
result = image.transpose(Image.Transpose.ROTATE_90)

transform

transform(size: tuple[int, int], method: int | ImageTransformHandler | SupportsGetData, data: Sequence[object] | None = None, resample: int = NEAREST, fill: int = 1, fillcolor: str | int | tuple[int, ...] | None = None) -> Image

Map source pixels to a new canvas using a Transform method.

AFFINE and PERSPECTIVE use inverse mapping coefficients. EXTENT takes a source rectangle. QUAD takes NW, SW, SE, NE source corners; MESH takes (destination rectangle, source quad) pairs in drawing order. Supports NEAREST, BILINEAR and BICUBIC, plus optional fillcolor.

Parameters:

Name	Type	Description	Default
`size`	`tuple[int, int]`	Output `(width, height)` in pixels.	required
`method`	`int \| ImageTransformHandler \| SupportsGetData`	Method from `Image.Transform`, a getdata() object, or an ImageTransformHandler.	required
`data`	`Sequence[object] \| None`	Coefficients, source rectangle, quadrilateral, or mesh for the selected transform.	`None`
`resample`	`int`	Resampling filter from `Image.Resampling`; supported filters depend on the operation.	`NEAREST`
`fill`	`int`	Pillow-compatible fill flag.	`1`
`fillcolor`	`str \| int \| tuple[int, ...] \| None`	Color for pixels outside the source image.	`None`

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
result = image.transform((8, 8), Image.Transform.AFFINE, (1, 0, 1, 0, 1, 0))

crop

crop(box: tuple[float, float, float, float] | None = None) -> Image

Return the rectangular region defined by box.

Coordinates are (left, upper, right, lower). Areas outside the source image are padded with zero-valued pixels, as in Pillow.

Parameters:

Name	Type	Description	Default
`box`	`tuple[float, float, float, float] \| None`	`(left, top, right, bottom)` rectangle, or None to copy the image; outside pixels are zero-filled.	`None`

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
result = image.crop((1, 1, 7, 7))

resize

resize(size: tuple[int, int], resample: int | None = None, box: tuple[float, float, float, float] | None = None, reducing_gap: float | None = None) -> Image

Return a resized copy, using BICUBIC unless a filter is specified.

box selects a source rectangle within the image. reducing_gap optionally enables integer reduction before filtering (at least 1.0).

Parameters:

Name	Type	Description	Default
`size`	`tuple[int, int]`	Output `(width, height)` in pixels.	required
`resample`	`int \| None`	Filter from `Image.Resampling`; None selects BICUBIC, or NEAREST for indexed images.	`None`
`box`	`tuple[float, float, float, float] \| None`	Optional floating-point source rectangle.	`None`
`reducing_gap`	`float \| None`	Optional pre-reduction optimization threshold; must be at least 1.0.	`None`

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
result = image.resize((16, 16), Image.Resampling.LANCZOS)

rotate

rotate(angle: float, resample: int = NEAREST, expand: bool = False, center: tuple[float, float] | None = None, translate: tuple[float, float] | None = None, fillcolor: str | int | tuple[int, ...] | None = None) -> Image

Return a copy rotated counterclockwise by an angle in degrees.

Supports NEAREST (default), BILINEAR, and BICUBIC. The default center is the image midpoint; translate shifts the result after rotation. expand enlarges the canvas assuming the default center and no translation. fillcolor colors pixels outside the source image.

Parameters:

Name	Type	Description	Default
`angle`	`float`	Counterclockwise angle in degrees.	required
`resample`	`int`	NEAREST, BILINEAR, or BICUBIC from `Image.Resampling`.	`NEAREST`
`expand`	`bool`	Expand the output canvas to contain the rotated image.	`False`
`center`	`tuple[float, float] \| None`	Rotation center in pixel coordinates, or None for the image center.	`None`
`translate`	`tuple[float, float] \| None`	Optional `(x, y)` translation after rotation.	`None`
`fillcolor`	`str \| int \| tuple[int, ...] \| None`	Color for pixels outside the source image.	`None`

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
result = image.rotate(30, expand=True)

to_pillow

to_pillow() -> object

Return an equivalent Pillow image for interoperability.

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
pillow_image = image.to_pillow()

save

save(fp: str | bytes | PathLike[str] | PathLike[bytes] | BinaryIO, format: str | None = None, **options: object) -> None

Save as PNG, JPEG, JPEG XL, TIFF, WebP, HEIF, AVIF, BMP, GIF, ICO, or PDF.

Pass a LosslessImageCompressor or LossyImageCompressor to compressor to optimize this save. Omitting it (or passing None) uses the normal encoder settings.

Parameters:

Name	Type	Description	Default
`fp`	`str \| bytes \| PathLike[str] \| PathLike[bytes] \| BinaryIO`	Filename, path-like object, or binary stream.	required
`format`	`str \| None`	Output format name; inferred from the filename when omitted.	`None`
`**options`	`object`	Format-specific encoder options and optional `compressor`; see the formats guide.	`{}`

Examples:

from blanket import Image

image = Image.new("RGB", (8, 8), (40, 100, 180))
from io import BytesIO

output = BytesIO()
image.save(output, format="PNG")

Resampling

Bases: IntEnum

Pillow-compatible resampling filter identifiers.

Transpose

Bases: IntEnum

Pillow-compatible flip and right-angle rotation identifiers.

Transform

Bases: IntEnum

Pillow-compatible geometric transformation identifiers.

Quantize

Bases: IntEnum

Pillow-compatible palette quantization methods.

Dither

Bases: IntEnum

Pillow-compatible dithering identifiers.

ImageTransformHandler

Base class for custom transformation handlers.

transform

transform(size: tuple[int, int], image: Image, resample: int = NEAREST, fill: int = 1) -> Image

Implement this method in a custom handler to return a transformed image.

Parameters:

Name	Type	Description	Default
`size`	`tuple[int, int]`	Output `(width, height)` in pixels.	required
`image`	`Image`	Input image.	required
`resample`	`int`	Resampling filter from `Image.Resampling`; supported filters depend on the operation.	`NEAREST`
`fill`	`int`	Pillow-compatible fill flag.	`1`

Examples:

from blanket import Image


class CopyHandler(Image.ImageTransformHandler):
    def transform(self, size, image, resample=Image.Resampling.NEAREST, fill=1):
        return image.resize(size, resample)


image = Image.new("RGB", (8, 8), "navy")
result = image.transform((16, 16), CopyHandler())

SupportsGetData

Bases: Protocol

Protocol for objects supplying a transformation method and coefficients.

getdata

getdata() -> tuple[int, Sequence[object]]

Return the transformation identifier and its associated data.

Examples:

from blanket import Image


class IdentityTransform:
    def getdata(self):
        return Image.Transform.AFFINE, (1, 0, 0, 0, 1, 0)


image = Image.new("RGB", (8, 8), "navy")
result = image.transform(image.size, IdentityTransform())

Image

Create and open

Inspect and edit pixels

Transform and resize

Compose images

Quantize and use palettes

Save and metadata

Reference

new

open

frombytes

fromarray

merge

blend

composite

alpha_composite

Image

mode property

bit_depth property

size property

width property

height property

format property

info property

is_animated property

has_transparency_data property

load

close

convert

copy

getpixel

getpalette

putpixel

getdata

get_flattened_data

putdata

getcolors

putpalette

quantize

tobytes

filter

paste

alpha_composite

putalpha

split

getbands

getchannel

histogram

getextrema

getbbox

point

thumbnail

reduce

entropy

transpose

transform

crop

resize

rotate

to_pillow

save

Resampling

Transpose

Transform

Quantize

Dither

ImageTransformHandler

transform

SupportsGetData

getdata

mode `property`

bit_depth `property`

size `property`

width `property`

height `property`

format `property`

info `property`

is_animated `property`

has_transparency_data `property`