Internal communication protocol for image information.

Image handling in the collect package is one of the most advanced "Object Oriented" parts of the library. Understanding the basics of the functioning of this object framework is absolutely essential to master the low-level image handling capabilities of the "collect" package.

In a traditional non object-oriented program one would define an "Image" data structure, and make subroutines that work on such an image. This is a data-centered approach. In "collect", the basic unit is the "ImageSink": an object that can deal with image data. Image data is not built into a data object, but instead is passed through from an image source to an image sink. By making "filter classes" that function as image source as well as image sink, arbitrarily long chains of operations can be performed on images in a very efficient way. Using "multiple destinations", it is also possible to treat an image in two or more different ways without re-reading it.

The Image Source to Image Sink protocol

An image source object will call the methods of an image sink in a strictly determined order. First some terminology.

The KappaCCD knows a "scan" command. A "scan" consists of one of more "images". An "image" can consist of 1 or more "frames" (also called "repeats", because they constitute identical measurements).

With this in mind, the call order in an image sink is:

BeginSeries(n)

Called exactly once at the beginning of one "scan". n gives the number of images that will be in this "scan". The BeginSeries method is used by the yellow progress window in the "collect" program to maintain the correct status.

Begin(filename=None)

Called once for each "image".

BeginImage()

Called once for each image.

HeaderInfo(data)

Called once for each image. The data is an ImageHeader object.

Frame(data)

Called once for each frame. The data is a 2-dimensional Numeric python array. The first dimension is the vertical pixel number (0=top row), and the second dimension is the horizontal pixel number (0=leftmost column as seen from the crystal). The actual data can be of integer or floating point type, depending on where the data came from.

EndImage()

Called once for each image.

End()

Called once for each image.

FinalEnd()

Called only once, to signify that everything has finished, no more scans will be coming, and any roundup can be performed.

Outside of this call order, there are some control messages:

Abort()

Can be called at any moment to signify an "alert" situation. To the imagesink it means that it should forget any intermediate results, and be ready for a restart.

Skip(time)

Will be called by the "scan" if it notices that an image was already measured before. Skip() is meaningless outside of the measurement itself. It is used by the yellow "progress" window in collect to maintain an accurate status.

There are also methods that determine how an image file will be written:

SetOutputFilename(outname)

This is an optional method that can be called to overwrite the image file name specified using Begin(). This is used by procedures that read a sequence of images, and write one or more output images under a different name.

SetFormat(format)

Set the compression format that should be used for writing the image to disk. The format variable is the compression extension (.Z, .gz, or .bz2)

SetOutputDatatype(format)

Set the data format that should be used for writing the image to disk. KappaCCD images can be written as raw 16 bit data (format=u16) or as CCP4 compressed 16 bit data (format=ccp4w)

setscale(scale)

Set a fixed scaling factor for the conversion to 16 bit integers when writing the image (normally the scaling is automatically determined from the data range).

setshift(shift)

Set a fixed shift for the conversion to 16 bit integers when writing the image (normally the shift is automatically determined from the lowest data value).

send1 (
        sink,
        filename,
        header,
        frame,
        )