pyimageio

PyImageIO

From Fable

Define an Image class for python. Try to keep all the functionality in fabian and ImageD11 but share the read/write code so we can share the bug fixes.

Proposed_fabio?

Proposed fabio

Name Fabio = Fable io
Have a base class for all our 2D diffraction greyscale images. This consists of a 2D array (either Numeric, or numpy in the near future) and a python dictionary of header information in (string key, string value) pairs.

class fabioimage  # [should this be PyImage, FableImage, Fabric, DiffrnImage, DetectorImage ?

Needs a name which will not to be confused with an RGB color image.
Contains member data elements:

data   -> 2D array
header -> dictionary

rows, columns, dim1, dim2 -> data.shape
header_keys               -> header.keys() used to retain the order of the header when writing an image to disk
bytecode                  -> data.typecode()
m, minval, maxval, stddev -> image statistics, could add others, eg roi[slice]

Offers member functions:

integrate_area()      -> return sum(self.data) within slice
rebin(fact)           -> rebins data, adjusts dims
toPIL16()             -> returns a PILimage
getheader()           -> returns self.header
resetvals()           -> resets the statistics
getmean()             -> (computes) returns self.m
getmin()              -> (computes) returns self.minval
getmax()              -> (computes) returns self.maxval
getstddev()           -> (computes) returns self.stddev


read()        -> read image from file [or stream, or shared memory]
write()       -> write image to file  [or stream, or shared memory]
readheader()  -> read only the header [much faster for scanning files]

Each individual file format would then "inherit" all the functionality of this class and just make new read and write methods.
It would also be useful to take the fileseries thing from fabian and have it deal also with streams and shared memory.
New functionalities/ classes which could be useful:

• read_roi() -> do a "fast" read of a region of interest. Just read full image and take a slice if the individual format does not support it (eg compressed)
• class roi -> defines a region of interest, generates array slice indices from "coords".
  • Support of naming and saving into an ascii file.
  • Also putting in/out of mysql database at ID11 (for defining pseudo counters in spec).
  • Investigate "help(slice)" in a recent python.
• Crystallographic metadata
  • Give array indices directions in real space
  • Give at least one rotation axis direction and handedness
  • Give rotation angle for each axis
  • Wavelength
  • sample to detector distance
  • Beam centre
  • etc
• possibility for using on-the-fly external compression - i.e. if files are stored as something as .gz, .bz2 etc could decompress them, using an external compression mechanism (if available). This is present in fabian but requires that images are edfs.

Known_file_formats?

Known file formats

We could try to contact the various manufacturers to see if they can offer any advice or test images? For each format we should have at least one image with known dimensions, min, max, stddev and mean values. Reading this in would be a quick way to check on the code. In some cases, several images with different quirks (eg overflows) could be added.

• Bruker
  • brukerimage.py/ bruker100image.py in fabian
  • readbruker in ImageD11.opendata
  • FRM2FRM bruker C sources - licensing?
• Mar
  • marccd fabian
  • marIP - Erik in progress
  • cctbx has code which wraps CBFlib, but this is not yet released
  • CBFlib img.c - is released under GPL
• CBF/imgCIF
  • pycbf - Jon in progress
• edf
  • edfimage.py in fabian
  • ImageD11.opendata.openedf in ImageD11
  • Pure python module existed in PyDis in the past
• ADSC
  • adscimage.py in fabian
• GE detector at APS
  • GE-script.py found in ImageD11 from Antonino Miceli
• pnm
  • fabian.pnmimage
• tif
  • fabian.tifimage - wraps PIL tif.

Fabians_current_image_classes?

Fabians current image classes

Methods from fabian which seem to be common for any 16 bit greyscale image would be:

add(otherimage)       -> modifies self.data, no return val
integrate_area(coords)-> return sum(self.data) within coords
rebin(fact)           -> rebins data, adjusts dims
toPIL16()             -> returns a PILimage

These ones should also be in ImageD11.data

getheader()           -> returns k,v dictionary
resetvals()           -> resets the next 4
getmean()             -> (computes) returns self.m
getmin()              -> (computes) returns self.minval
getmax()              -> (computes) returns self.maxval
getstddev()           -> (computes) returns self.stddev

Member variables which match those in ImageD11:

data        -> A numeric array
header      -> A dictionary of key, value pairs
header_keys -> assert set(self.header.keys()) == set(self.header_keys)

Fabian specific stuff, that seems mirror other information:

bytecode    -> assert self.bytecode == self.data.typecode()
(dim1,dim2) -> assert (self.dim1,self.dim2) == self.data.shape

Fabian cached data:

m [mean], maxval, minval, stddev

Specific to each format would be:

read -> fills in self.header
                self.data
                self.dim1
                self.dim2
                self.header_keys
write -> creates a file

ImageD11s_data_class?

ImageD11s data class

Member functions :

__add__    -> new data object, header from first arg, data is sum
__sub__    -> new data object, header from first arg, data is difference
__mul__    -> new data object, header from first arg, data is product
__div__    -> new data object, header from first arg, data is quotient
getheader()-> returns the header

These ones should also be in fabian

getheader()           -> returns k,v dictionary
resetvals()           -> resets the next 4
getmean()             -> (computes) returns self.m
getmin()              -> (computes) returns self.minval
getmax()              -> (computes) returns self.maxval
getstddev()           -> (computes) returns self.stddev

Member variables:

data        -> A numeric array
header      -> A dictionary of key, value pairs
header_keys -> assert set(self.header.keys()) == set(self.header_keys)