Header to include: iimage.h
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)
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)
Frees the checking list to avoid memory leaks
Registers a callback function that can be used for periodic updates or to check for quitting during loading from an MRC-like or HDF file.
This function is called periodically during loading of a large section from an MRC-like or HDF file and calls the registered function if any.
Creates a new image file structure and initialize it to default or null values. Returns 1 for error.
Initializes the image file structure i for the given size and other characteristics
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.
Opens a new file whose name is in filename with the given mode, which must contain 'w'. The type of file is specified by fileKind, which can be either IIFILE_MRC, IIFILE_TIFF, IIFILE_HDF, or IIFILE_DEFAULT for the type defined by calling b3dOutputFileType. Adds the file to the list of opened files and returns the opened file pointer.
Reopen a file that has already been opened and analyzed. Returns 1 if the file is already open or 2 for other errors.
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.
Closes an image file inFile and removes it from the list of opened files
Deletes an image file inFile after closing and calling any cleanup functions
Makes a copy of the image file structure for inFile and opens the file with iiReopen to take advantage of the previous analysis of the file properties. Returns the opened file copy or NULL for various errors. For a TIFF file, copies can be used to access a file from multiple threads; this may or may not work with other file types.
Enables parallel reading from a TIFF file open on inFile, using a fixed array of ImodImageFile pointers in this module. Returns 0 if parallel reading is already set up for a different file, or if the file size is such that only one thread would be used; otherwise returns the number of threads for full-sized reading. The maximum number of threads to use can be passed in maxThreads; if this is 0 the default will used, 16.
Enables parallel reading from a TIFF file using a file pointer fp returned after opening it with iiFOpen. Calls iiUseTiffThreads and returns its return value.
Closes all the copies of the TIFF file in inFile opened by iiUseTiffThreads; has no effect if no copies were opened or if called with a different file.
Closes all the copies of a TIFF file opened by calling iiUseTiffThreadsForFP with fp. Has no effect if no copies were opened or if called with a different file.
Calls iiCopyOpen maxThreads - 1 times with the first element in the array fileCopies, putting the additional open files in fileCopies, thus allowing access from multiple threads. Returns the number of threads that can be used, which will be less than maxThreads if the opening of a copy fails.
For the image file inFile, initializes the MRC header structure hdata and fills in as many fields as possible with file-specific values. For an MRC file, it simply copies the already read-in header. Returns -1 if a header filling function is not defined or 1 if there is some other problem filling the header in.
Set up an MRC header with the size, mode, min, max, mean, and scale vales from inFile and sets bytes to be unsigned. All other values are initialized by mrc_head_new, so if this is used for syncing new information into an established header, other values like nlabl must be saved and restored.
For the image file inFile, synchronizes numerous values in the ImodImageFile structure from values in hdata, including size, mode, scale, origin, rotation, and min/max/mean values.
Returns default min/max/mean values for the data type type into amin, amax, and amean. Returns an actual file value for signed bytes, to be shifted up later in a header-reading routine.
Writes header and other metadata to inFile if the file type has a function defined for doing so. Returns 1 for error.
Adds a file to the list of opened files; this would be needed for a duplicate of an existing open iiFile.
Manages the list of open files, volume pointers in iiVolumes, and the fp entry after the ImodImageFile structure has been copied from oldFile to newFile. The old address no longer needs to be useable.
Opens an old or new ImodImageFile with the given filename and mode, adds it to the list of opened files, and returns the file pointer. When this function is used instead of fopen to open an image file, then most MRC file reading and writing functions listed in TOP, as well as mrc_head_read and mrc_head_write, will look up the file pointer in the list of opened files and perform the operation appropriate for the particular file type.
Returns the open ImodImageFile that has fp as its fp member.
Closes the file with pointer fp either by calling iiDelete for its corresponding ImodImageFile, or by simply closing it if it is not in the list of opened files. This function must be called for a newly written file if there is a possibility that it is a TIFF file.
Opens the volume at index volIndex in a multi-volume HDF file, where the index is numbered from 0 and must be at least 1; i.e., this should not be called on the initial volume accessed by iiFOpen.
Creates a new volume in an HDF file open on inFile that was not opened read-only and has volume datasets rather than a stack of single-image datasets. Sets the zChunkSize member of inFile to 1 to ensure that a volume dataset will be created later, but you can still change chunk properties with iiSetChunkSizes. ; Returns the fp member of the new ImodImageFile structure, or NULL for error.
Sets a flag to allow opening of multi-volume HDF files. There is a Fortran wrapper iiallowmultivolume.
For the HDF file or volume dataset in inFile, sets the tile (chunk) sizes in X and Y to xSize and ySize, and the chunk size in Z to zSize. Pass 0 for xSize or ySize to avoid tiling in those dimensions. zSize must be 1 or greater. This function must be called before the volume or its header is written. Returns 1 for error.
Returns an autodoc index for inFile. Set global non-zero for accessing or storing information that applies to all volumes of a multi-volume HDF file or information stored in sections other than in the ZValue collection. If the file is not an HDF file, it will return the existing value of the adocIndex member if it is non-negative or if openMdocOrNew is 0; otherwise it will attempt to open a metadata autodoc file by adding ".mdoc" to the filename if openMdocOrNew is positive or it will open a new autodoc if openMdocOrNew is negative. Returns -1 if there is no autodoc, or -2 for more serious errors.
Transfers all but Z-slice specific information from the autodoc structures associated with fromFile to those of toFile. The adocIndex member must be non-negative for both files. Global data (in the PreData section) are transferred between these two specific autodocs. Data in other sections, except for sections of type ZValue, are also transferred. For an HDF file, the autodoc index used in each case is the one in globalAdocIndex, if it is non-negative; otherwise it is the one in adocIndex. Returns 1 for errors.
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.
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.
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.
Reads the section inSection from the file inFile as unscaled floating point values into buffer buf. Returns -1 for undefined reading function or failure to reopen file, otherwise passes along return value of the reading function.
Reads the section inSection from the file inFile into buffer buf with conversion specified by convertTo, which must be one of MRSA_NOPROC, MRSA_BYTE, MRSA_USHORT, and MRSA_FLOAT. Returns -1 for undefined reading function, failure to reopen file, or invalide convertTo, otherwise passes along return value of the reading function.
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.
Write floating point or complex 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.
Returns the value of a single pixel at x, y, z from the image file inFile. Gives the value directly for byte, short, and float data, (by calling mrcReadZFloat) and the magnitude for complex data (after calling mrcReadZ). Returns the file minimum hdata->amin for coordinates out of bounds or if there is no function for reading floats for a file type.
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.
If ifFloat is set and the mode of the file inFile is not float, it makes a new buffer for the full contents of buf and converts the floats in buf to integer or byte, inverting the lines in Y and setting inverted to 1. Returns the new buffer in this case, or just returns buf. The name of the calling routine should be in routine.
Converts nx floating point values in the array fbufp to values in the mode specified by mrcMode, with signed bytes produced if byteSigned is nonzero. Values are placed in bdata.
Copies the parameters with loading information from iiFile to iiSave: ll and ur members for x, y, and z, axis, padLeft, padRight, slope, and offset.
Restores the parameters copied by iiSaveLoadParams from iiSave back to iiFile and returns the value in retVal for convenience.
Given an image size in one dimension in imSize, a target tile size in tileSize, and a factor that the tile size must be a multiple of in multipleOf, returns an optimal tile size that minimizes extra total image size in tileSize and the number of tiles in numTiles. It picks a tile size less than or equal to the target, unless the tile size with one fewer tile gives both less extra total image size and a tile size closer to the target. Fortran wrapper iibesttilesize.
Given an image size in one dimension in imSize, a target tile size in tileSize, and a factor that the tile size must be a multiple of in multipleOf, returns an optimal tile size that minimizes extra total image size in tileSize and the number of tiles in numTiles. It picks a tile size less than or equal to limit if that is greater than 0, and less than or equal to the target unless the tile size with one fewer tile gives both less extra total image size and a tile size closer to the target. Fortran wrapper iilimitedtilesize.
If environment variable IMOD_DFLT_EER_SUPER_RES is set, returns its value in superRes, otherwise leaves superRes unchanged. If IMOD_DFLT_EER_Z_SUMMING is set, returns its value in zSumming, otherwise leaves zSumming unchanged.
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 in inFile. This function is called automatically when the header is written for an HDF file containing a stack of single images or only one volume, so it needs to be called only when working with a multi-volume file.
Adds a dataset for section cz to an HDF file open on inFile without writing data; buf should be defined but need not be more than a few bytes. Returns error values from the writing routine or 1 if the package does not support HDF.
Tests if the file filename is an HDF file without opening it extensively; this function can be used when a file may be open for writing in another process. Returns -2 if the package does not support HDF, -1 for an error opening the file, 0 if file is not HDF, or 1 if it is. Fortran wrapper iitestifhdf
Changes the order of sections in an HDF stack file open on inFile by renaming the HDF groups containing the section data. The array sectOrder specifies the Z value that each section should become; there must be the same number of values as the Z size of the file, they must be non-negative, and there must be no duplicates in the list. In principle, this list can contain gaps, as can the original group names for the sections, but it has been tested only without such gaps. Returns 1 for a variety of errors.
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)
Frees the checking list and all its data to avoid memory leaks
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.
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.
Analyzes a file known to be a DigitalMicrograph version 3 or 4, as indicated in dmformat; 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 the DM data type number in dmtype. Returns IOERR_IO_ERROR for errors reading the file or IOERR_NO_SUPPORT for other errors in analyzing the file.
/* Except IIFILE_DEFAULT means use the default output file type */
#define IIFILE_DEFAULT -1
#define IIFILE_UNKNOWN 0
#define IIFILE_TIFF 1
#define IIFILE_MRC 2
#define IIFILE_QIMAGE 3
#define IIFILE_RAW 4
#define IIFILE_HDF 5
#define IIFILE_JPEG 6
#define IIFILE_ADOC 7
#define IIFILE_SHR_MEM 8
/* 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_UNUSED 3
#define IISTATE_BUSY 4
/* Recognized values for the tiffCompression member of ImodImageFile, a
copy of TIFF definitions. Other compressions will have other values. */
#define IICOMPRESSION_NONE 1
#define IICOMPRESSION_LZW 5
#define IICOMPRESSION_JPEG 7
#define IICOMPRESSION_ZIP 8
/* EER format supported compression codes */
#define IICOMPRESSION_EER_8BIT 65000
#define IICOMPRESSION_EER_7BIT 65001
#define FEI_TIFF_DEFECT_TAG 65100
#define FEI_EER_METADATA_TAG 65001
/* 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
#define IIERR_QUITTING 5
#define IIERR_NOT_PRESENT 6
/* Codes for source of HDF files */
#define IIHDF_IMOD 1
#define IIHDF_OTHER_MRC 2
#define IIHDF_EMAN 3
#define IIHDF_CHIMERA 4
#define IIHDF_UNKNOWN 5
/* Codes for data conversion type in "ReadSectionAny" functions */
#define MRSA_NOPROC 0
#define MRSA_BYTE 1
#define MRSA_FLOAT 2
#define MRSA_USHORT 3
/* Flags for userData */
#define IIFLAG_BYTES_SWAPPED 1
#define IIFLAG_TVIPS_DATA 2
/* Flags for calling tiffEERsuperResAndFlags */
#define IIFLAG_SKIP_EER_DIRS 1
#define IIFLAG_ADD_TO_EER_SUM 2
#define IIFLAG_START_END_EER_SUM 4
#define IIFLAG_IGNORE_BAD_EER_END 8
#define IIFLAG_ANTIALIAS_EER 16
#define IIFLAG_EER_USE_LANCZOS 32
#define EER_AA_SCALING_BIT_SHIFT 6
#define EER_AA_SCALING_MASK 7
#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
typedef int (*iiSectionFunc)(ImodImageFile *inFile, char *buf, int inSection);
struct ImodImageFileStruct
{
char *filename;
char fmode[4];
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 */
int newFile; /* Newly created file */
/* optional data to be set if input file supports it. */
float amin, amax, amean, rms;
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 */
int padLeft; /* Padding at start or end of line when reading or writing a */
int padRight; /* subset of the array, in pixels not bytes */
/* extra storage used by individual file format functions. */
int headerSize;
int sectionSkip;
int hasPieceCoords; /* Flag that MRC file has piece coordinates in header */
char *header;
#ifdef _WIN32
HANDLE shrMemFile;
#else
int shrMemFile;
#endif
char *userData;
unsigned int userFlags; /* Flags for the userData */
int userCount; /* Number of bytes of 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 */
int anyTiffPixSize; /* Set non-0 to have TIFF pixel size put into [xyz]scale */
int rawPaletteBytes; /* Set non-zero to have palette image returned as bytes */
int tiffCompression; /* Compression type in tiff file */
int readEERasSuperRes; /* Super-resolution factor when reading EER file */
int numFramesInEERfile; /* Actual number of frames in file when autogrouping */
int antialiasEERfilter; /* Filter type for antialiasing while reading */
int EERkernelScale; /* Scale factor when reading EER as antialiased shorts */
int tileSizeX; /* Tile size in X, or 0 if no tiles */
int tileSizeY; /* Tile size in Y if tiles, strip size if not */
int lastWrittenZ; /* Last Z written, needed if sequential writing only */
int packed4bits; /* Data in file are 4-bit, packed 2 pixels per byte */
int fillOrder; /* Fill order for the 4-bit data */
int halfFloats; /* Data in file are 16-bit floats */
Ilist *directoryNums; /* List of directory numbers for qualifying images in file */
/* HDF variables */
Ilist *stackSetList; /* Names, ID's for stack of single-image datasets */
int *zToDataSetMap; /* Map from Z value to index in dataset list */
int zMapSize; /* Allocated size of Z map */
char *datasetName; /* Dataset name for single volume open in this iifile */
int datasetID; /* ID for dataset of single volume */
int datasetIsOpen; /* Flag that it is open */
int numVolumes; /* Number of volume datasets in the HDF file */
ImodImageFile **iiVolumes; /* Array of pointers to iifiles open in the HDF file */
int adocIndex; /* Index of autodoc with metadata for this iifile */
int globalAdocIndex; /* Index for global metadata in multifile case */
int hdfSource; /* Apparent source of file (IIHDF_ value) */
int hdfFileID; /* File ID */
int zChunkSize; /* Size of chunk in Z; must be nonzero for a volume */
int hdfCompression; /* Compression level for Zip compression */
/* Callback functions used by different file formats. */
iiSectionFunc readSection;
iiSectionFunc readSectionByte;
iiSectionFunc readSectionUShort;
iiSectionFunc readSectionFloat;
iiSectionFunc writeSection;
iiSectionFunc writeSectionFloat;
void (*cleanUp)(ImodImageFile *inFile);
void (*close)(ImodImageFile *inFile);
int (*reopen)(ImodImageFile *inFile);
int (*fillMrcHeader)(ImodImageFile *inFile, MrcHeader *hdata);
int (*syncFromMrcHeader)(ImodImageFile *inFile, MrcHeader *hdata);
int (*writeHeader)(ImodImageFile *inFile);
};
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 */
float pixel; /* Pixel size in Angstroms, set to 0. if unknown */
float zPixel; /* Pixel size in Z if different, set to 0. otherwise */
} RawImageInfo;