Mrcfiles and Mrcsec modules

These modules contain functions for reading and manipulating an MRC file header, reading and writing from an MRC file, and other associated actions. When a file is opened with iiFOpen some of these functions will work with all supported file types by redirecting I/O through the iimage module.

Headers to include: mrcfiles.h, iimage.h

MRC Header Related Functions


int mrc_head_read(FILE *fin, MrcHeader *hdata)
int sizeCanBe4BitK2SuperRes(int nx, int ny)
void fixTitlePadding(char *label)
int mrc_test_size(MrcHeader *hdata)
int mrcGetStandardVersion(MrcHeader *hdata)
int mrcGetExtendedType(MrcHeader *hdata, int *version)
int mrc_head_write(FILE *fout, MrcHeader *hdata)
int mrc_head_label(MrcHeader *hdata, const char *label)
void mrcFillLabelString(const char *label, void *outLabel)
int mrcPrintLabelString(MrcHeader *hdata, int labelInd)
int mrc_head_label_cp(MrcHeader *hin, MrcHeader *hout)
int mrcCopyExtraHeader(MrcHeader *hin, MrcHeader *hout)
int mrcReadExtraHeader(MrcHeader *hin, unsigned char **extData)
int mrcWriteExtraHeader(MrcHeader *hout, unsigned char *extData, int next)
void mrcCopyValidExtendedType(MrcHeader *hin, MrcHeader *hout)
int mrc_head_new(MrcHeader *hdata, int x, int y, int z, int mode)
void mrcInitOutputHeader(MrcHeader *hdata)
void mrc_get_scale(MrcHeader *h, float *xs, float *ys, float *zs)
void mrc_set_scale(MrcHeader *h, double x, double y, double z)
void mrc_coord_cp(MrcHeader *hout, MrcHeader *hin)
int mrc_byte_mmm( MrcHeader *hdata, unsigned char **idata)
void mrc_swap_header(MrcHeader *hdata)

Reading and Writing Functions in mrcfiles.c


void *mrc_mread_slice(FILE *fin, MrcHeader *hdata, int slice, char axis)
int mrc_read_slice(void *buf, FILE *fin, MrcHeader *hdata, int slice, char axis)
int mrcReadFloatSlice(b3dFloat *buf, MrcHeader *hdata, int slice)
unsigned char **mrc_read_byte(FILE *fin, MrcHeader *hdata, IloadInfo *li, void (*func)(const char *))
void mrcContrastScaling(MrcHeader *hdata, float smin, float smax, int black, int white, int ramptype, float *slope, float *offset)
int mrc_write_idata(FILE *fout, MrcHeader *hdata, void *data[])
int mrc_write_slice(void *buf, FILE *fout, MrcHeader *hdata, int slice, char axis)
int mrcWriteFFT(const char *filename, float *fft, int nxReal, int nyReal, int ifScale)

Reading Functions in mrcsec.c


int mrcReadZ(MrcHeader *hdata, IloadInfo *li, unsigned char *buf, int z)
int mrcReadZByte(MrcHeader *hdata, IloadInfo *li, unsigned char *buf, int z)
int mrcReadZUShort(MrcHeader *hdata, IloadInfo *li, unsigned char *buf, int z)
int mrcReadZFloat(MrcHeader *hdata, IloadInfo *li, b3dFloat *buf, int z)
int mrcReadY(MrcHeader *hdata, IloadInfo *li, unsigned char *buf, int z)
int mrcReadYByte(MrcHeader *hdata, IloadInfo *li, unsigned char *buf, int z)
int mrcReadYUShort(MrcHeader *hdata, IloadInfo *li, unsigned char *buf, int z)
int mrcReadYFloat(MrcHeader *hdata, IloadInfo *li, b3dFloat *buf, int z)
int mrcReadSection(MrcHeader *hdata, IloadInfo *li, unsigned char *buf, int z)
int mrcReadSectionByte(MrcHeader *hdata, IloadInfo *li, unsigned char *buf, int z)
int mrcReadSectionUShort(MrcHeader *hdata, IloadInfo *li, unsigned char *buf, int z)
int mrcReadSectionFloat(MrcHeader *hdata, IloadInfo *li, b3dFloat *buf, int z)
int iiInitReadSectionAny(MrcHeader *hdata, IloadInfo *li, unsigned char *buf, LineProcData *d, int *freeMap, int *yEnd, const char *caller)
int iiProcessReadLine(MrcHeader *hdata, IloadInfo *li, LineProcData *d, unsigned char *bdataIn, unsigned char *bufpIn)
int mrcWriteZ(MrcHeader *hdata, IloadInfo *li, unsigned char *buf, int z)
int mrcWriteZFloat(MrcHeader *hdata, IloadInfo *li, b3dFloat *buf, int z)

Basic I/O Support Functions


unsigned char **mrcGetDataMemory(IloadInfo *li, size_t xysize, int zsize, int pixsize)
void mrcFreeDataMemory(unsigned char **idata, int contig, int zsize)
unsigned char *get_byte_map(float slope, float offset, int outmin, int outmax, int bytesSigned)
unsigned char *get_short_map(float slope, float offset, int outmin, int outmax, int ramptype, int swapbytes, int signedint)
float mrcGetComplexScale()
void mrcComplexSminSmax(float inMin, float inMax, float *outMin, float *outMax)
void mrcMirrorSource(int nx, int ny, int imageX, int imageY, int *fileX, int *fileY)
int mrc_init_li(IloadInfo *li, MrcHeader *hd)
int mrc_fix_li(IloadInfo *li, int nx, int ny, int nz)
int get_loadinfo(MrcHeader *hdata, IloadInfo *li)
int mrc_getdcsize(int mode, int *dsize, int *csize)
void mrc_swap_shorts(b3dInt16 *data, int amt)
void mrc_swap_longs(b3dInt32 *data, int amt)
void mrc_swap_floats(b3dFloat *data, int amt)

Structures and Definitions for I/O Functions


MRC data modes
MrcHeader structure
IloadInfo structure

MRC Header Related Functions

int mrc_head_read(FILE *fin, MrcHeader *hdata)

Reads an MRC header into hdata from the file with pointer fin. Determines whether byte-swapping is necessary by requiring that nx, ny, and nz are positive, that one of them is < 65536, and that mapc, mapr, and maps be between 0 and 4.  Leaves the file pointer fin in the fp member of hdata.  Returns -1 for I/O error, or 1 if these requirements are not met or if the mode or number of labels are inappropriate.  However, if fin is a file pointer in the list of opened ImodImageFiles, it calls iiFillMrcHeader instead since the header has already been read.

int sizeCanBe4BitK2SuperRes(int nx, int ny)

Returns 1 if the size nx, ny matches a size that the SerialEMCCD plugin to DigitalMicrograph would save as 4-bit data packed into a byte mode file for super-resolution frames from a K2 or K3 camera.  The sizes tested are 3838x7420, 3710x7676, 3840x7424, 3712x7680, 11520x4092, and 5760x8184.  The size must match within 2 pixels.

void fixTitlePadding(char *label)

Tests whether the string is null-terminated before its end and pads it with space to its end

int mrc_test_size(MrcHeader *hdata)

Tests the image size and map entries in MRC header hdata to see if they are within allowed ranges: nx, ny, and nz all positive, and at least one of them less than 65536; and map values between 0 and 3.  Returns 0 if that is the case, 1 if not.

int mrcGetStandardVersion(MrcHeader *hdata)

Returns the nversion component of header hdata, or 0 if it is not between 20140 and 10 * (current year plus 2), or -1 for hdata NULL.

int mrcGetExtendedType(MrcHeader *hdata, int *version)

Returns a numeric code for the contents of the extType field of the header in hdata and a version number, if any, in version.  The codes are currently 1 for SERI, 2 for AGAR, 3 for FEIn, 4 for unknown (the field is of the form A-ZA-Z0-9A-Z0-9A-Z (nul) and the file has an MRC version stamp), and 0 otherwise (for a blank/nul field, one without the form just described, or a file without a valid MRC version stamp).

int mrc_head_write(FILE *fout, MrcHeader *hdata)

Write the MRC header in hdata to the file with pointer fout.  First, it looks up fout in the list of opened ImodImageFiles and if it finds that it belongs to a non-MRC file, it calls iiSyncFromMrcHeader and returns 0.  Otherwise, it returns 1 for error.

int mrc_head_label(MrcHeader *hdata, const char *label)

Adds label to the header hdata or replaces the last one if there are already 10 labels.  The label will be truncated at 55 characters or padded with spaces to that length, and a standard date-time stamp will be added. Returns 0.

void mrcFillLabelString(const char *label, void *outLabel)

Copies label into outLabel, which must be at least 80 bytes, and adds the standard date-time string, truncating the label to 55 characters if necessary.

int mrcPrintLabelString(MrcHeader *hdata, int labelInd)

Prints the label at index labelInd in the header hdata.  Returns 1 for NULL header or index out of range.

int mrc_head_label_cp(MrcHeader *hin, MrcHeader *hout)

Copies all labels from header hin to header hout.  Returns 0.

int mrcCopyExtraHeader(MrcHeader *hin, MrcHeader *hout)

Copies extra header data from MRC file whose header is in hin to MRC file whose header is in hout, swapping data if necessary if it consists of short integers or floats and ints.  Returns 1 if hin or hout or one of their file pointers is NULL or the output file is swapped, 2 for seek errors, 3 for memory allocation error, 4 or 5 for read or write errors, or 6 if the output file is not an MRC file.

int mrcReadExtraHeader(MrcHeader *hin, unsigned char **extData)

Reads extra header data from MRC file whose header is in hin.  extData is a pointer to the buffer pointer into which data are read; if the buffer pointer is NULL then the buffer is allocated and its address returned in extData.  Data are swapped if necessary if they consists of short integers or floats and ints.  Returns 1 if hin, the file pointer in hin, or extData is NULL, 2 for seek error, 3 for memory allocation error, 4 for read error, or -1 if there are no extra data.

int mrcWriteExtraHeader(MrcHeader *hout, unsigned char *extData, int next)

Writes the extended header to the MRC file whose header is in hout, writing next bytes from extData and setting the header members next and headerSize. Returns 1 if hout, the file pointer in hout, or extData is NULL or if next is not positive, 2 for seek error, 5 for write error, or 6 if the output file is not an MRC file.

void mrcCopyValidExtendedType(MrcHeader *hin, MrcHeader *hout)

Copies the extended header stamp extType from header hin to header hout if a valid one seems to exist, namely, if the MRC_EXT_TYPE_ is not NONE and either the type is not UNKNOWN or the nint and nreal members do not fit as SerialEM bytes and flags.

int mrc_head_new(MrcHeader *hdata, int x, int y, int z, int mode)

Fills in the header structure hdata to default settings for the given file size x, y, z and the given mode.  Returns 0.

void mrcInitOutputHeader(MrcHeader *hdata)

Initialize the header in hdata for a new output file by eliminating extra header data, setting the MAP stamp, setting the swapped and yInverted members to 0, setting the bytesSigned member appropriately, and initializing to no extended header.

void mrc_get_scale(MrcHeader *h, float *xs, float *ys, float *zs)

Computes the pixel size or scale values in the MRC header h and returns them in xs, ys, and zs.

void mrc_set_scale(MrcHeader *h, double x, double y, double z)

Sets values in the MRC header h so that the pixel size or scale is x, y, and z.  If x is nonzero, it sets the xlen element to h to be x times the mx element; otherwise it sets xlen and mx equal to nx.  y and z are treated similarly.

void mrc_coord_cp(MrcHeader *hout, MrcHeader *hin)

Copies the scale values, current tilt angles, and origin values from the MRC header hin to header hout.

int mrc_byte_mmm( MrcHeader *hdata, unsigned char **idata)

Determines the min, max and mean values of the byte data in idata and places them into header hdata.  idata must be an array of pointers to hdata->nz planes of data.  Returns -1 for error.

void mrc_swap_header(MrcHeader *hdata)

Swaps each section of the header hdata as appropriate for its data type.

Reading and Writing Functions in mrcfiles.c

void *mrc_mread_slice(FILE *fin, MrcHeader *hdata, int slice, char axis)

Allocates and returns one plane of data at the coordinate given by slice along the axis given by axis, which must be one of x, X, y, Y, z, or Z. Reads from the file with pointer fin according to the header in hdata and swaps bytes if necessary.  Calls mrc_read_slice. ; Returns NULL for errors.

int mrc_read_slice(void *buf, FILE *fin, MrcHeader *hdata, int slice, char axis)

Reads one plane of data into the buffer buf at the coordinate given by slice along the axis given by axis, which must be one of x, X, y, Y, z, or Z.  Reads from the file with pointer fin according to the header in hdata and swaps bytes if necessary.  Should work with planes > 4 GB on 64-bit systems.  If the axis is Y or Z, it calls mrcReadSection and returns its return value; thus it can read from all file types for Z planes and from file types other than TIFF for Y planes.  Can read X planes only from MRC-like files; in that case it returns -1 for errors.

int mrcReadFloatSlice(b3dFloat *buf, MrcHeader *hdata, int slice)

Reads a whole Z slice at Z value slice from the MRC file whose header is is in hdata, and returns it into buf.  Works only for real data (byte, integer, float).  Simply calls mrcReadZFloat .  Returns 1 for an illegal request, 2 for a memory error, or 3 for an error reading the file.

unsigned char **mrc_read_byte(FILE *fin, MrcHeader *hdata, IloadInfo *li, void (*func)(const char *))

Reads a file into an array of unsigned bytes and returns an array of pointers to the planes of data.  fin is the pointer to the file, hdata is the MRC header structure, li is an IloadInfo structure specifying the limits and scaling of the load, and func is a function to receive a status string after each slice.  If li is NULL, sensible defaults are used.  Scaling is set from the smin, smax, black, white and ramptype members of li using mrcContrastScaling , where ramptype can be MRC_RAMP_LIN, MRC_RAMP_LOG, or MRC_RAMP_EXP, but the latter two should be used only for integer and float input data. Data memory is allocated with mrcGetDataMemory and should be freed with mrcFreeDataMemory .  Should work with planes > 4 GB on 64-bit systems.  Will work for non-MRC-like files since it calls mrcReadZByte.  Returns NULL for error.

void mrcContrastScaling(MrcHeader *hdata, float smin, float smax, int black, int white, int ramptype, float *slope, float *offset)

Computes scaling of data to bytes with potentially two levels of scaling. The first level of scaling maps smin and smax to 0 to 255; if these two values are equal, then the file min and max in hdata are used instead. The second level of scaling maps black and white in these scaled values to 0 to 255 to mimic the effect of black and white sliders in 3dmod. ramptype can be MRC_RAMP_LIN, MRC_RAMP_LOG, or MRC_RAMP_EXP.  The factors for scaling by pixel * slope + offset are returned in slope and offset.

int mrc_write_idata(FILE *fout, MrcHeader *hdata, void *data[])

Writes byte, short, or float image data to the file with pointer fout according to the dimensions and mode in header hdata, and starting from the beginning of the file.  data must be an array of pointers to hdata->nz planes of data.  Simply calls mrc_write_slice and returns its return value.  An earlier version was used by mrcbyte until 5/30/08; this is currently unused.

int mrc_write_slice(void *buf, FILE *fout, MrcHeader *hdata, int slice, char axis)

Writes one plane of data from the buffer buf at the coordinate given by slice along the axis given by axis, which must be one of x, X, y, Y, z, or Z.  Writes to the file with pointer fout according to the header in hdata and swaps bytes if necessary.  Should handle planes > 4 GB on 64-bit systems.  When writing to a Z slice, it calls mrcWriteZ and returns its return value.  Otherwise, it will only work with MRC files and returns -1 for errors.

int mrcWriteFFT(const char *filename, float *fft, int nxReal, int nyReal, int ifScale)

Writes a single FFT to a file named filename; the FFT should be in fft in standard memory organization, with real-space dimensions of nxReal by nyReal.  Data will be scaled down by the image size if ifScale is non-zero.  Returns 1 for any errors.

Reading Functions in mrcsec.c

int mrcReadZ(MrcHeader *hdata, IloadInfo *li, unsigned char *buf, int z)

Reads one Z slice of raw data at Z value z into the buffer buf from the MRC file whose header is in hdata.  The IloadInfo structure li controls the subarea loaded through its members xmin, xmax, ymin, and ymax  If it is not already being called by one of the iiRead functions in TOP, it looks up whether the fp member of hdata is on the list of opened ImodImageFiles and if so, redirects the call through an iiRead function. Returns 1 for an illegal request, 2 for a memory error, 3 for an error reading the file, or if the call is redirected, it can return -1 if no function is defined for the operation or error codes from I/O functions for other file types.

int mrcReadZByte(MrcHeader *hdata, IloadInfo *li, unsigned char *buf, int z)

Reads one Z slice of data, like mrcReadZ, and scales it to bytes. Scaling is controlled by li members slope, offset, and ramp, but ramp should be MRC_RAMP_LIN unless reading in integers or floats.

int mrcReadZUShort(MrcHeader *hdata, IloadInfo *li, unsigned char *buf, int z)

Reads one Z slice of data, like mrcReadZ, and scales it to unsigned short integers. Scaling is controlled by li members slope, offset, and ramp, but ramp should be MRC_RAMP_LIN unless reading in integers or floats.

int mrcReadZFloat(MrcHeader *hdata, IloadInfo *li, b3dFloat *buf, int z)

Reads one Z slice of data, like mrcReadZ, and returns it as floats. Only works for real modes: byte, signed and unsigned short, float.

int mrcReadY(MrcHeader *hdata, IloadInfo *li, unsigned char *buf, int z)

Reads one Y slice of raw data at Y value z into the buffer buf from the MRC file whose header is in hdata.  The IloadInfo structure li controls the subarea loaded through its members xmin, xmax, zmin, and zmax. Returns 1 for an illegal request, 2 for a memory error, or 3 for an error reading the file.

int mrcReadYByte(MrcHeader *hdata, IloadInfo *li, unsigned char *buf, int z)

Reads one Y slice of data, like mrcReadY, and scales it to bytes. Scaling is controlled by li members slope, offset, and ramp, but ramp should be MRC_RAMP_LIN unless reading in integers or floats.

int mrcReadYUShort(MrcHeader *hdata, IloadInfo *li, unsigned char *buf, int z)

Reads one Y slice of data, like mrcReadY, and scales it to unsigned short integers. Scaling is controlled by li members slope, offset, and ramp, but ramp should be MRC_RAMP_LIN unless reading in integers or floats.

int mrcReadYFloat(MrcHeader *hdata, IloadInfo *li, b3dFloat *buf, int z)

Reads one Y slice of data, like mrcReadY, and returns it as floats. Only works for real modes: byte, signed and unsigned short, and float.

int mrcReadSection(MrcHeader *hdata, IloadInfo *li, unsigned char *buf, int z)

Reads one slice of raw data into the buffer buf from the MRC file whose header is in hdata.  A Y slice at Y = z is loaded if the axis member of li is 2; otherwise a Z slice at Z = z is loaded. The subarea loaded is determined by li members xmin, xmax, and ymin and ymax (for a Z slice) or zmin and zmax (for a Y slice).  If it is not already being called by one of the iiRead functions in TOP, it looks up whether the fp member of hdata is on the list of opened ImodImageFiles and if so, redirects the call through an iiRead function. Returns 1 for an illegal request, 2 for a memory error, 3 for an error reading the file, or if the call is redirected, it can return -1 if no function is defined for the operation or error codes from I/O functions for other file types.

int mrcReadSectionByte(MrcHeader *hdata, IloadInfo *li, unsigned char *buf, int z)

Reads one slice of data, like mrcReadSection, and scales it to bytes. Scaling is controlled by li members slope, offset, and ramp, but ramp should be MRC_RAMP_LIN unless reading in integers or floats.

int mrcReadSectionUShort(MrcHeader *hdata, IloadInfo *li, unsigned char *buf, int z)

Reads one slice of data, like mrcReadSection, and scales it to bytes. Scaling is controlled by li members slope, offset, and ramp, but ramp should be MRC_RAMP_LIN unless reading in integers or floats.

int mrcReadSectionFloat(MrcHeader *hdata, IloadInfo *li, b3dFloat *buf, int z)

Reads one slice of data, like mrcReadSection, and returns it as floats. Only works for real modes: byte, signed and unsigned short, and float.

int iiInitReadSectionAny(MrcHeader *hdata, IloadInfo *li, unsigned char *buf, LineProcData *d, int *freeMap, int *yEnd, const char *caller)

Initialize most variables in the data structure, figure out scaling and need for data conversion and buffering, set up the dreaded FFT mirroring, get pixel size and mapping

int iiProcessReadLine(MrcHeader *hdata, IloadInfo *li, LineProcData *d, unsigned char *bdataIn, unsigned char *bufpIn)

Process one line of data that has been read in according to the conversion needs, and maintain the buffer pointers.  The only "error" return from this is from a positive iiCheckForQuit

int mrcWriteZ(MrcHeader *hdata, IloadInfo *li, unsigned char *buf, int z)

Writes one Z slice of raw data at Z value z from the buffer buf into the MRC file whose header is in hdata.  The data must be in the form expected for the data mode in hdata, and they are swapped or bytes shifted to signed based on the swapped and bytesSigned members of hdata.  The IloadInfo structure li controls the lines to be written through its members ymin and ymax; only full lines can be written and xmin and xmax must be 0 and nx - 1. Lines will be written in invered order in Y if the MRC header member yInverted is nonzero, as of IMOD 4.10.31. If it is not already being called by one of the iiWrite functions in TOP, it looks up whether the fp member of hdata is on the opened file list and if so, redirects the call through an iiWrite function. Returns 1 for an illegal request, 2 for a memory error, 3 for an error seeking or writing the file, or if the call is redirected, it can return -1 if no function is defined for the operation or error codes from I/O functions for other file types.

int mrcWriteZFloat(MrcHeader *hdata, IloadInfo *li, b3dFloat *buf, int z)

Writes one Z slice of floating point or complex data, like mrcWriteZ, but converting it to the output mode indicated in hdata.  The input data must be either floats, complex floats, or complex shorts, and in the latter two cases the output mode must be MRC_MODE_COMPLEX_FLOAT or MRC_MODE_COMPLEX_SHORT, respectively.  The output mode may not be MRC_MODE_RGB.

Basic I/O Support Functions

unsigned char **mrcGetDataMemory(IloadInfo *li, size_t xysize, int zsize, int pixsize)

Allocates memory for zsize planes of data to contain xysize pixels at pixsize bytes per pixel, and returns an array of pointers to the planes. It attempts to allocate the data in contigous memory if li is non-NULL and the contig element of li is non-zero.  If this fails it falls back to allocating planes separately, sets contig to 0, and issues a warning with b3dError.  Should be able to allocate planes > 4GB on 64-bit systems. Returns NULL for error.

void mrcFreeDataMemory(unsigned char **idata, int contig, int zsize)

Frees data memory allocated by mrcGetDataMemory; zsize specifies the number of Z planes and contig indicates if the memory was allocated contiguously

unsigned char *get_byte_map(float slope, float offset, int outmin, int outmax, int bytesSigned)

Returns a pointer to a lookup table of 256 scaled intensities, given a scaling specified by index * slope + offset.  Output values will be truncated at outmin and outmax.  If outmax is <= 255 then the map will indeed be unsigned bytes, but if outmax is > 255 then the map will be unsigned shorts instead.  If bytesSigned is nonzero, then the map will be wrapped around so that signed values read from file and used as unsigned values when indexing the map will be shifted up by 128.

unsigned char *get_short_map(float slope, float offset, int outmin, int outmax, int ramptype, int swapbytes, int signedint)

Returns a pointer to a lookup table of scaled intensities for 65536 index values, which can be either unsigned or signed short integers.  The scaling will be index * slope + offset for ramptype = MRC_RAMP_LIN, exp(index) * slope + offset for ramptype = MRC_RAMP_EXP, and log(index) * slope + offset for ramptype = MRC_RAMP_LOG. Output values will be truncated at outmin and outmax.  If outmax is <= 255 then the map will indeed be unsigned bytes, but if outmax is > 255 then the map will be unsigned shorts instead.  Set swapbytes nonzero to for a table that swaps bytes, and signedint nonzero for signed integer indices.  The table is allocated with malloc and should be freed by the caller.  Returns NULL for error allocating memory.

float mrcGetComplexScale()

Returns a standard scaling factor for taking the log of complex data by log (1 + scale * value)

void mrcComplexSminSmax(float inMin, float inMax, float *outMin, float *outMax)

Computes the min and max for log scaling of complex numbers between inMin and inMax and returns them in outMin and outMax

void mrcMirrorSource(int nx, int ny, int imageX, int imageY, int *fileX, int *fileY)

For a mirrored FFT whose full size is nx by ny, computes where the location imageX, imageY in the image comes from in the file and returns this location in fileX, fileY.

int mrc_init_li(IloadInfo *li, MrcHeader *hd)

Initialize the IloadInfo structure li with some sensible default values if hd is NULL; otherwise it just calls mrc_fix_li with the sizes defined in the header hd.  For proper initialization, this function must be called once with a hd NULL, then again with a header if needed. Returns -1 if hd is NULL.

int mrc_fix_li(IloadInfo *li, int nx, int ny, int nz)

Fixes the min and max loading parameters (xmin, xmax, etc) in the IloadInfo structure * li based on the image dimensions given either in nx, ny, nz or in the px, py, and pz elements of li if there is a piece list.  Undefined parameters are changed to full-range values and values are fixed to be within 0 to the dimension - 1.

int get_loadinfo(MrcHeader *hdata, IloadInfo *li)

Gets x, y, and z loading limits for a MRC file whose header is in  hdata and places them in the  IloadInfo structure * li, using interactive input from standard input.  Returns 1 for no errors.

int mrc_getdcsize(int mode, int *dsize, int *csize)

For the given MRC file mode in mode, returns the number of bytes of the basic data element in dsize and the number of data channels in csize. Returns -1 for an unsupported or undefined mode.  Simply calls dataSizeForMode unless mode is SLICE_MODE_MAX.

void mrc_swap_shorts(b3dInt16 *data, int amt)

Swaps the bytes in 16-bit integers in data; amt specifies the number of values to swap.

void mrc_swap_longs(b3dInt32 *data, int amt)

Swaps the bytes in 32-bit integers in data; amt specifies the number of values to swap.

void mrc_swap_floats(b3dFloat *data, int amt)

Swaps the bytes in 32-bit floats in data; amt specifies the number of values to swap.

Structures and Definitions for I/O Functions

MRC data modes

The modes defined for MRC files in IMOD
#define MRC_MODE_BYTE          0
#define MRC_MODE_SHORT         1
#define MRC_MODE_FLOAT         2
#define MRC_MODE_COMPLEX_SHORT 3
#define MRC_MODE_COMPLEX_FLOAT 4
#define MRC_MODE_USHORT        6
#define MRC_MODE_HALF_FLOAT    12
#define MRC_MODE_RGB           16
#define MRC_MODE_4BIT          101

MrcHeader structure

The header structure for MRC files
typedef struct MRCheader
{
  b3dInt32   nx;         /*  # of Columns                  */
  b3dInt32   ny;         /*  # of Rows                     */
  b3dInt32   nz;         /*  # of Sections.                */
  b3dInt32   mode;       /*  given by #define MRC_MODE...  */

  b3dInt32   nxstart;    /*  Starting point of sub image.  UNSUPPORTED */
  b3dInt32   nystart;
  b3dInt32   nzstart;

  b3dInt32   mx;         /* "Grid size", # of pixels in "unit cell"    */
  b3dInt32   my;         /* Keep the same as nx, ny, nz                */
  b3dInt32   mz;

  b3dFloat   xlen;       /* length of unit cell in Angstroms           */
  b3dFloat   ylen;       /* get scale = xlen/nx ...                    */
  b3dFloat   zlen;

  b3dFloat   alpha;      /* cell angles, ignored, set to 90            */
  b3dFloat   beta;
  b3dFloat   gamma;

  b3dInt32   mapc;       /* map column  1=x,2=y,3=z.     UNSUPPORTED  */
  b3dInt32   mapr;       /* map row     1=x,2=y,3=z.                  */
  b3dInt32   maps;       /* map section 1=x,2=y,3=z.                  */

  b3dFloat   amin;
  b3dFloat   amax;
  b3dFloat   amean;
  
  /* 1/12/12: Removed nsymbt and made ispg be 4 bytes to match standard */
  b3dInt32   ispg;       /* space group number in the standard */

  /* 64 bytes */

  b3dInt32   next;     /* This is nsymbt in the MRC standard */
  b3dInt16   creatid;  /* Used to be creator id, hvem = 1000, now 0 */

  b3dByte    blank[6];
  b3dByte    extType[4]; /* Extended type */
  b3dInt32   nversion;  /* Version number in MRC 2014 standard */
  b3dByte    blank2[16];
  
  b3dInt16   nint;
  b3dInt16   nreal;
  b3dInt16   sub;
  b3dInt16   zfac;

  b3dFloat   min2;
  b3dFloat   max2;
  b3dFloat   min3;
  b3dFloat   max3;
  b3dInt32   imodStamp;
  b3dInt32   imodFlags;

  /*  UINT   extra[MRC_NEXTRA];*/

  /* HVEM extra data */
  /* DNM 3/16/01: divide idtype into two shorts */
  b3dInt16   idtype;
  b3dInt16   lens;
  b3dInt16   nd1;     /* Devide by 100 to get float value. */
  b3dInt16   nd2;
  b3dInt16   vd1;
  b3dInt16   vd2;
  b3dFloat   tiltangles[6];  /* 0,1,2 = original:  3,4,5 = current */

#ifdef OLD_STYLE_HEADER
  /* before 2.6.20 */
  /* DNM 3/16/01: redefine the last three floats as wavelength numbers */
  b3dInt16   nwave;   /* # of wavelengths and values */
  b3dInt16   wave1;
  b3dInt16   wave2;
  b3dInt16   wave3;
  b3dInt16   wave4;
  b3dInt16   wave5;
  b3dFloat   zorg;           /* origin */
  
  b3dFloat   xorg;
  b3dFloat   yorg;
#else
  /* MRC 2000 standard */
  b3dFloat   xorg;
  b3dFloat   yorg;
  b3dFloat   zorg;
  b3dByte    cmap[4];
  b3dByte    stamp[4];
  b3dFloat   rms;
#endif

  b3dInt32 nlabl;
  b3dByte  labels[MRC_NLABELS][MRC_LABEL_SIZE + 1];

  /* Internal data not stored in file header */
  b3dUByte *symops;
  FILE   *fp;
  int    pos;
  struct LoadInfo *li;
  int    headerSize;
  int    sectionSkip;
  int    swapped;
  int    bytesSigned;
  int    yInverted;
  int    iiuFlags;
  int    packed4bits;
  int    halfFloats;

  char *pathname;
  char *filedesc;
  char *userData;
} MrcHeader;

IloadInfo structure

Used to control loading a subsection of a 3-D data file.
typedef struct LoadInfo
{

  /* Sub area to load. */
  int xmin;      
  int xmax;
  int ymin;
  int ymax;
  int zmin;
  int zmax;
  int padLeft;     /* Padding at start or end of line when reading or writing a */
  int padRight;    /* subset of the array, in pixels not bytes */
  
  int ramp;      /* Contrast ramp type. */
  int scale;
  int black;     /* Change contrast values. */
  int white;
  
  int axis;      /* 1=x, 2=y, 3=z , 0 = default */
  
  float slope;         /* Scale input by value * slope + offset */
  float offset;
  float smin,smax;     /* Scale range smin-smax in input to 0-255 */
  int contig;          /* Load idata in contigous memory if possible */
  
  int outmin, outmax;  /* clamp values to outmin and outmax after scaling. */
  int mirrorFFT;       /* Return mirrored FFT when scaling to bytes */
  
  int   plist;         /* Size of piece list.         */
  float opx, opy, opz; /* origin of pieces.           */
  float px, py, pz;    /* size of final pieced image. */
  int   pdz;           /* number of zsections that have data. */
  int *pcoords;        /* The piece list.             */

} IloadInfo;