EMAN::ImageIO Class Reference

ImageIO classes are designed for reading/writing various electron micrography image formats, including MRC, IMAGIC, SPIDER, PIF, etc. More...

#include <imageio.h>

Inheritance diagram for EMAN::ImageIO:

Collaboration diagram for EMAN::ImageIO:

Public Types
enum	IOMode { READ_ONLY = 1 , READ_WRITE = 2 , WRITE_ONLY = 3 }

Public Member Functions
	ImageIO (const string &fname, IOMode rw)
virtual	~ImageIO ()
virtual int	read_header (Dict &dict, int image_index=0, const Region *area=0, bool is_3d=false)=0
	Read the header from an image. More...
virtual int	write_header (const Dict &dict, int image_index=0, const Region *area=0, EMUtil::EMDataType filestoragetype=EMUtil::EM_FLOAT, bool use_host_endian=true)=0
	Write a header to an image. More...
virtual int	read_data (float *data, int image_index=0, const Region *area=0, bool is_3d=false)=0
	Read the data from an image. More...
virtual int	read_data_8bit (unsigned char *data, int image_index=0, const Region *area=0, bool is_3d=false, float minval=0.0f, float maxval=0.0f)
	Read the data from an image as an 8 bit array, regardless of format. More...
virtual int	write_data (float *data, int image_index=0, const Region *area=0, EMUtil::EMDataType filestoragetype=EMUtil::EM_FLOAT, bool use_host_endian=true)=0
	Write data to an image. More...
virtual int	read_ctf (Ctf &ctf, int image_index=0)
	Read CTF data from this image. More...
virtual void	write_ctf (const Ctf &ctf, int image_index=0)
	Write CTF data to this image. More...
virtual void	flush ()=0
	Flush the IO buffer. More...
virtual int	get_nimg ()
	Return the number of images in this image file. More...
virtual bool	is_complex_mode ()=0
	Is this an complex image or not. More...
virtual bool	is_image_big_endian ()=0
	Is this image in big endian or not. More...
virtual bool	is_single_image_format () const
	Is this image format only storing 1 image or not. More...
template<class T >
void	become_host_endian (T *data, size_t n=1)
	Convert data of this image into host endian format. More...
string	get_filename () const

Protected Member Functions
virtual void	init ()=0
	Do some initialization before doing the read/write. More...
void	check_read_access (int image_index)
	Validate 'image_index' in file reading. More...
void	check_read_access (int image_index, const float *data)
	Validate 'image_index' and 'data' in file reading. More...
void	check_write_access (IOMode rw_mode, int image_index, int max_nimg=0)
	Validate rw_mode and image_index in file writing. More...
void	check_write_access (IOMode rw_mode, int image_index, int max_nimg, const float *data)
	Validate rw_mode, image_index, and data pointer in file writing. More...
void	check_region (const Region *area, const FloatSize &max_size, bool is_new_file=false, bool inbounds_only=true)
	Validate image I/O region. More...
void	check_region (const Region *area, const IntSize &max_size, bool is_new_file=false, bool inbounds_only=true)
	Validate image I/O region. More...
FILE *	sfopen (const string &filename, IOMode mode, bool *is_new=0, bool overwrite=false)
	Run fopen safely. More...

Protected Attributes
string	filename
IOMode	rw_mode
FILE *	file = nullptr
bool	initialized = false

Detailed Description

ImageIO classes are designed for reading/writing various electron micrography image formats, including MRC, IMAGIC, SPIDER, PIF, etc.

ImageIO class is the base class for all image io classes. Each subclass defines the IO routines for reading/writing a type of image format. For example, MrcIO is for reading/writing MRC images.

A subclass should implement functions declared in DEFINE_IMAGEIO_FUNC macro.

Image header I/O is separated from image data I/O.

Some image formats (e.g., MRC, DM3, Gatan2, TIFF, PNG, EM, ICOS) only store a single 2D or 3D images. For them, image_index should always be 0. To read/write part of the image, use a region.

Some image formats (e.g., Imagic) can store either a stack of 2D images or a single 3D image. From the physical image file itself, there is no difference between them. Only at reading time, they may be treated as either a stack of 2D images, or a single 3D image. A boolean hint should be given for these formats at reading time.

Some image formats (e.g. HDF, PIF) can store a stack of images. Each image can be 2D or 3D.

For image formats storing multiple images, valid image_index = [0, n].

For image formats storing multiple images, the image append and insertion policy is:

• it should support appending image to existing file.
• it should support appending image to new file.
• it should support insert image in existing file with gap between EOF and the new image. The gap should be zeroed.
• it should support insert image in new file with image index != 0.
• insert image in existing file overwriting existing image.
• The gap from insertion or appending should be filled with zero.

Image region writing follows the following principles:

• The file must exist before writing a region to it.
• The image header usually won't be changed except the statistics fields and timestamp.
• The region must be inside the original image.
• If the new data are in different endian from the endian of the original image, swap the new data.
• If the new data are of different data type from the data type of the original image, convert the new data. This may lose information when converting from longer data type to shorter data type.

Each ImageIO subclass XYZ must define a static function to determine whether a given image is a valid XYZ image or not. It looks like: static bool is_valid(const void *first_block); 'first_block' is the first block of binary data in that image file.

The typical way to use an ImageIO instance is: a) To read: ImageIO *imageio = EMUtil::get_imageio(filename, ImageIO::READ_ONLY); int err = imageio->read_header(dict, img_index, region, is_3d); err = imageio->read_ctf(ctf, img_index); err = imageio->read_data(data, img_index, region, is_3d);

b) To write: similar to read.

Definition at line 126 of file imageio.h.

Member Enumeration Documentation

IOMode

enum EMAN::ImageIO::IOMode

Enumerator
READ_ONLY
READ_WRITE
WRITE_ONLY

Definition at line 129 of file imageio.h.

{ READ_ONLY = 1, READ_WRITE = 2, WRITE_ONLY = 3 };

Constructor & Destructor Documentation

ImageIO()

ImageIO::ImageIO	(	const string &	fname,
		IOMode	rw
	)

Definition at line 40 of file imageio.cpp.

                : filename(fname), rw_mode(rw)
{}

~ImageIO()

ImageIO::~ImageIO ( )

virtual

Definition at line 44 of file imageio.cpp.

{
}

Member Function Documentation

become_host_endian()

template<class T >

void EMAN::ImageIO::become_host_endian ( T *  data, size_t  n = 1  )

inline

Convert data of this image into host endian format.

Parameters

data	An array of data. It can be any type, short, int, float, double, etc.
n	Array size.

Definition at line 261 of file imageio.h.

                {
                        if (is_image_big_endian() != ByteOrder::is_host_big_endian()) {
                                ByteOrder::swap_bytes(data, n);
                        }
                }

References EMAN::ByteOrder::is_host_big_endian(), is_image_big_endian(), and EMAN::ByteOrder::swap_bytes().

check_read_access() [1/2]

void ImageIO::check_read_access ( int  image_index )

protected

Validate 'image_index' in file reading.

Parameters

image_index

The 'image_index'th image. Valid value = [0, nimg-1].

Exceptions

OutofRangeException

If image_index is out of range.

Definition at line 95 of file imageio.cpp.

{
        init();
 
        int nimg = get_nimg();
        if (image_index < 0 || image_index >= nimg) {
                throw OutofRangeException(0, nimg-1, image_index, "image index");
        }
}

References get_nimg(), init(), and OutofRangeException.

Referenced by check_read_access().

check_read_access() [2/2]

void ImageIO::check_read_access ( int  image_index, const float *  data  )

protected

Validate 'image_index' and 'data' in file reading.

Parameters

image_index	The 'image_index'th image. Valid value = [0, nimg-1].
data	The array used to store the image data in reading.

Exceptions

NullPointerException	If 'data' is NULL.
OutofRangeException	If image_index is out of range.

Definition at line 105 of file imageio.cpp.

{
        check_read_access(image_index);
        if (!data) {
                throw NullPointerException("image data is NULL");
        }
}

References check_read_access(), and NullPointerException.

check_region() [1/2]

void ImageIO::check_region ( const Region *  area, const FloatSize &  max_size, bool  is_new_file = false, bool  inbounds_only = true  )

protected

Validate image I/O region.

Parameters

area	The image I/O region.
max_size	The upper limit of the region's size. The region must be within 'max_size'.
is_new_file	Whether it is on a new file or not.
inbounds_only	if true verifies that the region is inside the image, otherwise no check is performed

Exceptions

ImageReadException

Any image reading problem.

Definition at line 58 of file imageio.cpp.

{
        if (area) {
                if (is_new_file) {
                        throw ImageReadException("", "file must exist before accessing its region");
                }
                int img_ndim = max_size.get_ndim();
                int area_ndim = area->get_ndim();
 
                if (area_ndim > img_ndim) {
                        char desc[256];
                        sprintf(desc, "Image is %dD. Cannot read %dD region", img_ndim, area_ndim);
                        throw ImageReadException("", desc);
                }
 
                // EMUtil::process_region_io handles regions that are outside the image. So some image types don't mind if the
                // region is beyond the boundary. It would be ideal if they all could do this, but it would take some work.
                if (inbounds_only ){
                        if (!area->is_region_in_box(max_size)) {
                                char desc[1024];
                                sprintf(desc, "Region box %s is outside image area (%d,%d,%d)",
                                                area->get_string().c_str(), (int)max_size[0],
                                                (int)max_size[1], (int)max_size[2]);
                                throw ImageReadException("", desc);
                        }
                }
        }
}

References EMAN::FloatSize::get_ndim(), EMAN::Region::get_ndim(), EMAN::Region::get_string(), ImageReadException, and EMAN::Region::is_region_in_box().

Referenced by check_region(), EMAN::MrcIO::read_fei_header(), EMAN::MrcIO::read_mrc_header(), EMAN::SpiderIO::write_single_data(), and EMAN::SpiderIO::write_single_header().

check_region() [2/2]

void ImageIO::check_region ( const Region *  area, const IntSize &  max_size, bool  is_new_file = false, bool  inbounds_only = true  )

protected

Validate image I/O region.

Parameters

area	The image I/O region.
max_size	The upper limit of the region's size. The region must be within 'max_size'.
is_new_file	Whether it is on a new file or not.
inbounds_only	if true verifies that the region is inside the image, otherwise no check is performed

Exceptions

ImageReadException

Any image reading problem.

Definition at line 88 of file imageio.cpp.

{
        check_region(area, FloatSize(max_size[0], max_size[1], max_size[2]),
                                 is_new_file,inbounds_only);
}

References check_region().

check_write_access() [1/2]

void ImageIO::check_write_access ( IOMode  rw_mode, int  image_index, int  max_nimg, const float *  data  )

protected

Validate rw_mode, image_index, and data pointer in file writing.

Parameters

rw_mode	File Read/Write mode.
image_index	The 'image_index'th image. Valid value = [0, max_nimg].
max_nimg	Maximum number of images in the file. If its value <= 0, don't check image_index againt max_nimg.
data	The data array to be writing to the image file.

Exceptions

ImageWriteException	Image is not opened for writing.
OutofRangeException	If image_index is out of range.

Definition at line 126 of file imageio.cpp.

{
        check_write_access(iomode, image_index, max_nimg);
        if (!data) {
                throw NullPointerException("image data is NULL");
        }
}

References check_write_access(), and NullPointerException.

check_write_access() [2/2]

void ImageIO::check_write_access ( IOMode  rw_mode, int  image_index, int  max_nimg = 0  )

protected

Validate rw_mode and image_index in file writing.

Parameters

rw_mode	File Read/Write mode.
image_index	The 'image_index'th image. Valid value = [0, max_nimg].
max_nimg	Maximum number of images in the file. If its value <= 0, don't check image_index against max_nimg.

Exceptions

ImageWriteException	Image is not opened for writing.
OutofRangeException	If image_index is out of range.

Definition at line 113 of file imageio.cpp.

{
        init();
 
        if (iomode == READ_ONLY) {
                throw ImageWriteException("", "File is not opened to write");
        }
 
        if ((image_index < -1) || (max_nimg > 0 && image_index >= max_nimg)) {
                throw OutofRangeException(-1, max_nimg - 1, image_index, "image index");
        }
}

References ImageWriteException, init(), OutofRangeException, and READ_ONLY.

Referenced by check_write_access(), EMAN::SpiderIO::write_single_data(), and EMAN::SpiderIO::write_single_header().

flush()

virtual void EMAN::ImageIO::flush ( )

pure virtual

Flush the IO buffer.

get_filename()

string EMAN::ImageIO::get_filename ( ) const

inline

Definition at line 268 of file imageio.h.

                                            {
                        return filename;
                }

References filename.

get_nimg()

int ImageIO::get_nimg ( )

virtual

Return the number of images in this image file.

Reimplemented in EMAN::DM4IO, EMAN::EerIO, EMAN::ImagicIO, EMAN::ImagicIO2, EMAN::LstFastIO, EMAN::LstIO, EMAN::MrcIO, EMAN::PifIO, EMAN::SerIO, EMAN::SpiderIO, and EMAN::XYZIO.

Definition at line 176 of file imageio.cpp.

{
        init();
        return 1;
}

References init().

Referenced by check_read_access(), and EMAN::EMUtil::get_image_count().

init()

virtual void EMAN::ImageIO::init ( )

protectedpure virtual

Do some initialization before doing the read/write.

Referenced by check_read_access(), check_write_access(), EMAN::DM4IO::get_nimg(), get_nimg(), EMAN::ImagicIO::get_nimg(), EMAN::ImagicIO2::get_nimg(), EMAN::LstFastIO::get_nimg(), EMAN::LstIO::get_nimg(), EMAN::MrcIO::get_nimg(), EMAN::PifIO::get_nimg(), EMAN::SerIO::get_nimg(), EMAN::SpiderIO::get_nimg(), EMAN::XYZIO::get_nimg(), EMAN::FitsIO::read_ctf(), EMAN::MrcIO::read_ctf(), EMAN::MrcIO::read_fei_header(), EMAN::FitsIO::write_ctf(), EMAN::MrcIO::write_ctf(), EMAN::ImagicIO::write_ctf(), and EMAN::ImagicIO2::write_ctf().

is_complex_mode()

virtual bool EMAN::ImageIO::is_complex_mode ( )

pure virtual

Is this an complex image or not.

Referenced by read_binedimage(), and EMAN::MrcIO::read_mrc_header().

is_image_big_endian()

virtual bool EMAN::ImageIO::is_image_big_endian ( )

pure virtual

Is this image in big endian or not.

Referenced by become_host_endian(), and EMAN::EMData::save_byteorder_to_dict().

is_single_image_format()

virtual bool EMAN::ImageIO::is_single_image_format ( ) const

inlinevirtual

Is this image format only storing 1 image or not.

Some image formats like MRC only store 1 image in a file, so this function returns 'true' for them. Other image formats like IMAGIC/HDF5 may store mutliple images, so this function returns 'false' for them.

Reimplemented in EMAN::ImagicIO, EMAN::ImagicIO2, EMAN::LstFastIO, EMAN::LstIO, EMAN::PifIO, EMAN::SpiderIO, EMAN::SingleSpiderIO, and EMAN::EerIO.

Definition at line 250 of file imageio.h.

                {
                        return true;
                }

read_ctf()

int ImageIO::read_ctf ( Ctf &  ctf, int  image_index = 0  )

virtual

Read CTF data from this image.

Parameters

ctf	Used to store the CTF data.
image_index	The index of the image to read.

Returns

0 if OK; 1 if error.

Reimplemented in EMAN::FitsIO, and EMAN::MrcIO.

Definition at line 48 of file imageio.cpp.

{
        return 1;
}

read_data()

virtual int EMAN::ImageIO::read_data ( float *  data, int  image_index = 0, const Region *  area = 0, bool  is_3d = false  )

pure virtual

Read the data from an image.

Parameters

data	An array to store the data. It should be created outside of this function.
image_index	The index of the image to read.
area	Define an image-region to read.
is_3d	Whether to treat the image as a single 3D or a set of 2Ds. This is a hint for certain image formats which has no difference between 3D image and set of 2Ds.

Returns

0 if OK; 1 if error.

read_data_8bit()

virtual int EMAN::ImageIO::read_data_8bit ( unsigned char *  data, int  image_index = 0, const Region *  area = 0, bool  is_3d = false, float  minval = 0.0f, float  maxval = 0.0f  )

inlinevirtual

Read the data from an image as an 8 bit array, regardless of format.

Parameters

data	An array to store the data. It should be created outside of this function.
image_index	The index of the image to read (image number in file).
area	If provided reads only the specified region.
is_3d	Whether to treat the image as a single 3D or a set of 2Ds. This is a hint for certain image formats which has no difference between 3D image and set of 2Ds.
minval	image value to map to 0 in the returned unsigned char
maxval	image value to map to 255 in the returned unsigned char. If minval==maxval, autoscaling will be used.

Returns

0 if OK; 1 if error.

Definition at line 193 of file imageio.h.

                                                                                                                                                 {
                        throw ImageFormatException("8 bit reading not supported for this format");
                }

References ImageFormatException.

read_header()

virtual int EMAN::ImageIO::read_header ( Dict &  dict, int  image_index = 0, const Region *  area = 0, bool  is_3d = false  )

pure virtual

Read the header from an image.

Parameters

dict	A keyed-dictionary to store the header information.
image_index	The index of the image to read.
area	Define an image-region to read.
is_3d	Whether to treat the image as a single 3D or a set of 2Ds. This is a hint for certain image formats which has no difference between 3D image and set of 2Ds.

Returns

0 if OK; 1 if error.

Referenced by read_binedimage().

sfopen()

FILE * ImageIO::sfopen ( const string &  filename, IOMode  mode, bool *  is_new = 0, bool  overwrite = false  )

protected

Run fopen safely.

Parameters

filename	The file name to be opened.
mode	File open mode.
is_new	Is this a new file?
overwrite	If the file exists, should we truncate it?

Exceptions

FileAccessException

The file has access error.

Returns

The opened file pointer.

Definition at line 135 of file imageio.cpp.

{
        FILE *f = 0;
        if (mode == READ_ONLY)
                f = fopen(filename.c_str(), "rb");
        else if (mode == READ_WRITE) {
                if (overwrite) {
                        f = fopen(filename.c_str(), "wb");
                        if (is_new)
                                *is_new = true;
                }
                else {
                        f = fopen(filename.c_str(), "r+b");
                        if (!f) {
                                FILE *f1 = fopen(filename.c_str(), "wb");
                                if (!f1)
                                        throw FileAccessException(filename);
                                else {
                                        if (is_new)
                                                *is_new = true;
                                        fclose(f1);
                                        f1 = 0;
                                        f = fopen(filename.c_str(), "r+b");
                                }
                        }
                }
        }
        else if (mode == WRITE_ONLY) {
                f = fopen(filename.c_str(), "wb");
                if (is_new)
                        *is_new = true;
        }
 
        if (!f)
                throw FileAccessException(filename);
 
        return f;
}

References FileAccessException, filename, READ_ONLY, READ_WRITE, and WRITE_ONLY.

write_ctf()

void ImageIO::write_ctf ( const Ctf &  ctf, int  image_index = 0  )

virtual

Write CTF data to this image.

Parameters

ctf	Ctf instance storing the CTF data.
image_index	The index of the image to write.

Returns

0 if OK; 1 if error.

Reimplemented in EMAN::FitsIO, and EMAN::MrcIO.

Definition at line 53 of file imageio.cpp.

{
 
}

write_data()

virtual int EMAN::ImageIO::write_data ( float *  data, int  image_index = 0, const Region *  area = 0, EMUtil::EMDataType  filestoragetype = EMUtil::EM_FLOAT, bool  use_host_endian = true  )

pure virtual

Write data to an image.

Parameters

data	An array storing the data.
image_index	The index of the image to write.
area	The region to write data to.
filestoragetype	The image data type used in the output file.
use_host_endian	Whether to use the host machine endian to write out or not. If false, use the endian opposite to the host machine's endian.

Returns

0 if OK; 1 if error.

Implemented in EMAN::SingleSpiderIO.

write_header()

virtual int EMAN::ImageIO::write_header ( const Dict &  dict, int  image_index = 0, const Region *  area = 0, EMUtil::EMDataType  filestoragetype = EMUtil::EM_FLOAT, bool  use_host_endian = true  )

pure virtual

Write a header to an image.

Parameters

dict	A keyed-dictionary storing the header information.
image_index	The index of the image to write.
area	The region to write data to.
filestoragetype	The image data type used in the output file.
use_host_endian	Whether to use the host machine endian to write out or not. If false, use the endian opposite to the host machine's endian.

Returns

0 if OK; 1 if error.

Implemented in EMAN::SingleSpiderIO.

Member Data Documentation

file

FILE* EMAN::ImageIO::file = nullptr

protected

Definition at line 354 of file imageio.h.

Referenced by EMAN::LstFastIO::calc_ref_image_index(), EMAN::LstIO::calc_ref_image_index(), EMAN::PifIO::fseek_to(), EMAN::DM4IO::get_nimg(), EMAN::SerIO::get_nimg(), EMAN::PifIO::PifIO(), EMAN::SerIO::read_data_element(), EMAN::SerIO::read_data_tag(), EMAN::VtkIO::read_dataset(), EMAN::SerIO::read_dim_arr(), EMAN::MrcIO::read_fei_header(), EMAN::MrcIO::update_stats(), EMAN::MrcIO::write_ctf(), EMAN::SpiderIO::write_single_data(), EMAN::SpiderIO::write_single_header(), EMAN::AmiraIO::~AmiraIO(), EMAN::Df3IO::~Df3IO(), EMAN::DM3IO::~DM3IO(), EMAN::DM4IO::~DM4IO(), EMAN::EmIO::~EmIO(), EMAN::FitsIO::~FitsIO(), EMAN::Gatan2IO::~Gatan2IO(), EMAN::IcosIO::~IcosIO(), EMAN::LstFastIO::~LstFastIO(), EMAN::LstIO::~LstIO(), EMAN::MrcIO::~MrcIO(), EMAN::OmapIO::~OmapIO(), EMAN::PgmIO::~PgmIO(), EMAN::PifIO::~PifIO(), EMAN::SalIO::~SalIO(), EMAN::SerIO::~SerIO(), EMAN::SitusIO::~SitusIO(), EMAN::SpiderIO::~SpiderIO(), EMAN::VtkIO::~VtkIO(), and EMAN::XplorIO::~XplorIO().

filename

string EMAN::ImageIO::filename

protected

Definition at line 352 of file imageio.h.

Referenced by EMAN::LstFastIO::calc_ref_image_index(), EMAN::LstIO::calc_ref_image_index(), EMAN::EerIO::EerIO(), get_filename(), EMAN::SerIO::get_nimg(), EMAN::ImagicIO::ImagicIO(), EMAN::ImagicIO2::ImagicIO2(), EMAN::ImagicIO2::init_test(), EMAN::SerIO::read_data_element(), EMAN::SerIO::read_data_tag(), EMAN::VtkIO::read_dataset(), EMAN::SerIO::read_dim_arr(), EMAN::MrcIO::read_fei_header(), EMAN::MrcIO::read_mrc_header(), sfopen(), EMAN::SpiderIO::SpiderIO(), EMAN::MrcIO::update_stats(), EMAN::MrcIO::write_ctf(), EMAN::SpiderIO::write_single_data(), and EMAN::SpiderIO::write_single_header().

initialized

bool EMAN::ImageIO::initialized = false

protected

Definition at line 355 of file imageio.h.

Referenced by EMAN::VtkIO::get_datasettype_from_name(), EMAN::VtkIO::get_datatype_from_name(), and EMAN::ImagicIO2::init_test().

rw_mode

IOMode EMAN::ImageIO::rw_mode

protected

Definition at line 353 of file imageio.h.

Referenced by EMAN::LstFastIO::calc_ref_image_index(), EMAN::LstIO::calc_ref_image_index(), EMAN::SpiderIO::write_single_data(), and EMAN::SpiderIO::write_single_header().

---

The documentation for this class was generated from the following files:

• imageio.h
• imageio.cpp