EMAN2
Public Types | Public Member Functions | Protected Member Functions
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:
Inheritance graph
[legend]

List of all members.

Public Types

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

Public Member Functions

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.
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.
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.
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.
virtual int read_ctf (Ctf &ctf, int image_index=0)
 Read CTF data from this image.
virtual void write_ctf (const Ctf &ctf, int image_index=0)
 Write CTF data to this image.
virtual void flush ()=0
 Flush the IO buffer.
virtual int get_nimg ()
 Return the number of images in this image file.
virtual bool is_complex_mode ()=0
 Is this an complex image or not.
virtual bool is_image_big_endian ()=0
 Is this image in big endian or not.
virtual bool is_single_image_format () const
 Is this image format only storing 1 image or not.
template<class T >
void become_host_endian (T *data, size_t n=1)
 Convert data of this image into host endian format.

Protected Member Functions

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

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:

Image region writing follows the following princeples:

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 130 of file imageio.h.


Member Enumeration Documentation

Enumerator:
READ_ONLY 
READ_WRITE 
WRITE_ONLY 

Definition at line 133 of file imageio.h.

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

Constructor & Destructor Documentation

ImageIO::~ImageIO ( ) [virtual]

Definition at line 48 of file imageio.cpp.

{
}

Member Function Documentation

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:
dataAn array of data. It can be any type, short, int, float, double, etc.
nArray size.

Definition at line 245 of file imageio.h.

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

void ImageIO::check_read_access ( int  image_index) [protected]

Validate 'image_index' in file reading.

Parameters:
image_indexThe 'image_index'th image. Valid value = [0, nimg-1].
Exceptions:
OutofRangeExceptionIf image_index is out of range.

Definition at line 99 of file imageio.cpp.

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

Referenced by check_read_access().

{
        init();

        int nimg = get_nimg();
        if (image_index < 0 || image_index >= nimg) {
                throw OutofRangeException(0, nimg-1, image_index, "image index");
        }
}
void ImageIO::check_read_access ( int  image_index,
const float *  data 
) [protected]

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

Parameters:
image_indexThe 'image_index'th image. Valid value = [0, nimg-1].
dataThe array used to store the image data in reading.
Exceptions:
NullPointerExceptionIf 'data' is NULL.
OutofRangeExceptionIf image_index is out of range.

Definition at line 109 of file imageio.cpp.

References check_read_access(), and NullPointerException.

{
        check_read_access(image_index);
        if (!data) {
                throw NullPointerException("image data is NULL");
        }
}
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:
areaThe image I/O region.
max_sizeThe upper limit of the region's size. The region must be within 'max_size'.
is_new_fileWhether it is on a new file or not.
inbounds_onlyif true verifies that the region is inside the image, otherwise no check is performed
Exceptions:
ImageReadExceptionAny image reading problem.

Definition at line 62 of file imageio.cpp.

References EMAN::Region::get_ndim(), EMAN::FloatSize::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().

{
        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);
                        }
                }
        }
}
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:
areaThe image I/O region.
max_sizeThe upper limit of the region's size. The region must be within 'max_size'.
is_new_fileWhether it is on a new file or not.
inbounds_onlyif true verifies that the region is inside the image, otherwise no check is performed
Exceptions:
ImageReadExceptionAny image reading problem.

Definition at line 92 of file imageio.cpp.

References check_region().

{
        check_region(area, FloatSize(max_size[0], max_size[1], max_size[2]),
                                 is_new_file,inbounds_only);
}
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_modeFile Read/Write mode.
image_indexThe 'image_index'th image. Valid value = [0, max_nimg].
max_nimgMaximum number of images in the file. If its value <= 0, don't check image_index against max_nimg.
Exceptions:
ImageWriteExceptionImage is not opened for writing.
OutofRangeExceptionIf image_index is out of range.

Definition at line 117 of file imageio.cpp.

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

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

{
        init();

        if (iomode == READ_ONLY) {
                throw ImageWriteException("", "File is not openned to write");
        }

        if ((image_index < -1) || (max_nimg > 0 && image_index >= max_nimg)) {
                throw OutofRangeException(-1, max_nimg - 1, image_index, "image index");
        }
}
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_modeFile Read/Write mode.
image_indexThe 'image_index'th image. Valid value = [0, max_nimg].
max_nimgMaximum number of images in the file. If its value <= 0, don't check image_index againt max_nimg.
dataThe data array to be writting to the image file.
Exceptions:
ImageWriteExceptionImage is not opened for writing.
OutofRangeExceptionIf image_index is out of range.

Definition at line 130 of file imageio.cpp.

References check_write_access(), and NullPointerException.

{
        check_write_access(iomode, image_index, max_nimg);
        if (!data) {
                throw NullPointerException("image data is NULL");
        }
}
virtual void EMAN::ImageIO::flush ( ) [pure virtual]

Flush the IO buffer.

Referenced by EMAN::EMData::write_image().

int ImageIO::get_nimg ( ) [virtual]

Return the number of images in this image file.

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

Definition at line 185 of file imageio.cpp.

References init().

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

{
        init();
        return 1;
}
virtual void EMAN::ImageIO::init ( ) [protected, pure virtual]
virtual bool EMAN::ImageIO::is_complex_mode ( ) [pure virtual]

Is this an complex image or not.

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

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().

virtual bool EMAN::ImageIO::is_single_image_format ( ) const [inline, virtual]

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, and EMAN::SingleSpiderIO.

Definition at line 234 of file imageio.h.

Referenced by EMAN::EMData::write_image().

                {
                        return true;
                }
int ImageIO::read_ctf ( Ctf ctf,
int  image_index = 0 
) [virtual]

Read CTF data from this image.

Parameters:
ctfUsed to store the CTF data.
image_indexThe index of the image to read.
Returns:
0 if OK; 1 if error.

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

Definition at line 52 of file imageio.cpp.

{
        return 1;
}
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:
dataAn array to store the data. It should be created outside of this function.
image_indexThe index of the image to read.
areaDefine an image-region to read.
is_3dWhether 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 EMAN::EMData::read_image().

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:
dictA keyed-dictionary to store the header information.
image_indexThe index of the image to read.
areaDefine an image-region to read.
is_3dWhether 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 EMAN::EMData::read_binedimage(), and EMAN::EMData::read_image().

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

Run fopen safely.

Parameters:
filenameThe file name to be opened.
modeFile open mode.
is_newIs this a new file?
overwriteIf the file exists, should we truncate it?
Exceptions:
FileAccessExceptionThe file has access error.
Returns:
The opened file pointer.

Definition at line 139 of file imageio.cpp.

References FileAccessException, READ_ONLY, READ_WRITE, and WRITE_ONLY.

{
        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;
}
void ImageIO::write_ctf ( const Ctf ctf,
int  image_index = 0 
) [virtual]

Write CTF data to this image.

Parameters:
ctfCtf instance storing the CTF data.
image_indexThe index of the image to write.
Returns:
0 if OK; 1 if error.

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

Definition at line 57 of file imageio.cpp.

{

}
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:
dataAn array storing the data.
image_indexThe index of the image to write.
areaThe region to write data to.
filestoragetypeThe image data type used in the output file.
use_host_endianWhether 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.

Referenced by EMAN::EMData::write_image().

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:
dictA keyed-dictionary storing the header information.
image_indexThe index of the image to write.
areaThe region to write data to.
filestoragetypeThe image data type used in the output file.
use_host_endianWhether 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.

Referenced by EMAN::EMData::write_image().


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