Image Formats

 TIFF Image Tiled Pyramid Structure In order to maximize the speed and efficiency of the system, the source images must be in a multi-resolution format. This allows for rapid access to individual image tiles at any resolution with minimal server overhead. The is especially important for very high resolution images. The IIPImage server supports both TIFF and JPEG2000 formats. TIFF is supported natively by IIPImage and files must be saved in tiled multi-resolution format. JPEG2000 requires inclusion of the Kakadu JPEG decoder at this time (which is not open source).

Images can be in either 8, 16 or 32 bits per channel format and in greyscale, sRGB or CIE L*a*b* colour space.

Tiled Multi-Resolution TIFF

Tiled Multi-Resolution (or Tiled Pyramidal) TIFF is simply a tiled multi-page TIFF image, with each resolution stored as a separate layer within the TIFF. This is a standard TIFF extension and is supported by most image processing applications including Photoshop, GIMP, VIPS and ImageMagick. The libtiff codec library is also perfectly capable of reading and writing such images.

Tiled Pyramidal TIFF images can also be optionally compressed using lossless Deflate or LZW. Or be compressed lossily with JPEG for smaller file sizes.

In order to test the server, you may use this example TIFF image.

Conversion using VIPS

These images can be created using the VIPS image processing suite (NOTE: version 0.9.5 of the IIPImage server and earlier require Tiled Pyramidal TIFF images produced with the VIPS stable 7.8 branch or earlier only. For users of iipsrv version 0.9.6 and later, use the latest stable or unstable VIPS releases). To generate a tiled pyramidal TIFF image use Nip2, the VIPS GUI or use the command line.

vips im_vips2tiff <source_image> <output_image.tif>:<compression>,tile:<size>,pyramid
  • source_image: can be any kind of image supported by VIPS
  • output_image.tif: your TIFF output image
  • compression: either none, deflate, LZW or JPEG
  • size: pixel dimensions of tiles, eg: 256×256

For example, to generate a TIFF with deflate compression and a tile size of 256×256, use:

vips im_vips2tiff source_image output_image.tif:deflate,tile:256x256,pyramid

It is also possible to generate tiled pyramidal TIFF images with JPEG compression at quality 75:

vips im_vips2tiff source_image output_image.tif:jpeg:75,tile:256x256,pyramid

The latest version of libtiff (version 4+) includes BigTIFF support, allowing images to go beyond the standard TIFF size limit of 4GB. To use this, make sure that both VIPS and IIPImage have been compiled and are linked to the correct version of libtiff. The conversion syntax for creating an image with VIPS is slightly different:

vips im_vips2tiff source_image output_image.tif:jpeg:75,tile:256x256,pyramid,,,,8

where the 8 indicates that the TIFF should be BigTIFF enabled. (The 3 blank commas before the 8 are for the optional parameters format,resolution and ICC profile. See the VIPS documentation for more details).

From VIPS version 7.28 onwards, a new sequential mode is available within VIPS which is both faster and more efficient in terms of disk access. To enable this, use the following syntax (type vips tiffsave on the command line to see a full list of options):

vips tiffsave source_image output_image.tif --tile --pyramid --compression deflate
                                --tile-width 256 --tile-height 256

Conversion using ImageMagick

You can also use ImageMagick to create Tiled Pyramid TIFF. This only works with version 6.4.7-10 and upwards. In this case use the convert command. For example, to generate a 256×256 pyramidal tiled tiff:

convert s -define tiff:tile-geometry=256x256 -compress jpeg 'ptif:o.tif'
  • s: source image – can be any kind of image supported by ImageMagick (almost all)
  • ptif: specify your image format as pyramidal tiff
  • o.tif: output image – *MUST* have tif or ptif extension;
  • 256×256: the tile size

Conversion using STIFF

It is also possible to create a Tiled Pyramidal TIFF from scientific FITS data using STIFF. STIFF is a FITS to TIFF conversion package for astronomy data that  allows control of gamma, contrast,  brightness and color saturation and is fully compatible with IIPImage. See the STIFF documentation for more details on how to use it and the options available.


JPEG2000 is an advanced wavelet-based image compression and coding format that gives improved compression over standard JPEG and much greater flexibility with support for multi-resolution coding, multiple bit-depths, region-of-interest, quality layers and lossless compression. IIPImage (version 0.9.9 onwards) can decode JPEG2000  images via the Kakadu library. Images can be in 8 or 16 bits per channel and both the jp2 (JPEG2000 Part 1 ISO/IEC 15444-1) and jpx  (JPEG2000 Part 2 ISO/IEC 15444-2) formats are supported. Note that jpc raw JPEG2000 codestreams are not yet supported.

If you wish to use this feature, you will need to compile the IIPImage server with Kakadu enabled or download one of the binaries from our download page. Note, however, that Kakadu is not open source and that the available binaries are for non-commercial use only. If you require commercial licensing, please contact us.

Future versions of IIPImage will also be compatible with OpenJPEG for a fully open source solution.

Any JPEG2000 image can be used with IIPImage, but in order to get the best performance, you should encode your images with multi-resolution and precincts enabled.

Encoding with Kakadu

In order to encode using Kakadu, you can use the kdu_compress command line tool. The key parameters are Clayers (number of quality layers), Clevels (number of resolutions), Cprecincts (precinct size – which are tiles in the wavelet domain), Cblk (code block size), Corder (encoding compression order – RPCL for resolution encoding) and rate (compression rate).

For example, to create a lossy encoded JPEG2000 (part 1) image with 1 quality layer, 7 resolutions, precincts of size 256×256, code blocks of size 64×64, multi-resolution encoding and a compression rate of 2.5:

kdu_compress -i input.tif -o output.jp2 -rate 2.5  Clayers=1 Clevels=7
    "Cprecincts={256,256}" "Corder=RPCL" "Cblk={64,64}" 

(The Cuse_sop=yes parameter adds packet synchronization markers)

It is also possible to additionally add tiling through the Stiles parameter.  If using tiling, you should also add tile part markers through the parameters ORGgen_plt and ORGtparts. For example, to use a a tile size of 512×512 pixels, add the following parameters to the above command:

"Stiles={512,512} "ORGgen_plt=yes" "ORGtparts=R"

It is also possible to encode losslessly using the Creversible=yes parameter. Lossless encoding with JPEG2000 is capable of reducing file size to around 40% of the original TIFF file. Several quality layers can also be included if you wish to keep a lossless archive image, but allow users to have fast access to only a lower quality lossy version of the image.

Encoding with OpenJPEG

OpenJPEG is a fully open source JPEG2000 codec, which can also be used to encode images. To create a lossy encoded JPEG2000 (part 1) image with 1 quality layer, 7 resolutions, precincts of size 256×256, code blocks of size 64×64, multi-resolution encoding and a compression rate of 2.5:

opj_compress -i input.tif -o output.jp2 -r 2.5 -n 7 -c "[256,256]"  -b "64,64"
     -p RPCL -SOP

If no rate parameter is specified, encoding is performed losslessly. If tiling is required, add the following parameters, where -t specifies the desired tile size and -TP specifies the use of tile part markers:

-t 512,512 -TP R

Image Security and Storage

IIPImage allows you to protect your original images as they do not need to be directly accessible by the client via the web server (Apache, Lightttpd etc). They, therefore, do not need to be in the web server document root or in any subdirectory. The user, therefore, does not need to have download access to the full resolution image file – only the IIPImage server needs to. The images can be stored in any directory (or mounted directory via NFS, for example) on the machine on which the IIPImage server iipsrv executable runs. This machine can also be a machine separate to the web server front-end.

The image paths given to the IIPImage server via the FIF variable must be absolute system paths on the server machine (eg. FIF=/images/test.tif) and not paths relative to the web server document root location. Don’t forget to make sure the IIPImage server process owner has read access on the images! On Windows, you should still use forward slashes “/” for the image path, not “\” and there is no need for the “c:” prefix.

You can also use the operating system’s access control to grant read access permission to the iipsrv process for specific directories or images only.

Dynamic Watermarking

Watermark exampleThe IIPImage server (as of version 0.9.9) is able to perform dynamic watermarking without the need to modify the source image. The watermark is dynamically added server-side to each tile that is streamed to the client with user-defined levels of transparency. It’s also possible to set a level of probability that a particilar tile will have a watermark applied to it if you do not wish to have a watermark applied to every single tile. You can see a demo of dynamic watermarking in action on the demo page.

The server supports three watermarking related parameters:

WATERMARK TIFF image to use as watermark file.
WATERMARK_PROBABILITY The probability that a particilar tile will have a watermark applied to it. 0 means never, 1 means always.
WATERMARK_OPACITY The opacity (between 0 and 1) applied to the watermark image.

The watermark file must be a TIFF image which can be greyscale or color, either 8 or 16 bit and can optionally include an alpha channel. The watermark should be not bigger than the tile size used for the source TIFF or JPEG2000 tiling (typically 256 pixels for both width and height). If bigger, the watermark will simply be cropped to the image tile size. If the watermark is smaller, the watermark will be positioned randomly within the available space. This randomness adds an extra level of security, making any automated watermark removal far more difficult. The watermark is simply added pixel by pixel to the image data, taking into account the WATERMARK_OPACITY parameter and any alpha channel included in the watermark. Thus, the watermarked image for a given pixel i:

output image[i] = source image[i] +
        ( watermark image[i] * alpha channel[i] * watermark opacity parameter )

Thus, you should avoid using white backgrounds in your watermark, unless you have a suitable alpha channel. Furthermore, your watermark logo or text should not be black (pixel value = 0) as the pixel values are added to the output. If you have trouble creating your watermark, you can download an example watermark file here.

Flattr this

Donations appreciated Bookmark and Share
Get IIPImage at Fast, secure and Free Open Source software downloads