ImFiles ioharness

Introduction

ioharness is a test program for developers of ImFiles plugins for Chalice (version 1.2 or greater). It exists so that developers may create and test their file I/O plugins in a simpler environment than the full Chalice program. It only exercises those capabilities of ImFiles that Chalice actually uses. It does not attempt to fully exercise all of the capabilities that ImFiles has. However, any ImFiles plugin that can pass the tests detailed below should work in the Chalice environment.

I/O operations that Chalice will perform

Chalice will always read/write all channels in an image in RGBAO order. For reads, Chalice will do one of the"following:
  1. Read the entire image.
  2. Read strips of an image from top to bottom. Eg. all columns, but only some rows.
  3. Read "random" rectangles out of an image.
For writes, Chalice will:
  1. Write the entire image.
  2. Write the image in ordered strips.
ioharness provides ways simulate all of these I/O operations so that the developer may use his ImFiles plugin in Chalice with some confidence.

What ioharness can do

ioharness can perform 5 different tests corresponding to the tests given above. It can also be used to test a few other functions that ImFiles provides and that Chalice uses. ImFiles provides for plugins to have various user setable options. ioharness can print and set these options. ImFiles also provides a function to check on file type information without creating an Im object. ioharness can test this as well.

The I/O tests

The I/O tests are numbered and correspond to the list given above. When you are first testing your ImFiles plugin, it would be wise to start with read test #1 and work your way down.

Read test #1

ioharness [-F frame_number] [-f plugin_format] -r 1 plugin_image.ext
result_image.tiff
This test will read the entire image and write it to a Tiff file. We recommend using Tiff files as output, because they can handle all of the data storage types that Chalice can handle.

Read test #2

ioharness [-F frame_number] [-f plugin_format] -r 2 #_slices
plugin_image.ext result_image.tiff
This test will read the image in slices. The second argument after the 2 is the number of slices to use. We recommend trying several different slicing numbers, including the number of lines in the image.

Read test #3

ioharness [-F frame_number] [-f plugin_format] -r 3 X1 Y1 X2 Y2
plugin_image.ext result_image.tiff
This test reads a rectangle starting at X1, Y1 and extending to X2, Y2 and writes it to the result file. Remember that ImFiles assumes that 0,0 is in the upper left hand corner of the image.

There are two optional arguments to ioharness that may be of use. The '-F' option specifies a frame number for those file formats that handle motion files. The '-f' specifies the input format. In general, you should NOT need to use the '-f' option, because your plugin should autosense the file type. However, some plugins, such as device plugins, may not be able to autosense and you should use the '-f' option for these.

Write test #1

ioharness [-F frame_number] -f plugin_format -w 1 source_image.ext
plugin_image.ext
This test will write the source image in the specified format. It will do the entire image in one big write.

Write test #2

ioharness [-F frame_number] [-f plugin_format] -w 2 #_slices
source_image.tiff plugin_image.ext
This test will write the image in slices. The second argument after the 2 is the number of slices to use. We recommend trying several different slicing numbers, including the number of lines in the image.

Information test

ioharness -i plugin_image.ext
This test runs the 'format' (or 'getFormat' in the plugin) function to get the size and type information about an image.

The other flags

Options

The '-O' flag can be used to dump all of the user setable options that a file format has. The first 2 columns indicate whether the options are input options "I", output options "O", or both "IO". The line contains the option and possible values. Here is a dump of the ImTiff options as of the writing of this file. Notice that you must use the '-f' option to specify the file format.
csh> ioharness -f ImTiff -O
 O String 'Compression' default=lzw, menu {JPEG, LZW, Packbits, Pixar Log, Zip}
 O Toggle 'Prediction encoding' default=True
 O Integer 'Jpeg quality' count=1, default=90, hard min=1, hard max=100
 O Integer 'Zip Level' count=1, default=9, hard min=1, hard max=5
 O Integer 'Pixar Level' count=1, default=9, hard min=1, hard max=5
I  String 'Pixar Type' default=default, menu {Default, 8 bit, 16 bit, Float}
The '-o' flag can be used to set an option for the given format. This flag requires two arguments, the option name and the value. Here is an example of using the '-o' flag.
ioharness -f ImTiff -o 'Compression' zip -w 1 ~/grail/pics/girl.comp.tiff foo.tiff

Glossary

RGBAO

Red, green, blue, alpha, other. Since ImFiles (and Chalice) can handle more than 4 channels per image, all channels above alpha are considered other. There may be 0 or more other channels.