imagecat.data module

Functionality for manipulating images and related data structures.

class imagecat.data.Image(layers=None, metadata=None)[source]

Bases: object

Storage for a multi-layer bitmap image.

An Imagecat Image is composed of zero-to-many layers, which are instances of Layer. Each layer is named, and all layer names must be unique.

Parameters
  • layers (dict, optional) – Dictionary mapping str layer names to Layer instances that contain the data for each layer. If None (the default), creates an empty (no layers) image.

  • metadata (dict, optional) – Arbitrary user-defined metadata for the image. This could be populated by image loaders, modified in operators, and subsets saved by writers. An example of real-world metadata is Cryptomatte information loaded from an EXR file.

See also

Images

For an in-depth discussion of how images are stored in Imagecat.

copy(layers=None, metadata=None)[source]

return a shallow copy of the image, with optional modifications.

Returns a new instance of Image that can be altered without modifying the original. Note that the new image will references the same layers as the original, unless a new set of layers are supplied as an argument.

Parameters

layers (dict, optional) – Dictionary mapping str layer names to Layer instances that contain the data for each layer. Replaces the original layers if not None (the default).

Returns

image – The new image instance with optional modifications.

Return type

Image

property layers

dict containing image layers.

Returns

layers – Dictionary mapping str layer names to Layer instances that contain the data for each layer.

Return type

dict

match_layer_names(patterns)[source]

Return layer names in this image that match the given patterns.

See match_layer_names() for a description of the pattern syntax.

Parameters

patterns (str, required) – Patterns to match against this image’s layer names.

Returns

layers – Layer names in this image that match patterns.

Return type

sequence of str

property metadata

dict containing image metadata.

Returns

metadata – Dictionary containing arbitrary image metadata.

Return type

dict

class imagecat.data.Layer(*, data, role=None)[source]

Bases: object

Storage for one layer in a bitmap image.

An Imagecat Layer contains the data and metadata that describe a single layer in an Imagecat Image. This includes the raw data itself, plus an enumerated role that describes the semantic purpose of the layer.

Parameters
  • data (numpy.ndarray, required) – A three dimensional \(M \times N \times C\) array containing the layer data, organized into \(M\) rows in top-to-bottom order, \(N\) columns in left-to-right order, and \(C\) channels. The array dtype should be numpy.float16 for most data, with numpy.float32 and numpy.int32 reserved for special cases such as depth maps and object id maps, respectively.

  • role (Role, optional) – Semantic purpose of the layer. If None (the default), the role will default to Role.NONE.

See also

Images

For an in-depth discussion of how images are stored in Imagecat.

copy(data=None, role=None)[source]

Return a shallow copy of the layer, with optional modifications.

This method returns a new instance of Layer that can be altered without modifying the original. Note that the new layer still references the same data as the original, unless a new data array is supplied as an argument.

Parameters
  • data (numpy.ndarray, optional) – Replaces the existing data array in the new layer, if not None (the default).

  • role (Role, optional) – Replaces the existing role in the new layer, if not None (the default).

Returns

layer – The new layer instance with modifications.

Return type

Layer

property dtype

Numpy dtype of the underlying data array.

Returns

dtype

Return type

numpy.dtype

property res

Layer resolution in x and y.

Returns

res – The resolution of the layer, ignoring the number of channels.

Return type

(width, height) tuple

property shape

Shape of the underlying data array.

Returns

shape

Return type

(rows, columns, channels) tuple

class imagecat.data.Role(value)[source]

Bases: Enum

Semantic description of how Layer data should be interpreted.

Because Imagecat allows an image to contain an arbitrary number of layers with arbitray names, and a layer can contain one of many different types of data - not just color information - Role is used to indicate how the data in a given layer will be used. The layer role can influence many operations in Imagecat, including visualization and file IO.

See also

Images

For an in-depth discussion of how images are stored in Imagecat.

ALPHA = 8

Layer with one channel of alpha (opacity) information.

BLUE = 7

Layer with one channel of blue color information.

DEPTH = 11

Layer with one channel of depth (distance from viewer) information.

GREEN = 6

Layer with one channel of green color information.

GREENBLUE = 3

Layer with two channels of green-blue color information.

LUMINANCE = 10

Layer with one channel of luminance (intensity) information.

MATTE = 9

Layer with one channel of matte (selection / mask) information.

NONE = 0

General purpose layer with an unknown role and any number of channels.

NORMAL = 16

Layer with three channels of normal vector information.

RED = 5

Layer with one channel of red color information.

REDBLUE = 4

Layer with two channels of red-blue color information.

REDGREEN = 2

Layer with two channels of red-green color information.

RGB = 1

Layer with three channels of red-green-blue color information.

RGBA = 12

Layer with three channels of red-green-blue color and one channel of alpha (opacity) information.

UV = 13

Layer with two channels of texture coordinate information.

VELOCITY = 15

Layer with three channels of velocity information.

XYZ = 14

Layer with three channels of position information.

imagecat.data.channels(role)[source]

Return a set of standard channel names for a given role.

Parameters

role (Role, required) –

Returns

channels

Return type

list of str

imagecat.data.default_font()[source]

Path to a default font file included with Imagecat.

Returns

path – Absolute path to the default Imagecat font.

Return type

str

imagecat.data.depth(role)[source]

Returns the number of channels (depth) for the given role.

Parameters

role (Role, required) –

Returns

depth

Return type

int

imagecat.data.from_array(data, role=None, name=None)[source]

Warning

function ‘imagecat.data.from_array’ undocumented

imagecat.data.match_layer_names(names, patterns)[source]

Match image layer names against a pattern.

Use this function to implement operators that operate on multiple image layers. patterns is a str that can contain multiple whitespace delimited patterns. Patterns can include "*" which matches everything, "?" to match a single character, "[seq]" to match any character in seq, and "[!seq]" to match any character not in seq.

Parameters
  • names (Sequence of str, required) – The image layer names to be matched.

  • pattern (str, required) – Whitespace delimited collection of patterns to match against layer names.

Returns

names

Return type

sequence of str layer names that match patterns.

imagecat.data.to_pil(layer)[source]

Convert a Layer to a PIL.Image.

This is useful for visualization and disk IO.

Parameters

layer (Layer, required) – The layer to be converted

Returns

pil_image – PIL image containing the layer data.

Return type

PIL.Image