Nearly all header operations will work with all file types, although for a file type that does not support a particular header value, a default value will be returned, and setting the value will have no effect. All MRC header fields are supported in HDF files.
Unless otherwise noted, Fortran wrappers use the same arguments, minus any string lengths at the end of the argument list. Most functions have two wrappers, one to support existing code, one matching the longer, more informative name of the C function.
Header to include: iiunit.h (which includes iimage.h)
Opens a file on unit number iunit, between 1 and 1000, with filename name and attribute specified as 'NEW', 'OLD', 'RO' (for read-only), and 'SCRATCH' (deleted when closed). Only first letter of attribute is checked and it may be either case. If the unit is already in use a warning is printed and the existing file is closed. Fortran wrapper iiuOpen.
Closes the file on unit iunit. It ignores a unit number out of range or unit not open. Fortran wrapper iiuClose and imclose
Returns pointer to the ImodImageFile structure for unit iunit.
Returns the number of volume datasets in an HDF file that is not a stack of single-image datasets; otherwise returns 0. Fortran wrapper iiuretnumvolumes.
Opens a new or existing volume in the HDF file open on unit mainUnit, assigning it to newUnit. Set volIndex negative to open a new volume, or to the index of the existing volume to open (numbered from 0, must be 1 or higher). The file must not be open read-only and must not consist of a stack of single-image datasets. Fortran wrapper iiuvolumeopen.
Returns the autodoc index for an HDF file or potentially opens a metadata autodoc or a new autodoc for an MRC file; see iiGetAdocIndex. Fortran wrapper iiuretadocindex, returns an index numbered from 1 but -2 or -2 for error
Writes global autodoc information and autodoc information contained in sections other than of type ZValue to the top images group of the HDF file opened on unit iunit. See hdfWriteGlobalAdoc. The function needs to be called only when working with a multi-volume file. Fortran wrapper iiuwriteglobaladoc.
Returns the size of tiles (chunks) in X and Y in xSize and ySize, and of chunks in Z in zSize, for unit iunit. The Z size will be nonzero only for a volume dataset of an HDF file; the X and Y sizes may be non-zero for TIFF files as well. Fortran wrapper iiuretchunksizes.
Sets the size of chunks in a volume dataset of an HDF file open on unit iunit to xSize, ySize, and zSize in X, Y, and Z. xSize or ySize can be set to zero to avoid chunking in those dimensions; zSize must be positive. Returns 1 for error. Fortran wrapper iiualtchunksizes.
Sets the ZIP compression level for the file open on unit iunit to compression, overriding the environment variable IMOD_HDF_COMPRESSION. Fortran wrapper iiusethdfcompression.
Sets the position for the next read or write on unit iunit to the Z value in section and the Y value in line, both numbered from zero. Fortran wrappers iiuSetPosition and imposn.
Reads the current section from unit iunit into array. Returns the error from the reading operation regardless of the setting of whether to exit on error. Fortran wrapper iiuReadSection.
Reads part of the current section from unit iunit into array. The portion of the section from indX0 to indX1, inclusive, in X, and from indY0 to indY1 in Y will be read, and the current position will be advanced to the start of the next section. The X dimension of array is supplied nxdim; if this is not equal to the extent being read, data will be placed into the left part of the array and padded on the right. Returns the error from the reading operation regardless of the setting of whether to exit on error. Fortran wrapper iiuReadSecPart.
Reads numLines lines from unit iunit into array, starting at the current position. The current position is advanced to the line after the last one read. Returns the error from the reading operation regardless of the setting of whether to exit on error. Fortran wrapper iiuReadLines.
Writes the data in array to the current section of unit iunit. If not exiting on error, returns negative values for internal errors and positive values for an error from the writing operation. Fortran wrappers iiuWriteSection and iwrsec (a void).
Writes data from a subset of array to the current section and line of unit iunit. The X dimension of array is given in nxdim, the starting index from which to take data in X in ixStart, and the starting and ending indices from which to take data in Y in iyStart and iyEnd (inclusive, numbered from 0). The current position is advanced to the first line of the next section. If not exiting on error, returns negative values for internal errors (bad coordinates) and positive values for an error from the writing operation. Fortran wrapper iiuWriteSubarray.
Writes data from a subset of array to the current section and line of unit iunit, where a subset of the output file in X can be written if the file is a chunked HDF file and the starting and ending indexes to write to in indX0, indX1 correspond to chunk boundaries. The X dimension of array is given in nxdim, the starting index from which to take data in X in ixStart, and the starting and ending indices from which to take data in Y in iyStart and iyEnd (inclusive, numbered from 0). The current position is advanced to the first line of the next section. If not exiting on error, returns negative values for internal errors (bad coordinates) and positive values for an error from the writing operation. Fortran wrapper iiuWriteSecPart.
Writes numLines lines to unit iunit from array, starting at the current position. The current position is advanced to the line after the last one written. If not exiting on error, returns negative values for internal errors and positive values for an error from the writing operation. Fortran wrappers iiuWriteLines, iwrsecl (a void), and iwrlin(int *iunit, char *array), a void to write one line.
Returns information for unit iunit: the file size in KB in fileSize; the type of
file in fileType, which can be 1 for TIFF, 2 for MRC, 4 for other raw-type files or
5 for HDF; and flags in flags:
bit 0 - bytes are swapped
bit 1 - bytes are stored signed
bit 2 - old-style header with no MAP and origin wrong place
bit 3 - Extra header nint value was corrected to 0
bit 4 - map values were bad and were corrected
bit 5 - File is a true 4-bit mode
bit 6 - File has 4-bit values packed into bytes and the X size is half the true value
If the unit is not open, fileSize is returned with -1. Fortran wrapper iiuFileInfo.
The value in doExit sets whether to exit on error when calling most functions with an error return; the default is 1 and a value of 0 allows the return. The value in storeError will be sent to b3dSetStoreError upon initialization; the default is -1 for printing to stdout, and a value of 1 would allow error messages to be retrieved instead. Fortran wrapper iiuExitOnError.
Sets whether brief headers should be written, overriding the value of environment variable IMOD_BRIEF_HEADER. A val greater than 0 gives brief output, a value of 0 gives full output. Callable with this name from C or Fortran.
Returns 1 if brief header should be written, 0 otherwise. Callable with this name from C or Fortran.
Sets whether header printing is on if val is non-zero. Callable with this name from C or Fortran.
Returns a non-zero value if header printing is on. Callable with this name from C or Fortran.
Sets the option for conversion to/from floats on input and output for unit iunit; a val of 0 turns off conversion. Fortran wrapper iiualtconvert.
Returns the MRC header for unit iunit. If this is not an open unit, it prints a message including the text in function and exits if doExit is non-zero. If checkRW is 1, it tests whether reading is not possible given the current setting of the conversion option; if checkRW is 2 it tests whether writing is possible; in either case it exits or returns depending on the value of doExit.
Copies image size from the MRC header to the ImodImageFile structure and sets the file pointer from the latter to the MRC header. This should be called after changing the image size or doing a structure copy to the MRC header.
Fixes the pointer to the header for unit iunit if it is an HDF file and the the underlying ImodImageFile has been reopened, since a new header structure is created on the reopen. Exits upon error; the file must be an HDF file.
Returns the type of file open on unit iunit: IIFILE_MRC (2), IIFILE_TIFF (1) or IIFILE_HDF (5). Fortran wrapper iiufiletype.
Returns the number of bytes per pixel in an I/O buffer for unit iunit.
Returns some header values for unit iunit: image dimensions in nxyz, sampling in mxyz, data mode in mode, and minimum, maximum, and mean density in dmin, dmax, and dmean. Fortran wrapper iiuRetBasicHead.
Creates a new header, i.e., initializes the header, for unit iunit with the give image size in nxyz, sample size in mxyz, file mode in mode, and numLabels titles in labels. Fortran wrappers iiuCreateHeader and icrhdr.
Writes the header for unit iunit to file with the minimum, maximum and mean
density values in dmin, dmax, and dmean. A single title can be supplied in
an 80-byte array, label, and will be treated according to the value of labFlag:
0: label becomes the only title
1: label is added at the end of existing titles, replacing the last one if there
are already 10 titles
2: label is added as the first title and others are shifted up
-1 or anything else: do not add a title
Returns -1 for various internal errors or 1 for an error writing the header.
Fortran wrappers iiuWriteHeader and iwrhdr (a void).
Writes a header just as iiuWriteHeader does, but with label being a string instead of an 80-byte array. Fortran wrappers iiuWriteHeaderStr and iwrhdrc (a void).
Prints a brief header for unit iunit; if filePrefix is not NULL, it prints the filename after that string.
Transfers all header information from unit iunit to intoUnit, including the extended header if any. Returns -1 for internal errors or 1 for an error writing the extended header. Fortran wrappers iiuTransHeader and itrhdr (a void).
Return the cell size xlen, ylen, zlen and cell angles alpha, beta, and gamma into cell for unit iunit. Fortran wrappers iiuRetCell and irtcel.
Sets the cell size xlen, ylen, zlen and cell angles alpha, beta, and gamma to values in cell for unit iunit. Fortran wrappers iiuAltCell and ialcel.
Returns data type information for unit iunit. The original description of its
meaning is:
itype = 0 normal mono data
itype = 1 tilt set N1 = # angles stored per section
if n1=0 then n2=axis, v1=start ang, v2=delang
itype = 2 stereo pairs stored L,R V1= angle V2 = angle R
itype = 3 avg mono N1 = number sects avg, N2 = offset per sect
itype = 4 avg stereo N1 = number sects avg, N2 = offset per sect
V1,V2 = angls L,R
Fortran wrappers iiuRetDataType and irtdat.
Sets data type information for unit iunit, as described in iiuRetDataType. Fortran wrappers iiuAltDataType and ialdat.
Returns the image dimensions nx, ny, nz into nxyz, the sample size mx, my, mz into mxyz, and starting coordinates into nxyzst for unit iunit. Fortran wrappers iiuRetSize and irtsiz.
Sets the image dimensions nx, ny, nz to values in nxyz and starting indexes to values in nxyzst for unit iunit. Fortran wrappers iiuAltSize and ialsiz.
Returns the sample size mx, my, mz into mxyz for unit iunit. Fortran wrappers iiuRetSample and irtsam.
Sets the sample size mx, my, mz to mxyz for unit iunit. Fortran wrappers iiuAltSample and ialsam.
Returns the (unsupported) axis map values mapc, mapr, maps into mapcrs for unit iunit. Fortran wrappers iiuRetAxisMap and irtmap.
Sets the (unsupported) axis map values mapc, mapr, maps from values in mapcrs for unit iunit. Fortran wrappers iiuAltAxisMap and ialmap.
Returns the imodFlags component in iflags and 1 if the file has the IMOD stamp in ifImod for unit iunit. Fortran wrappers iiuRetImodFlags and irtImodFlags.
Sets the imodFlags component to iflags for unit iunit. Fortran wrappers iiuAltImodFlags and ialimodflags
Sets flag for whether to write bytes as signed (transient byteSigned member) to value of iflags for unit iunit. Fortran wrappers iiuAltSigned and ialsigned.
Returns the nversion component in version for unit iunit, or 0 if it is not between 20140 and 10 * (current year plus 2). Fortran wrapper iiuRetMRCVersion.
Sets the nversion component to version for unit iunit. This should be set non-zero only for a file fully conforming to at least the 2014 MRC standard. Fortran wrapper iiuAltMRCVersion.
Returns the X, Y, and Z origin values into xorig, yorig, and zorig for unit iunit. Fortran wrappers iiuRetOrigin and irtorg.
Sets the X, Y, and Z origin values from xorig, yorig, and zorig for unit iunit. Fortran wrappers iiuAltOrigin and ialorg.
Sets file mode for unit iunit to mode. Fortran wrappers iiuAltMode and ialmod.
Changes the file mode to or from mode 101 depending on whether direction is > 0 or < 0. With direction > 0, it changes the mode to 101 if it is not in that mode already, or returns 2 if the file was not already recognized as containing packed 4-bit data and has signed bytes. With direction < 0, it changes the mode back to 0 if the mode is 101, or returns 3 if the file has an odd size in X. Returns 1 if the file is not mode 0 or 101, and -1 if nothing was done.
Returns the RMS value, if set, into rmsVal for unit iunit. Fortran wrappers iiuRetRMS and irtrms.
Sets the RMS value for unit iunit to rmsVal. Fortran wrappers iiuAltRMS and ialrms.
Returns current tilt angles (items 3, 4, 5 in tiltangles) into tilt for unit iunit. Fortran wrappers iiuRetTilt and irttlt.
Set current tilt angles (items 3, 4, 5 in tiltangles) from values in tilt for unit iunit. Fortran wrappers iiuAltTilt and ialtlt.
Returns original tilt angles (items 0, 1, 2 in tiltangles) into tilt for unit iunit. Fortran wrappers iiuRetTiltOrig and irttlt_orig.
Set current tilt angles (items 3, 4, 5 in tiltangles) from values in tilt for unit iunit. Fortran wrappers iiuAltTiltOrig and ialtlt_orig.
Rotate the current tilt angles by the X, Y, Z angles in tilt for unit iunit. Fortran wrappers iiuAltTiltRot and ialtlt_rot.
Returns the pixel size in X, Y and Z in Angstroms into delta for unit iunit. This is defined as the cell size divided by the sample size, or 1 if the latter is not positive. Fortran wrappers iiuRetDelta and irtdel.
Sets pixel size in X, Y, Z in Angstroms to the values in delta for unit iunit by changing the cell sizes. Fortran wrappers iiuAltDelta and ialdel.
Returns the space group entry, ispg, into ispg for unit iunit. Fortran wrapper iiuRetSpaceGroup.
Sets the space group entry, ispg, with the value in ispg for unit iunit. Fortran wrapper iiuAltSpaceGroup.
Returns number of labels for unit iunit in numLabels and returns the 80 characters of that number of label contiguously into labels. Fortran wrappers iiuRetLabels and irtlab.
Sets the labels for unit iunit from the array in labels, which should have the 80 characters for numLabels labels packed contiguously. The labels may be null-terminated; the null and following bytes will be filled with spaces. Fortran wrappers iiuAltLabels and iallab.
Transfers labels from unit iunit to intoUnit. Fortran wrappers iiuTransLabels and itrlab.
Returns the number of bytes in the extended header of unit iuit into numBytes. Fortran wrappers iiuRetNumExtended and irtnbsym.
Sets the number of bytes in the extended header of unit iuit into numBytes. Fortran wrappers iiuAltNumExtended and ialnbsym.
Returns the elements nint and nreal describing the extended header data type and size per section for unit iunit for headers with an extType value of "SERI" or "AGAR" or with no type indicated there. For other types is returns the negative of the type in nintOrBytes and a version number if appropriate in nrealOrFlags; currently -3 and 1 for FEI1, and -4 and 0 for an unknown type. Fortran wrappers iiuRetExtendedType and irtsymtyp.
Sets the elements nint and nreal for unit iunit. Fortran wrappers iiuAltExtendedType and ialsymtyp.
Returns a numeric code for the contents of the extType field of the header for unit iunit into type and a version number, if any, in version, by calling mrcGetExtendedType. Fortran wrapper iiuRetHeaderExtType.
Returns the extended header data for unit iunit into array extra with byte swapping if needed and returns the number of bytes into numBytes. Returns -1 for internal errors or 1 for a read error. Fortran wrappers iiuRetExtendedData and irtsym (a void).
Set the extended header data for unit iunit to be numBytes bytes with the contents of array extra. Returns negative values for internal errors or 2 for a write error. Returns with no error if the output file is not MRC. Fortran wrappers iiuAltExtendedData and ialsym (a void).
Transfers extended header data from unit iunit to intoUnit, which is not allowed to be a byte-swapped MRC file. Also transfers global and non-ZValue section data between autodocs associated with these units. Returns negative values for internal errors, 1 for a read error, 2 for a write error, or 3 for an error in autodoc transfer. Fortran wrappers iiuTransExtendedData and itrextra (a void).
Transfers the extType stamp from one MRC file, iunit, to another, intoUnit, if it appears to be valid (see mrcCopyValidExtendedType). Fortran wrapper iiuTransValidExtType.