Image reader API

Utility classes

pni::image_info

class pni::image_info

image information type

ImageInfo holds basic information about a particular image.

Public Functions

image_info()

default constructor

image_info(size_t nx, size_t ny)

constructor

Parameters

  • nx: number of pixels in x-direction

  • ny: number of pixels in y-direction

image_info(image_info &&i) = default

move constructor

Use compiler provided default implementation.

image_info(const image_info &i) = default

copy constructor

Use compiler provided default implementation

image_info &operator=(image_info &&i) = default

move assignment operator

Use compiler provided default implementation

image_info &operator=(const image_info &i) = default

copy assignment operator

Use compiler provided default implementation

size_t nx() const noexcept

get pixels along x

Return

number of pixels in x-direction (the slow direction)

size_t ny() const noexcept

get pixels along y

Return

number of pixels in y-direction (the fast direction)

size_t npixels() const noexcept

get total number of pixels

Computes the total number of pixels of the image (nx*ny).

Return

total number of pixels.

size_t bit_per_pixel() const

get number of bits per pixel

Return the number of bits per pixel.

Return

number of bits per pixel

std::vector<size_t> bits_per_channel() const

get bits per channel

Return the number of bits used to store data for each channel.

Return

vector with the number of bits for each channel

std::vector<pni::type_id_t> types_per_channel() const

get types per channel

Return a vector with the different types per channel.

Return

vector with data types for each channel

size_t nchannels() const

get number of channels

Return

number of channels

void append_channel(const image_channel_info &i)

append a new channel

Append information about a channel to the image information class.

Parameters

  • i: channel information

image_channel_info get_channel(size_t i) const

get channel information

Return the channel information for channle i.

Return

channel information.

Parameters

  • i: channel number

Related

PNINEXUS_EXPORT std::ostream &operator<<(std::ostream &o, const image_info &i)

brief output operator for ImageInfo

Overloaded output stream operator for the ImageInfo type.

Return

reference to the output stream

Parameters

  • o: reference to output stream

  • i: reference to an instance of ImageInfo

pni::image_channel_info

class pni::image_channel_info

image channel information class

image_channle_info holds information specific to a particular image channel.

Public Functions

image_channel_info()

default constructor

image_channel_info(const pni::type_id_t &id, size_t bits)

standard constructor

Parameters

  • id: Typd id for the channel

  • bits: number of bits used to store channel data

pni::type_id_t type_id() const

get type ID

Returns the TypeID for the channel described by this object.

Return

type ID

size_t bits() const

get bits

Return the number of bits used to store this channels data

Return

number of bits

Reader classes

pni::image_reader

class pni::image_reader : public pni::data_reader

base class for image readers

The image_reader class provides the basic functionality for all other image readers. It opens the file and provides a stream from which to read data. ImageReader objects cannot be copied or copy-assigned. However, they can be moved using std::move.

Like data_reader (from which it is derived) an ImageReader object cannot be instantiated using this class. All constructors and assignment operators are thus protected making them only available to derived classes.

Subclassed by pni::cbf_reader, pni::tiff_reader

Public Functions

~image_reader()

destructor

size_t nimages() const = 0

get number of images

Returns the number of images stored in the file. This methods reflects the fact that many image formats can hold more than one image in a single file (CBF, TIFF). Although this feature is hardly used for experiments it should be taken into account. This is a virtual function which must be implemented by the concrete reader classes.

Return

number of images

image_info info(size_t i) const = 0

get image info

Return an instance of ImageInfo with the information of image i in the image stack. This is a virtual function which must be implemented by the concrete reader classes.

Return

vector with ImageInfo objects

Parameters

  • i: index of the image

template<typename ArrayT>
ArrayT image(size_t i, size_t c)

method to read a single channel

This method returns an object determined by ArrayType holding the data from channel c (default is 0) of image i in the file.

This method must be implemented by all child classes of ImageReader. It is assumed that the method will allocate enough memory and configure the returning object appropriately.

Return

instance of ArrayType holding the channel data

Parameters

  • i: index of the image in the file

  • c: (default = 0) image channel to read

template<typename ArrayT>
void image(ArrayT &array, size_t i, size_t c)

method to read a single image channel

This method reads the data from channle c (default = 0) of image i in the file and stores it in an Array template supplied by the user. The array must provide enough space to hold the data otherwise exceptions will be thrown. The addvantage of this method is that it does not waste time with memory allocation. It is thus useful in cases where data from many files of same size must be read.

Parameters

  • array: array where to store the data

  • i: index of the image in the file

  • c: (default = 0) index of the channel from which to read data.

pni::tiff_reader

class pni::tiff_reader : public pni::image_reader

TIFF file reader.

TIFFReader is an implementation of the Reader class for reading TIFF image files. Actually only uncompressed TIFF images are supported. The copy constructor and the copy assignment operator are deleted to prevent copy construction of this object.

Public Functions

tiff_reader()

default constructor

tiff_reader(tiff_reader &&r)

move constructor

Parameters

  • r: reader from which to move data to the new instance

tiff_reader(const pni::string &fname)

standard constructor

tiff_reader(const tiff_reader&) = delete

copy constructor is deleted

~tiff_reader()

destructor

tiff_reader &operator=(tiff_reader &&r)

move assignment operator

tiff_reader &operator=(const tiff_reader &r) = delete

copy assignment operator is deleted

size_t nimages() const

get number of images

Return the number of images stored in the image file.

Return

number of images

image_info info(size_t i) const

get ImageInfo

Return an instance of ImageInfo for image i stored in the file.

Return

instance of ImageInfo for the requested image

Parameters

  • i: index of the image

void open()

open the file

void close()

close the file

template<typename ContainerT>
ContainerT image(size_t i, size_t c = 0)

read image data

Template method to read image data from the file. The returns an instance of the the template Array<T,BaseT> and does all the configuration and memory allocation work for this object.

Return

instance of an array template

Exceptions
Parameters

  • i: index of the image in the file

  • c: index of the image channel to read

template<typename ContainerT>
void image(ContainerT &data, size_t i, size_t c = 0)

read image data

Reads the image data from the file and stores it in a user suppliedb array object. The method checks if the arrays shape and allocation state fits the requirements of the image. The advantage of this method is that memory allocation must be done only once before this method is called. This increases performance dramatically in particular if many images of equal size should be read.

Exceptions

  • size_mismatch_error: if the size of the container does not match the number of pixels stored in the image

Parameters

  • data: instance of ContainerT where data will be stored

  • i: index of the image in the file

  • c: index of the image channel to read

Friends

PNINEXUS_EXPORT std::ostream &operator<<(std::ostream &o, const tiff_reader &r)

output operator of an TIFFReader object

pni::cbf_reader

class pni::cbf_reader : public pni::image_reader

base clase for CBF readers

CBFReader is the base class for all readers of data stored in binary CIF format. Although CBF is standardized by the ICUR the guys from Dectris (the vendor of the Pilatus detector) use a kind of dialect which must be treated in a slightly different way. The field _header_convention in the class indicates whether or not the header is in standard CBF format or in the Dectris dialect.

Reading a CBF file is a two step process:

  • the header is read and the information stored there kept in in a CIFBinaryHeader object

  • the binary data is read from the stream using a CBFBinStreamReader object The header information contains enough information to decide which binary reader to use and to construct the data objects which will hold the data read from the file. From such a point of view the header object can be consideres as a factory for the binary readers and the array objects holding the data.

Public Functions

cbf_reader()

default constructor

cbf_reader(const pni::string &fname)

construct reader object

The name of the CBFFile is passed as a String object. During instantiation of class the file is parsed. Throws an exception if the flavor of the CBF file cannot be deduced from the header.

Exceptions
Parameters

  • fname: name of the file

~cbf_reader()

destructor

cbf_reader(const cbf_reader &r) = delete

the copy constructor is deleted

cbf_reader &operator=(const cbf_reader &r) = delete

the copy assignment operator is deleted

cbf_reader &operator=(cbf_reader &&r) = default

move assignment

Use compiler provided default implementation here

void close()

close the file

void open()

open file

Opens the file given by filename.

Exceptions

  • FileError: in case of errors

size_t nimages() const

get number of images

Returns the number of images stored in the file. This methods reflects the fact that many image formats can hold more than one image in a single file (CBF, TIFF). Although this feature is hardly used for experiments it should be taken into account. This is a virtual function which must be implemented by the concrete reader classes.

Return

number of images

image_info info(size_t i) const

get image info

Return an instance of ImageInfo with the information of image i in the image stack. This is a virtual function which must be implemented by the concrete reader classes.

Return

vector with ImageInfo objects

Parameters

  • i: index of the image

template<typename ContainerT>
ContainerT image(size_t i, size_t c = 0)

read image

Return

instance of ContainerT with image data

Template Parameters

  • ContainerT: container type for storing data

Exceptions
Parameters

  • i: image number to read

  • c: channel to read (default = 0)

template<typename ContainerT>
void image(ContainerT &array, size_t i, size_t c = 0)

read data from detector file

Reads a single image from a detector file and stores it in an container of type ContainerT.

Exceptions
Template Parameters

  • ContainerT: container type holding the image data

Parameters

  • array: instance of ContainerT where data will be stored

  • i: image number

  • c: channel number