RLEMask#

class rlemasklib.RLEMask(obj, *, shape=None)[source]#

Run-length encoded mask.

The RLEMask class represents a binary mask using run-length encoding. The mask can be created from a dense array, a bounding box, a polygon, or a circle, or from run-length counts. The mask can be manipulated using set operations like union, intersection, and difference, and can be converted to a dense array. Morphological operations, warping, transpose, flipping, cropping, padding, connected components, and other operations are also supported.

The main constructor can take a dense array, a dictionary, or a list of run-length counts.

It is recommended to use the static factory methods from_array(), from_dict(), from_counts(), from_bbox(), from_polygon(), zeros(), and ones() to create new RLEMask objects, as they are more explicit.

Parameters:

  • obj – the input object to create the mask from. It can be a dense 2D array, a dictionary, or a list/1D-array of run-length counts.

  • shape (Optional[Sequence[int]]) – [height, width] of the mask, in case the input is a list of run-length counts.

Raises:

  • ValueError – if the input is not a dense 2D array, a dictionary, or a sequence of run-length counts.

  • ValueError – if the sum of the counts is not equal to height * width when counts are given.

  • ValueError – if the shape is not provided when counts are given.

Properties#

shape

The shape of the mask (height, width).

counts

The run-length counts of the mask, as a copy of the underlying data.

counts_view

The run-length counts of the mask, as a direct view of the underlying memory.

density

The ratio of the number of runlengths vs number of pixels of the entire mask

T

The transpose of the mask (i.e., columns become rows and vice versa)

Instance Methods#

area()

The area of the mask (number of foreground pixels).

perimeter()

The number of pixels along the contour of the mask.

is_valid_rle()

Check if the RLE mask is valid (no nonfirst zero runs and runs summing to H*W).

count_nonzero()

The number of nonzero pixels in the mask, equivalent to area().

nonzero()

The indices of the nonzero elements in the mask as a 2D numpy array.

__getitem__(key)

Crop the RLE mask to get a submask, by slicing, or retrieve a single pixel value.

__setitem__(key, value)

Set the value of a submask to either a constant or another RLE or dense mask.

__invert__()

Compute the complement of an RLE mask.

__or__(other)

Compute the union of two RLE masks.

__ior__(other)

Compute the union with another RLEMask in place.

__and__(other)

Compute the intersection of two RLEMasks.

__iand__(other)

Compute the intersection with another RLEMask in place.

__xor__(other)

Compute the symmetric difference of two RLEMasks.

__ixor__(other)

Compute the symmetric difference with another RLEMasks in place.

__sub__(other)

Compute the difference of two RLEMasks.

__isub__(other)

Compute the difference with another RLEMask in place.

__eq__(other)

Check if two RLEMasks are equal (same runlengths and shape).

__repr__()

A string representation of the RLEMask, containing the shape and the runlengths.

__array__([dtype, copy])

Convert the RLEMask to a dense numpy array, used by numpy functions.

any()

Check if any pixel in the mask is foreground.

all()

Check if all pixels in the mask are foreground.

dilate_vertical([up, down, inplace])

Dilate the mask vertically.

max_pool2x2([inplace])

Max-pool the mask by a factor of 2.

min_pool2x2([inplace])

Min-pool the mask by a factor of 2.

avg_pool2x2()

Average-pool the mask by a factor of 2.

avg_pool2d_valid(kernel_size[, stride, threshold])

Perform a 2D average pooling with the given kernel size and threshold the result.

conv2d_valid(kernel[, stride, threshold])

Perform a 2D convolution with the given weighted kernel and threshold the result.

resize(output_imshape[, fx, fy])

Resize the mask to a new shape.

warp_affine(M, output_imshape)

Apply an affine warping transformation to the mask.

warp_perspective(H, output_imshape)

Apply a perspective warping (homography) transformation to the mask.

warp_distorted(R1, R2, K1, K2, d1, d2, polar_ud1, ...)

[Experimental] Warp the mask according to changing lens-distorted camera parameters

pad(top, bottom, left, right[, border_type, value, ...])

Pad the mask with constant values.

complement([inplace])

Compute the complement of an RLE mask.

shift(offset[, border_value, inplace])

Shift (translate) the mask by an offset vector.

dilate([kernel_shape, kernel_size, inplace])

Dilate a mask with a kernel of a given shape and size.

erode([kernel_shape, kernel_size, inplace])

Erode a mask with a kernel of a given shape and size.

dilate3x3([connectivity, inplace])

Dilate a mask with a 3x3 kernel.

erode3x3([connectivity, inplace])

Erode a mask with a 3x3 kernel.

dilate5x5([inplace])

Dilate a mask with a round 5x5 kernel.

erode5x5([inplace])

Erode a mask with a round 5x5 kernel.

contours()

An RLE consisting of those foreground pixels that have at least one background neighbor.

largest_interior_rectangle([aspect_ratio])

The largest axis-aligned rectangle that fits entirely inside the foreground.

largest_interior_rectangle_around(center_point[, ...])

The largest axis-aligned foreground rectangle with a given center point.

merge(other, func)

Merge this mask with another using a Boolean function.

repeat(num_h, num_w[, inplace])

Repeat the mask pixels multiple times along the axes.

centroid()

The centroid of the mask, as a numpy float32 array [x, y].

moments()

Compute image moments, same as cv2.moments.

hu_moments()

Compute the 7 Hu moment invariants [1].

connected_components([connectivity, min_size, filter_fn])

Extract connected components from the mask.

connected_component_stats([connectivity, min_size])

Get statistics for all connected components without extracting them.

count_connected_components([connectivity, min_size])

Count connected components without extracting them.

connected_components_with_stats([connectivity, ...])

Extract connected components and their stats in a single pass.

largest_connected_component([connectivity, inplace])

Extract the largest connected component of the mask.

remove_small_components([min_size, connectivity, inplace])

Remove small connected components from the mask.

fill_small_holes([min_size, connectivity, inplace])

Fill small holes (i.e., connected components of the background) in the mask.

bbox()

The bounding box of the foreground, i.e. the smallest rectangle that contains the mask.

crop(bbox[, inplace])

Crop the mask to the bounding box.

tight_crop([inplace])

Crop the mask to the bounding box of the foreground.

transpose()

Transpose the mask, i.e. swap the axes such that columns become rows and vice versa.

rot90([k, inplace])

Rotate the mask by a multiple of 90 degrees.

flip(axis)

Flip the mask along an axis.

flipud()

Flip the mask vertically (upside down).

fliplr()

Flip the mask horizontally (left-right).

tile(num_h, num_w)

Tile the mask multiple times along the axes, analogous to np.tile.

copy()

Clone the mask.

fill_rectangle(rect[, value, inplace])

Fill a rectangle in the mask.

fill_circle(center, radius[, value, inplace])

Fill a circle in the mask.

to_dict([zlevel])

Convert the RLE mask to a dictionary.

to_array([fg_value, bg_value, dtype, order, value])

Convert the RLE mask to a dense numpy array.

decode_into(arr[, fg_value, bg_value, value])

Decode the RLE mask into an existing array.

__reduce__()

Support for pickle serialization.

iou(other)

Compute the intersection-over-union (IoU) between two masks.

Static Methods#

from_counts(counts, shape[, order, validate_sum])

Create an RLEMask object from run-length counts.

from_array(mask_array[, threshold, is_sparse, thresh128])

Create an RLEMask object from a dense mask.

from_dict(d)

Create an RLEMask object from an RLE dictionary.

from_bbox(bbox[, imshape, imsize])

Create an RLEMask object from a bounding box.

from_circle(center, radius[, imshape, imsize])

Create an RLEMask object representing a filled circle.

from_png([path, data, threshold])

Create an RLEMask from an 8-bit grayscale PNG.

from_polygon(poly[, imshape, imsize])

Create an RLEMask object from a polygon.

zeros(shape)

Create a new RLE mask of zeros.

ones(shape)

Create a new RLE mask of ones.

ones_like(mask)

Create a new RLE mask of ones with the same shape as another mask.

zeros_like(mask)

Create a new RLE mask of zeros with the same shape as another mask.

merge_count(masks, threshold)

Return a mask where each pixel is set if and only if at least threshold of the

intersection(masks)

Return a mask where each pixel is set if and only if all input masks have the pixel set.

union(masks)

Return a mask where each pixel is set if at least one of the input masks has the pixel set.

merge_many(masks, func)

Merge many masks using either the same or different Boolean functions.

merge_many_custom(masks, func)

Merge many masks using a custom n-ary boolean function.

make_merge_function(func[, arity])

Create a merge function from a custom n-ary boolean function.

merge_to_label_map(rles)

Merge a list of RLE masks to a label map indicating which masks contains each pixel.

from_label_map(label_map)

Convert a label map to a dict of RLEMasks.

from_label_map_png([path, data])

Convert a PNG label map directly to a dict of RLEMasks.

concatenate(masks[, axis])

Concatenate masks along an axis.

hconcat(masks)

Horizontally concatenate masks.

vconcat(masks)

Vertically concatenate masks.

iou_matrix(masks1, masks2)

Compute the intersection-over-union (IoU) between two sets of masks.

References