API Reference

DerivativeFilesGenerator

class image_processing.derivative_files_generator.DerivativeFilesGenerator(kakadu_base_path='', jpg_high_quality_value=92, jpg_thumbnail_resize_value=0.6, kakadu_compress_options=['Clevels=6', 'Clayers=6', 'Cprecincts={256,256},{256,256},{128,128}', 'Stiles={512,512}', 'Corder=RPCL', 'ORGgen_plt=yes', 'ORGtparts=R', 'Cblk={64,64}', 'Cuse_sop=yes', 'Cuse_eph=yes', '-flush_period', '1024', 'Creversible=yes', '-rate', '-'], use_default_filenames=True, require_icc_profile_for_greyscale=False, require_icc_profile_for_colour=True, exiftool_path='exiftool')

Given a source image file, generates the derivative files (preservation/display image formats, extracted technical metadata etc.) we store in our repository

__init__(kakadu_base_path='', jpg_high_quality_value=92, jpg_thumbnail_resize_value=0.6, kakadu_compress_options=['Clevels=6', 'Clayers=6', 'Cprecincts={256,256},{256,256},{128,128}', 'Stiles={512,512}', 'Corder=RPCL', 'ORGgen_plt=yes', 'ORGtparts=R', 'Cblk={64,64}', 'Cuse_sop=yes', 'Cuse_eph=yes', '-flush_period', '1024', 'Creversible=yes', '-rate', '-'], use_default_filenames=True, require_icc_profile_for_greyscale=False, require_icc_profile_for_colour=True, exiftool_path='exiftool')
Parameters

  • kakadu_base_path – the location of the kdu_compress and kdu_expand executables

  • jpg_high_quality_value – between 0 and 95

  • jpg_thumbnail_resize_value – between 0 and 1

  • kakadu_compress_options – options for kdu_compress to create a lossless jp2 file

  • use_default_filenames – use the filenames specified in this module instead of using the original filename

  • require_icc_profile_for_greyscale – raise an error if a greyscale image doesn’t have an ICC profile. Note: bitonal images do not need ICC profiles even if this is true

  • require_icc_profile_for_colour – raise an error if a colour image does not have an ICC profile

  • exiftool_path – path to the exiftool executable

check_conversion_was_lossless(source_file, lossless_jpg_2000_file)

Visually compare the source file to the TIFF generated by expanding the lossless JPEG2000, and raise a ValidationError if they do not match. Does not check technical metadata beyond colour profile and mode.

Parameters

  • source_file – Must be TIFF - cannot convert losslessly from JPEG to TIFF

  • lossless_jpg_2000_file – The JPEG2000 file to compare.

generate_derivatives_from_jpg(jpg_filepath, output_folder, save_embedded_metadata=True, check_lossless=True, save_jpylyzer_output=False)

Extracts the embedded metadata, creates a copy of the JPEG file and a validated JPEG2000 file. Stores all in the given folder.

Parameters

  • jpg_filepath – The path to the source JPEG file.

  • output_folder – The folder where the derivatives will be stored

  • save_embedded_metadata – If true, metadata will be extracted from the image file and preserved in a separate xml file

  • save_jpylyzer_output – If true, the jyplyzer output from validating the jp2 will be preserved in a separate xml file

  • check_lossless – If true, check the created JPEG2000 file is visually identical to the TIFF created from the source file

Returns

filepaths of created files

generate_derivatives_from_tiff(tiff_filepath, output_folder, include_tiff=False, save_embedded_metadata=True, create_jpg_as_thumbnail=True, check_lossless=True, save_jpylyzer_output=False)

Extracts the embedded metadata, creates a JPEG file and a validated JPEG2000 file. Stores all in the given folder.

Parameters

  • create_jpg_as_thumbnail – create the JPG as a resized thumbnail, not a high quality image. Parameters for resize and quality are set on a class level

  • tiff_filepath –

  • output_folder – the folder where the related dc.xml will be stored

  • include_tiff – Include copy of source tiff file in derivatives

  • save_embedded_metadata – If true, metadata will be extracted from the image file and preserved in a separate xml file

  • save_jpylyzer_output – If true, the jyplyzer output from validating the jp2 will be preserved in a separate xml file

  • check_lossless – If true, check the created jpg2000 file is visually identical to the source file

Returns

filepaths of created files

generate_jp2_from_tiff(tiff_file, jp2_filepath)

Creates lossless JPEG2000 at jp2_filepath

Parameters

  • tiff_file – The source TIFF file.

  • jp2_filepath – The output filepath

validate_jp2_conversion(tiff_file, jp2_filepath, check_lossless=True, jpylyzer_output_filepath=None)

Validate the jp2 file using jpylyzer, and check that the conversion from tif to jp2 was lossless Raises a ValidationError if either check fails.

Parameters

  • tiff_file –

  • jp2_filepath –

  • check_lossless – if false, don’t check the conversion from tif to jp2 was lossless

  • jpylyzer_output_filepath – write the jpylyzer xml output to this file if given

Validation

image_processing.validation.check_colour_profiles_match(source_filepath, converted_filepath)

Check the ICC profile and colour mode match. Allows greyscale and bitonal images to match, as that is how kakadu expands JP2s which were originally bitonal. Raises ValidationError if they do not match.

Parameters

  • source_filepath –

  • converted_filepath –

image_processing.validation.check_image_suitable_for_jp2_conversion(image_filepath, require_icc_profile_for_greyscale=False, require_icc_profile_for_colour=True)

Check over the image and checks if it is in a supported and tested format for conversion to jp2. Raises ValidationError if it is not

Parameters

  • image_filepath –

  • require_icc_profile_for_greyscale – raise an error if a greyscale image doesn’t have an icc profile. Note: bitonal images don’t need icc profiles even if this is true

  • require_icc_profile_for_colour – raise an error if a colour image doesn’t have an icc profile

image_processing.validation.check_visually_identical(source_filepath, converted_filepath, source_pixel_checksum=None)

Visually compare the files (i.e. that the pixel values are identical). Raises a ValidationError if they don’t match.

Note

Does not check technical metadata beyond colour profile and mode.

Parameters

  • source_filepath –

  • converted_filepath –

  • source_pixel_checksum – if not None, uses this to compare against instead of reading out the source pixels again. Should be one generated using generate_pixel_checksum

image_processing.validation.generate_pixel_checksum(image_filepath)

Generate a format-independent checksum based on the image’s pixel values.

Parameters

image_filepath –

image_processing.validation.generate_pixel_checksum_from_pil_image(pil_image)

Generate a format-independent checksum based on this image’s pixel values

Parameters

pil_image – PIL.Image instance

image_processing.validation.validate_jp2(image_file, output_file=None)

Uses jpylyzer (jpylyzer.jpylzer.checkOneFile()) to validate the jp2 file. Raises a ValidationError if it is invalid

Parameters

  • image_file (str) –

  • output_file – if not None, write the jpylyzer xml output to this file

Conversion

class image_processing.conversion.Converter(exiftool_path='exiftool')

Convert TIFF to and from JPEG while preserving technical metadata and ICC profiles

convert_icc_profile(image_filepath, output_filepath, icc_profile_filepath, new_colour_mode=None)

Convert the image to a new icc profile. This is lossy, so should only be done when necessary (e.g. if jp2 doesn’t support the colour profile) Doesn’t support 16bit images due to limitations of Pillow

Uses the perceptual rendering intent, as it’s the recommended one for general photographic purposes, and loses less information on out-of-gamut colours than relative colormetric However, if we’re converting to a matrix profile like AdobeRGB, this will use relative colormetric instead, as perceptual intents are only supported by lookup table colour profiles In practise, we should be converting to a wide gamut profile, so out-of-gamut colours will be limited anyway :param image_filepath: :param output_filepath: :param icc_profile_filepath: :param new_colour_mode: :return:

convert_to_jpg(input_filepath, output_filepath, resize=None, quality=None)

Convert an image file to JPEG, preserving ICC profile and embedded metadata :param input_filepath: :param output_filepath: :param resize: if present, resize by this amount to make a thumbnail. e.g. 0.5 to make a thumbnail half the size :param quality: quality of created jpg: either None, or 1-95

convert_to_tiff(input_filepath, output_filepath)

Convert an image file to TIFF, preserving ICC profile and embedded metadata :param input_filepath: :param output_filepath:

copy_over_embedded_metadata(input_image_filepath, output_image_filepath, write_only_xmp=False)

Copy embedded image metadata from the input_image_filepath to the output_image_filepath :param input_image_filepath: input filepath :param output_image_filepath: output filepath :param write_only_xmp: Copy all information to the same-named tags in XMP (if they exist). With JP2 it’s safest to only use xmp tags, as other ones may not be supported by all software

extract_xmp_to_sidecar_file(image_filepath, output_xmp_filepath)

Extract embedded image metadata from the image_filepath to an xmp file. Includes the ICC profile description.

Exceptions

exception image_processing.exceptions.ImageProcessingError

Bases: Exception

exception image_processing.exceptions.KakaduError

Bases: ImageProcessingError

exception image_processing.exceptions.ValidationError

Bases: ImageProcessingError

Kakadu

image_processing.kakadu.ALPHA_OPTION = '-jp2_alpha'

kdu_compress() command line option for images with alpha channels

image_processing.kakadu.DEFAULT_COMPRESS_OPTIONS = ['Clevels=6', 'Clayers=6', 'Cprecincts={256,256},{256,256},{128,128}', 'Stiles={512,512}', 'Corder=RPCL', 'ORGgen_plt=yes', 'ORGtparts=R', 'Cblk={64,64}', 'Cuse_sop=yes', 'Cuse_eph=yes', '-flush_period', '1024']

Some default command line options for kdu_compress(), without lossy/lossless specified.

image_processing.kakadu.DEFAULT_LOSSLESS_COMPRESS_OPTIONS = ['Clevels=6', 'Clayers=6', 'Cprecincts={256,256},{256,256},{128,128}', 'Stiles={512,512}', 'Corder=RPCL', 'ORGgen_plt=yes', 'ORGtparts=R', 'Cblk={64,64}', 'Cuse_sop=yes', 'Cuse_eph=yes', '-flush_period', '1024', 'Creversible=yes', '-rate', '-']

Default lossless command line options for kdu_compress()

class image_processing.kakadu.Kakadu(kakadu_base_path)

Python wrapper for jp2 compression and expansion functions in Kakadu (http://kakadusoftware.com/)

kdu_compress(input_filepaths, output_filepath, kakadu_options)

Converts an image file supported by kakadu to jpeg2000 Bitonal or greyscale image files are converted to a single channel jpeg2000 file

Parameters

  • input_filepaths – Either a single filepath or a list of filepaths. If given three single channel files, Kakadu will combine them into a single 3 channel image

  • output_filepath –

  • kakadu_options – command line arguments

kdu_expand(input_filepath, output_filepath, kakadu_options)

Converts a jpeg2000 file to tif

Parameters

  • input_filepath –

  • output_filepath –

  • kakadu_options – command line arguments

image_processing.kakadu.LOSSLESS_OPTIONS = ['Creversible=yes', '-rate', '-']

kdu_compress() command line options which make the compression lossless

image_processing.kakadu.LOSSY_OPTIONS = ['-rate', '3']

kdu_compress() command line options which make the compression lossy