core

channel_map

class cv_depot.core.channel_map.ChannelMap

Bases: OrderedDict

A channel to channel mapping between multiple source images and one target image.

property source: list[str]

Ordered list of source channels.

Type:

list[str]

property target: list[str]

Ordered list of target channels.

Type:

list[str]

color

class cv_depot.core.color.BasicColor(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

A convenience enum for basic, common color vectors. Legal colors include:

• BLACK

• WHITE

• GREY

• RED

• GREEN

• BLUE

• YELLOW

• MAGENTA

• CYAN

BG = ('#242424', [0.141], [0.141, 0.141, 0.141])

BLACK = ('#000000', [0.0], [0.0, 0.0, 0.0])

BLUE = ('#0000FF', None, [0.0, 0.0, 1.0])

BLUE1 = ('#5F95DE', None, [0.373, 0.584, 0.871])

BLUE2 = ('#93B6E6', None, [0.576, 0.714, 0.902])

CYAN = ('#00FFFF', None, [0.0, 1.0, 1.0])

CYAN1 = ('#7EC4CF', None, [0.494, 0.769, 0.812])

CYAN2 = ('#B6ECF3', None, [0.714, 0.925, 0.953])

DARK1 = ('#040404', [0.016], [0.016, 0.016, 0.016])

DARK2 = ('#141414', [0.078], [0.078, 0.078, 0.078])

DIALOG1 = ('#444459', None, [0.267, 0.267, 0.349])

DIALOG2 = ('#5D5D7A', None, [0.365, 0.365, 0.478])

GREEN = ('#00FF00', None, [0.0, 1.0, 0.0])

GREEN1 = ('#8BD155', None, [0.545, 0.82, 0.333])

GREEN2 = ('#A0D17B', None, [0.627, 0.82, 0.482])

GREY = ('#808080', [0.5], [0.5, 0.5, 0.5])

GREY1 = ('#343434', [0.204], [0.204, 0.204, 0.204])

GREY2 = ('#444444', [0.267], [0.267, 0.267, 0.267])

LIGHT1 = ('#A4A4A4', [0.643], [0.643, 0.643, 0.643])

LIGHT2 = ('#F4F4F4', [0.957], [0.957, 0.957, 0.957])

MAGENTA = ('#FF00FF', None, [1.0, 0.0, 1.0])

ORANGE1 = ('#EB9E58', None, [0.922, 0.62, 0.345])

ORANGE2 = ('#EBB483', None, [0.922, 0.706, 0.514])

PURPLE1 = ('#C98FDE', None, [0.788, 0.561, 0.871])

PURPLE2 = ('#AC92DE', None, [0.675, 0.573, 0.871])

RED = ('#FF0000', None, [1.0, 0.0, 0.0])

RED1 = ('#F77E70', None, [0.969, 0.494, 0.439])

RED2 = ('#DE958E', None, [0.871, 0.584, 0.557])

WHITE = ('#FFFFFF', [1.0], [1.0, 1.0, 1.0])

YELLOW = ('#FFFF00', None, [1.0, 1.0, 0.0])

YELLOW1 = ('#E8EA7E', None, [0.91, 0.918, 0.494])

YELLOW2 = ('#E9EABE', None, [0.914, 0.918, 0.745])

__init__(hexidecimal, one_channel, three_channel)

Parameters:

• hexidecimal (str) – Hexidecimal representation of color.

• one_channel (list[float]) – List with single float.

• three_channel (list[float]) – List with three floats.

Returns:

BasicColor instance.

Return type:

BasicColor

static _get_color(value, attr)

Finds BasicColor instance given a value and an attribute name.

Parameters:

• value (str or BasicColor) – BasicColor value to be looked up.

• attr (str) – Attribute name to be used in lookup.

Raises:

ValueError – If no BasicColor corresponds to given value.

Returns:

BasicColor instance.

Return type:

BasicColor

static from_hexidecimal(value)

Contructs a BasicColor instance from a given hexidecimal string.

Parameters:

value (str) – Hexidecimal value of color.

Returns:

BasicColor instance.

Return type:

BasicColor

static from_list(value)

Contructs a BasicColor instance from a given list of floats or ints.

Parameters:

value (list) – BasicColor as list of numbers.

Returns:

BasicColor instance.

Return type:

BasicColor

static from_list_8_bit(value)

Contructs a BasicColor instance from a given list of ints between 0 and 255.

Parameters:

value (list) – BasicColor as list of numbers.

Returns:

BasicColor instance.

Return type:

BasicColor

static from_string(value)

Contructs a BasicColor instance from a given string.

Parameters:

value (str) – Name of color.

Returns:

BasicColor instance.

Return type:

BasicColor

property hexidecimal: str

Hexidecimal representation of color.

Type:

str

property one_channel: list[float]

One channel, floating point representation of color.

Type:

list[float]

property one_channel_8_bit: list[int]

One channel, 8 bit representation of color.

Type:

list[int]

property string: str

String representation of color.

Type:

string

property three_channel: list[float]

Three channel, floating point representation of color.

Type:

list[float]

property three_channel_8_bit: list[int]

Three channel, 8 bit representation of color.

Type:

list[int]

class cv_depot.core.color.Color(data)

Bases: object

Makes working with color vectors easy.

__init__(data)

Constructs a Color instance.

Parameters:

data (numpy.NDArray) – A 1 dimensional numpy array of shape (n,).

Raises:

• TypeError – If data is not a numpy array.

• AttributeError – If data’s number of dimensions is not 1.

Returns:

Color instance.

Return type:

Color

bit_depth = (<class 'numpy.float32'>, 32, True, <class 'float'>)

static from_array(data, num_channels=None, fill_value=0)

Contructs a Color instance from a given numpy array.

Parameters:

• data (numpy.NDArray) – Numpy array.

• num_channels (int, optional) – Number of desired channels in the Color instance. Number of channels equals len(data) if set to None. Default: None.

• fill_value (float, optional) – Value used to fill additional channels. Default: 0.

Returns:

Color instance of given data.

Return type:

Color

static from_basic_color(data, num_channels=3, fill_value=0.0)

Contructs a Color instance from a BasicColor enum.

Parameters:

• data (BasicColor) – BasicColor enum.

• num_channels (int, optional) – Number of desired channels in the Color instance. Default: 3.

• fill_value (float, optional) – Value used to fill additional channels. Default: 0.

Raises:

• EnforceError – If num_channels is less than 1.

• EnforceError – If no shape is one channel and no one channel equivalent of the given color could be found.

Returns:

Color instance of given data.

Return type:

Color

static from_list(data, num_channels=None, fill_value=0, bit_depth=BitDepth.FLOAT32)

Contructs a Color instance from a given list of ints or floats.

Parameters:

• data (list) – List of ints or floats.

• num_channels (int, optional) – Number of desired channels in the Color instance. Number of channels equals len(data) if set to None. Default: None.

• fill_value (float, optional) – Value used to fill additional channels. Default: 0.

• bit_depth (BitDepth, optional) – Bit depth of given list. Default: BitDepth.FLOAT32.

Returns:

Color instance of given data.

Return type:

Color

property num_channels: int

Number of channels in color vector.

to_array(bit_depth=BitDepth.FLOAT32)

Returns color as a numpy array at a given bit depth.

Parameters:

bit_depth (BitDepth, optional) – Bit depth of output. Default: BitDepth.FLOAT32.

Returns:

Color vector as numpy array.

Return type:

numpy.NDArray

enforce

cv_depot.core.enforce.enforce_homogenous_type(iterable, name='Iterable')

Ensures that iterable only contains only one type of object.

Parameters:

• items (iterable) – Iterable.

• name (str, optional) – First word in error message. Default: Iterable.

Raises:

EnforceError – If iterable contains more than one type of object.

Return type:

None

enum

class cv_depot.core.enum.Anchor(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: EnumBase

Legal anchors.

Includes:

• TOP_LEFT

• TOP_CENTER

• TOP_RIGHT

• CENTER_LEFT

• CENTER_CENTER

• CENTER_RIGHT

• BOTTOM_LEFT

• BOTTOM_CENTER

• BOTTOM_RIGHT

BOTTOM_CENTER = ('bottom', 'center')

BOTTOM_LEFT = ('bottom', 'left')

BOTTOM_RIGHT = ('bottom', 'right')

CENTER_CENTER = ('center', 'center')

CENTER_LEFT = ('center', 'left')

CENTER_RIGHT = ('center', 'right')

TOP_CENTER = ('top', 'center')

TOP_LEFT = ('top', 'left')

TOP_RIGHT = ('top', 'right')

class cv_depot.core.enum.BitDepth(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: EnumBase

Legal bit depths.

Includes:

• FLOAT16

• FLOAT32

• UINT8

• INT8

FLOAT16 = (<class 'numpy.float16'>, 16, True, <class 'float'>)

FLOAT32 = (<class 'numpy.float32'>, 32, True, <class 'float'>)

INT8 = (<class 'numpy.int8'>, 8, True, <class 'int'>)

UINT8 = (<class 'numpy.uint8'>, 8, False, <class 'int'>)

__init__(dtype, bits, signed, type_)

Parameters:

• dtype (numpy.type) – Numpy datatype.

• bits (int) – Number of bits per channel.

• signed (bool) – Whether channel scalars are signed.

• type (type) – Python type of scalar. Options include: [int, float].

Returns:

BitDepth instance.

Return type:

BitDepth

static from_dtype(dtype)

Construct a BitDepth instance from a given numpy datatype.

Parameters:

dtype (numpy.type) – Numpy datatype. Options include: [float16, float32, uint8, int8].

Raises:

TypeError – If invlaid dtype is given.

Returns:

BitDepth instance of given type.

Return type:

BitDepth

class cv_depot.core.enum.Direction(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: EnumBase

Legal directions.

Includes:

• TOP

• BOTTOM

• LEFT

• RIGHT

BOTTOM = 'bottom'

LEFT = 'left'

RIGHT = 'right'

TOP = 'top'

class cv_depot.core.enum.EnumBase(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

classmethod from_string(string)

Constructs an enum instance from a given string.

Parameters:

string (int) – Enum string.

Raises:

• EnforceError – If value given is not a string.

• EnforceError – If no EnumBase type can be found for given string.

Returns:

Enum instance.

Return type:

EnumBase

class cv_depot.core.enum.ImageFormat(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Legal image formats.

Includes:

• EXR

• PNG

• JPEG

• TIFF

EXR = ('exr', [BitDepth.FLOAT16, BitDepth.FLOAT32], ['r', 'g', 'b', 'a', '...'], 1023, True)

JPEG = ('jpeg', [BitDepth.UINT8], ['r', 'g', 'b'], 3, False)

PNG = ('png', [BitDepth.UINT8], ['r', 'g', 'b', 'a'], 4, False)

TIFF = ('tiff', [BitDepth.INT8, BitDepth.UINT8, BitDepth.FLOAT32], ['r', 'g', 'b', 'a', '...'], 500, False)

__init__(extension, bit_depths, channels, max_channels, custom_metadata)

Parameters:

• extension (str) – Name of file extension.

• bit_depths (list[BitDepth]) – Supported bit depths.

• channels (list[str]) – Supported channels.

• max_channels (int) – Maximum number of channels supported.

• custom_metadata (bool) – Custom metadata support.

Returns:

ImageFormat instance.

Return type:

ImageFormat

static from_extension(extension)

Construct an ImageFormat instance for a given file extension.

Parameters:

extension (str) – File extension.

Raises:

TypeError – If extension is illegal.

Returns:

ImageFormat instance of given extension.

Return type:

ImageFormat

class cv_depot.core.enum.VideoCodec(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Legal video codecs.

Includes:

• H264

• H265

H264 = ('h264', 'h264')

H265 = ('h265', 'hevc')

__init__(string, ffmpeg_code)

Parameters:

• string (str) – String representation of codec.

• ffmpeg_code (str) – FFMPEG code.

class cv_depot.core.enum.VideoFormat(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Legal video formats.

Includes:

• MP4

• MPEG

• MOV

• M4V

M4V = ('m4v', [BitDepth.UINT8], ['r', 'g', 'b'], 3, False)

MOV = ('mov', [BitDepth.UINT8], ['r', 'g', 'b'], 3, False)

MP4 = ('mp4', [BitDepth.UINT8], ['r', 'g', 'b'], 3, False)

MPEG = ('mpeg', [BitDepth.UINT8], ['r', 'g', 'b'], 3, False)

__init__(extension, bit_depths, channels, max_channels, custom_metadata)

Parameters:

• extension (str) – Name of file extension.

• bit_depths (list[BitDepth]) – Supported bit depths.

• channels (list[str]) – Supported channels.

• max_channels (int) – Maximum number of channels supported.

• custom_metadata (bool) – Custom metadata support.

Returns:

VideoFormat instance.

Return type:

VideoFormat

static from_extension(extension)

Construct an VideoFormat instance for a given file extension.

Parameters:

extension (str) – File extension.

Raises:

TypeError – If extension is invalid.

Returns:

VideoFormat instance of given extension.

Return type:

VideoFormat

image

class cv_depot.core.image.Image(data, metadata={}, format_=None, allow=False)

Bases: object

Class for reading, writing, converting and displaying properties of images.

__init__(data, metadata={}, format_=None, allow=False)

This constructor should not be called directly except internally and in testing.

Parameters:

• data (numpy.NDArray) – Image.

• metadata (dict, optional) – Image metadata. Default: {}.

• format (ImageFormat, optional) – Format of image. Default: None.

• allow (bool, optional) – Whether to allow construction using init. Default: False.

Raises:

AttributeError – If image data dimensions are not 2 or 3.

Returns:

Image instance.

Return type:

Image

_repr()

Return type:

str

_repr_html_()

Creates a HTML representation of image data.

Return type:

None

_repr_png()

Creates a PNG representation of image data.

Returns:

PNG.

Return type:

str

_string_to_channels(string)

Converts string to list of channels.

Parameters:

string (str) – String representation of channels.

Returns:

List of channels.

Return type:

list

property bit_depth: BitDepth

Bit depth of image.

Type:

BitDepth

property channel_layers: list[str]

List of channel layers.

Type:

list[str]

property channels: list[str | int]

List of channel names.

Type:

list[str or int]

compare(image, content=False, diff_only=False)

Compare this image with a given image.

Parameters:

• image (Image) – Image to compare.

• content (bool, optional) – If True, compare data. Default: False.

• diff_only (bool, optional) – If True, only return the keys with differing values. Default: False.

Raises:

• EnforceError – If image is not an Image instance.

• ValueError – IF content is True and images cannot be compared.

Returns:

A dictionary of comparisons.

Return type:

dict

property data: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Image data.

Type:

numpy.NDArray

property extension: str | None

Image format extension.

Type:

str

static from_array(array)

Construct an Image instance from a given numpy array.

Parameters:

array (numpy.NDArray) – Numpy array.

Returns:

Image instance of given numpy array.

Return type:

Image

static from_pil(image)

Construct an Image instance from a given PIL Image.

Parameters:

image (pil.Image) – PIL Image.

Returns:

Image instance of a given PIL Image.

Return type:

Image

property height: int

Height of image.

Type:

int

property info: dict[str, Any]

A dictionary of all information about the Image instance.

Type:

dict

property max_channels: int | None

Maximum number of channels supported by image format.

Type:

int

property num_channels: int

Number of channels in image.

Type:

int

static read(filepath)

Constructs an Image instance given a full path to an image file.

Parameters:

filepath (str or Path) – Image filepath.

Raises:

• FileNotFoundError – If file could not be found on disk.

• TypeError – If filepath is not a str or Path.

Returns:

Image instance of given file.

Return type:

Image

set_channels(channels)

Set’s channels names.

Parameters:

channels (list[str or int]) – List of channel names:

Raises:

• ValueError – If number of channels given doesn’t not equal data shape.

• ValueError – If duplicate channel names found.

Returns:

self.

Return type:

Image

property shape: Tuple[int, int, int]

(width, height, channels) of image.

Type:

tuple[int]

to_array()

Returns numpy array.

Returns:

Image as numpy array.

Return type:

numpy.NDArray

to_bit_depth(bit_depth)

Convert image to given bit depth. Warning: Numpy’s conversions for INT8 are bizarre.

Parameters:

bit_depth (BitDepth) – Target bit depth.

Raises:

• ValueError – If converting from float to 8-bit and values exceed 1.

• ValueError – If converting from float to 8-bit and values less than 0.

Returns:

New Image instance at given bit depth.

Return type:

Image

to_pil()

Returns pil.Image.

Returns:

Image as pil.Image.

Return type:

pil

to_unit_space()

Normalizes image to [0, 1] range.

Returns:

Normalized image.

Return type:

Image

property width: int

Width of image.

Type:

int

property width_and_height: Tuple[int, int]

(width, height) of image.

Type:

tupe[int]

Image.write(filepath, codec=<ImageCodec.PIZ>

Image.write  string: piz

Image.writeexr_code: 4)

Write image to file.

Parameters:

• filepath (str or Path) – Full path to image file.

• codec (ImageCodec, optional) – EXR compression scheme to be used. Default: ImageCodec.PIZ.

Raises:

• TypeError – If format does not support instance bit depth.

• AttributeError – If format does not support the number of channels in instance.

Return type:

None

cv_depot.core.image._has_super_brights(image)

Determines if given image has values above 1.0

Parameters:

image (Image) – Image instance.

Raises:

EnforceError – If image is not an Image instance.

Returns:

Presence of super brights.

Return type:

bool

cv_depot.core.image._has_super_darks(image)

Determines if given image has values below 0.0

Parameters:

image (Image) – Image instance.

Raises:

EnforceError – If image is not an Image instance.

Returns:

Presence of super darks.

Return type:

bool

tools

cv_depot.core.tools.get_channels_from_array(array)

Returns a list of strings representing the given array’s channels. If array has only one channel then [‘l’] is returned. First 4 channels are [r, g, b, a], in that order. All subsequent channels are integers starting at 4.

Parameters:

array (numpy.NDArray) – Numpy array with 2+ dimensional shape.

Returns:

Channels.

Return type:

list[str and int]

video

cv_depot.core.video.get_video_metadata(filepath)

Retrieve video file metadata with ffmpeg.

Parameters:

filepath (str or Path) – Path to video file.

Raises:

• EnforceError – If filepath is not a file or does not exist.

• EnforceError – If filepath format is unsupported.

Returns:

Metadata.

Return type:

dict

write_video(source, target, framerate=24, codec=<VideoCodec.H264>

write_video  string: h264

write_video  ffmpeg_code: h264, format_=<VideoFormat.MP4>

write_video      extension: mp4

write_video     bit_depths: ['UINT8']

write_video       channels: ['r', 'g', 'b']

write_video   max_channels: 3

write_videocustom_metadata: False)

Writes given input file or file pattern to given target file.

Parameters:

• source (str or Path) – Source image filepath or file pattern.

• target (str or Path) – Target file.

• framerate (int, optional) – Video framerate. Default: 24 fps.

• codec (VideoCodec, optional) – Video codec. Default: VideoCodec.H264.

• format (VideoFormat, optional) – Video container format. Default: VideoFormat.MP4

Raises:

• EnforceError – If source is not a filepath or file pattern.

• EnforceError – framerate is not an integer greater than 0.

• EnforceError – If codec is illegal.

• EnforceError – If format is illegal.

Return type:

None

viewer

class cv_depot.core.viewer.ImageViewer(image, size=81, gamma=1, premultiply=False)

Bases: object

__init__(image, size=81, gamma=1, premultiply=False)

Constructs an ImageViewer widget, used for displaying Image instances.

Parameters:

• image (Image) – Image instance.

• size (int, optional) – Image size in percentage. Default: 81.

• gamma (float, optional) – Initial gamma value. Default: 1.

• premultiply (bool, optional) – Premultiply image by last channel. Default: False.

Raises:

EnforceError – If image is not an Image instance.

_get_channel_options()

Get list of channel options.

Returns:

List of channel options.

Return type:

list

_get_info()

Creates a HTML representation of image info.

Returns:

HTML.

Return type:

str

_get_layer_options()

Get list of channel layers.

Returns:

List of channel layers.

Return type:

list[str]

_get_png()

Creates a PNG representation of image data.

Returns:

PNG.

Return type:

str

_handle_channel_event(event)

Handles channel selector events.

Parameters:

event (dict) – Event.

Return type:

None

_handle_gamma_event(event)

Handles image resize events.

Parameters:

event (dict) – Event.

Return type:

None

_handle_layer_event(event)

Handles layer selector events.

Parameters:

event (dict) – Event.

Return type:

None

_handle_premult_event(event)

Handles premultiply events.

Parameters:

event (dict) – Event.

Return type:

None

_handle_resize_event(event)

Handles image resize events.

Parameters:

event (dict) – Event.

Return type:

None

show()

Call ipython.display with widgets.

Return type:

None