Iimage modules

These modules contain functions for identifying and doing I/O from MRC and other file types defined in an image-type independent manner in the ImodImageFile structure.

Header to include: iimage.h

Functions in iimage.c


void iiAddCheckFunction(IIFileCheckFunction func)
void iiInsertCheckFunction(IIFileCheckFunction func, int index)
void iiDeleteCheckList()
ImodImageFile *iiNew()
int iiInit(ImodImageFile *i, int xsize, int ysize, int zsize, int file, int format, int type)
ImodImageFile *iiOpen(const char *filename, char *mode)
int iiReopen(ImodImageFile *inFile)
int iiSetMM(ImodImageFile *inFile, float inMin, float inMax, float scaleMax)
void iiClose(ImodImageFile *inFile)
void iiDelete(ImodImageFile *inFile)
int iiReadSection(ImodImageFile *inFile, char *buf, int inSection)
int iiReadSectionByte(ImodImageFile *inFile, char *buf, int inSection)
int iiReadSectionUShort(ImodImageFile *inFile, char *buf, int inSection)
int iiWriteSection(ImodImageFile *inFile, char *buf, int inSection)
int iiLoadPCoord(ImodImageFile *inFile, int useMdoc, IloadInfo *li, int nx, int ny, int nz)

Functions in iilikemrc.c


void iiAddRawCheckFunction(IIRawCheckFunction func, char *name)
void iiDeleteRawCheckList()
int iiLikeMRCCheck(ImodImageFile *inFile)
int iiSetupRawHeaders(ImodImageFile *inFile, RawImageInfo *info)
int analyzeDM3(FILE *fp, char *filename, int dmformat, RawImageInfo *info, int *dmtype)

Structures and Definitions for ImodImageFiles


ImodImageFile definitions
Raw mode codes
ImodImageFile structure
RawImageInfo structure

Functions in iimage.c

void iiAddCheckFunction(IIFileCheckFunction func)

Adds the given function to the end of the list of functions that iiOpen will call to check a file.  The format of the function is
  int iiFormatCheck(ImodImageFile *inFile)

void iiInsertCheckFunction(IIFileCheckFunction func, int index)

Insert the given function into the list of functions that iiOpen will call to check a file at position index in the list.  The format of the function is
  int iiFormatCheck(ImodImageFile *inFile)

void iiDeleteCheckList()

Frees the checking list to avoid memory leaks

ImodImageFile *iiNew()

Creates a new image file structure and initialize it to default or null values.  Returns 1 for error.

int iiInit(ImodImageFile *i, int xsize, int ysize, int zsize, int file, int format, int type)

Initializes the image file structure i for the given size and other characteristics

ImodImageFile *iiOpen(const char *filename, char *mode)

Tries to open an image file with name filename and with the fopen mode mode (e.g. "rb"), using the file format check functions on the list. If filename is NULL or an empty string, then it assigns stdin to the file pointer.  Returns NULL for error; it and all checking routines should call b3dError with their error strings.

int iiReopen(ImodImageFile *inFile)

Reopen a file that has already been opened and analyzed

int iiSetMM(ImodImageFile *inFile, float inMin, float inMax, float scaleMax)

Sets the scaling min and max (smin and smax in the image file structure inFile and computes the scaling slope and offset that will map smin to and smax to scaleMax by scaling with value * slope + offset. Uses the input values inMin and inMax, or the file min and max if these values are equal.  Returns 0.

void iiClose(ImodImageFile *inFile)

Closes an image file inFile

void iiDelete(ImodImageFile *inFile)

Deletes an image file inFile after closing and calling any cleanup functions

int iiReadSection(ImodImageFile *inFile, char *buf, int inSection)

Reads the section inSection from the file inFile as raw data into buffer buf.  Returns -1 for undefined reading function or failure to reopen file, otherwise passes along return value of the reading function.

int iiReadSectionByte(ImodImageFile *inFile, char *buf, int inSection)

Reads the section inSection from the file inFile as scaled byte data into buffer buf.  Returns -1 for undefined reading function or failure to reopen file, otherwise passes along return value of the reading function.

int iiReadSectionUShort(ImodImageFile *inFile, char *buf, int inSection)

Reads the section inSection from the file inFile as scaled unsigned short data into buffer buf.  Returns -1 for undefined reading function or failure to reopen file, otherwise passes along return value of the reading function.

int iiWriteSection(ImodImageFile *inFile, char *buf, int inSection)

Write data in the buffer buf to section inSection of the file inFile. Returns -1 for undefined writing function or failure to reopen file; otherwise passes along return value of the writing function.  Note that neither iimrc nor iitiff define writing functions.

int iiLoadPCoord(ImodImageFile *inFile, int useMdoc, IloadInfo *li, int nx, int ny, int nz)

Loads piece coordinates from an MRC file inFile of size nx, ny, nz and places them in the LoadInfo structure li.  If no coordinates are found and useMdoc is non-zero, it then tries to load coordinates from a metadata file named as the image filename plus .mdoc.  Returns 0 regardless of whether there are piece coordinates or errors.

Functions in iilikemrc.c

An MRC-like file consists of images that are all of equal size, where each image is a continuous series of numbers organized as one horizontal line after another. The images start after a header of a defined size and there can be a fixed amount to skip between each image.

void iiAddRawCheckFunction(IIRawCheckFunction func, char *name)

Add the given raw-type checking function func to the front of the checking list; name is a name for the format.  The definition of such a function is
  int checkMyFormat(FILE *fp, char *filename, RawImageInfo *info)

void iiDeleteRawCheckList()

Frees the checking list and all its data to avoid memory leaks

int iiLikeMRCCheck(ImodImageFile *inFile)

Checks the image file in inFile for one known MRC-like (raw-type) format after another. Returns IIERR codes for errors.  b3dError is called with a message for all errors that occur during checking, except for IIERR_NOT_FORMAT.

int iiSetupRawHeaders(ImodImageFile *inFile, RawImageInfo *info)

Creates an MRC header and fills it and the items in inFile from the information in info; specifically the nx, ny, nz, swapBytes, headerSize, sectionSkip, yInverted, and type members. Returns IOERR_MEMORY_ERR for error allocating header.

int analyzeDM3(FILE *fp, char *filename, int dmformat, RawImageInfo *info, int *dmtype)

Analyzes a file known to be a DigitalMicrograph version 3; the file pointer is in fp and the filename in filename.  Returns size, type, and other information in info; specifically the nx, ny, nz, swapBytes, headerSize, and type members.  Returns IOERR_IO_ERROR for errors reading the file or IOERR_NO_SUPPORT for other errors in analyzing the file.

Structures and Definitions for ImodImageFiles

ImodImageFile definitions

Values for the file member of ImodImageFile, describing kind of file
#define IIFILE_UNKNOWN 0
#define IIFILE_TIFF    1
#define IIFILE_MRC     2
#define IIFILE_QIMAGE  3
#define IIFILE_RAW     4

  /* Values for the format member of ImodImageFile, describing kind data */
#define IIFORMAT_LUMINANCE 0
#define IIFORMAT_RGB       1
#define IIFORMAT_RGBA      2
#define IIFORMAT_COMPLEX   3
#define IIFORMAT_COLORMAP  4

  /* Values for the type member of ImodImageFile, describing numeric type */
#define IITYPE_UBYTE   0
#define IITYPE_BYTE  1
#define IITYPE_SHORT  2
#define IITYPE_USHORT 3
#define IITYPE_INT    4
#define IITYPE_UINT   5
#define IITYPE_FLOAT  6

  /* Values for the state member of ImodImageFile, describing file state */
#define IISTATE_NOTINIT 0
#define IISTATE_PARK    1
#define IISTATE_READY   2
#define IISTATE_BUSY    4

  /* Error codes, used by check routines */
#define IIERR_BAD_CALL  -1
#define IIERR_NOT_FORMAT 1
#define IIERR_IO_ERROR   2
#define IIERR_MEMORY_ERR 3
#define IIERR_NO_SUPPORT 4

Raw mode codes

Yet another set of mode values, which define the order for radio buttons in a raw type selector dialog
#define RAW_MODE_SBYTE         0
#define RAW_MODE_BYTE          1
#define RAW_MODE_SHORT         2
#define RAW_MODE_USHORT        3
#define RAW_MODE_FLOAT         4
#define RAW_MODE_COMPLEX_FLOAT 5
#define RAW_MODE_RGB           6

ImodImageFile structure

typedef struct ImodImageFileStruct ImodImageFile;
  typedef int (*iiSectionFunc)(ImodImageFile *inFile, char *buf, int inSection);

  struct  ImodImageFileStruct
  {
    char *filename;
    char *fmode;
    FILE *fp;
    char *description;
    int   state;

    /* Data set by new and open functions. */
    int   nx, ny, nz;
    int   file;       /* Type of file, i.e. MRC, TIF... */
    int   format;     /* Kind of data represented: i.e. gray, color, complex */
    int   type;       /* Type if numerical elements, i.e. byte, etc. */
    int   mode;       /* MRC mode value */

    /* optional data to be set if input file supports it. */
    float amin, amax, amean;
    float xscale, yscale, zscale;
    float xtrans, ytrans, ztrans;
    float xrot,   yrot,   zrot;
    int   time, wave;

    /* load info: change these for loading sub sections. */
    int   llx, lly, llz, urx, ury, urz;
    float slope, offset, smin, smax;
    int   axis;
    int   mirrorFFT;   /* Return mirrored FFT when scaling to bytes */

    /* extra storage used by individual file format functions. */
    int   headerSize;
    int   sectionSkip;
    char *header;
    char *userData;
    unsigned char *colormap;
    int  planesPerImage;     /* # of planes per TIFF image */
    int  contigSamples;      /* # of contiguous samples per pixel in plane */
    int  multipleSizes;      /* Flag that TIFF file has multiple sizes */
    int  rgbSamples;         /* Number of samples for RGB TIFF file */

    /* Callback functions used by different file formats. */
    iiSectionFunc readSection;
    iiSectionFunc readSectionByte;
    iiSectionFunc readSectionUShort;
    iiSectionFunc writeSection;
    void (*cleanUp)(ImodImageFile *inFile);
    void (*close)(ImodImageFile *inFile);
    int (*reopen)(ImodImageFile *inFile);

  };

RawImageInfo structure

A structure for passing bare-bones information about an MRC-like (raw) file to a routine that makes an MRC header
  typedef struct raw_image_info {
    int type;           /* Data type, one of the RAW_MODE_* values */
    int nx, ny, nz;     /* Size of file in X, Y, Z */
    int swapBytes;      /* Whether bytes are swapped */
    int headerSize;     /* Offset to data */
    float amin, amax;   /* Data min and max, set to 0 if unknown */
    int scanMinMax;     /* Flag that scan is needed, used internally */
    int allMatch;       /* Flag that all files match, used internally */
    int sectionSkip;    /* Padding after each section - there may be no padding
                           after last section */
    int yInverted;      /* Lines are inverted in Y */
  } RawImageInfo;