ImageMagick Media Filters

ImageMagic Media Filters

Overview

The ImageMagick Media Filters provide consistent, high quality thumbnails for image bitstreams and PDF bitstreams.

These filters require a separate software installation of the conversion utilities (ImageMagick and Ghostscript).  

The media filters use the library im4java to invoke the conversion utilities.  This library constructs a conversion command launches a sub-process to perform the generation of media files.

Installation

• Install ImageMagick on your server
• If you wish to generate PDF thumbnails, install Ghostscript on your server
• The ImageMagick and Ghostscript executables should be accessible from the same directory (e.g. /usr/bin)

DSpace Configuration

In the filter.plugins section your dspace.cfg file, uncomment the ImageMagick media filter definition.

    ImageMagick Image Thumbnail, ImageMagick PDF Thumbnail, \

This will activate the following settings which are already present in dspace.cfg

    org.dspace.app.mediafilter.ImageMagickImageThumbnailFilter = ImageMagick Image Thumbnail, \
    org.dspace.app.mediafilter.ImageMagickPdfThumbnailFilter = ImageMagick PDF Thumbnail

These media filters contain the following configuration properties

Thumbnail Dimensions

The following properties are used to define the dimensions of the generated thumbnails.

# maximum width and height of generated thumbnails
thumbnail.maxwidth  = 80
thumbnail.maxheight = 80

Conversion Utility Path

The following property provides a path to the ImageMagick and GhostScript utilities.

org.dspace.app.mediafilter.ImageMagickThumbnailFilter.ProcessStarter = /usr/bin

Overwriting Existing Thumbnails

The The ImageMagick media filters can differentiate thumbnails created by the DSpace default thumbnail generator and thumbnails that were manually uploaded by a user.  The media filter reads the bitstream description field to make this determination.  A regular expression can be provided to define the set of thumbnails that should be overwritten by the ImageMagick thumbnail generator. Thumbnail descriptions matching this pattern will be overwritten even if the -f option is not passed to the filter media process.

org.dspace.app.mediafilter.ImageMagickThumbnailFilter.replaceRegex = ^Generated Thumbnail$

The ImageMagick media filter will use the bitstream description field to identify bitstreams that it has created using the following setting.  Bitstreams containing this label will be overwritten only if the -f filter is applied.

org.dspace.app.mediafilter.ImageMagickThumbnailFilter.bitstreamDescription = IM Thumbnail

Thumbnail descriptions that do not match either of the patterns listed above are presumed to be manually uploaded thumbnails.  These thumbnails will not be replaced even if the -f option is passed to the filter media process.

Flatten

DSpaces uses JPEG as format for thumbnails. While JPEG doesn't support transparency, PDF, PNG and other formats does. As those formats are used as outgoing material in DSpace, DSpace has to care about transparency during the generation of the thumbnails. In combination of special versions of ImageMagick and Ghostscript it may occur, that completely transparent areas will become black. As solution ImageMagick recommends to flatten images extracted from PDFs before they are stored as JPEG. Since DSpace 5.2 the ImageMagick media filter flatten thumbnails extracted from PDFs. If you run in to problems you lead back to flattening of the extracted images, you can switch the flattening off by setting the following property in dspace.cfg to false:

org.dspace.app.mediafilter.ImageMagickThumbnailFilter.flatten = false

ICC Profiles

PDFs optimized for printing most probably use CMYK color schemes. While most Printers work with CMYK colors, monitors use RGB color schemes. Following that it is a good idea to convert CMYK color schemes to RGB when creating RGB. Furthermore the JSPUI currently does not support thumbnails using CMYK color schemes (see DS-2834). If you are using ghostscript at least in version 9 DSpace can create thumbnails that use RGB even if the source PDF was using CMYK. For the transformation from CMYK to RGB ghostscript needs ICC profiles. Default ones are provided by most Ghostscript installations from version 9 upwards. The following configuration options tells DSpace where those ICC porfiles are located. Giving ICC profiles to ImageMagick is optional. If the configuration properties in DSpace are unset, no profiles will be supplied to ImageMagick, which won't convert the thumbnails.

# org.dspace.app.mediafilter.ImageMagickThumbnailFilter.cmyk_profile = /usr/share/ghostscript/9.18/iccprofiles/default_cmyk.icc
# org.dspace.app.mediafilter.ImageMagickThumbnailFilter.srgb_profile = /usr/share/ghostscript/9.18/iccprofiles/default_rgb.icc

Additional Customization

The ImageMagick conversion software provides a large number of conversion options.  Subclasses of these media filters could be written to take advantage of the additional conversion properties available in the software.

Note: The PDF thumbnail generator is hard-coded to generate a thumbnail from the first page of the PDF.