image_processing DocumentationRelease 1.6

Mel Mason

Jan 16, 2020

Contents:

1 Introduction 11.1 Use cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.3 Quick start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

2 Digital Preservation 32.1 Embedded metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

3 JPEG2000 Profile 53.1 Kakadu compression parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53.2 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

4 JP2 colour profiles for digital preservation 74.1 Preservation guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74.2 JP2 conversion details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74.3 Recommendations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84.4 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94.5 Further Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

5 API Reference 115.1 DerivativeFilesGenerator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125.2 Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145.3 Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165.4 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165.5 Kakadu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

6 Indices and tables 19

Python Module Index 21

Index 23

i

ii

CHAPTER 1

Introduction

Image-processing is a Python library that converts a source image (TIFF or JPEG) to a JP2 file with a focus on digitalpreservation and making sure the conversion is reversible.

At the Bodleian we use it to generate the derivative image files we ingest into Digital Bodleian for both delivery andlong-term preservation.

1.1 Use cases

• An all-in-one workflow to go from source file to derivatives including all validation checks. The defaults aretailored to Digital Bodleian preferences, but this is customisable.

• Individual functions to be called separately from a workflow manager like Goobi.

• Easy TIFF to JP2 conversion from Python: basic Python wrapper around Kakadu, along with some testedparameter recipes.

1.2 Installation

pip install git+https://github.com/bodleian/image-processing.git

• Compatible with both Python 2.7 and 3.5+

1.2.1 Dependencies

• Exiftool

– yum install perl-Image-ExifTool

1

image_processing Documentation, Release 1.6

– apt install exiftool

• Kakadu

– If you want to process compressed TIFFs, compile it with libtiff support. In the makefile apps/make/Makefile-<OS>, add -DKDU_INCLUDE_TIFF to CFLAGS and -ltiff to LIBS

• Pillow prerequisites before pip install

– May need some image packages installed before pip installation (may not need lcms2 depending onwhich TIFF formats you’ll be processing)

– yum install lcms2 lcms2-devel libtiff libtiff-devel libjpeglibjpeg-devel

– The virtual environment’s python binary needs to match the Python.h used by GCC. If necessary, useexport C_INCLUDE_PATH=/usr/local/include/python2.7/

• Jpylyzer prerequisites before pip install

– Needs a relatively recent pip version to install - it fails on 1.4.

1.3 Quick start

To run a full conversion on a TIFF file, with validation, format checks, XMP extraction and creation of a thumbnailJPEG:

From the command line:

convert_tiff_to_jp2 input.tif

In Python:

from image_processing.derivative_files_generator import DerivativeFilesGeneratorderivatives_gen = DerivativeFilesGenerator(kakadu_base_path="/opt/kakadu")derivatives_gen.generate_derivatives_from_tiff("input.tif", "output/folder")

To access the validation and conversion functions separately so they can be integrated into a workflow system likeGoobi:

from image_processing.derivative_files_generator import DerivativeFilesGeneratorfrom image_processing import kakadu, validationderivatives_gen = DerivativeFilesGenerator(kakadu_base_path="/opt/kakadu",

kakadu_compress_options=kakadu.DEFAULT_→˓LOSSLESS_COMPRESS_OPTIONS)

# each of these statements can be run separately, with different instances of→˓DerivativeFilesGeneratorvalidation.check_image_suitable_for_jp2_conversion("input.tif")derivatives_gen.generate_jp2_from_tiff("input.tif", "output.jp2")derivatives_gen.validate_jp2_conversion("input.tif", "output.jp2", check_→˓lossless=True)

To just use Kakadu directly through the wrapper:

from image_processing import kakadukdu = kakadu.Kakadu(kakadu_base_path="/opt/kakadu")kdu.kdu_compress("input.tif", "output.jp2", kakadu_options=kakadu.DEFAULT_LOSSLESS_→˓COMPRESS_OPTIONS)

2 Chapter 1. Introduction

CHAPTER 2

Digital Preservation

This package has a strong emphasis on digital preservation, as we want to use lossless JP2s as our preservation masterfiles. It was developed with input from our digital preservation team.

By default it checks:

• the JP2 is valid (using jpylyzer)

• the JP2 can be converted back into a TIFF, which

– has the same pixels as the source TIFF (or the TIFF we converted from the source JPEG)

– has the same colour profile and mode as the source image

It does not check:

• the technical metadata is correctly copied over to the JP2 (we extract this to a separate file)

• the JP2 displays as expected in viewers

• JPEG to TIFF conversion, if the source file was a JPEG (beyond checking the colour profiles match). This is alossy conversion, so the pixels will not be identical

We have run tests on a wide sample of source images from our repository. We cannot share this test repository onGitHub due to copyright issues, but if you want to run your own tests these automatic lossless checks should simplifythat. The full lossless checks can be disabled in production, but we would recommend keeping them enabled if digitalpreservation is a concern.

Note: our testing has been focused on the source images we ingest, not all possible formats. Thecheck_image_suitable_for_jp2_conversion() function is run when generating derivatives, and shouldfail for image formats we have not tested.

See JP2 colour profiles for digital preservation for some more background information and recommendations.

2.1 Embedded metadata

We extract image metadata from the source file to a separate XML file for digital preservation, using Exiftool. Exiftoolis a command line tool for reading, writing and editing embedded metadata with very thorough support for image

3

image_processing Documentation, Release 1.6

embedded metadata formats.

This separate XML file is stored along with the JP2 in the archive. The metadata in the file is stored in the imagemetadata format XMP, mapped from whatever formats (EXIF, IPTC etc.) were used in the TIFF file. Exiftool alsooffers a proprietary XML format which preserves the original format of the metadata fields, but we chose XMP as awidely recognised format for sidecar files, rather than going with a proprietary format that may change in future.

2.1.1 Copying over metadata

While the extracted metadata is what we rely on for preservation, we also want to have as much of the original metadataas possible in the JP2 image.

Maintaining embedded metadata while converting between image file formats is difficult. All of the image conversionsoftware we’ve tried had problems with embedded metadata.

• ImageMagick sometimes produces badly formed metadata in the converted file

• Pillow by default doesn’t copy over any metadata. Embedded metadata related functionality is limited

• Kakadu only copies over some metadata

Because of this, we don’t rely on the image conversion library we use (Pillow) to copy over metadata. Instead, weuse Exiftool to copy over metadata after the image is converted, both when converting from JPEG to TIFF and whenconverting from TIFF to JP2. When copying over to JP2 we map all embedded metadata formats to XMP, as JP2doesn’t have an official standard for storing EXIF.

4 Chapter 2. Digital Preservation

CHAPTER 3

JPEG2000 Profile

3.1 Kakadu compression parameters

Digital Bodleian uses a specific set of kdu_compress options (DEFAULT_LOSSLESS_COMPRESS_OPTIONS)for lossless JP2 conversion, and alters the rate and Creversible parameters for lossy JP2 conversion.

The terminal commands are as follows:

3.1.1 Lossless

kdu_compress -i input.tif -o output.jp2 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 -

3.1.2 Lossy

kdu_compress -i input.tif -o output.jp2 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 -rate 3

3.1.3 Parameter explanation

• Clevels=6 Resolution levels. At least 3 are recommended to help compression. After that, the aim is to havethe lowest resolution sub-image be roughly thumbnail-sized, so the optimal value is dependent on image size.1

• Clayers=6 Quality layers. More layers can help with quicker decompression; you can decode only a subsetof the layers when dealing with lower resolution images where quality decrease is not noticed.1

1 JPEG 2000 as a Preservation and Access Format for the Wellcome Trust Digital Library

5

image_processing Documentation, Release 1.6

• -rate - Compression rates for each quality layer. An initial value of - is needed to ensure true losslessness,as otherwise some data may be discarded. Subsequent numbers can be added to specify bit-rates for each of thelower quality layers - if they are all left unspecified, as they are here, “an internal heuristic determines a lowerbound and logarithmically spaces the layer rates over the range”2

• Creversible=yes Use reversible wavelet and component transforms (required for losslessness)1

• Cprecincts={256,256},{256,256},{128,128} Precinct sizes for each resolution level. The lastvalue applies to all subsequent levels2

• Stiles={512,512} Tile size2

• Corder=RPCL Progression order of Resolution, Position, Component, Layer. This defines which sub-imagesoccur first in the datastream. Having resolution first optimises for fast decompression of thumbnails].1 Perfor-mance analysis by the British Library4 recommended RPCL for their use case.

• ORGgen_plt=yes Include packet length information in the header of all tile-parts2

• ORGtparts=R Controls the division of each tile’s packets into tile-parts2

• Cblk={64,64} Code-block size2

• Cuse_sop=yes Include SOP markers. Limits the damage of bit flipping errors to a single block3

• Cuse_eph=yes Include EPH markers. Limits the damage of bit flipping errors to a single block3

• -flush_period 1024 allows streaming when writing to output file. The value is dependent on tile size andsometimes precinct size2

For RGBA images we add:

• -jp2_alpha Treat the 4th image component as alpha2

3.2 References

• JPEG 2000 seminar – edited highlights #1

• IIPImage & An Analysis of JPEG2000 Encoding Parameters

• JPEG 2000 profiles – examples from a range of institutions

• Diva.js JPEG 2000 encoding with Kakadu

• JPEG2000 Implementation at Library and Archives Canada

Note: most of these are from around 2010 - more recent examples of profiles would be welcome.

2 kdu_compress -usage (online copy here)4 British Library JPEG 2000 profile3 JPEG 2000 Specifications for The National Library of the Czech Republic

6 Chapter 3. JPEG2000 Profile

CHAPTER 4

JP2 colour profiles for digital preservation

4.1 Preservation guidelines

Digital preservation recommendations are that the original colour profile is retained in the preservation copy, and notconverted.

• Specified color space preferred over unspecified or unknown color space.

• Color space from initial creation preferred to transcoded color space

—https://www.loc.gov/preservation/digital/formats/content/still_preferences.shtml

Note also that colour profile conversion can be lossy.

4.2 JP2 conversion details

The JPEG 2000 format supports only a restricted set of ICC Profile features.

The -jp2_space parameter on kdu_compress sets the colour profile in the image metadata, but does not oth-erwise convert the image - the pixel values remain the same. The sRGB value sets the colour profile to the sRGBIEC61966-2.1 profile. (This is not the only way to set the colour profile)

Kakadu (and JP2 itself) will not support CYMK images:

Only three colour channels, R (red), G (green) and B (blue), are supported by the JP2 file format. Alter-natively, a luminance image may have exactly one colour channel, Y (luminance). –Kakadu manual

JPX does support it, but is not recommended for digital preservation.

For example the sRGB v4 ICC preference profile is not supported, and cannot be embedded into a JP2 file usingKakadu. Setting -jp2_space sRGB on kdu_compress will erase the embedded profile and so allow it to beconverted. The sRGB IEC61966-2.1 profile thus assigned is sufficiently different that in some cases there is a notice-able tint to the created JP2.

7

image_processing Documentation, Release 1.6

4.3 Recommendations

When using JP2 for preservation, preserve the original colour space where possible and keep it embedded in the JP2.To ensure the broadest possible compatibility while retaining a wide colour gamut, we recommend that the colourprofile in your source TIFFs is Adobe RGB 1998. This will allow for the best colour representation through TIFF toJPEG 2000, and should display correctly in modern browsers.

4.3.1 Supported RGB colour profiles

If the original TIFF has an RGB colour profile supported by JP2, this is simple. Convert directly from the originalTIFF, without any colour conversion beforehand, and do not use the -jp2_space parameter in kdu_compress.

4.3.2 Monochrome colour spaces

The conversion process is the same for greyscale and bitonal images as it is for RGB images. JP2 supports singlechannel colour. Note: bitonal JP2s converted back to TIFFs end up as greyscale TIFFs (but are still visually identical).

Bitonal images do not need colour profiles. Ideally greyscale images should have one - the digital preservation recom-mendation is Grayscale Gamma 2.2. This will be embedded in the created JP2.

It is possible to convert monochrome images to RGB when compressing to JP2. These three channel JP2s expand tosingle channel TIFFs. We have historically done this with our monochrome images, originally because a legacy imageserver did not support single channel JP2s. This is no longer an issue for us (we have tested single channel JP2s withIIPServer and Jpylyzer), so we stick to the original colour mode and profile, as recommended.

4.3.3 RGBA colour spaces

The kdu_compress command options we use do not always preserve alpha channel information with RGBA TIFFs.We add the -jp2_alpha option, which tells kakadu to treat the 4th image component as alpha, but there is still anissue with unassociated alpha channels, which cannot be converted back to TIFF using kdu_expand:

Kakadu Warning: Alpha channel cannot be identified in a TIFF file since it is of the unassociated (i.e., notpremultiplied) type, and these are not supported by TIFF. You can save this to a separate output file.

As very few of our input images have an alpha channel, and we have not encountered failing cases in live data (asopposed to constructed test data), this is not a priority for us. We just make sure to check RGBA JP2 conversions arelossless, so we will catch any future failing cases.

4.3.4 Colour profiles / modes not supported by JP2

Convert to a wide gamut RGB colour profile supported by JP2 - we use Adobe RGB 1998. This may be lossy, soconsider keeping a copy of the original TIFF for preservation.

4.3.5 Images without colour profiles

Ideally, we would work out the closest colour profile for the image and assign that. If this is not possible, either readthe technical metadata and find out the profile most commonly used in the scanner/camera, or run tests and visualcomparisons on some of the files to see if there is a standard colour profile that makes the least change to the colour.Without a colour profile, images will be assumed to be sRGB by browsers.

If we are not able to calculate a profile, the recommendation is to leave it without one rather than assigning onearbitrarily.

8 Chapter 4. JP2 colour profiles for digital preservation

image_processing Documentation, Release 1.6

4.3.6 Delivery

Where delivery is the priority, rather than preservation, there are two options:

1. Convert the image to sRGB (and embed the sRGB profile)

2. Keep the image with its original colour profile

Historically, many browsers have not supported colour profiles and have displayed images as if they were all sRGB.This is still the case with some older versions of browsers, especially on mobile platforms. Android only startedsupporting colour profiles with 8.0. So (1) is the safest option to ensure colour accuracy on all browsers.

However, the latest versions of all major browsers (including Chrome, Edge, Firefox, IE, Safari, and Chrome andSafari on mobile) now support colour profiles (as do many IIIF servers, such as IIP). So with (2) most users would stillbe able to view images with colour accuracy. Keeping the original colour profile also permits users with wide gamutmonitors to see Adobe RGB 1998 images with the full depth of colour, rather than being limited to the narrower sRGBgamut.

We use the same JP2 for preservation and delivery, so we have to use (2) in any case, to avoid the lossy conversion tosRGB.

4.4 Testing

As well as manual visual checks, our JP2 conversion methods have all been tested by

1. Compressing the TIFF to JP2

2. Validating the JP2 with jpylyzer

3. Expanding the JP2 to a new TIFF

4. Comparing the colour mode, colour profile and pixels of the original and new TIFF

If any of the comparisons are not equal (with the exception of bitonal images, which we expect to produce greyscaleTIFFs when converted back), the conversion is not considered lossless. This test ensures we can always return to avisually identical source TIFF file.

4.5 Further Reading

For further reading on this topic, please consult the following sources:

ICC profiles and resolution in JP2: update on 2011 D-Lib paper

JP2 and colour profile limitations: a positive conclusion and findings

4.4. Testing 9

image_processing Documentation, Release 1.6

10 Chapter 4. JP2 colour profiles for digital preservation

11

image_processing Documentation, Release 1.6

CHAPTER 5

API Reference

5.1 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’,’Clay-ers=6’,’Cprecincts={256,256},{256,256},{128,128}’,’Stiles={512,512}’,’Corder=RPCL’,’ORGgen_plt=yes’,’ORGt-parts=R’,’Cblk={64,64}’,’Cuse_sop=yes’,’Cuse_eph=yes’,’-flush_period’,’1024’,’Cre-versible=yes’,’-rate’,’-’],use_default_filenames=True,re-quire_icc_profile_for_greyscale=False,re-quire_icc_profile_for_colour=True,exiftool_path=’exiftool’)

Given a source image file, generates the derivative files (preservation/display image formats, extracted technical

12 Chapter 5. API Reference

image_processing Documentation, Release 1.6

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, re-quire_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 ofusing the original filename

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

• require_icc_profile_for_colour – raise an error if a colour image does nothave 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 aValidationError if they do not match. Does not check technical metadata beyond colour profile andmode.

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 allin 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 fileand preserved in a separate xml file

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

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

Returns filepaths of created files

5.1. DerivativeFilesGenerator 13

image_processing Documentation, Release 1.6

generate_derivatives_from_tiff(tiff_filepath, output_folder, include_tiff=False,save_embedded_metadata=True, cre-ate_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 givenfolder.

Parameters

• create_jpg_as_thumbnail – create the JPG as a resized thumbnail, not a highquality 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 fileand preserved in a separate xml file

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

• check_lossless – If true, check the created jpg2000 file is visually identical to thesource 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, jpy-lyzer_output_filepath=None)

Validate the jp2 file using jpylyzer, and check that the conversion from tif to jp2 was lossless Raises aValidationError 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

5.2 Validation

image_processing.validation.check_colour_profiles_match(source_filepath, con-verted_filepath)

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

Parameters

• source_filepath –

14 Chapter 5. API Reference

image_processing Documentation, Release 1.6

• converted_filepath –

image_processing.validation.check_image_suitable_for_jp2_conversion(image_filepath,re-quire_icc_profile_for_greyscale=False,re-quire_icc_profile_for_colour=True)

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

Parameters

• image_filepath –

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

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

image_processing.validation.check_visually_identical(source_filepath, con-verted_filepath,source_pixel_checksum=None)

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

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 read-ing 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 aValidationError if it is invalid

Parameters

• image_file (str) –

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

5.2. Validation 15

image_processing Documentation, Release 1.6

5.3 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 jp2doesn’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, andloses less information on out-of-gamut colours than relative colormetric However, if we’re converting toa matrix profile like AdobeRGB, this will use relative colormetric instead, as perceptual intents are onlysupported 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: :paramicc_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 tomake 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 in-put_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 xmptags, 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 de-scription.

5.4 Exceptions

exception image_processing.exceptions.ImageProcessingErrorBases: exceptions.Exception

exception image_processing.exceptions.KakaduErrorBases: image_processing.exceptions.ImageProcessingError

exception image_processing.exceptions.ValidationErrorBases: image_processing.exceptions.ImageProcessingError

5.5 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.

16 Chapter 5. API Reference

image_processing Documentation, Release 1.6

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 toa single channel jpeg2000 file

Parameters

• input_filepaths – Either a single filepath or a list of filepaths. If given three singlechannel 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

5.5. Kakadu 17

image_processing Documentation, Release 1.6

18 Chapter 5. API Reference

CHAPTER 6

Indices and tables

• genindex

• modindex

• search

19

image_processing Documentation, Release 1.6

20 Chapter 6. Indices and tables

Python Module Index

iimage_processing.conversion, 16image_processing.derivative_files_generator,

12image_processing.exceptions, 16image_processing.kakadu, 16image_processing.validation, 14

21

image_processing Documentation, Release 1.6

22 Python Module Index

Index

Symbols__init__() (image_processing.derivative_files_generator.DerivativeFilesGenerator

method), 13

AALPHA_OPTION (in module image_processing.kakadu),

16

Ccheck_colour_profiles_match() (in module

image_processing.validation), 14check_conversion_was_lossless() (im-

age_processing.derivative_files_generator.DerivativeFilesGeneratormethod), 13

check_image_suitable_for_jp2_conversion()(in module image_processing.validation), 15

check_visually_identical() (in module im-age_processing.validation), 15

convert_icc_profile() (im-age_processing.conversion.Converter method),16

convert_to_jpg() (im-age_processing.conversion.Converter method),16

convert_to_tiff() (im-age_processing.conversion.Converter method),16

Converter (class in image_processing.conversion), 16copy_over_embedded_metadata() (im-

age_processing.conversion.Converter method),16

DDEFAULT_COMPRESS_OPTIONS (in module im-

age_processing.kakadu), 16DEFAULT_LOSSLESS_COMPRESS_OPTIONS (in

module image_processing.kakadu), 16DerivativeFilesGenerator (class in im-

age_processing.derivative_files_generator),12

Eextract_xmp_to_sidecar_file() (im-

age_processing.conversion.Converter method),16

Ggenerate_derivatives_from_jpg() (im-

age_processing.derivative_files_generator.DerivativeFilesGeneratormethod), 13

generate_derivatives_from_tiff() (im-age_processing.derivative_files_generator.DerivativeFilesGeneratormethod), 13

generate_jp2_from_tiff() (im-age_processing.derivative_files_generator.DerivativeFilesGeneratormethod), 14

generate_pixel_checksum() (in module im-age_processing.validation), 15

generate_pixel_checksum_from_pil_image()(in module image_processing.validation), 15

Iimage_processing.conversion (module), 16image_processing.derivative_files_generator

(module), 12image_processing.exceptions (module), 16image_processing.kakadu (module), 16image_processing.validation (module), 14ImageProcessingError, 16

KKakadu (class in image_processing.kakadu), 17KakaduError, 16kdu_compress() (image_processing.kakadu.Kakadu

method), 17kdu_expand() (image_processing.kakadu.Kakadu

method), 17

LLOSSLESS_OPTIONS (in module im-

age_processing.kakadu), 17

23

image_processing Documentation, Release 1.6

LOSSY_OPTIONS (in module im-age_processing.kakadu), 17

Vvalidate_jp2() (in module im-

age_processing.validation), 15validate_jp2_conversion() (im-

age_processing.derivative_files_generator.DerivativeFilesGeneratormethod), 14

ValidationError, 16

24 Index