B3dutil Module

The b3dutil module contains various utility functions, such as for large-file I/O and error processing.

Header to include: b3dutil.h
(includes cfsemshare.h and mrcslice.h)


int imodVersion(const char *pname)
void imodCopyright(void)
void imodUsageHeader(const char *pname)
char *IMOD_DIR_or_default(int *assumed)
char *imodProgName(const char *fullname)
int imodBackupFile(const char *filename)
int imodbackupfile(const char *filename, int strlen)
int imodgetenv(char *var, char *value, int varSize, int valueSize)
int imodGetpid()
int imodgetpid()
void pidToStderr()
void pidtostderr()
int imodgetstamp()
void overrideWriteBytes(int value)
void overridewritebytes(int *value)
int writeBytesSigned()
int writebytessigned()
int readBytesSigned(int stamp, int flags, int mode, float dmin, float dmax)
int readbytessigned(int *stamp, int *flags, int *mode, float *dmin, float *dmax)
void b3dShiftBytes(unsigned char *usbuf, char *sbuf, int nx, int ny, int direction, int bytesSigned)
void b3dshiftbytes(unsigned char *usbuf, char *sbuf, int *nx, int *ny, int *direction, int *bytesSigned)
void overrideInvertMrcOrigin(int value)
void overrideinvertmrcorigin(int *value)
int invertMrcOriginOnOutput()
void overrideOutputType(int type)
void overrideoutputtype(int *type)
int b3dOutputFileType()
int b3doutputfiletype()
int setOutputTypeFromString(const char *typeStr)
int setoutputtypefromstring(const char *str, int strSize)
void overrideAllBigTiff(int value)
void overrideallbigtiff(int *value)
int makeAllBigTiff()
void setNextOutputSize(int nx, int ny, int nz, int mode)
void setnextoutputsize(int *nx, int *ny, int *nz, int *mode)
int setTiffCompressionType(int typeIndex, int overrideEnv)
int settiffcompressiontype(int *typeIndex, int *overrideEnv)
void set4BitOutputMode(int inVal)
void set4bitoutputmode(int *inVal)
int write4BitModeForBytes()
char *f2cString(const char *str, int strSize)
int c2fString(const char *cStr, char *fStr, int fSize)
void b3dError(FILE *fout, const char *format, ...)
void b3dSetStoreError(int ival)
char *b3dGetError()
int b3dFseek(FILE *fp, int offset, int flag)
size_t b3dFread(void *buf, size_t size, size_t count, FILE *fp)
size_t b3dFwrite(void *buf, size_t size, size_t count, FILE *fp)
void b3dRewind(FILE *fp)
int mrc_big_seek(FILE *fp, int base, int size1, int size2, int flag)
int mrcHugeSeek(FILE *fp, int base, int x, int y, int z, int nx, int ny, int dsize, int flag)
int fgetline(FILE *fp, char s[], int limit)
int dataSizeForMode(int mode, int *dataSize, int *channels)
void b3dHeaderItemBytes(int *nflags, int *nbytes)
void b3dheaderitembytes(int *nflags, int *nbytes)
int extraIsNbytesAndFlags(int nint, int nreal)
int extraisnbytesandflags(int *nint, int *nreal)
void setOrClearFlags(b3dUInt32 *flags, b3dUInt32 mask, int state)
int numberInList(int num, int *list, int nlist, int noListValue)
int numberinlist(int *num, int *list, int *nlist, int *noListValue)
void balancedGroupLimits(int numTotal, int numGroups, int groupInd, int *start, int *end)
void balancedgrouplimits(int *numTotal, int *numGroups, int *groupInd, int *start, int *end)
unsigned char **makeLinePointers(void *array, int xsize, int ysize, int dsize)
int b3dIMin(int narg, ...)
int b3dIMax(int narg, ...)
double wallTime(void)
double walltime(void)
int b3dMilliSleep(int msecs)
int b3dmillisleep(int *msecs)
int numOMPthreads(int optimalThreads)
int numompthreads(int *optimalThreads)
int b3dOMPthreadNum()
int numCoresAndLogicalProcs(int *physical, int *logical)
int totalCudaCores(int major, int minor, int multiprocCount)
double b3dPhysicalMemory()
double b3dphysicalmemory()
char **expandArgList(const char **argVec, int numArg, int *newNum, int *ifAlloc, int *noMatchInd)
int replaceFileArgVec(const char ***argv, int *argc, int *firstInd, int *ifAlloc)
float b3drand()
void b3dsrand(int *seed)
float b3dran(int *seed)
double angleWithinLimits(float angle, float lowerLim, float upperLim)
double anglewithinlimits(float *angle, float *lowerLim, float *upperLim)
void b3dSetLockTimeout(float timeout)
void b3dsetlocktimeout(float *timeout)
int b3dOpenLockFile(const char *filename)
int b3dopenlockfile(char *filename, int namelen)
int b3dLockFile(int index)
int b3dlockfile(int *index)
int b3dUnlockFile(int index)
int b3dunlockfile(int *index)
int b3dCloseLockFile(int index)
int b3dcloselockfile(int *index)

int imodVersion(const char *pname)

Prints program name provided in pname, IMOD version and compilation date

void imodCopyright(void)

Prints copyright notice

void imodUsageHeader(const char *pname)

Calls imodVersion and imodCopyright

char *IMOD_DIR_or_default(int *assumed)

Returns the value of IMOD_DIR if it is set, or the default install location for the particular OS.  If assumed is not NULL, it is returned with 1 if the string is the default install location.

char *imodProgName(const char *fullname)

Returns a program name stripped of directories and .exe, given the full name (argv[0]) in fullname. It returns a pointer internal to argv[0], unless the name ends in .exe, in which case it tries to return a duplicate copy.  Do not free it.

int imodBackupFile(const char *filename)

Renames an existing file named filename to filename~ and deletes filename~ first if necessary

int imodbackupfile(const char *filename, int strlen)

A fortran wrapper for imodBackupFile

int imodgetenv(char *var, char *value, int varSize, int valueSize)

A Fortran-callable routine to get an environment variable, var and return its value in value.  Returns -1 for error or 1 if the variable is not defined.

int imodGetpid()

Returns the process ID

int imodgetpid()

Fortran-callable routine to get the process ID

void pidToStderr()

Prints the PID to standard error with the prefix expected by Etomo

void pidtostderr()

Fortran wrapper to pidToStderr

int imodgetstamp()

Fortran-callable function to return the IMOD stamp for MRC files

void overrideWriteBytes(int value)

Sets the value to be returned by writeBytesSigned overriding both the default value and the value of the environment variable WRITE_MODE0_SIGNED.

void overridewritebytes(int *value)

Fortran-callable  version of overrideWriteBytes

int writeBytesSigned()

Returns 0 if bytes are to be written unsigned, or non-zero if they are to be written, based on the default value, WRITE_SBYTES_DEFAULT, the value of environment variable WRITE_MODE0_SIGNED, and whether overrideWriteBytes has been called.

int writebytessigned()

Fortran wrapper for writeBytesSigned

int readBytesSigned(int stamp, int flags, int mode, float dmin, float dmax)

Returns 1 if bytes are to be read as signed and the file mode in mode is 0, otherwise returns 0.  stamp is the imodStamp header entry, flags is the imodFlags entry, dmin and dmax are the minimum and maximum from the header.  If the stamp is for an IMOD file, the value of the first bit of flags determines the result unless it is overridden by environment variable READ_MODE0_SIGNED having a value < -1 or > 1. Otherwise, the values of dmin and dmax determine the value unless READ_MODE0_SIGNED is nonzero.

int readbytessigned(int *stamp, int *flags, int *mode, float *dmin, float *dmax)

Fortran wrapper for readBytesSigned

void b3dShiftBytes(unsigned char *usbuf, char *sbuf, int nx, int ny, int direction, int bytesSigned)

Changes bytes from unsigned to signed or back either in place or while copying to a new array, provided that bytesSigned is nonzero.  If direction is >= 0, changes unsigned bytes in usbuf to signed bytes in buf by subtracting 128; otherwise it changes signed bytes in buf to unsigned bytes in usbuf by adding 128.  The number of bytes is given by nx * ny.  usbuf and  buf may be the same.

void b3dshiftbytes(unsigned char *usbuf, char *sbuf, int *nx, int *ny, int *direction, int *bytesSigned)

Fortran wrapper to b3dShiftBytes

void overrideInvertMrcOrigin(int value)

Sets the value to be returned by invertMrcOriginOnOutput overriding both the default value and the value of the environment variable INVERT_MRC_ORIGIN.

void overrideinvertmrcorigin(int *value)

Fortran wrapper for overrideInvertMrcOrigin

int invertMrcOriginOnOutput()

Returns 1 if the origin should be inverted on output to an MRC file or 0 if not, based first on a value set by calling overrideInvertMrcOrigin, if any, then on the value of environment variable INVERT_MRC_ORIGIN, if set, then on the default for this version of IMOD defined by INVERT_MRC_ORIGIN_DEFAULT.

void overrideOutputType(int type)

Sets the output file type, overriding the default and the value specified by environment variable.  Valid values are OUTPUT_TYPE_MRC (2) and OUTPUT_TYPE_TIFF (1).

void overrideoutputtype(int *type)

Fortran wrapper to overrideOutputType

int b3dOutputFileType()

Returns the current output file type  OUTPUT_TYPE_MRC (2), OUTPUT_TYPE_TIFF (1), or OUTPUT_TYPE_HDF (5) (provided the package was build with HDF). The type is either the default type (which is MRC), or the value of the environment variable IMOD_OUTPUT_FORMAT if that is set and is 'MRC', 'TIF', 'TIFF', or 'HDF', overridden by a value set with overrideOutputType.

int b3doutputfiletype()

Fortran wrapper to b3dOutputFileType

int setOutputTypeFromString(const char *typeStr)

Sets output filetype based on a string in typeStr, which can contain 'MRC', 'TIF', 'TIFF', 'JPG', 'JPEG', or 'HDF' (or all lower-case equivalents).  Returns 2 for MRC, 1 for TIFF, 6 for JPEG, -6 for JPEG if there is no JPEG support, 5 for HDF, -5 for HDF if there is no HDF support, and -1 for other entries

int setoutputtypefromstring(const char *str, int strSize)

Fortran wrapper for setOutputTypeFromString

void overrideAllBigTiff(int value)

A value of 1 causes all new TIFF files to be opened in large file format with "w8", overriding both the default setting in the defined macro ALL_BIGTIFF_DEFAULT and the value of the environment value IMOD_ALL_BIG_TIFF.

void overrideallbigtiff(int *value)

Fortran wrapper for overrideAllBigTiff

int makeAllBigTiff()

Returns 1 if all new TIFF files should be opened in large file format, based upon the default in the defined macro ALL_BIGTIFF_DEFAULT, the value of the environment value IMOD_ALL_BIG_TIFF, and a value set with overrideAllBigTiff.

void setNextOutputSize(int nx, int ny, int nz, int mode)

Indicates the output size in nx, ny, nz and the data mode in mode of a file about to be opened; the routine calls overrideAllBigTiff to force a new TIFF file to have either the large file format or the older format as appropriate.

void setnextoutputsize(int *nx, int *ny, int *nz, int *mode)

Fortran wrapper for setNextOutputSize

int setTiffCompressionType(int typeIndex, int overrideEnv)

Sets the compression type for TIFF output to none, LZW, JPEG, or ZIP for typeIndex values of 0, 1, 2, or 3, respectively, by setting the environment variable IMOD_TIFF_COMPRESSION.  If overrideEnv is 0, the variable will not be set if it is already set; if it is 1, the variable will be set unconditionally, overriding the environment value.

int settiffcompressiontype(int *typeIndex, int *overrideEnv)

Fortran wrapper to setTiffCompressionType

void set4BitOutputMode(int inVal)

If inVal is non-zero, byte output into an MRC file opened after this call will be packed into 4 bits and the MRC mode of the file will be 101.

void set4bitoutputmode(int *inVal)

Fortran wrapper for set4BitOutputMode

int write4BitModeForBytes()

Returns a non-zero value if an MRC file being opened for writing in mode 0 should be made mode 101 and written with 4-bit values instead of bytes.

char *f2cString(const char *str, int strSize)

Creates a C string with a copy of a Fortran string described by str and strsize, using malloc.

int c2fString(const char *cStr, char *fStr, int fSize)

Converts a C string in cStr into a Fortran string fStr with size fSize; returns -1 for error if the string will not fit.

void b3dError(FILE *fout, const char *format, ...)

Stores an error message and may print it as well.  The message is internally printed with vsprintf.  It is printed to fout unless b3dSetStoreError has been called with a non-zero value.

void b3dSetStoreError(int ival)

Sets flag to print messages passed by b3dError if ival is 0 (the default), just to store them internally if ival is 1, or to print messages destined to stderr to stdout instead if ival is -1.

char *b3dGetError()

Returns the current error string

int b3dFseek(FILE *fp, int offset, int flag)

A substitute for fseek that works for large files on all systems.

size_t b3dFread(void *buf, size_t size, size_t count, FILE *fp)

A substitute for fread that works for large files on all systems.  On Windows and Mac OSX, if the file is stdin, it will call again up to 5 times to try to satisfy the full request. The total bytes read can not be more than 2 GB on either system.

size_t b3dFwrite(void *buf, size_t size, size_t count, FILE *fp)

A substitute for fwrite that works for large files on all systems.

void b3dRewind(FILE *fp)

A substitute for rewind that works for large files on all systems.

int mrc_big_seek(FILE *fp, int base, int size1, int size2, int flag)

Does a seek in a large file with pointer fp.  The amount to seek is given by base + size1 * size2.  flag has the standard meaning for seeks, e.g., SEEK_SET, etc.  Returns the nonzero seek error if error.

int mrcHugeSeek(FILE *fp, int base, int x, int y, int z, int nx, int ny, int dsize, int flag)

Does a seek in a large image file with pointer fp.  The amount to seek is given by base plus the change in position indicated by x, y, and z, where nx and ny are the image dimensions in X and Y and dsize is the number of bytes per data element.  Specifically, it seeks by
  base + x * dsize + nx * dsize * (y + ny * z).
flag has the standard meaning for seeks, e.g., SEEK_SET, etc.  Returns the nonzero seek error if error.

int fgetline(FILE *fp, char s[], int limit)

Reads a line of characters from the file pointed to by fp and places it into array s of size limit.  Replaces newline or return-newline with a null or terminates the string with null if reading stops because the array limit is reached.  Returns the length of the string, -1 for an error, -2 for end of file after a newline, or the negative of the length of the string plus two for end of file on a line not terminated by newline.

int dataSizeForMode(int mode, int *dataSize, int *channels)

For the given MRC file mode or SLICE_MODE_MAX in mode, returns the number of bytes of the basic data element in dataSize and the number of data channels in channels. Returns -1 for an unsupported or undefined mode.

void b3dHeaderItemBytes(int *nflags, int *nbytes)

Returns the number of possible extra header items encoded as short integers by SerialEM in nflags, and the number of bytes that each occupies in nbytes, an array that should be dimensioned to 32.

void b3dheaderitembytes(int *nflags, int *nbytes)

A Fortran wrapper for b3dHeaderItemBytes

int extraIsNbytesAndFlags(int nint, int nreal)

Returns 1 if the nint and nreal members of an MRC header represent number of bytes and flags from SerialEM, 0 otherwise.

int extraisnbytesandflags(int *nint, int *nreal)

A Fortran wrapper for extraIsNbytesAndFlags

void setOrClearFlags(b3dUInt32 *flags, b3dUInt32 mask, int state)

Set or clear bits in flags with the given mask, depending on whether state is nonzero or zero.

int numberInList(int num, int *list, int nlist, int noListValue)

Return 1 if num is in the list of nlist values in list, 0 if it is not, and noListValue if the list is empty (nlist 0 or list NULL).

int numberinlist(int *num, int *list, int *nlist, int *noListValue)

Fortran wrapper for numberInList

void balancedGroupLimits(int numTotal, int numGroups, int groupInd, int *start, int *end)

Computes inclusive limits start and end of group at index groupInd when dividing a total of numTotal items into numGroups groups as evenly as possible, with the remainder from the division distributed among the first groups.

void balancedgrouplimits(int *numTotal, int *numGroups, int *groupInd, int *start, int *end)

Fortran wrapper for balancedGroupLimits

unsigned char **makeLinePointers(void *array, int xsize, int ysize, int dsize)

Returns a set of pointers to the lines of array, which has xsize data elements per line, ysize lines, and data element size dsize.  Returns NULL for memory error.

int b3dIMin(int narg, ...)

A variable argument min function for multiple integer arguments. Call as:  b3dIMin(4, ival1, ival2, ival3, ival4); For only two arguments with acceptable cost of multiple evaluations, use the macro, B3DMIN(val1, val2);

int b3dIMax(int narg, ...)

A variable argument max function for multiple integer arguments. Call as:  b3dIMax(4, ival1, ival2, ival3, ival4); For only two arguments with acceptable cost of multiple evaluations, use the macro, B3DMAX(val1, val2);

double wallTime(void)

Returns a measure of time in seconds with microsecond precision on Linux and Mac and the precision of the high performance counter on Windows.

double walltime(void)

Fortran wrapper for wallTime

int b3dMilliSleep(int msecs)

Sleeps for msec milliseconds.  Returns 0 on Windows; elsewhere it returns -1 for an error or the number of times the sleep was interrupted.

int b3dmillisleep(int *msecs)

Fortran wrapper for b3dMilliSleep

int numOMPthreads(int optimalThreads)

Computes the number of threads to specify in an OpenMP directive by taking the minimum of the given optimal thread number optimalThreads, the number of processors, and the value of OMP_NUM_THREADS, if any.  It evaluates the number of processors and value of OMP_NUM_THREADS only on the first call.  It attempts to limit the number of processors to the number of physical cores by calling int numCoresAndLogicalProcs.  If the environment variable IMOD_REPORT_CORES is set, it reports whatever values it received from that routine. Returns 1 if there is no OpenMP available.

int numompthreads(int *optimalThreads)

Fortran wrapper for numOMPthreads

int b3dOMPthreadNum()

Returns the thread number of the current thread, numbered from 0 when calling from C or numbered from 1 when calling the Fortran wrapper.

int numCoresAndLogicalProcs(int *physical, int *logical)

Returns the number of physical processor cores in physical and the number of logical processors in logical.  The return value is 1 if valid information could not be obtained for both items.  It uses sysctlbyname on Mac, GetLogicalProcessorInformation on Windows, and /proc/cpuinfo on Linux.

int totalCudaCores(int major, int minor, int multiprocCount)

Returns the total number of CUDA cores given the compute capability values in major and minor and the number of multiprocessors in multiprocCount.

double b3dPhysicalMemory()

Returns the total physical memory in the system in bytes, or 0 if it is not available

double b3dphysicalmemory()

Fortran wrapper to b3dPhysicalMemory

char **expandArgList(const char **argVec, int numArg, int *newNum, int *ifAlloc, int *noMatchInd)

Does wildcard expansion of filenames in the vector of argument strings in argVec, processing numArg strings.  This operation is done only in Windows.  The new number of arguments is returned in newNum, and ifAlloc is set non-zero if new strings are actually allocated.  In that case, the return value is the new vector; otherwise the return value is simply argVec.  If a string fails to match any files, it is passed unchanged; noMatchInd is set to the index of the first such argument.  Returns NULL for memory allocation errors.

int replaceFileArgVec(const char ***argv, int *argc, int *firstInd, int *ifAlloc)

On Windows, replaces the portion of an argument vector consisting only of filenames with a new list if any of the strings need wild-card expansion.  Pointers to the original argument vector and number of arguments must be passed in argv and argc, respectively, and firstInd should be a pointer to the index of the first argument after any option entries.  If no expansion is done, these entries are not modified and ifAlloc is returned with a 0.  If any filenames are expanded, argv is returned with a new vector consisting of just the expanded filenames, argc is returned with the new number of strings, and ifAlloc is returned with a 1.  The return value is 0 for success, -1 for a memory allocation error, and 1 for failure to match an entry with wildcards.  Error messages are set with b3dError in each case.

float b3drand()

Fortran-callable function to return a random number between 0 and 1 from the standard C library rand() function.

void b3dsrand(int *seed)

Fortran-callable function to seed the b3drand random number generator with the value of seed.

float b3dran(int *seed)

Fortran-callable function to generate a random number between 0 and 1 using the standard C library rand() function.  The random number generator is seeded by calling C library srand() function with seed whenever a different value of seed is passed.  seed is never returned with a new value.  It behaves like the Intel Fortran compiler ran() compatibility function in that if it is called repeatedly with seed, it will continue to generate new numbers in a sequence, unless a new value of seed is passed.

double angleWithinLimits(float angle, float lowerLim, float upperLim)

Returns angle or a value adjusted by a multiple of upperLim - lowerLim so that angle is greater than lowerLim and less than or equal to upperLim.

double anglewithinlimits(float *angle, float *lowerLim, float *upperLim)

Fortran wrapper for angleWithinLimits

void b3dSetLockTimeout(float timeout)

Sets the timeout that will be assigned when a new lock file is opened, in seconds; the default is 30 sec.

void b3dsetlocktimeout(float *timeout)

Fortran wrapper for b3dSetLockTimeout

int b3dOpenLockFile(const char *filename)

Opens the file whose name is in filename for use as a lock file with the following routines.  Up to 8 such files can be opened.  Returns an index to be used in following calls for locking, unlocking, or closing the file, numbered from 0, -1 if too many lock files are open, or -2 if the file could not be opened.

int b3dopenlockfile(char *filename, int namelen)

Fortran wrapper for b3dOpenLockFile.  Returns -3 for failure to convert string

int b3dLockFile(int index)

Obtains a lock on the file with the given index, retrying every 50 ms until the timeout defined for this file is reached.  Returns -1 for an index out of range, -2 if no lock file is open with the given index, or 1 if the lock could not be obtained.  If the file is already locked by this process, increments a lock count that is decremented on each call to b3dUnlockFile.

int b3dlockfile(int *index)

Fortran wrapper for b3dLockFile

int b3dUnlockFile(int index)

Releases a file lock at the given index, or just decrements the lock count if it is greater than 1.  Returns -1 for an index out of range, -2 if no lock file is open with the given index, -3 if the file is not locked, or 1 if there is an error in the call to unlock the file.

int b3dunlockfile(int *index)

Fortran wrapper for b3dUnlockFile

int b3dCloseLockFile(int index)

Closes the lock file at the given index.  Returns -1 for an index out of range, -2 if no lock file is open with the given index, or 1 if there is an error in the call to unlock the file.

int b3dcloselockfile(int *index)

Fortran wrapper for b3dCloseLockFile