kaiju_images.converter module

class ImageConverter

Bases: AbstractFileConverter

A class for image conversion/processing.

Converter accepts a specific set instructions (see ImageConverter.Settings) of how it will process images. Here is an example of such instruction. You can set multiple parameters including version names, which image acts as a source for each version, version metadata, extensions etc.

{
    'ext': ['jpg', 'jpeg'],
    'filename_mask': 'image[0-9]*',
    'directory_mask': None,
    'meta': {
        'some_meta': True,
    },
    'operations': [
        {'name': 'blur'}
    ],
    'versions': [

        {
            'version': 'original',
            'format': 'png',
            'source': 'unprocessed_original'
        },

        {
            'version': 'resized',
            'format': 'jpeg',
            'source': 'unprocessed_original',
            'operations': [
                {'name': 'resize', 'params': [200, 200]}
            ],
            'meta': {
                'tag': 'some_tag'
            }
        },

        {
            'version': 'scaled',
            'format': 'jpeg',
            'source': 'processed_original',
            'operations': [
                {'name': 'scale', 'params': 0.5},
                {'name': 'flip_vertical'}
            ],
            'save_settings': {
                'quality': 10
            }
        }

    ]
}

Settings object should contain a base settings and version settings. Here is base settings summary:

{
    'ext': ['jpg', 'jpeg'],             # accepted extensions
    'filename_mask': 'image[0-9]*',     # accepted filenames
    'directory_mask': None,             # accpeted dirs
    'meta': {                           # additional user metadata for each version
        'some_meta': True,
    },
    'operations': [         # operations to perform on a base image
                            # this base processed image can be passed to a version by specifying
                            # 'source': 'processed_original' in a version settings
        {'name': 'blur'}
    ],
    "versions": [...]       # a list of versions
}

Here is a short description of parameters accepted by an image version:

{
    'version': 'resized',  # version name used in metadata under 'version' key
    'format': 'jpeg',      # version format (perform an automatic conversion)
    'source': 'unprocessed_original',   # source of a base image for this version
    'operations': [        # sequential list of operations (see `kaiju_image.functions`)
        {'name': 'resize', 'params': [200, 200]}
    ],
    'meta': {              # additional metadata for this particular version
        'tag': 'some_tag'
    },
    'save_settings': {     # optional args for PIL 'save image' command
        'quality': 10
    },
    "output_extension": "xxx"  # you may provide a different output extension for a file if you really want
}

The use of converter itself is pretty straightforward. You can yield versions from ImageConverter.convert method.

for file, metadata in image_converter.convert(test_image_file, **test_meta):
    ...

Each metadata dict looks like this:

{
    'some_meta': True,
    'version': 'scaled',
    'source': 'processed_original',
    'format': 'jpeg',
    'output_extension': None,
    'size': (270, 152)
}

Metadata contains essential information about a version as well as user data. File is a temporary file object where the version is stored.

class Settings

Bases: Settings

Image converter settings object.

class Version

Bases: Serializable

Image version with specific processing.

class Sources

Bases: Enum

Base image sources for different versions.

unprocessed_original = 'unprocessed_original'

processed_original = 'processed_original'

previous_version = 'previous_version'

class Operation

Bases: tuple

Operation(name, params)

name

Alias for field number 0

params

Alias for field number 1

FORMATS = frozenset({'bmp', 'gif', 'jpeg', 'png', 'tiff', 'webp'})

DEFAULT_SOURCE = 'processed_original'

__init__(version, format=None, source=None, operations=None, save_settings=None, meta=None, output_extension=None)

Parameters:

• version (str) – version name (will appear in metadata)

• format (str | None) – image file extension

• source (str | None) – image source (see Sources)

• operations (List[dict] | None) – list of sequential file processing operations (see kaiju.files.images.operations)

• save_settings (dict | None) – specific format saving settings (quality etc.)

• meta (dict | None) – specific file metadata for this version

• output_extension (str | None) – output file extension

version

source

operations

format

save_settings

output_extension

repr()

Must return a representation of object __init__ arguments.

By default it will ignore all underscore elements.

Return type:

dict

property meta: dict

classmethod init_operations(operations)

perform_operations(image)

Parameters:

image (Image) –

Return type:

Image

save(image, path, mode='wb')

Parameters:

image (Image) –

__init__(versions, *args, operations=None, **kws)

Parameters:

• filename_mask – regular expression mask for input filenames, named groups are allowed and will be used for extracting file metadata if needed, None (default) for no specific mask

• directory_mask – same as filename mask but for parent dir

• ext – list of allowed file extensions, only alphanumeric chars allowed, None (default) for no specific extensions

• meta – specific metadata added to converted files

• output_extension – output file extension

• versions (List[dict]) –

• operations (List[dict] | None) –

ext

operations

versions

repr()

Must return a representation of object __init__ arguments.

By default it will ignore all underscore elements.

Return type:

dict

classmethod spec()

Return type:

Object

classmethod init_operations(operations)

perform_operations(image)

Parameters:

image (Image) –

Return type:

Image

filename_mask

directory_mask

meta

output_extension

READ_MODE = 'rb'

WRITE_MODE = 'wb'

MAX_PROCESSING_TIME = 60