module pixeltable.functions.image

Pixeltable UDFs for ImageType. Example:

import pixeltable as pxt

t = pxt.get_table(...)
t.select(t.img_col.convert('L')).collect()

iterator tile_iterator()

Signature

@pxt.iterator
tile_iterator(
    image: pxt.Image,
    tile_size: pxt.Json[(Int, Int)],
    *,
    overlap: pxt.Json[(Int, Int)] = (0, 0)
)

Iterator over tiles of an image. Each image will be divided into tiles of size tile_size, and the tiles will be iterated over in row-major order (left-to-right, then top-to-bottom). An optional overlap parameter may be specified. If the tiles do not exactly cover the image, then the rightmost and bottommost tiles will be padded with blackspace, so that the output images all have the exact size tile_size. Outputs: One row per tile, with the following columns:

tile (pxt.Image): The image tile
tile_coord (pxt.Json): The (x, y) coordinates of the tile in the grid of tiles
tile_box (pxt.Json): The (x1, y1, x2, y2) pixel coordinates of the tile in the original image

Parameters:

image (pxt.Image): Image to split into tiles.
tile_size (pxt.Json[(Int): Size of each tile, as a pair of integers (width, height).
overlap (Any): Amount of overlap between adjacent tiles, as a pair of integers (width, height).

Examples: This example assumes an existing table tbl with a column img of type pxt.Image. Create a view that splits all images into 256x256 tiles with 32 pixels of overlap:

pxt.create_view(
    'image_tiles',
    tbl,
    iterator=tile_iterator(
        tbl.img, tile_size=(256, 256), overlap=(32, 32)
    ),
)

uda stitch_tiles()

Signature

@pxt.uda
stitch_tiles(*args, **kwargs) -> pxt.Image | None

Reconstructs a single image from the tiles produced by tile_iterator, pasting each tile back at its original position. This is the inverse of tile_iterator: aggregate the tiles of an image (grouped by a column that identifies the source image) to obtain the full image, optionally after transforming each tile first (e.g., drawing a segmentation overlay on it). The reconstruction is naive: tiles are pasted in the order they arrive, so where tiles overlap, later tiles overwrite earlier ones. It composites pixels and does not merge or deduplicate detections across tile seams. Args: tile: The image tile to paste, the same size as the tiles emitted by tile_iterator. All tiles in a group must have the same mode (and palette, for palette images). tile_box: The (x1, y1, x2, y2) pixel coordinates of the tile in the original image, as emitted by tile_iterator. width: The width of the original image, in pixels. height: The height of the original image, in pixels. Returns: The reconstructed image, of size (width, height) and in the mode of the tiles, or None if there are no non-null tiles. Examples: Split each image into tiles, draw a segmentation overlay on every tile, then stitch the overlaid tiles back into a single full-resolution image, one per source image. Assumes a view tiles created with tile_iterator, with an overlay column computed per tile:

tiles.group_by(tiles.image).select(
    stitched=stitch_tiles(
        tiles.pos,
        tiles.overlay,
        tiles.tile_box,
        tiles.image.width,
        tiles.image.height,
    )
).collect()

udf alpha_composite()

Signature

@pxt.udf
alpha_composite(im1: pxt.Image, im2: pxt.Image) -> pxt.Image

Alpha composite im2 over im1. Equivalent to PIL.Image.alpha_composite()

udf b64_encode()

Signature

@pxt.udf
b64_encode(
    img: pxt.Image,
    image_format: pxt.String = 'png'
) -> pxt.String

Convert image to a base64-encoded string. Parameters:

img (pxt.Image): image
image_format (pxt.String): image format supported by PIL

udf blend()

Signature

@pxt.udf
blend(
    im1: pxt.Image,
    im2: pxt.Image,
    alpha: pxt.Float
) -> pxt.Image

Return a new image by interpolating between two input images, using a constant alpha. Equivalent to PIL.Image.blend()

udf composite()

Signature

@pxt.udf
composite(
    image1: pxt.Image,
    image2: pxt.Image,
    mask: pxt.Image
) -> pxt.Image

Return a composite image by blending two images using a mask. Equivalent to PIL.Image.composite()

udf convert()

Signature

@pxt.udf
convert(self: pxt.Image, mode: pxt.String) -> pxt.Image

Convert the image to a different mode. Equivalent to PIL.Image.Image.convert(). Parameters:

mode (pxt.String): The mode to convert to. See the Pillow documentation for a list of supported modes.

udf crop()

Signature

@pxt.udf
crop(
    self: pxt.Image,
    box: pxt.Json[(Int, Int, Int, Int)]
) -> pxt.Image

Return a rectangular region from the image. The box is a 4-tuple defining the left, upper, right, and lower pixel coordinates. Equivalent to PIL.Image.Image.crop()

udf effect_spread()

Signature

@pxt.udf
effect_spread(self: pxt.Image, distance: pxt.Int) -> pxt.Image

Randomly spread pixels in an image. Equivalent to PIL.Image.Image.effect_spread() Parameters:

distance (pxt.Int): The distance to spread pixels.

udf entropy()

Signature

@pxt.udf
entropy(
    self: pxt.Image,
    mask: pxt.Image | None = None,
    extrema: pxt.Json[(Json, ...)] | None = None
) -> pxt.Float

Returns the entropy of the image, optionally using a mask and extrema. Equivalent to PIL.Image.Image.entropy() Parameters:

mask (pxt.Image | None): An optional mask image.
extrema (pxt.Json[(Json): An optional list of extrema.

udf get_metadata()

Signature

@pxt.udf
get_metadata(self: pxt.Image) -> ImageMetadata

Return metadata for the image.

udf getbands()

Signature

@pxt.udf
getbands(self: pxt.Image) -> pxt.Json[(String, ...)]

Return a tuple containing the names of the image bands. Equivalent to PIL.Image.Image.getbands()

udf getbbox()

Signature

@pxt.udf
getbbox(
    self: pxt.Image,
    *,
    alpha_only: pxt.Bool = True
) -> pxt.Json[(Int, Int, Int, Int)] | None

Return a bounding box for the non-zero regions of the image. Equivalent to PIL.Image.Image.getbbox() Parameters:

alpha_only (pxt.Bool): If True, and the image has an alpha channel, trim transparent pixels. Otherwise, trim pixels when all channels are zero.

udf getchannel()

Signature

@pxt.udf
getchannel(self: pxt.Image, channel: pxt.Int) -> pxt.Image

Return an L-mode image containing a single channel of the original image. Equivalent to PIL.Image.Image.getchannel() Parameters:

channel (pxt.Int): The channel to extract. This is a 0-based index.

udf getcolors()

Signature

@pxt.udf
getcolors(
    self: pxt.Image,
    maxcolors: pxt.Int = 256
) -> pxt.Json[(Json[(Int, Int)], ...)]

Return a list of colors used in the image, up to a maximum of maxcolors. Equivalent to PIL.Image.Image.getcolors() Parameters:

maxcolors (pxt.Int): The maximum number of colors to return.

udf getextrema()

Signature

@pxt.udf
getextrema(self: pxt.Image) -> pxt.Json[(Int, Int)]

Return a 2-tuple containing the minimum and maximum pixel values of the image. Equivalent to PIL.Image.Image.getextrema()

udf getpalette()

Signature

@pxt.udf
getpalette(
    self: pxt.Image,
    mode: pxt.String | None = None
) -> pxt.Json[(Int, ...)] | None

Return the palette of the image, optionally converting it to a different mode. Equivalent to PIL.Image.Image.getpalette() Parameters:

mode (pxt.String | None): The mode to convert the palette to.

udf getpixel()

Signature

@pxt.udf
getpixel(
    self: pxt.Image,
    xy: pxt.Json[(Json, ...)]
) -> pxt.Json[(Int,)]

Return the pixel value at the given position. The position xy is a tuple containing the x and y coordinates. Equivalent to PIL.Image.Image.getpixel() Parameters:

xy (pxt.Json[(Json): The coordinates, given as (x, y).

udf getprojection()

Signature

@pxt.udf
getprojection(self: pxt.Image) -> pxt.Json[(Json[(Int, ...)], Json[(Int, ...)])]

Return two sequences representing the horizontal and vertical projection of the image. Equivalent to PIL.Image.Image.getprojection()

udf height()

Signature

@pxt.udf
height(self: pxt.Image) -> pxt.Int

Return the height of the image.

udf histogram()

Signature

@pxt.udf
histogram(
    self: pxt.Image,
    mask: pxt.Image | None = None,
    extrema: pxt.Json[(Json, ...)] | None = None
) -> pxt.Json[(Int, ...)]

Return a histogram for the image. Equivalent to PIL.Image.Image.histogram() Parameters:

mask (pxt.Image | None): An optional mask image.
extrema (pxt.Json[(Json): An optional list of extrema.

udf mode()

Signature

@pxt.udf
mode(self: pxt.Image) -> pxt.String

Return the image mode.

udf point()

Signature

@pxt.udf
point(
    self: pxt.Image,
    lut: pxt.Json[(Int, ...)],
    mode: pxt.String | None = None
) -> pxt.Image

Map image pixels through a lookup table. Equivalent to PIL.Image.Image.point() Parameters:

lut (pxt.Json[(Int): A lookup table.

udf quantize()

Signature

@pxt.udf
quantize(
    self: pxt.Image,
    colors: pxt.Int = 256,
    method: pxt.Int | None = None,
    kmeans: pxt.Int = 0,
    palette: pxt.Image | None = None,
    dither: pxt.Int = <Dither.FLOYDSTEINBERG: 3>
) -> pxt.Image

Convert the image to ‘P’ mode with the specified number of colors. Equivalent to PIL.Image.Image.quantize() Parameters:

colors (pxt.Int): The number of colors to quantize to.
method (pxt.Int | None): The quantization method. See the Pillow documentation for a list of supported methods.
kmeans (pxt.Int): The number of k-means clusters to use.
palette (pxt.Image | None): The palette to use.
dither (pxt.Int): The dithering method. See the Pillow documentation for a list of supported methods.

udf reduce()

Signature

@pxt.udf
reduce(
    self: pxt.Image,
    factor: pxt.Int,
    box: pxt.Json[(Int, Int, Int, Int)] | None = None
) -> pxt.Image

Reduce the image by the given factor. Equivalent to PIL.Image.Image.reduce() Parameters:

factor (pxt.Int): The reduction factor.
box (pxt.Json[(Int): An optional 4-tuple of ints providing the source image region to be reduced. The values must be within (0, 0, width, height) rectangle. If omitted or None, the entire source is used.

udf resize()

Signature

@pxt.udf
resize(self: pxt.Image, size: pxt.Json[(Int, Int)]) -> pxt.Image

Return a resized copy of the image. The size parameter is a tuple containing the width and height of the new image. Equivalent to PIL.Image.Image.resize()

udf rotate()

Signature

@pxt.udf
rotate(self: pxt.Image, angle: pxt.Int) -> pxt.Image

Return a copy of the image rotated by the given angle. Equivalent to PIL.Image.Image.rotate() Parameters:

angle (pxt.Int): The angle to rotate the image, in degrees. Positive angles are counter-clockwise.

udf thumbnail()

Signature

@pxt.udf
thumbnail(
    self: pxt.Image,
    size: pxt.Json[(Int, Int)],
    resample: pxt.Int = <Resampling.LANCZOS: 1>,
    reducing_gap: pxt.Float | None = 2.0
) -> pxt.Image

Create a thumbnail of the image. Equivalent to PIL.Image.Image.thumbnail() Parameters:

size (pxt.Json[(Int): The size of the thumbnail, as a tuple of (width, height).
resample (Any): The resampling filter to use. See the Pillow documentation for a list of supported filters.
reducing_gap (Any): The reducing gap to use.

udf to_video()

Signature

@pxt.udf
to_video(
    image: pxt.Image,
    *,
    duration: pxt.Float,
    fps: pxt.Int = 24,
    video_encoder: pxt.String | None = None,
    video_encoder_args: pxt.Json | None = None
) -> pxt.Video

Convert a still image into a video of a specified duration with ffmpeg’s -loop option. Requirements:

ffmpeg needs to be installed and in PATH

Parameters:

image (pxt.Image): Input image to convert to video.
duration (pxt.Float): Duration of the output video in seconds.
fps (pxt.Int): Frames per second for the output video.
video_encoder (pxt.String | None): Video encoder to use. If not specified, uses the default encoder.
video_encoder_args (pxt.Json | None): Additional arguments to pass to the video encoder.

Returns:

pxt.Video: A video displaying the input image for the specified duration.

Examples: Create a 5-second video from an image:

tbl.select(tbl.image.to_video(duration=5.0)).collect()

Create a 10-second video at 30 fps from a rotated image:

tbl.select(
    tbl.image.rotate(180).to_video(duration=10.0, fps=30)
).collect()

udf transpose()

Signature

@pxt.udf
transpose(self: pxt.Image, method: pxt.Int) -> pxt.Image

Transpose the image. Equivalent to PIL.Image.Image.transpose() Parameters:

method (pxt.Int): The transpose method. See the Pillow documentation for a list of supported methods.

udf width()

Signature

@pxt.udf
width(self: pxt.Image) -> pxt.Int

Return the width of the image.

​module pixeltable.functions.image

​iterator tile_iterator()

​uda stitch_tiles()

​udf alpha_composite()

​udf b64_encode()

​udf blend()

​udf composite()

​udf convert()

​udf crop()

​udf effect_spread()

​udf entropy()

​udf get_metadata()

​udf getbands()

​udf getbbox()

​udf getchannel()

​udf getcolors()

​udf getextrema()

​udf getpalette()

​udf getpixel()

​udf getprojection()

​udf height()

​udf histogram()

​udf mode()

​udf point()

​udf quantize()

​udf reduce()

​udf resize()

​udf rotate()

​udf thumbnail()

​udf to_video()

​udf transpose()

​udf width()

module pixeltable.functions.image

iterator tile_iterator()

uda stitch_tiles()

udf alpha_composite()

udf b64_encode()

udf blend()

udf composite()

udf convert()

udf crop()

udf effect_spread()

udf entropy()

udf get_metadata()

udf getbands()

udf getbbox()

udf getchannel()

udf getcolors()

udf getextrema()

udf getpalette()

udf getpixel()

udf getprojection()

udf height()

udf histogram()

udf mode()

udf point()

udf quantize()

udf reduce()

udf resize()

udf rotate()

udf thumbnail()

udf to_video()

udf transpose()

udf width()