limbo.data module

Functionality for working with Limbo Data Format datasets.

class limbo.data.Cryptomatte(sample, synthetic)

Bases: object

Provides access to extra information provided by synthetic samples.

The Cryptomatte has access to high quality masking information created for synthetic samples at render time, and can convert that information into many different representations, including contours and rectangular bounding boxes.

There is no reason to create an instance of this class yourself, callers should obtain instances from the Synthetic.cryptomatte() property.

bbox(instances=None)

Compute a bounding box.

Note that bounding boxes are computed from contour information.

Parameters:

instances (str, list of str, or None, optional) – If None, computes a bounding box that contains every object in the sample. Otherwise, computes a bounding box that contains just the given object instances.

Returns:

bbox – Returns the bounding box using absolute pixel values.

Return type:

(left, top, width, height) tuple

contours(instances=None)

Compute polygon contours.

Note that contours are computed from matte information.

Parameters:

instances (str, list of str, or None, optional) – If None, returns contours for every object in the sample. Otherwise, returns contours that contain just the given object instances.

Returns:

contours – Returns a \(N \times 2\) numpy.ndarray for each contour, containing absolute pixel values.

Return type:

list of numpy.ndarray

property image

Return the Cryptomatte data for this sample.

The Cryptomatte for a sample contains masking information for every instance. All mattes, contours, and bounding boxes are derived from this information.

Returns:

cryptomatte – Imagecat image containing the Cryptomatte data for this sample.

Return type:

imagecat.data.Image

property instances

Return the set of visible object instances for this sample.

Note that an instance label can be any string - any semantics encoded in instance labels are dataset-specific.

Returns:

instances – Unique instance labels for this sample.

Return type:

list of str

materialize_bounds()

Warning

method ‘limbo.data.Cryptomatte.materialize_bounds’ undocumented

matte(instances=None)

Compute matte images.

Note that mattes are computed from Cryptomatte data, and are subpixel accurate: where an object covers a fraction of a pixel’s area, the matte will contain a value between 0 and 1.

Parameters:

instances (str, list of str, or None, optional) – If None, returns a matte containing every object in the sample. Otherwise, returns a matte that contains just the given object instances.

Returns:

matte – Imagecat image containing the given matte.

Return type:

imagecat.data.Image

preview(show_bboxes=False, show_contours=False, instances=None)

Warning

method ‘limbo.data.Cryptomatte.preview’ undocumented

resized_matte(instances, res)

Compute a resized matte image.

Returns:

image – Imagecat image containing the resized matte.

Return type:

imagecat.data.Image or None

segmentation(instances=None)

Compute segmentation images.

A segmentation image contains a distinct color for each visible instance in the image.

Note that segmentation images are only accurate to a single pixel: each pixel can only be one color, and each color represents a single object instance.

Parameters:

instances (str, list of str, or None, optional) – If None, returns a segmentation containing every object in the sample. Otherwise, returns a segmentation that contains just the given object instances.

Returns:

matte – Imagecat image containing the given segmentation.

Return type:

imagecat.data.Image

class limbo.data.Dataset(paths)

Bases: object

Provides access to one-or-more Limbo Data Format datasets.

Use len(dataset) to retrieve the number of samples in the dataset.

Use dataset[index] to retrieve the Sample at the given integer index.

Use for sample in dataset: to iterate over samples.

Parameters:

paths (str or list of str, required) – Paths to one-or-more directories containing data in Limbo Data Format. The resulting dataset object can be used to access the union of the data from the given paths.

property paths

Paths used to initialize the dataset.

Returns:

paths – Absolute paths used to initialize this object.

Return type:

list of str

class limbo.data.Sample(path)

Bases: object

Provides access to one sample within a Limbo Data Format dataset.

Although callers are free to create Sample objects directly, they are typically returned from an instance of Dataset.

Parameters:

path (str, required) – Absolute path to the JSON metadata file for a sample.

property categories

All categories that have been applied to this sample, regardless of annotation type.

Returns:

categories

Return type:

set of str

property default_cryptomatte_path

Warning

property ‘limbo.data.Sample.default_cryptomatte_path’ undocumented

property default_image_path

Warning

property ‘limbo.data.Sample.default_image_path’ undocumented

property default_synthetic_path

Warning

property ‘limbo.data.Sample.default_synthetic_path’ undocumented

delete()

Unconditionally remove this sample and related files.

property graph

Graphcat network used for image processing.

This is used by the rest of the API and should be of little interest to callers.

Returns:

graph

Return type:

graphcat.graph.Graph

property image

Reference image for this sample, if it exists.

Returns:

image

Return type:

imagecat.data.Image or None

property image_path

Filesystem path of the reference image for this sample, if it exists.

Returns:

image

Return type:

str or None

property metadata

Metadata for this sample.

Returns:

metadata

Return type:

dict

property name

Name for this sample.

Returns:

name

Return type:

str

property path

Metadata path for this sample.

Returns:

path – Absolute path to the metadata file for this sample.

Return type:

str

preview(show_bboxes=False, show_contours=False, include=None)

Generate an annotated preview image from the sample.

Note

This method only displays annotations that are stored in the sample metadata; annotations provided by a Cryptomatte object will not be visible, unless they have been materialized using Cryptomatte.materialize_bounds().

Parameters:

• show_bboxes (bool, optional) – If True, the preview will include bounding box annotations.

• show_contours (bool, optional) – If True, the preview will include contour annotations.

• include (callable object, optional) – If specified, the given callable object will be called once per sample annotation. If it returns True, the annotation will be included in the preview.

Returns:

surface – Skia drawing library surface containing the preview that can be converted into a bitmap or other image format.

Return type:

skia.Surface

resized_image(res)

Resized reference image for this sample, if it exists.

Returns:

image

Return type:

imagecat.data.Image or None

property synthetic

Optional synthetic data for this sample.

Samples that are generated synthetically contain information that isn’t present in samples gathered from more traditional sources (like photographs), and the object returned by this property (if any) provides access to that information.

Returns:

synthetic

Return type:

Synthetic or None

update_metadata(updates)

Modify the metadata for this sample.

Parameters:

updates (dict, required) – Metadata information that will be merged with the existing metadata, and saved to disk.

class limbo.data.Synthetic(sample)

Bases: object

Provides access to extra information provided by synthetic samples.

There is no reason to create an instance of this class yourself, callers should obtain instances from the Sample.synthetic() property.

property cryptomatte

Optional cryptomatte data for this sample.

Samples that are generated synthetically typically include masking information that is stored using a cryptomatte, and the object returned by this property (if any) provides access to the cryptomatte data.

Returns:

cryptomatte

Return type:

Cryptomatte or None

property depth

Rendered depth (LIDAR) image for this sample.

Returns:

image

Return type:

imagecat.data.Image

property image

Rendered image for this sample.

Note that the rendered image for the sample is a high-dynamic-range image with floating-point pixel values. Thus, it is higher-quality than the reference image for the sample, which is clipped and stored in PNG format using unsigned bytes.

Returns:

image

Return type:

imagecat.data.Image

materialize_image()

Extract a reference image for this sample.

The reference image is converted from the high quality rendered image, and stored as a PNG with unsigned byte pixel values.

limbo.data.ccw(contour)

Return True if the given contour is counter-clockwise.

Parameters:

contour (sequence of x,y coordinates, required)

Returns:

ccw – True if the contour coordinates are in counter-clockwise order, otherwise False.

Return type:

bool

limbo.data.signed_area(contour)

Return the signed area of a contour.

Parameters:

contour (sequence of x,y coordinates, required)

Returns:

area – Signed area of the given closed contour. Positive if the contour coordinates are in counter-clockwise order, negative otherwise.

Return type:

float