Image reader API

Utility classes

pni::image_info

class image_info

image information type

ImageInfo holds basic information about a particular image.

Public Functions

inline 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

inline size_t nx() const noexcept

get pixels along x

Returns:

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

inline size_t ny() const noexcept

get pixels along y

Returns:

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

inline size_t npixels() const noexcept

get total number of pixels

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

Returns:

total number of pixels.

inline size_t bit_per_pixel() const

get number of bits per pixel

Return the number of bits per pixel.

Returns:

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.

Returns:

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.

Returns:

vector with data types for each channel

inline size_t nchannels() const

get number of channels

Returns:

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.

Parameters:

i – channel number

Returns:

channel information.

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.

Parameters:

  • o – reference to output stream

  • i – reference to an instance of ImageInfo

Returns:

reference to the output stream

pni::image_channel_info

class image_channel_info

image channel information class

image_channle_info holds information specific to a particular image channel.

Public Functions

inline image_channel_info()

default constructor

inline 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

inline pni::type_id_t type_id() const

get type ID

Returns the TypeID for the channel described by this object.

Returns:

type ID

inline size_t bits() const

get bits

Return the number of bits used to store this channels data

Returns:

number of bits

Reader classes

pni::image_reader

class 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

virtual ~image_reader()

destructor

virtual 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.

Returns:

number of images

virtual 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.

Parameters:

i – index of the image

Returns:

vector with ImageInfo objects

template<typename ArrayT>
inline 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.

Parameters:

  • i – index of the image in the file

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

Returns:

instance of ArrayType holding the channel data

template<typename ArrayT>
inline 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 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

explicit 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

virtual size_t nimages() const

get number of images

Return the number of images stored in the image file.

Returns:

number of images

virtual image_info info(size_t i) const

get ImageInfo

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

Parameters:

i – index of the image

Returns:

instance of ImageInfo for the requested image

virtual void open()

open the file

virtual void close()

close the file

template<typename ContainerT>
inline 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.

Throws:

memory_allocation_error – if array allocation fails

Parameters:

  • i – index of the image in the file

  • c – index of the image channel to read

Returns:

instance of an array template

template<typename ContainerT>
inline 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.

Throws:

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 friend std::ostream &operator<<(std::ostream &o, const tiff_reader &r)

output operator of an TIFFReader object

pni::cbf_reader

class 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.

Throws:

file_error – if the CBF flavor cannot be deduced

Parameters:

fname – name of the file

virtual ~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

virtual void close()

close the file

virtual void open()

open file

Opens the file given by filename.

Throws:

FileError – in case of errors

virtual 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.

Returns:

number of images

virtual 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.

Parameters:

i – index of the image

Returns:

vector with ImageInfo objects

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

read image

Template Parameters:

ContainerT – container type for storing data

Throws:
Parameters:

  • i – image number to read

  • c – channel to read (default = 0)

Returns:

instance of ContainerT with image data

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.

Throws:
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