Imsubs File and Stream Functions

Reference Guide

Introduction

Compiling and Linking

Release Notes

Library Functions


Introduction

About the IMSubs File Format

IVE images are stored using the Imsubs image file format. This format is derived from, the "MRC" file format, which was originated at the Medical Research Council in Cambridge, England.

In brief, Imsubs images consist of several main parts:

Primary header
Is a 1024 byte section that describes the history of the image and its primary attributes.
Extended header
Holds additional information about the image data. A field in the primary header sets its size.
Image data elements
Is a table of numbers representing the intensity of a regularly spaced array of picture elements. Fields in the primary header set the number of columns, rows, and sections expected as well as the how each element is encoded.
Sub-resolution image data elements
Holds zero or more downsampled versions of the data. Fields in the primary header set the total number of resolutions and the z downsampling factor.

The functions described in this document were originally intended for manipulating image data stored on hard disks. Over time, the functions were enhanced, so that they can also manipulate image data contained in computer display windows. The distinction between files and windows is simple: when a stream is opened with a simple numeric name, such as "1" or "2", the stream will be connected to window with the same number; when a stream is opened with a more complicated file name, such as "myfile" the functions will connect the stream to a file.

When linking your application, you can choose whether or not to use the extended versions; see Compiling and Linking for details. In the case where these functions are being used to connect streams to windows, you will probably want to use functions from the Image Window Library (IWL) to better control how the data is presented in the window.


Imsubs Image Files

Imsubs image files consist of a header, extended header, and image data. Each part is detailed below.

Image Header

The Imsubs image header has a fixed size of 1024 bytes. The information within the header includes a description of the extended header and image data. Imsubs will write one of two header formats. The first format is primarily used for optical microscope data and is the same format as Priism has used for years. priism_mrc_header.html describes its header layout. The second format is primarily used for electron microscope data and deviates less from the Image2000 format used for crystallography and the MRC2014 format. em_mrc_header.html describes the header layout for the second format. The Imsubs library automatically recognizes the two formats and presents much the same programming interface for working with them. You can use the Imsubs functions, IMRtHdrFmt() (irthfmt() in Fortran) and IMAlHdrFmt() (ialhfmt() in Fortran), to control which of the two header formats that library uses. If you are working with the files without the Imsubs library, the easiest way to distinguish the two formats is to look at bytes 209 through 214 (with one as the first byte in the file). The EM format has the ASCII character string 'MAP ' (i.e. 115, 101, 120, and 40) in bytes 209 through 212 and either 17 and 17 (indicating big-endian data) or 68 and 65 (indicating little-endian data) in bytes 213 and 214. Priism's original format does not have a fixed pattern for the values in those bytes.

Image File Extended Header

The extended header follows immediately after the standard header. It contains additional information that relates to each individual section. The layout of the extended header is determined by the contents of the standard header.

Most importantly, the total size (next) is given by the signed 32-bit integer in header bytes 93 through 96. The signed 32-bit integer in bytes 89 through 92 (nspg) indicate how the extended header should be interpreted. Values between one and 230 (if using Priism's standard version of the header) or between two and 230 (if using the EM version of the header) are used for crystallographic data. All other values for nspg assumed to correspond to crystallographic data. If you use the IM library, the helper function, IMRtExHdrFmt() (irtexhf() in Fortran), is the recommended way to test whether the extended header represents crystallography symmetry information.

For non-crystallogaphic data, the extended header contains NumInts (from the signed 16-bit integer in bytes 129 and 130) 4-byte integers and NumFloats (from the signed 16-bit integer in bytes 131 and 132) 4-byte floating-point values per section so the size of the extended header should be at least

     (NumInts + NumFloats) * NumSections * 4

where NumSections is the signed 32-bit integer in bytes 9 - 12 of the header. The size may be more than that with the extra bytes unused. The extended header values for section k (k in the range of 1 to NumSections) start at the offset (from the beginning of the file),

    1025 + (k - 1) * (NumInts + NumFloats) * 4

The integer values for the section appear first and the floating-point values appear after them; all are packed contiguously. The byte ordering for the extended header is the same as for the primary header. For more details about the extended header for image data, see IMRtExHdrType and IMRtExHdrValueZWT.

Four extended header formats that have been used for data collection systems in the Agard and Sedat labs are:

UCSF Tomography
Has thirty two floating-point values and zero integer values for each image. UCSFTomographyExtendedHeader.html describes how the values are used.
EM430 and older EM microscopes
Data from these systems have the image type set to five and use either two floating-point values or one floating-point value and one integer value for each image. With two floating-point values, the first is the setting for the objective lens current and the second is the tilt angle, in degrees. With one floating-point value and one integer, the floating-point value is the tilt angle in degrees, and the integer is the setting for the objective lens current.
OM1
Has one integer and one floating-point value per image. The integer value is the photosensor reading and the floating-point value is the exposure time in seconds.
OM0
Has three integer values and one floating-point value per image. The first integer value is the least significant portion of the photosensor reading. The second integer value is the most significant portion of the photosensor reading. The third value is the number of conversions performed by the photosensor. The floating-point value is the exposure time in seconds.

In the case of x-ray crystallographs, the extended header contains symmetry information, as outlined in International Tables. Operators are separated by an asterisk, "*", and grouped into lines of 80 characters. Note that symmetry operators cannot extend beyond an 80 character width and do not terminate with an asterisk. Symmetry information is not used with Priism images.

Image Data

The image data immediately follow the extended header. The bytes between the offsets, (n-1)*m+1) and n*m, past the extended header hold the value for the n element of the image data. m is the number of bytes per pixel as indicated in the list of pixel data types. The byte ordering for multi-byte pixel formats is the same as is used in the primary header. The nth element belongs to the ((n-1) modulo ncol + 1) column, (((n-1) / ncol) modulo nrow + 1) row, and ((n-1) / (ncol*nrow)) section. ncol is the 32-bit signed integer in bytes 1 through 4 of the header. nrow is the 32-bit signed integer in bytes 5 through 8 of the header. The section index may represent one or more dimensions for more information on that see the description of the image sequence values. The different image types can also describe how different sections in the data relate to one another. The maximum value for the section index is the 32-bit integer in bytes 9 through 12 of the header.

The ith (i is an integer greater than zero) resolution data set should be present if the 16-bit signed integer in bytes 133 and 134 of the header is greater than i. That data immediately follows the (i-1)th resolution (the 0th resolution is the full resolution data described above) and has the same layout except that the number of columns and rows is one half (truncating any remainder) of the previous resolution and the number of z sections is divided by the z downsampling factor (the 16-bit signed integer in bytes 136 and 136 of the the header) with any remainder rounded up. Any other dimensions contributing to the section count are not downsampled.


Image Types

The type of a Priism image is given by the signed 16-bit integer in header bytes 161 and 162. The meaning of these types is given in the table below. The floating-point attributes, v1 and v2, used by some image types are stored as 16-bit signed integers in the header; to do so the values are multiplied by 100 and rounded to the nearest integer when stored and are divided by 100 when retrieved. These conversions are automatically applied if the IMAlDat or IMRtDat calls are used.

0 (IM_NORMAL_IMAGES)
Used for normal image data.
1 (IM_TILT_SERIES)
Used for single axis tilt series with a uniform angle increment. n1 specifies the tilt axis (1 for x, 2 for y, 3 for z) and v1 the angle increment in degrees. n2 relates the coordinates in the tilt series to coordinates in a 3D volume: the assumed center of rotation is the z origin from the header plus n2 times one half of the z pixel spacing from the header. v2 is always zero.
2 (IM_STEREO_TILT_SERIES)
Used for stereo tilt series. n1 specifies the tilt axis (1 for x, 2 for y, 3 for z), v1 the angle increment in degrees, and v2 is the angular separation in degrees for the stereo pairs. n2 is always zero.
3 (IM_AVERAGED_IMAGES)
Used for averaged images. n1 is the number of averaged sections and n2 is the number of sections between averaged sections. v1 and v2 are always zero.
4 (IM_AVERAGED_STEREO_PAIRS)
Used for averaged stereo pairs. n1 is the number of averaged sections, n2 is the number of sections between averaged sections, and v2 is the angular separation in degrees for the stereo pairs. v2 is always zero.
5 (IM_EM_TILT_SERIES)
Used for EM tomography data. The tilt angles are stored in the extended header.
20 (IM_MULTIPOSITION)
Used for images of well plates. The following quantities are bit-encoded in n1 (valid range for each is show in parentheses): iwell (0-3), ishape (0-1), ibin (0-15), ispeed (0-2), igain (0-3), and mag (0-1). n2 is the number of fields per well. v1 is the fill factor (.01 to 1.5 in .01 steps). v2 is not used.
8000 (IM_PUPIL_FUNCTION)
Used for images of pupil functions. n1 and n2 are not used. v1 is the numerical aperture times ten. v2 is the immersion media refractive index times one hundred. The pixel spacings and origin have units of cycles per micron rather than microns.

Pixel Data Types

The data type used for image pixel values, stored as a signed 32-bit integer in bytes 13 through 16, is designated by one of the code numbers in the following table.

CodeC/C++ MacroDescription
0IW_BYTE1-byte unsigned integer
1IW_SHORT2-byte signed integer (two's complement for negative values)
2IW_FLOAT4-byte floating-point (IEEE)
3IW_COMPLEX_SHORT4-byte complex value as 2 2-byte signed integers
4IW_COMPLEX8-byte complex value as 2 4-byte floating-point (IEEE) values
5IW_EMTOM2-byte signed integer (two's complement for negative values)
6IW_USHORT2-byte unsigned integer
7IW_LONG4-byte signed integer (two's complement for negative values)
101IW_U4BIT4-bit unsigned integer. Within a row, the values are stored contiguously. A byte holds the value from an even column in the least significant 4 bits and holds the value from the next odd column in the most significant 4 bits. If the number of columns is odd, the row is padded at the end with 4 bits so that start of the rows are aligned on byte boundaries.

Note that IMLIB functions that read images from a storage device will always convert the data to floating-point. Also, IMLIB functions that write images to the storage device will always convert images from floating-point to the type indicated by PixelType (in header bytes 13 through 16). If necessary, use the IWAlCon function to prevent conversion to and from floating-point data.

Type codes 5, 6, 7, and 101 are not standard MRC types and are not likely to be correctly interpreted by other software that uses MRC files.


Image Sequence Values

The sections in the MRC file may represent several different dimensions of the data. If the data uses Priism's header format, the section index is decomposed to three indices, z, wavelength, and time. The number of wavelengths (nw)is set by the signed 16-bit integer in bytes 197 through 198 of the header (most applications, however, will only recognize up to five wavelengths). The number of time points (nt) is set by the signed 16-bit integer in bytes 181 and 182 of the header. The number of z sections (nz) is the total number of sections (ns) divided (with the remainder discarded) by the product of the number of wavelengths and time points. The header field for the image type indicates how to interpret the z sections. The ordering of the z, wavelength, and time sections in the file is indicated by the signed 16-bit integer in bytes 183 and 184 of the header. Currently three values for that integer are understood. They are:

0 (C/C++ macro is ZTW_SEQUENCE)
This is the normal arrangement for processed images. Sometimes referred to as "non-interleaved". The relationship between the section index, is with 0 <= is < ns, and the z (iz), wavelength (iw), and time (it) indices is is = iz + nz * (it + nt * iw). Reversing that gives iz = is modulo nz, iw = is / (nz * nt), and it = (is / nz) modulo nt.
1 (C/C++ macro is WZT_SEQUENCE)
This is the typical arrangement for images acquired from a microscope. Sometimes referred to as "interleaved". The relationship between the section index, is with 0 <= is < ns, and the z (iz), wavelength (iw), and time (it) indices is is = iw + nw * (iz + nz * it). Reversing that gives iz = (is / nw) modulo nz, iw = is modulo nw, and it = is / ( nw * nz).
2 (C/C++ macro is ZWT_SEQUENCE)
Although not widely used, ZWT will find uses with certain processing algorithms. The relationship between the section index, is with 0 <= is < ns, and the z (iz), wavelength (iw), and time (it) indices is is = iz + nz * (iw + nw * it). Reversing that gives iz = is modulo nz, iw = (is / nz) modulo nw, and it = is / (nz * nw).

If the data is in the EM header format, it should fall into one of these three categories based on the value of the space group, the signed 32-bit integer in bytes 89 through 92:

0
The ns sections in the file should be interpreted as appropriate for the value of the image type.
1
The ns sections in the file should be interpreted as ns parallel slices through one volume. For use with Priism, the image type would normally be zero.
401
The ns sections in the file should be interpreted as nv volumes each with nvz slices. nvz is the signed 32-bit bit integer in bytes 37 through 40 of the header, and nv is ns divided by nvz (discarding any remainder). The nvz slices of the first volume appear first in the file, followed by the nvz slices of the second volume, and so on.

The IMSubs library will report one wavelength for all three categories. It will report one time point for the first two categories, and nv time points for the third category. All three categories will be reported as having the ZTW_SEQUENCE interleaving. If you use the IMSubs library to alter the number of wavelengths, number of time points, or interleaving, consult the function call documentation (IMAlZWT() or IMAlWav()) for how the IMSubs library will change the space group or header representation, to satisfy the request.


Compiling and Linking

Programs written in C/C++ which use the IM functions should include IWInclude.h to provide prototypes and define structures and macros used with the IM functions. If you only use the IM functions and do not use the IWL calls, you can, starting with the March 2000 release of IVE 3.3, include IMInclude.h rather than IWInclude.h. The version of the library for Windows only provides IMInclude.h. To define constants for the different extended header types and values as used by IMRtExHdrType, IWRtExHdrValueZWT, or IWAlExHdrValueZWT, programs written in fixed-format Fortran should include exhdr.inc and programs written in free-format Fortran should include exhdr.inc90.

When linking your application, link against libIWL.a or libIWL.so (libIWL.dylib on Mac OS X) to get the extended IM functions which can operate on image windows; otherwise, link against libimlib.a or libimlib.so (libimlib.dylib on Mac OS X). The version of the library for Windows only provides the archive library, libimlib.a.

Another library, libimcompat.a, provides functions that were previously packaged with the IM and IW libraries but which were primarily used by Fortran programs and which were not documented in the IM and IW library documentation. At this point, that library is only available for OS X and Linux.

Platform Specifics

x86 Linux

To use the x86 Linux libraries, you will need an x86 Linux system that supports compiling ELF executables and has glibc2.3 or later. To use the IW library and headers, the X libraries and headers must be installed.

The headers are located in the Linux/x86/INCLUDE directory of the Priism distribution. IWInclude.h (via IWL.h) includes one of the X include files; so if your code includes either of those files and the X include directory is not in the search path, it will be necessary to add the X include directory to the search path (in most cases, adding

     -I/usr/X11R6/include

to the compilation options will do this).

The libraries are located in the Linux/x86/LIB directory of the Priism distribution. If you link against libIWL.so, it is necessary to instruct the linker to search Linux/x86/LIB for libraries that libIWL.so uses. If you invoke the linker directly, this can be done by adding

     -rpath-link install_dir/Linux/x86/LIB

to the linker options (replace install_dir with the path to the Priism distribution). If the compiler is used to invoke the linker, then you will need to determine how to instruct the compiler to pass the above option to the linker; for most compilers it can be done with

     -Wl,-rpath-link,install_dir/Linux/x86/LIB

libIWL.so also depends on the X libraries so if the X library directory is not in the directory search path it is also necessary to supply a -rpath-link option for the X library directory.

When you use the shared library, it can be useful to set the path from which to load the library in the generated executable. Otherwise, you'll need to set the LD_LIBRARY_PATH environment variable to include the path to the Priism libraries prior to running your executable. To set the path from which to load the library in the executable, add

    -rpath install_dir/Linux/x86/LIB

to the linker options if you invoke the linker directly to make the executable. If you use the compiler to generate the executable, this,

    -Wl,-rpath,install_dir/Linux/x86/LIB

will work with most compilers. If you want to use the executable on systems where Priism installed in a different location, it is easiest if you maintain the same relative path between where the executable is and where Priism is installed. Then you would use

    -rpath '$ORIGIN'/relative_path

as the linker option if invoking the linker directly or, typically,

    -Wl,-rpath,'$ORIGIN'/relative_path

if using the compiler to generate the executable. In either case, replace relative_path with the relative path from where the executable will be installed to where the Priism libraries will be located. $ORIGIN is quoted so that it will not be expanded by the shell. The dynamic linker, ld.so, will replace $ORIGIN with the path to the executable.

If you use the archive libraries (libimlib.a or libIWL.a), it is necessary to link against the libraries that those libraries use. For libimlib.a, these additional libraries can be specified on the command-line as

     install_dir/Linux/x86/LIB/libive.a -lm -lc

For libIWL.a, the additional libraries can be specified on the command line as

     -lX11 install_dir/Linux/x86/LIB/libive.a -lm -lc

(this assumes that the X libraries are in the library directory search path; if not it will be necessary to add them).

For Fortran programs, the name mangling of the libraries is compatible with the default mangling done by the Intel Fortran compiler (names are converted to lower case with a single underscore appended to the end). The library includes alternate entry points which are compatible with the default name mangling done by g77. Two versions of libimcompat.a are included: the one in install_dir/Linux/x86/LIB is for gfortran (it was generated by gfortran 4.8.5), and the one in install_dir/Linux/x86/LIB/pg is for the Portland Group compiler (version 10.2 was used to generate the library).

x86_64 Linux

To use the x86_64 Linux libraries, you will need an x86_64 Linux system with glibc 2.3. To use the IW library and headers, the X libraries and headers must be installed.

The headers are located in the Linux/x86_64/INCLUDE directory of the Priism distribution. IWInclude.h (via IWL.h) includes one of the X include files; so if your code includes either of those files and the X include directory is not in the search path, it will be necessary to add the X include directory to the search path (in most cases, adding

     -I/usr/X11R6/include

to the compilation options will do this).

The libraries are located in the Linux/x86_64/LIB directory of the Priism distribution. If you link against libIWL.so, it is necessary to instruct the linker to search Linux/x86/LIB for libraries that libIWL.so uses. If you invoke the linker directly, this can be done by adding

     -rpath-link install_dir/Linux/x86/LIB

to the linker options (replace install_dir with the path to the Priism distribution). If the compiler is used to invoke the linker, then you will need to determine how to instruct the compiler to pass the above option to the linker; for most compilers it can be done with

     -Wl,-rpath-link,install_dir/Linux/x86/LIB

libIWL.so also depends on the X libraries so if the X library directory is not in the directory search path it is also necessary to supply a -rpath-link option for the X library directory.

When you use the shared library, it can be useful to set the path from which to load the library in the generated executable. Otherwise, you'll need to set the LD_LIBRARY_PATH environment variable to include the path to the Priism libraries prior to running your executable. To set the path from which to load the library in the executable, add

    -rpath install_dir/Linux/x86_64/LIB

to the linker options if you invoke the linker directly to make the executable. If you use the compiler to generate the executable, this,

    -Wl,-rpath,install_dir/Linux/x86_64/LIB

will work with most compilers. If you want to use the executable on systems where Priism installed in a different location, it is easiest if you maintain the same relative path between where the executable is and where Priism is installed. Then you would use

    -rpath '$ORIGIN'/relative_path

as the linker option if invoking the linker directly or, typically,

    -Wl,-rpath,'$ORIGIN'/relative_path

if using the compiler to generate the executable. In either case, replace relative_path with the relative path from where the executable will be installed to where the Priism libraries will be located. $ORIGIN is quoted so that it will not be expanded by the shell. The dynamic linker, ld.so, will replace $ORIGIN with the path to the executable.

If you use the archive libraries (libimlib.a or libIWL.a), it is necessary to link against the libraries that those libraries use. For libimlib.a, these additional libraries can be specified on the command-line as

     install_dir/Linux/x86/LIB/libive.a -lm -lc

For libIWL.a, the additional libraries can be specified on the command line as

     -lX11 install_dir/Linux/x86/LIB/libive.a -lm -lc

(this assumes that the X libraries are in the library directory search path; if not it will be necessary to add them).

For Fortran programs, the name mangling of the libraries is compatible with the default mangling done by the Intel Fortran compiler (names are converted to lower case with a single underscore appended to the end). The library includes alternate entry points which are compatible with the default name mangling done by g77. Two versions of libimcompat.a are included: the one in install_dir/Linux/x86_64/LIB is for gfortran (it was generated by gfortran 4.8.5), and the one in install_dir/Linux/x86_64/LIB/pg is for the Portland Group compiler (version 10.2 was used to generate the library).

Mac OS X

To use the IW library on Mac OS X, it is necessary to have the X libraries and include files installed. To link applications with the Priism libraries you'll likely need Mac OS X 10.7.4 or later and XCode 4.5 or later since the libraries include load commands that are not understood by earlier versions of XCode.

If you are compiling a 32-bit application, the headers are located in the Darwin/INCLUDE directory of the Priism distribution. If you are compiling a 64-bit application, the headers are located in Darwin64/INCLUDE. IWInclude.h (via IWL.h) includes one the X include files; so if your code includes either of those files, you will have to add the X include directory to the search path (in most cases, adding

     -I/usr/X11R6/include

to the compilation options will do this).

The 32-bit libraries are located in the Darwin/LIB directory of the Priism distribution. The 64-bit libraries are included in the Darwin64/LIB directory of the Priism distribution. Since Priism 4.5.0, all the Priism shared libraries have been set up to expect that the executable sets rpath to be the path to the Priism directory with the executables for the appropriate platform. If you use the linker directly, you can do that by adding the option

    -rpath install_dir/Darwin/BIN

if you are building a 32-bit executable or

    -rpath install_dir/Darwin64/BIN

if you are building a 64-bit executable. In either case, replace install_dir with the path to the Priism distribution. If you use the compiler to invoke the linker, then, for most compilers, you would use the option

    -Wl,-rpath,install_dir/Darwin/BIN

for a 32-bit executable or

    -Wl,-rpath,install_dir/Darwin64/BIN

for a 64-bit executable. If you want to use the executable on systems where Priism may not be installed in the same location, it is easiest if you maintain the same relative path between where the executable is and where Priism is installed. If you can do that, the option you would add when building the executable is similar to those already given except that you would replace install_dir with @loader_path/relative_path/ where relative_path is the relative path from where the executable will be to where the Priism executable directory will be. If you can't guarantee a fixed location for the location of Priism or the same relative path between your executable and Priism, you'll need to set either the DYLD_LIBRARY_PATH or DYLD_FALLBACK_LIBRARY_PATH environment variables to include the path to the Priism libraries before running your executable.

If you use libimlib.a, you'll also have to link with either the dynamic version (libive.dylib) or the archive version (libive.a) of libive. Assuming you want the archive version, you'd add

    install_dir/Darwin/LIB/libive.a

to the link options for the 32-bit library where you must replace install_dir with the path to Priism's top-leve directory. For the 64-bit library you'd add

    install_dir/Darwin64/LIB/libive.a

to the link options. Linking with libIWL.a is similar, but you'll also have to link with the X11 library, i.e. use

    install_dir/Darwin/LIB/libive.a -lX11

for the 32-bit library and

    install_dir/Darwin64/LIB/libive.a -lX11

for the 64-bit library. With XFree86 or Apple's X11, the X library is in /usr/X11R6/lib.

For Fortran programs, the name mangling of the libraries is compatible with typical Unix behavior (names converted to all lowercase with an underscore appended). The library includes alternate entry points which are compatible with the default name mangling done by g77. Two versions of libimcompat.a are included. The one in install_dir/Darwin/LIB is a 32-bit library for gfortran (the library was generated with gfortran 4.8.5). The version of libimcompat.a in install_dir/Darwin64/LIB is a 64-bit library for gfortran (the library was generated with gfortran 4.8.5).

Windows

A 32-bit version of the archive library, libimlib.a is in the win32/LIB directory. The corresponding include files are in win32/INCLUDE. The 64-bit version of the library is in win64/LIB, and the include files are in win64/INCLUDE. When you link against libimlib.a, you'll also have to link against libive.a, which is in same directory as libimlib.a. The only other symbols needed are in the system libraries, KERNEL32.dll and msvcrt.dll.

The libraries were generated with a mingw-w64 cross-compiler running under Linux. The libraries have only been tested with that compiler, but should work easily with other compilers. The tests of the library on different versions of Windows have been limited to Windows 7 and 32-bit Windows XP. No problems were found on Windows 7, but the tests for files larger than two or four gigabytes did not work on 32-bit Windows XP.


Release Notes

Changes in IVE 4.5.0 which may break Makefile compatibility:

Changes in 4.5.0 which may break backward binary or Makefile compatibility:

Changes in IVE 4.4.0 which may break backward source or binary compatibility are:

Changes in IVE 4.3.0 which may break backward makefile compatibility or binary compatibility are:

Changes in IVE 4.2.9 which may break backward makefile or binary compatibility:

Changes in IVE 4.2.7 which may break backward makefile compatibility are:

Changes in IVE 4.2.6 which may break backward makefile compatibility are:

Changes in IVE 4.1.2 which break backward makefile compatibility are:

Changes in IVE 4.1.0 which break backward makefile compatibility are:

Changes between IVE 4 and IVE 3.3 which break backward source or makefile compatibility are:

The following constants were added in IVE 4.6.1:

The following functions or constants have been added in IVE 4.4.0:

The following functions have been added in IVE 4:

Other changes made between IVE 4 and IVE 3.3 are:

Changed made in IVE 3.3:


Library Functions

Described below are the IM library functions. Functions prototypes are provided in IWL.h, and the functions themselves can be obtained by linking with libIWL.a (or libIWL.so). Definitions can be found in IWApiConstants.h.

Categories of Functions:

File Header - "IM*Hdr"

Alter Image Information - "IMAl"

Return Image Information - "IMRt"

Read Image Information - "IMRd"

Write Image Information - "IMWr"

Stream Pointer Functions

Identifying the Stream Type


File Header - "IM*Hdr"

Functions that work with the entire image header or large sections of the header.

IMOpen - Open an image file and attach it to a stream.
IMClose - Close the stream and associated image file.
IMRdHdr - Read the header from the stored image.
IMWrHdr - Write the image header to the storage device.
IMGetHdr - Get the entire header in a single block of memory.
IMPutHdr - Put an entire header into a stream.
IMGetExHdr - Get the entire extended header in a single block of memory.
IMTrHdr - Transfer a header from one stream to another.
IMTrLab - Transfer image titles from one stream to another.
IMTrCel - Transfer the cell properties from one stream to another.
IMCrHdr - Create a new header with certain user defined properties.
IMRtHdrFmt - Returns how the IM library interprets the primary header.
IMAlHdrFmt - Alters how the IM library interprets the primary header.
IMRtExHdrFmt - Returns how to interpret the extended header data.
IMTrExHdr2 - Transfer the extended header from one stream to another.
IMFixExHdr - Fix extended header values
IMFixExHdrZWT - Fix extended header values.
IMTrExHdr - Transfer the extended header corresponding to a single section from one stream to another.


IMOpen

Name

IMOpen - Open an image file and attach it to a stream.

C Synopsis

int IMOpen(int StreamNum, const char *Name, const char *Attributes);

Fortran Synopsis

integer function imopen(streamnum,name,attributes)
integer istream
character name*(*)
character attributes*(*)

Description

Open an image file named Name and attach it to stream number StreamNum. StreamNum must be a positive integer. Name can either be a file name, or a window number. For example, if Name="/tmp/my_image" then the image file on the disk will be attached to the stream. If Name="1", then window number 1 will be attached to the stream. For this reason, it is not possible to use image files with simple numeric names such as "1", "2", or "3".

Remote programs can access windows on your Priism session or files only visible to your local machine. In this case Name is the window number or filename preceded by :: (two colons). See the Remote Process Event Handling topic in WM.html for details on how to set up such a remote program.

Use one of the image attributes listed below:

ro
Opens an existing file or image window for reading only.
new
Creates a file or image window and opens it for reading and writing.
old
Opens an existing file or image window for reading and writing.
scratch
Creates a new file or image window. In the case of a file, functions identically to the "new" option except the file will automatically be deleted when closed. The behavior is very different for an image window. A new window is created and is opened for reading and writing. The window can have multiple wavelengths or z sections, but the number of time points is forced to be one. The window can only have one resolution. For a scratch window with one wavelength, new images are written to increasing z section numbers (regardless of the z position set with IMPosn or IMPosnZWT) until the last z section is filled. After that, subsequent writes cause all the previous images to be shifted down by one z section and the new image is written to the last z section. In the process, the oldest image is lost. A scratch window with multiple wavelengths functions similarly but the wavelengths are not treated independently. If the wavelength with the most images written has n images, a write to another wavelength will fill the n minus one z section unless the other wavelength also has n images. In that case the image will be written to the nth z section: if n is equal to the number of z sections that can be stored, all wavelengths are shifted down and the image is written to the n minus one z section.

Return Values

IMOpen returns TRUE when an error has occurred, and otherwise returns FALSE. See also IMClose.

Side Effects

IMOpen for an image window or remote resource can have the side effect of calling getenv(). Because of that, if you have a pointer in C or C++ returned by getenv() (perhaps through some other interface that calls getenv()) and want to guarantee that the pointed to value is preserved after the call to IWOpen() for an image window or remote resource, you have to copy the value to other storage.


IMClose

Name

IMClose - Close the stream and associated image file.

C Synopsis

void IMClose(int StreamNum);

Fortran Synopsis

subroutine imclose(streamnum)
integer streamnum

Description

To ensure that all buffers are emptied, use IMClose when finished with StreamNum. See also IMOpen.


IMRdHdr

Name

IMRdHdr - Read the header from the stored image.

C Synopsis

void IMRdHdr(int StreamNum, int ixyz[3], int mxyz[3], int *PixelType, float *Min, float *Max, float *Mean);

Fortran Synopsis

subroutine irdhdr(istreamnum, inxyz, mxyz, ipixeltype,dmin,dmax,dmean)
integer istreamnum,ipixeltype
dimension inxyz(3), mxyz(3)
real dmin,dmax,dmean

Description

This call must be used before any other information can be retrieved using IMRt functions as it reads the header into memory. In addition, basic information is returned through the arguments.

ixyz contains the number of columns, rows and sections in the data file.

mxyz contains the number of columns, rows and sections in the entire unit cell. The values in mxyz usually follow one of the following conventions:

PixelType is the mode the data is stored in. The possibilities are listed in the pixel data types table.

The min, max, and mean intensity here refers to the first wavelength of the data file only. To access other information about the image file, use the IMRt functions.

Reading the header has the side effect of resetting the current position to the first line in the first section of the highest resolution.


IMWrHdr

Name

IMWrHdr - Write the image header to the storage device.

C Synopsis

void IMWrHdr(int StreamNum, const char Title[80], int TitleFlag, float Min, float Max, float Mean);

Fortran Synopsis

subroutine iwrhdrc(istream, title, ntflag, dmin, dmax, dmean)
integer istream
character*(*) title
integer ntflag
real dmin,dmax,dmean

subroutine iwrhdr(istream, title, ntflag, dmin, dmax, dmean)
integer istream
character title*80
integer ntflag
real dmin,dmax,dmean

Description

Write image header associated with StreamNum to the storage device. Use this function to save the results of all IMAl functions. Header modifications are not saved until IMWrHdr is used! The contents of Title will be saved in the header according to the method indicated by ntflag. The minimum, maximum, and mean intensity - Min, Max, and Mean, respectively - of wavelength 0 are also saved in the header every time IMWrHdr is used.

TitleFlag Action

-1

no titles added to the list

0

use Title as the only title

1

add Title to the end of the list

2

add Title to the beginning of the list

IMGetHdr

Name

IMGetHdr - Get the entire header in a single block of memory.

C Synopsis

void IMGetHdr(int StreamNum, void *Header);

Fortran Synopsis

subroutine igethdr(istream, header)
integer istream
character header*1024

Description

Get the header of StreamNum and put it into Header. Header should point to a memory location with 1024 bytes allocated.


IMPutHdr

Name

IMPutHdr - Put an entire header into a stream.

C Synopsis

void IMPutHdr(int StreamNum, const void *Header);

Fortran Synopsis

subroutine iputhdr(istream, header)
integer istream
char header*1024

Description

Header should point to a memory location that contains a complete image header.


IMGetExHdr

Name

IMGetExHdr - Retrieves the entire extended header into a single block of memory.

C Synopsis

void IMGetExHdr(int StreamNum, void *Extended);

Fortran Synopsis

subroutine igetexhdr(istream, extended)
integer istream
real extended(*)

Description

The complete contents of the extended header are copied to Extended.


IMTrHdr

Name

IMTrHdr - Transfer a header from one stream to another.

C Synopsis

void IMTrHdr(int StreamNum, int StreamNum2);

Fortran Synopsis

subroutine itrhdr(istream, istream2)
integer istream,istream2

Description

Transfer the header (including the extended header, if any) associated with StreamNum2 to the header associated with StreamNum.


IMTrLab

Name

IMTrLab - Transfer image titles from one stream to another.

C Synopsis

void IMTrLab(int StreamNum, int StreamNum2);

Fortran Synopsis

subroutine itrlab(istream,istream2)
integer istream,istream2

Description

Transfer the image titles associated with StreamNum2 to those associated with StreamNum.


IMTrCel

Name

IMTrCel - Transfer the cell properties from one stream to another.

C Synopsis

void IMTrCel(int StreamNum, int StreamNum2);

Fortran Synopsis

subroutine itrcel(istream,istream2)
integer istream,istream2

Description

Transfer the cell properties associated with StreamNum2 to those associated with StreamNum.


IMCrHdr

Name

IMCrHdr - Create a new header with certain user defined properties. The remaining properties are determined by default.

C Synopsis

void IMCrHdr(int StreamNum, const int ixyz[3], const int mxyz[3], int PixelType, const char *Titles,
int NumTitles);

Fortran Synopsis

subroutine icrhdr(istream, ixyz, mxyz, iPixelType, Titles, NumTitles)
integer istream,ixyz(3),mxyz(3),iPixelType,NumTitles
character Titles(80,NumTitles)

Description

Creates a new header for StreamNum. The byte-order and header format are not changed (a stream, immediately after a call to IMOpen, will have the machine's byte order and use Priism's original format for the header). ixyz holds the image dimensions: the first component is the number of elements in x, the second is the number of elements in y, and the third is the number of images. mxyz holds the number of divisions in x, y, and z per unit cell. The values in mxyz usually follow one of the following conventions:

iPixelType sets the format used to store the image values; the table of pixel data types lists the allowed values for iPixelType. The number of titles in the new header will be zero if NumTitles is less than one and will be the smaller of NumTitles and ten if NumTitles is greater than zero. The titles in the header are copied from Titles. When called from C or C++, the titles are assumed to be packed contiguously with eighty characters per title in the memory pointed to by Titles.

Use the IMAl functions to alter other parts of the header. Remember that you must call IMWrHdr to ensure that any changes from calls to IMCrHdr or IMAl functions are saved.


IMRtHdrFmt

Name

IMRtHdrFmt - Returns the format that the IM library has assumed for the header.

C Synopsis

void IMRtHdrFmt(int istream, int* p_ifmt);

Fortran Synopsis

subroutine irthhmt(istream, ifmt)
integer istream, ifmt

Description

The IM library currently supports the header formats described in the Image Header section. IMRtHdrFmt sets *p_ifmt (ifmt in Fortran) to zero (equivalent to the C/C++ macro, IW_PRIISM0_HEADER) if istream uses Priism's original format. IMRtHdrFmt sets *p_ifmt to one (equivalent to the C/C++ macro, IW_EM0_HEADER) if istream's header is in the EM format.


IMAlHdrFmt

Name

IMAlHdrFmt - Changes which header format to use.

C Synopsis

void IMAlHdrFmt(int istream, int ifmt);

Fortran Synopsis

subroutine ialhfmt(istream, ifmt)
integer istream, ifmt

Description

The IM library currently supports the header formats described in the Image Header section. IMAlHdrFmt changes the format used for istream to be ifmt which should be zero (equivalent to the C/C++ macro, IW_PRIISM0_HEADER) for Priism's format or one (equivalent to the C/C++ macro, IW_EM0_HEADER) for the EM format. If ifmt is not zero or one, IMAlHdrFmt will not change the header.

For an image file, the change to the format will be committed when the header is written with IMWrHdr. Switching the header format from Priism's format to the EM format will force the number of wavelengths to be one (and lose any information about wavelength values) and may change the space group and z sampling information. Switching the header from the EM format to Priism's format will lose the RMS value.


IMRtExHdrFmt

Name

IMRtExHdrFmt - Returns how to interpret the extended header.

C Synopsis

void IMRtExHdrFmt(int istream, int* p_ifmt);

Fortran Synopsis

subroutine irtexhf(istream, ifmt)
integer istream

Description

Currently the extended header either contains symmetry information for crystallographic data or per-section information for optical or electron microscopy data. IMRtExHdrFmt is a convenience function for determining how the extended header should be interpreted. It will set *p_ifmt (ifmt in Fortran) to zero (equivalent to the C/C++ macro, IW_EXTHDR_PRIISM0) if the extended header should be interpreted as a fixed number of 32-bit integers and 32-bit floating-point values per section (as returned by IMRtExHdrSize) up to the size of the extended header (as returned by IMRtSpg). It will set *p_ifmt to one (equivalent to the C/C++ macro, IW_EXTHDR_CRYSTAL) if the extended header should be interpreted as crystallographic symmetry information. It will set *p_ifmt to negative one (equivalent to the C/C++ macro, IW_EXTHDR_UNKNOWN) if the extended header format is not recognized by the IM library. The return value of negative one and the IW_EXTHDR_UNKNOWN macro were added in the Priism 4.6.1 release.


IMTrExHdr2

Name

IMTrExHdr2 - Transfer the extended header from one stream to another.

C Synopsis

int IMTrExHdr2(int OutStream, int InStream, int ZSec1, int ZSec2, int ZInc,
int WaveTable[IW_MAX_WAVE], int Time1, int Time2, int TimeInc)

Fortran Synopsis

integer function itrexhdr2(OutStream, InStream, ZSec1, ZSec2, ZInc, WaveTable, Time1, Time2, TimeInc)
integer OutStream,InStream,ZSec1,ZSec2,Zinc,WaveTable(5),Time1,Time2,Timeinc

Description

Transfer the extended header from InStream to OutStream.

ZSec1, ZSec2, and ZInc describe the Z range that should be transferred. In most cases, (ZSec2-ZSec1)/ZInc should be equal to the Z dimension of OutStream.

The wave table describes which wavelengths should transferred. For example, if WaveTable[0]=0 and WaveTable[1]=1, then wavelength number zero should not be transferred, whereas wavelength one should be.

The time range Time1, Time2, TimeInc behaves the same was the Z range, described above.


IMFixExHdr

Name

IMFixExHdr - Fix extended header values.

C Synopsis

void IMFixExHdr(int StreamNum, int ZStart, int ZEnd, int ZSkip, int isizeflag);

Fortran Synopsis

subroutine ifixexhdr( StreamNum, ZStart, ZEnd, ZSkip, isizeflag)
integer StreamNum, ZStart,ZEnd,ZSkip
logical isizeflag

Description

Used to fix the extended header information when selecting a subset of image sections. Used following IMTrHdr and with IMAlSiz. New extended header is made from data for sections ZStart to ZEnd, incrementing by ZSkip. if isizeflag is true, extended header will be resized, otherwise left at previous size. Do not set true if sections have already been written out.


IMFixExHdrZWT

Name

IMFixExHdrZWT - Fix extended header values.

C Synopsis

void IMFixExHdrZWT(int StreamNum, int ZStart, int ZEnd, int NumWaves, const int Waves[], int TStart, int TEnd, int TInc, int isizeflag);

Fortran Synopsis

subroutine ifixexhdr_zwt(StreamNum, ZStart, ZEnd, NumWaves, Waves, TStart, TEnd, TInc, isizeflag)
integer StreamNum,ZStart,Zend,NumWaves,Waves(5),TStart,TEnd,Tinc
logical isizeflag

Description

Similar to IMFixExHdr, but used when the subset is described using z,wave and time ranges, as opposed to just sections. The Z range is described with (ZStart, ZEnd). Wavelength range uses NumWaves to tell how many waves will be included and the array Waves, to tell which actual waves to include(0-4). Time range is described with (TStart, TEnd, TInc).


IMTrExHdr

Name

IMTrExHdr - Transfer the extended header corresponding to a single section from one stream to another.

C Synopsis

void IMTrExHdr(int StreamNum, int StreamNum2, int SectionNum, int SectionNum2);

Fortran Synopsis

subroutine itrexhdr(StreamNum, StreamNum2, SectionNum, SectionNum2)
integer StreamNum,StreamNum2,SectionNum,SectionNum2

Description

Transfer the extended header of StreamNum2, section number SectionNum2 to StreamNum, section number SectionNum.


Alter Image Information - "IMAl"

All of these calls modify information in the image file header. Keep in mind that none of this information is actually written to the file header until the call is made to IMWrHdr.

IMAlCel - Set the cell properties.
IMAlCon - Set the image conversion mode during read/write operations from image storage.
IMAlDat - Set various data values in the header.
IMAlDel - Set the (x,y,z) voxel size.
IMAlDis - Enable or disable image display.
IMAlExHdr - Change the extended header values of a particular section.
IMAlExHdrSize - Set the extended header size for a new stream.
IMAlExHdrValueZWT - Alter a value in the extended header.
IMAlExHdrZWT - Change all the extended header values for a particular Z,W,T section.
IMAlExt -Alter extra information stored in unused portions of file header (8 words max)
IMAlFmt - Change the formatting assumed for an image file.
IMAlLab - Change the image titles.
IMAlMap - Change the columns rows sections to xyz mapping
IMAlMode - Change the image data type.
IMAlOrig - Change the coordinate origin of the image.
IMAlPrt - Enable or disable printing to standard output ("stdout").
IMAlRes - Alter multi-resolution information
IMAlRMS - Alter the RMS deviation from the mean for the first wavelength
IMAlSam - Alter sampling size information
IMAlSiz - Change the image size and starting point.
IMAlSpg - Change the crystallography space group number.
IMAlSym - Change the symmetry information in the extended header.
IMAlTlt - Change the tilt angles.
IMAlTltRot - Rotate the existing tilt angles to change tilt
IMAlTSt -Change the time start field in the header of a data set
IMAlWav - Change the number of wavelengths in the stream and the wavelength.
IMAlWavMM - Change the min and max intensity for a particular wavelength number.
IMAlZWT - Change the number of Z sections, wavelengths, and time-points in the image.


IMAlCel

Name

IMAlCel - Set the cell properties.

C Synopsis

void IMAlCel(int StreamNum, const float CellProps[6]);

Fortran Synopsis

subroutine ialcel( StreamNum, CellProps)
integer StreamNum
real cellprops(6)

Description

Set the cell properties of StreamNum to the values contained in CellProps. The cell properties consist of 3 cell lengths (x,y,z) and 3 cell angles (alpha,beta,gamma), in sequence.


IMAlCon

Name

IMAlCon - Set the image conversion mode during read/write operations from image storage.

C Synopsis

void IMAlCon(int StreamNum, int ConversionFlag);

Fortran Synopsis

subroutine ialcon( StreamNum, ConversionFlag)
integer StreamNum
logical ConversionFlag

Description

By default, images that are read from image storage are converted to 4-byte floating-point data. Similarly, when images are written to image storage they are converted to the data type indicated by the image data type associated with the corresponding stream (see IMAlMode). The default is ConversionFlag=TRUE.

When ConversionFlag=FALSE, IM functions will not convert the image data type while reading or writing images. As a result, image data will be directly passed between memory and the storage device without conversion.


IMAlDat

Name

IMAlDat - Set various data values in the header.

C Synopsis

void IMAlDat(int StreamNum, int ImageType, int LensNum, int n1, int n2, float v1, float v2);

Fortran Synopsis

subroutine ialdat( StreamNum, ImageType, LensNum, n1, n2, v1, v2)
integer StreamNum,ImageType,LensNum,n1,n2
real v1,v2

Description

Alter Data type info

lens = lens choice
itype = 0 normal mono data
itype = 1 tilt set N1 = axis, v1=delang
itype = 2 stereo tilt set N1 = axis, v1=delang v2=stereo ang
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 = stereo ang
itype = 5 EM data, N1=objlens current (I*4)
itype = 6 time lapse data, N1= # sections/stack
    V1= time interval between stacks
itype = 7 multi-wavelength data
    N2= 0 all wave/focus, 1 for all focus/wave
itype = 8 time lapse, multi wave data, N1= # sections/stack
    N2= 0 all wave/focus, 1 for all focus/wave
    V1= time interval between stacks
NOTE: # wavelengths stored with wavelength data (ialwav)


IMAlDel

Name

IMAlDel - Set the (x,y,z) voxel size.

C Synopsis

void IMAlDel(int StreamNum, const float PixelSize[3]);

Fortran Synopsis

subroutine ialdel(StreamNum, PixelSize)
integer StreamNum
real PixelSize(3)

Description

Set the pixel size for StreamNum. The values in PixelSize are expected to be in microns for x, y, and z for optical data and angstroms for em data.


IMAlDis

Name

IMAlDis - Enable or disable image display.

C Synopsis

void IMAlDis(int Flag);

Fortran Synopsis

subroutine ialdis( Flag)
logical Flag

Description

By default, Flag=TRUE, which indicates that images will be displayed whenever they are written to a stream that points to a window. When Flag=FALSE, images will not be automatically displayed with each IMWr___ call.


IMAlExHdr

Name

IMAlExHdr - Change the extended header values of a particular section.

C Synopsis

void IMAlExHdr(int StreamNum, int SectionNum, const int *IntValues, const float *FloatValues);

Fortran Synopsis

subroutine ialexhdr( StreamNum, SectionNum, IntValues, FloatValues)
integer StreamNum,SectionNum,IntValues(nints)
real FloatValues(nreals)

Description

Change the extended header values of section SectionNum. IntValues and FloatValues are vectors containing as many values as expected for StreamNum's extended header. See IMRtExHdrSize to get the current the number of reals and ints or IMAlExHdrSize to set the number of elements.


IMAlExHdrSize

Name

IMAlExHdrSize - Set the extended header size for a new stream.

C Synopsis

void IMAlExHdrSize(int StreamNum, int NumIntegers, int NumFloats, int NumSections);

Fortran Synopsis

subroutine ialexhdr_size(StreamNum, NumIntegers, NumFloats, NumSections)
integer StreamNum,NumIntegers,NumFloats,NumSections

Description

Set the number of integers (NumIntegers), floating-point values (NumFloats), and sections (NumSections) in the extended header. Use this function only when creating a new image stream and before writing any image data. Because image data are stored after the extended header, it is important to reserve space for the extended header.


IMAlExHdrValueZWT

Name

IMAlExHdrValueZWT - Alter a value in the extended header.

C Synopsis

int IMAlExHdrValueZWT(int StreamNum, int ZSecNum, int WaveNum, int TimeNum, int Field, double Value)

Fortran Synopsis

ialexhdrvaluezwt( StreamNum, ZSecNum, WaveNum, TimeNum, Field, Value)
integer StreamNum,ZSecNum,WaveNum,TimeNum,Field
double Value

Description

For a table of what fields are available, see IMRtExHdrValueZWT.

Return Values

IMRtExHdrValueZWT returns TRUE when it is unable to alter the requested field. For example, if *Field=STAGE_X_COORD and the extended header type=API_EXT_HEADER_TYPE1 (see IMRtExHdrType). The function will also return TRUE if ZSecNum, WaveNum, or TimeNum are inappropriate for StreamNum. Also, if the extended header size is zero IMRtExHdrValueZWT will return TRUE. Otherwise the function returns FALSE.


IMAlExHdrZWT

Name

IMAlExHdrZWT - Change all the extended header values for a particular Z,W,T section.

C Synopsis

void IMAlExHdrZWT(int StreamNum, int ZSecNum, int WaveNum, int TimeNum, const int *IntValues, const float *FloatValues);

Fortran Synopsis

subroutine ialexhdr_zwt( StreamNum, ZSecNum, WaveNum, TimeNum, IntValues, FloatValues)
integer StreamNum,ZSecNum,WaveNum,TimeNum,IntValues(nint)
real FloatValues(nreals)

Description

Change the extended header values for the section corresponding to z section=ZSecNum, wavelength number=WaveNum, and time-point number=TimeNum. See IMAlExHdr for a description of IntValues and FloatValues.

A more convenient method of changing extended header values is to use IMAlExHdrValueZWT.


IMAlExt

Name

IMAlExt -Alters extra information stored in unused portions of file header.

C Synopsis

int IMAlExt(int istream, const void *extra, int istart, int nextra)

Fortran Synopsis

subroutine ialext(istream, extra, istart, nextra)
integer istream,istart,nextra
char extra(nextra * 4)

Description

Priism's format for the header has 26 bytes that are not used. They are, indexed from one, bytes 99 and 100 and bytes 105 through 128. The EM format for the header has 64 unused bytes: bytes 97 through 100, 105 through 128, 137 through 160, and 173 through 184. IMAlExt can modify those parts of the header (and the intervening parts that are in use). extra holds the data to be transfered to the header. IMAlExt will affect nextra 4 byte chunks in the header starting with the chunk at istart where a value of one for istart is bytes 97 through 100 in the header. istart must be between one and 22, inclusive. nextra must be between zero and 22, inclusive. Values outside of those ranges will cause IMAlExt to do nothing.


IMAlFmt

Name

IMAlFmt - Change the formatting assumed for an image file.

C Synopsis

IMAlFmt(int StreamNum, int Format);

Fortran Synopsis

subroutine ialfmt( StreamNum, Format)
integer StreamNum,Format

Description

Two different formats for image data files are supported: one in which multi-byte quantities are written in big-endian format and one in which they are written in litte-endian format. Both formats use IEEE floating point representation. By default, the library automatically detects the format of the file when reading it and will apply any necessary byte swapping. When writing files, the default is to always write them in the big-endian format. If you wish to override these defaults, use IMAlFmt (or ialfmt in FORTRAN) to alter how subsequent reads and writes will be performed. Setting Format to a non-zero value will force the file to be interpreted in the little-endian format; setting it to zero forces the use of the big-endian format.

Prior to the June 1999 release of Priism, the two formats supported were a big-endian one which used the IEEE representation for floating-point values and a little-endian one which used a VAX representation for floating-point values. Library support for the VAX format was dropped in the June 1999 release and replaced with the little-endian format with IEEE floating-point values.


IMAlLab

Name

IMAlLab - Change the image titles.

C Synopsis

void IMAlLab(int StreamNum, const char *Titles, int NumTitles);

Fortran Synopsis

subroutine iallab( StreamNum, Titles,NumTitles)
integer StreamNum,NumTitles
char Titles(80,NumTitles)

Description

Change the image Titles. NumTitles determines how many titles will be changed. Titles contains at least NumTitles title strings, each of which must contain exactly 80 characters.


IMAlMap

Name

IMAlMap- Change the columns rows sections to xyz mapping

C Synopsis

void IMAlMap(int StreamNum, const int map[3]);

Fortran Synopsis

subroutine ialmap(StreamNum, map)
integer StreamNum,map(3)

Description

Pixel spacing for x y and z is determined by the unit cell size / sampling size for each direction. By altering the mapping, were saying that for example, the x direction is now what used to be z (or sections) so that the pixel spacing for the z direction is now unit cell size of oldx / sampling size of oldx, yet we are retaining the original values for the x y and z unit cell and sampling.


IMAlMode

Name

IMAlMode - Change the image data type.

C Synopsis

void IMAlMode(int StreamNum, int PixelType);

Fortran Synopsis

subroutine ialmod(StreamNum, PixelType)
integer StreamNum,PixelType

Description

Change the image data type to PixelType. Refer to the table of data types for the valid values of PixelType. Note that the actual image data is not changed by using this function! Only the PixelType variable in the header is changed. The most appropriate time to use this function is when a new image stream is being created and before image data has been written to storage.


IMAlOrig

Name

IMAlOrig - Change the coordinate origin of the image.

C Synopsis

void IMAlOrig(int StreamNum, float x0, float y0, float z0);

Fortran Synopsis

subroutine ialorg( StreamNum, x0, y0, z0);
integer StreamNum
real x0,y0,z0

Description

Set the coordinate origin of StreamNum to be x0, y0, and z0. Coordinates are expected in microns for optical data and angstroms for em data.


IMAlPrt

Name

IMAlPrt - Enable or disable printing to standard output ("stdout").

C Synopsis

void IMAlPrt(int Flag);

Fortran Synopsis

subroutine ialprt( Flag)
logical Flag

Description

Certain IM functions will print information to stdout if Format=TRUE, which is the default. To disable printing, set flag=FALSE.


IMAlRes

Name

IMAlRes - Alter multi-resolution information

C Synopsis

void IMAlRes(int istream, int mres, int mzfact);

Fortran Synopsis

subroutine ialres(istream, mres, mzfact)
integer istream,mres,mzfact

Description

Updates the file header that the file referenced by istream has mres resolution levels where the reduction factor is 2 for the x and y axis and mzfact for the z axis. If the stream points to a scratch image window, the library silently coerces the number of resolutions to be one.


IMAlRMS

Name

IMAlRMS - Alters the root-mean-square deviation from the mean

C Synopsis

void IMAlRMS(int istream, float frms);

Fortran Synopsis

subroutine ialrms(istream, frms
integer istream
real frms

Description

If the header of the stream, istream, is stored in the EM format, sets the root-mean-square deviation from the mean in the header to be frms. If the header is stored in another format, does nothing.


IMAlSam

Name

IMAlSam - Alter sampling size information

C Synopsis

void IMAlSam(int istream, const int mxyz[3]);

Fortran Synopsis

subroutine ialsam( istream, mxyz)
integer istream, mxyz(3)

Description

Updates the file header referenced by istream with how many divisions there are in a unit cell for the x, y, and z directions. The number of divisions in x is read from the first element of mxyz, the number of divisions in y is read from the second element of mxyz, and the number of divisions in z is read from the third element mxyz.

Because the EM header format uses the number of divisions in z to store the number of slices per volume when the data is a volume stack (indicated by a space group number of 401), take care when modifying the sampling intervals with IMAlSam.


IMAlSiz

Name

IMAlSiz - Change the image size and starting point.

C Synopsis

void IMAlSiz(int StreamNum, const int ixyz[3], const int nxyzst[3]);

Fortran Synopsis

subroutine ialsiz( StreamNum, ixyz, nxyzst )
integer StreamNum,ixyz(3),nxyzst(3)

Description

Change the number of columns, rows, and sections (ixyz) in the image.

In most cases, this function is used when configuring new streams. That is, before image data has been written to StreamNum. If image data already exists in StreamNum, then it probably doesn't make sense to the change the ixyz.

nxyzst sets the starting column, row, and section number for the image file. This is useful when you are selecting a subregion of a data set and want to retain the relative position in data space.


IMAlSpg

Name

IMAlSpg - Change the crystallography space group number.

C Synopsis

void IMAlSpg(int StreamNum, int nspg, int mbsym);

Fortran Synopsis

subroutine ialspg( StreamNum, nspg, mbsym)
integer StreamNum,nspg,mbsym

Description

Change the space group number with nspg and number of bytes in the extended header with mbsym. It is advisable to allocate space in units of 1024 bytes.

If the stream uses the EM header format, take care when setting the space group number since the EM header format uses that value to indicate the structure of the data: a value of zero for images or image stack, a value of one for volumes, and a value of 401 for a volume stack. If the stream uses Priism's header format, the space group should be zero unless the extended header will be used to store the crystallography symmetry information. When processing an existing data set to generate a new one, copying the space group number from the input to the output is usually best. Exceptions to that would involve the EM header format and processing that converts slices to a volume or vice versa.


IMAlSym

Name

IMAlSym - Change the symmetry information in the extended header.

C Synopsis

void IMAlSym(int StreamNum, int mbsym, const void *jbsym);

Fortran Synopsis

subroutine ialsym( StreamNum, mbsym, jbsym)
integer StreamNum,mbsym
char jbsym(mbsym)

Description

Change the symmetry information of StreamNum. mbsym is the number of bytes of information to change and jbsym is a character string containing symmetry (extended header)information.


IMAlTlt

Name

IMAlTlt - Change the tilt angles.

C Synopsis

void IMAlTlt(int StreamNum, const float vals[3]);

Fortran Synopsis

subroutine ialtlt( StreamNum, vals)
integer StreamNum
real vals(3)

Description

Tilt angles may be stored in the header for recording when an image is rotated. By convention, vals contains rotation angles about the X, Y, and Z axes.


IMAlTltRot

Name

IMAlTltRot - Change the tilt angles by rotating the existing tilt angles by the new rotation angles.

C Synopsis

void IMAlTltRot(int StreamNum, const float vals[3]);

Fortran Synopsis

subroutine ialtlt_rot( StreamNum, vals)
integer StreamNum
real vals(3)

Description

The existing tilt angles are modified by the new xyz tilt angles (vals). (premultiply)


IMAlTSt

Name

IMAlTSt-Change the time start field in the header of a data set

C Synopsis

void IMAlTSt(int StreamNum, int itst);

Fortran Synopsis

subroutine ialtst(StreamNum, itst)
integer StreamNum,itst

Description

Alters the starting time to be itst in file StreamNum,


IMAlWav

Name

IMAlWav - Change the number of wavelengths in the stream and the wavelength.

C Synopsis

void IMAlWav(int StreamNum, int NumWaves, const float *Wavelength);

Fortran Synopsis

subroutine ialwav(StreamNum, NumWaves, Wavelength)
integer StreamNum,NumWaves
real Wavelengths(5)

Description

Change the number of wavelengths (NumWaves), up to a maximum of 5. Wavelength contains the wavelengths in nm.

If the stream uses the EM header format, setting the number of wavelengths to be greater than one will cause the IM library to switch the header to Priism's format.


IMAlWavMM

Name

IMAlWavMM - Change the minimum and maximum intensity for a particular wavelength number.

C Synopsis

void IMAlWavMM(int StreamNum, int WaveNum, float MinInten, float MaxInten);

Fortran Synopsis

subroutine ialwav_mm(StreamNum, WaveNum, MinInten, MaxInten)
integer StreamNum,WaveNum
real MinInten, MaxInten

Description

Update the minimum (MinInten) and maximum (MaxInten) intensities for a particular wavelength (WaveNum). Wavelength numbers range from 0 to 4.


IMAlZWT

Name

IMAlZWT - Change the number of Z sections, wavelengths, and time-points in the image.

C Synopsis

void IMAlZWT(int StreamNum, int NumZSec, int NumWaves, int NumTimes, int ImgSequence);

Fortran Synopsis

subroutine ialzwt( StreamNum, NumZSec, NumWaves, NumTimes, ImgSequence)
integer StreamNum, NumZSec,NumWaves,NumTimes,ImgSequence

Description

Use IMAlZWT to change the number of Z sections (NumZSec), wavelengths (NumWaves), and time-points (NumTimes). For new images, set these values to the expected numbers. Before closing the file, double-check the image size and change the values again.

There are three possible image sequences for Imsubs images. See Image Sequence Values.

Similar to other IMAl functions, IMAlZWT does not actually change the number or arrangement of sections in a stored image. Use IMAlZWT to make the header consistent with the stored image.

IMAlZWT has the side effect of changing the position of the pointer to be at the same z and time section indices but to use the last wavelength.

If the stream points to a scratch image window, the library silently coerces the number of time points to be one.

If the stream uses the EM header format, setting the number of wavelengths to be greater than one will cause the IM library to switch the header format to Priism's header format. If the stream uses the EM header format, the number of wavelengths is set to one, and the number of times points is set to be greater than one, Priism will set the space group to 401 (to signal that the data is a "volume stack") and set the z sampling interval equal to the number of z points.


Return Image Information - "IMRt"

The IMRt functions return information about the image. To obtain valid information, the IMRdHdr function must be used before calling IMRt functions.

IMRtCel - Return cell information: size and axis separation angles.
IMRtDat - Return various information about the image, such as the image type and lens ID
IMRtDel - Return the pixel size, in microns (or Angstroms)
IMRtExHdr - Return extended header values for a particular section.
IMRtExHdrSize - Return the number of exhdr values stored for each section of the image.
IMRtExHdrType - Return the extended header type.
IMRtExHdrValueZWT - Return a value from the extended header.
IMRtExHdrZWT - Return extended header values for a particular Z-W-T section
IMRtExt - Return extra information stored in header
IMRtFmt - Return the formatting assumed for a file
IMRtLab - Return the title strings and number of active titles.
IMRtMap - Return the column, row, section mapping info.
IMRtMode - Return the image data type.
IMRtMst - Return the starting coordinates of the image array.
IMRtOrig - Return the coordinate origin, in microns.
IMRtRes - Return multi-resolution information for a file or window
IMRtResInfo - Return absolute information about the current resolution setting.
IMRtRMS - Return the RMS deviation from the mean for the first wavelength
IMRtSam - Return the sampling size
IMRtSiz - Return size information about the image stream.
IMRtSecNum - Return the section number for a given Z, W, and T position.
IMRtSpg - Return the crystallography space group information.
IMRtSym - Return the symmetry information.
IMRtTlt - Return the tilt angles.
IMRtTSt -Return the time start field from the header of a data set
IMRtWav - Return information about the image stream's wavelengths.
IMRtWavMM - Return the minimum and maximum intensity of a particular wavelength.
IMRtZWT - Return the number of Z sections, wavelengths, and time-points.
IMRtZWTNum - Return the ZWT positions given the section number.


IMRtCel

Name

IMRtCel - Return cell information: size and axis separation angles.

C Synopsis

void IMRtCel(int StreamNum, float CellProps[6]);

Fortran Synopsis

subroutine irtcel( StreamNum, CellProps)
integer StreamNum
real cellprops(6)

Description

Cell information is rarely used. In most situations, however, it is important that CellProps[3], CellProps[4], and CellProps[5] should equal 90 degrees.


IMRtDat

Name

IMRtDat - Return various information about the image, such as the image type and lens ID number.

C Synopsis

void IMRtDat(int StreamNum, int *ImageType, int *LensNum, int *n1, int *n2, float *v1, float *v2);

Fortran Synopsis

subroutine irtdat( StreamNum, ImageType, LensNum, n1, n2, v1, v2)
integer StreamNum,ImageType,LensNum,n1,n2
real v1,v2

Description

return data type info
lens = lens choice
itype = 0 normal mono data N1=intensity,v1=time
itype = 1 tilt set N1 = axis, v1=delang
itype = 2 stereo tilt set N1 = axis, v1=delang v2=stereo ang
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 = stereo ang
itype = 5 EM data, N1=objlens current (I*4)
itype = 6 time lapse data, N1= # sections/stack
V1= time interval between stacks
itype = 7 multi-wavelength data
N2= 0 all wave/focus, 1 for all focus/wave
itype = 8 time lapse, multi wave data, N1= # sections/stack
N2= 0 all wave/focus, 1 for all focus/wave
V1= time interval between stacks
NOTE: # wavelengths stored with wavelength data (ialwav)


IMRtDel

Name

IMRtDel - Return the pixel size, in microns.

C Synopsis

void IMRtDel(int StreamNum, float PixelSize[3]);

Fortran Synopsis

subroutine irtdel(StreamNum, PixelSize)
integer StreamNum
real PixelSize(3)

Description

PixelSize is given in microns for the X, Y, and Z. The X,Y values are not necessarily equal, and the Z value often represents optical section spacing.


IMRtExHdr

Name

IMRtExHdr - Return extended header values for a particular section.

C Synopsis

void IMRtExHdr(int StreamNum, int SectionNum, int *IntValues, float *FloatValues);

Fortran Synopsis

subroutine irtexhdr( StreamNum, SectionNum, IntValues, FloatValues)
integer StreamNum,SectionNum, IntValues(nints)
real FloatValues(nreals)

Description

The integer and floating-point values for section number SectionNum are returned in IntValues and FloatValues, respectively. Use IMRtExHdrSize to determine the size requirements for IntValues and FloatValues.

In most cases, IMRtExHdrZWT is a convenient alternative to IMRtExHdr.


IMRtExHdrSize

Name

IMRtExHdrSize - Return the number of integer and floating-point values stored for each section of the image.

C Synopsis

void IMRtExHdrSize(int StreamNum, int *NumInts, int *NumFloats);

Fortran Synopsis

subroutine irtexhdr_size(StreamNum, NumInts, NumFloats)
integer StreamNum,NumIntegers,NumFloats

Description

NumInts and NumFloats describe the structure of the extended header. Use this function before attempting to access extended header information with functions such IMRtExHdr.


IMRtExHdrType

Name

IMRtExHdrType - Return the extended type.

C Synopsis

int IMRtExHdrType(int StreamNum, int *ExtHeaderType, int *NumInts, int *NumFloats)

Fortran Synopsis

subroutine irtexthdrtype(StreamNum, ExtHeaderType, NumInts, NumFloats)
integer StreamNum,ExtHeaderType,NumInts,NumFloats

Description

There are five possible values of *iExtHeaderType. The types are defined in IWApiConstants.h.

UNKNOWN_EXT_HEADER_TYPE
The number of integer and floating-point values per section does not match a known format for the extended header.
UCSF_EXT_HEADER_TYPE1
Has one integer and one floating-point value per section. The integer value is the photosensor measurement and the floating-point value is the time elapsed, in seconds, since the start of the experiment.
API_EXT_HEADER_TYPE1
From DeltaVision 1.20, has two floating-point values per section. The first is the photosensor measurement, and the second is the time elapsed, in seconds, since the start of the experiment.
API_EXT_HEADER_TYPE2
From DeltaVision 2.00 and later, has 8 integer values and 32 floating-point values per section. Some of these are reserved for future use; the ones currently used are:
1st floating-point value
photosensor measurement
2nd floating-point value
time elapsed, in seconds, since start of experiment
3rd floating-point value
stage's x coordinate
4th floating-point value
stage's y coordinate
5th floating-point value
stage's z coordinate
6th floating-point value
minimum intensity in image
7th floating-point value
maximum intensity in image
8th floating-point value
mean image intensity
9th floating-point value
exposure time in seconds
10th floating-point value
neutral density value
11th floating-point value
excitation filter wavelength
12th floating-point value
emission filter wavelength
13th floating-point value
intensity scaling factor
14th floating-point value
energy conversion factor
UCSF_EXT_HEADER_TYPE2
Has three integer values and one floating-point value per section. The first two integer values are the low and high components, respectively, of a 64-bit measurement of the photosensor. The third integer values is the number of conversions that the photosensor performed to obtain the measurement. The floating-point value is the time elapsed, in seconds, since the start of the experiment.

The function also returns the number of integer (*NumInts) and floating point (*NumFloats) values stored for each section of the image.

Return Values

IMRtExHdrType returns TRUE when an error has occurred. For example, when there is no extended header. Otherwise the function returns FALSE.


IMRtExHdrValueZWT

Name

IMRtExHdrValueZWT - Return a value from the extended header.

C Synopsis

int IMRtExHdrValueZWT(int StreamNum, int ZSecNum, int WaveNum, int TimeNum, int Field, double *Value)

Fortran Synopsis

irtexhdrvaluezwt(StreamNum, ZSecNum, WaveNum, TimeNum, Field, Value)
integer StreamNum,ZSecNum,WaveNum,TimeNum, Field
double Value

Description

Return a Field from the extended header for a given Z section number (ZSecNum), wavelength number (WaveNum), and time point number (TimeNum). The fields are defined in IWApiConstants.h and are shown below for the different extended header types currently defined.

API and UCSF Style 1
PHOTOSENSOR_READING
photosensor reading in arbitrary units
TIME_STAMP_SECS
time stamp in seconds since the experiment began
UCSF Style 2
PHOTOSENSOR_READING
photosensor reading in arbitrary units
TIME_STAMP_SECS
time stamp in seconds since the experiment began
PHOTOSENSOR_NCONV
number of conversions performed for photosensor measurement
API Style 2
PHOTOSENSOR_READING
photosensor reading, typically in mV
TIME_STAMP_SECS
time stamp in seconds since the experiment began
STAGE_X_COORD
stage's x coordinate
STAGE_Y_COORD
stage's y coordinate
STAGE_Z_COORD
stage's z coordinate
MIN_INTEN
minimum intensity
MAX_INTEN
maximum intensity
MEAN_INTEN
mean intensity
EXP_TIME
exposure time in seconds
ND_FILTER
neutral density value
EX_WAVELEN
excitation filter wavelength
EM_WAVELEN
emission filter wavelength
INTEN_SCALING
intensity scaling factor, usually 1
ENERGY_CONV_FACTOR
energy conversion factor, usually 1

Return Values

IMRtExHdrValueZWT returns TRUE when it is unable to return the requested field. For example, if *Field=STAGE_X_COORD and the extended header type=API_EXT_HEADER_TYPE1 (see IMRtExHdrType). The function will also return TRUE if ZSecNum, WaveNum, or TimeNum are inappropriate for StreamNum. Also, if the extended header size is zero IMRtExHdrValueZWT will return TRUE. Otherwise the function returns FALSE.


IMRtExHdrZWT

Name

IMRtExHdrZWT - Return extended header values for a particular Z section, wavelength, and time-point.

C Synopsis

void IMRtExHdrZWT(int StreamNum, int ZSecNum, int WaveNum, int TimeNum, int *IntValues, float *FloatValues);

Fortran Synopsis

subroutine irtexhdr_zwt( StreamNum, ZSecNum, WaveNum, TimeNum, IntValues, FloatValues)
integer StreamNum,ZSecNum,WaveNum,TimeNum,IntValues(nint)
real FloatValues(nreals)

Description

The integer and floating-point values for the requested Z section (ZSecNum), wavelength (WaveNum), and time-point (TimeNum) are returned in IntValues and FloatValues, respectively.

Use IMRtExHdrSize to determine the size requirements for IntValues and FloatValues.


IMRtExt

Name

IMRtExt - Returns extra information stored in header.

C Synopsis

void IMRtExt(int istream, void *extra, int istart, int nextra);

Fortran Synopsis

irtext(istream, extra, istart, nextra)
integer istream,istart,nextra
char extra(nextra * 4)

Description

There are unused parts of the header; the description for IMAlExt specifies where they are. IMRtExt can return what is in those portions (and the intervening segments that are in use). IMRtExt will copy nextra chunks of four bytes starting at istart and store them in extra. A value of one for istart corresponds to the four byte chunk at bytes 97 through 100 in the header. istart must be between one and 22, inclusive. nextra must be between zero and 22, inclusive. If either is outside of those ranges, IMRtExt does nothing.


IMRtFmt

Name

IMRtFmt - Return the formatting assumed for an image file.

C Synopsis

void IMRtFmt(int StreamNum, int *iformat);

Fortran Synopsis

subroutine irtfmt(StreamNum, iformat)
integer StreamNum, iformat

Description

Sets iformat to zero if the file is assumed to be in big-endian byte order or one if the file is assumed to be in little-endian byte order. See the description of IMAlFmt for more information about byte ordering.


IMRtLab

Name

IMRtLab - Return the title strings and number of active titles.

C Synopsis

void IMRtLab(int StreamNum, char Titles[10][80], int *NumTitles);

Fortran Synopsis

subroutine irtlab( StreamNum, Titles, NumTitles)
integer StreamNum,NumTitles
char Titles(80,NumTitles)

Description

Return the title strings in a two dimensional character array (Titles). Space for as many as 10 titles, each of which is exactly 80 characters long, should be provided. Title strings are not necessarily null terminated.

The actual number of titles contained within the header is given by NumTitles.

NumTitles is between 0 and 10. Future versions of the library, however, may limit the number of titles to 4 or 5.


IMRtMap

Name

IMRtMap - Return the column, row, section mapping info.

C Synopsis

void IMRtMap(int StreamNum, int map[3]);

Fortran Synopsis

subroutine irtmap(StreamNum, map)
integer StreamNum,map(3)

Description

Pixel spacing for x y and z is determined by the unit cell size / sampling size for each direction. This call returns for x y and z which dimension will be assigned to columns, which to row and which to sections when reporting the pixel spacing for the different dimensions of the image data.


IMRtMode

Name

IMRtMode - Return the image data type.

C Synopsis

void IMRtMode(int StreamNum, int *PixelType);

Fortran Synopsis

subroutine irtmod(StreamNum, PixelType)
integer StreamNum, PixelType

Description

Sets PixelType to indicate how the pixel values are stored for the given stream. Possible values for PixelType are shown in pixel data types table.


IMRtMst

Name

IMRtMst - Return the starting coordinates of the image array.

C Synopsis

void IMRtMst(int StreamNum, int StartCoordinates[3]);

Fortran Synopsis

subroutine irtmst( StreamNum, StartCoordinates)
integer StreamNum, StartCoordinates

Description

Returns the xyz data coordinates of the starting position of the image file into StartCoordinates .


IMRtOrig

Name

IMRtOrig - Return the coordinate origin, in microns.

C Synopsis

void IMRtOrig(int StreamNum, float *x0, float *y0, float *z0);

Fortran Synopsis

subroutine irtorg( StreamNum, x0, y0, z0);
integer StreamNum
real x0,y0,z0

Description

The coordinate origin, usually in microns, of the image stream is returned into (x0, y0, z0).


IMRtRes

Name

IMRtRes - Return multi-resolution information

C Synopsis

void IMRtRes(int istream, int *mres, int *mzfact);

Fortran Synopsis

subroutine irtres(istream, mres, mzfact)
integer istream,mres,mzfact

Description

Returns info that the file referenced by istream has mres resolution levels where the reduction factor is 2 for the x and y axis and mzfact for the z axis.


IMRtResInfo

Name

IMRtResInfo - Return absolute information about the current resolution setting.

C Synopsis

void IMRtResInfo(int istream, int *nx, int *ny, int *nz, int *mxyfact, int *mzfact);

Fortran Synopsis

subroutine irtres_info( istream, nx, ny, nz, mxyfact, mzfact)
integer istream,nx,ny,nz, mxyfact, mzfact

Description

Given the istream of a multi-resolution image file, returns
nx, ny, nz: absolute image size at current resolution
mxyfact: current total reduction factor in X.Y
mzfact: current total reduction factor in Z
The current resolution setting is set using the call IMPosnRes.


IMRtRMS

Name

IMRtRMS - Returns the root-mean-square deviation from the mean.

C Synopsis

void IMRtRMS(int StreamNum, float* p_rms);

Fortran Synopsis

subroutine irtrms(StreamNum, rms)
integer StreamNum
real rms

Description

If the header of the stream, StreamNum, is stored in the EM format, sets *p_rms (rms in Fortran) to root-mean-squared deviation from the mean stored in the header. Otherwise, sets *p_rms to negative one.


IMRtSam

Name

IMRtSam - Return the sampling size.

C Synopsis

void IMRtSam(int StreamNum, int mxyz[3]);

Fortran Synopsis

subroutine irtsam(StreamNum, mxyz )
integer StreamNum, mxyz(3)

Description

Sets the first element of mxyz equal to the number of divisions of the unit cell in the x direction. Sets the second element of mxyz equal to the number of divisions of the unit cell in the y direction. Sets the third element of mxyz equal to the number of divisions of the unit cell in the z direction.


IMRtSiz

Name

IMRtSiz - Return size information about the image stream.

C Synopsis

void IMRtSiz(int StreamNum, int nxyz[3], int mxyz[3], int StartCoordinates[3]);

Fortran Synopsis

subroutine irtsiz( StreamNum, nxyz, mxyz, StartCoordinates)
integer StreamNum,nxyz(3),mxyz(3),StartCoordinates(3)

Description

Returns three size related arrays. nxyz holds the dimensions for the images: the first component is the number of elements in x, the second is the number of elements in y, and the third is the number of images. mxyz holds the number of divisions in x, y, and z per unit cell. The values in mxyz usually follow one of the following conventions:

StartCoordinates contains the starting coordinates of the file.


IMRtSecNum

Name

IMRtSecNum - Return the section number for a given the Z, W, and T position.

C Synopsis

int IMRtSecNum(int StreamNum,int ZSecNum, int WaveNum, int TimeNum, int *SecNum)

Fortran Synopsis

irtsecnum(StreamNum, ZSecNum, WaveNum, TimeNum,SecNum)
integer StreamNum, ZSecNum,WaveNum,TimeNum,SecNum

Description

Calculate the section number *SecNum (between 0 and the total number of sections) for the given ZSecNum, WaveNum, TimeNum. The result depends on the image sequence: WZT, ZTW, or ZWT.

Return Values

The function returns TRUE if ZSecNum, WaveNum, or TimeNum are inappropriate for StreamNum. Otherwise the function returns FALSE.


IMRtSpg

Name

IMRtSpg - Return the crystallography space group information.

C Synopsis

void IMRtSpg(int StreamNum, int *nspg, int *mbsym);

Fortran Synopsis

subroutine irtspg( StreamNum, nspg, mbsym)
integer StreamNum,nspg,mbsym

Description

Returns the space group number into nspg (set to 0 for image data), and number of bytes in the extended header (symmetry info for crystallography data) to mbsym.


IMRtSym

Name

IMRtSym - Return the symmetry information.

C Synopsis

void IMRtSym(int StreamNum, int *NumSymBytes, void *SymmetryInfo);

Fortran Synopsis

subroutine irtsym(StreamNum, NumSymBytes, SymmetryInfo)
integer StreamNum,NumSymBytes
char SymmetryInfo(numSymBytes)

Description

Returns symmetry information (or extended header info) into SymmetryInfo. The size of SymmetryInfo should be determined in advance by calling IMRtSpg. NumSymBytes equals the size, in bytes of the SymmetryInfo string. SymmetryInfo may not be null terminated.


IMRtTlt

Name

Return the tilt angles.

C Synopsis

void IMRtTlt(int StreamNum, float TiltAngles[3]);

Fortran Synopsis

subroutine irttlt( StreamNum, TiltAngles)
integer StreamNum
real TiltAngles(3)

Description

Return the tilt angles about xyz into TiltAngles.


IMRtTSt

Name

IMAlTSt-Return the time start field from the header of a data set

C Synopsis

void IMRtTSt(int StreamNum, int *itst);

Fortran Synopsis

subroutine irttst(StreamNum, itst)
integer StreamNum,itst

Description

The starting time value for the image stream is returned in itst .


IMRtWav

Name

Return information about the image stream's wavelengths.

C Synopsis

void IMRtWav(int StreamNum, int *NumWaves, float Wavelengths[IW_MAX_WAVE]);

Fortran Synopsis

subroutine irtwav(StreamNum, NumWaves, Wavelengths)
integer StreamNum,NumWaves
real Wavelengths(5)

Description

The number of wavelengths within the image stream is returned in NumWaves. The maximum number of wavelengths is 5 (IW_MAX_WAVE). NumWave should be at least 1.

The wavelengths, usually in nanometers, are returned in Wavelengths, which should be of size IW_MAX_WAVE.


IMRtWavMM

Name

IMRtWavMM - Return the minimum and maximum intensity of a particular wavelength.

C Synopsis

void IMRtWavMM(int StreamNum, int WaveNum, float *MinIntensity, float *MaxIntensity);

Fortran Synopsis

subroutine irtwav_mm(StreamNum, WaveNum, MinIntensity, MaxIntensity)
integer StreamNum,WaveNum
real MinInten, MaxInten

Description

The desired wavelength is specified with WaveNum, which can range from 0 to (IW_MAX_WAVE-1). If the image has only 3 wavelengths, however, the valid range for WaveNum is 0 - 2.


IMRtZWT

Name

IMRtZWT - Return the number of Z sections, wavelengths, and time-points.

C Synopsis

void IMRtZWT(int StreamNum, int *NumZSec, int *NumWaves, int *NumTimes, int *ImgSequence);

Fortran Synopsis

subroutine irtzwt( StreamNum, NumZSec, NumWaves, NumTimes, ImgSequence)
integer StreamNum, NumZSec,NumWaves,NumTimes,ImgSequence

Description

The number of Z sections, wavelengths, and time-points are given by NumZSec, NumWavelengths, and NumTimePoints, respectively.

There are three possible image sequences for Imsubs images. See Image Sequence Values.


IMRtZWTNum

Name

IMRtZWTNum - Return the ZWT positions given the section number.

C Synopsis

int IMRtZWTNum(int iStream,int *iz, int *iw, int *it, int iSecNum)

Fortran Synopsis

irtzwtnum( iStream,iz, iw, it, iSecNum)
integer iStream,iz,iw,it,iSecNum

Description

Given the section number iSecNum, and based on the image sequence of the data file referenced by iStream, the current iz, iw, and it for the section is returned.


Read Image Information - "Rd"

Read image content from the storage device.

IMRdLin - Read the next line in the image stream.
IMRdPal - Read part of the next line.
IMRdPas - Read part of the next section.
IMRdSec - Read the next section.
IMRdSecl - Read a number of lines from the next section.


IMRdLin

Name

IMRdLin - Read the next line in the image stream.

C Synopsis

void IMRdLin(int StreamNum, void *ImgBuffer);

Fortran Synopsis

subroutine irdlin(StreamNum, ImgBuffer, *line)
integer StreamNum
real ImgBuffer(size to read in)
line: branch to Fortran line # on error

Description

Reads the next line of the image stream into ImgBuffer and advances the file pointer by one line. If ires is the current resolution (0 is the highest), then the results of the read are undefined if ImgBuffer has less than (number of columns in image) / 2^ires elements.

In most cases, ImgBuffer will contain floating-point data. When image conversion is off, however, the data type of ImgBuffer should correspond to whatever data type is actually stored. For example, if the image data are stored as 16-bit integers, then ImgBuffer should point to a 16-bit buffer. See IMAlCon.


IMRdPal

Name

IMRdPal - Read part of the next line.

C Synopsis

void IMRdPal(int StreamNum, void *ImgBuffer, int *Column1, int *Column2);

Fortran Synopsis

subroutine irdpal( StreamNum, ImgBuffer, Column1, Column2, *line)
integer StreamNum,Column1,Column2
real ImgBuffer(size to read in)
line: branch to Fortran line # on error

Description

Reads part of the next line into ImgBuffer and advances the file pointer by one full line. If the resolution index is ires (0 is the highest resolution), then the read starts at Column1 / 2^ires and (Column2 - Column1 + 1) / 2^ires values are read.

In most cases, ImgBuffer will contain floating-point data. When image conversion is off, however, the data type of ImgBuffer should correspond to whatever data type is actually stored. For example, if the image data are stored as 16-bit integers, then ImgBuffer should point to a 16-bit buffer. See IMAlCon.


IMRdPas

Name

IMRdPas - Read part of the next section.

C Synopsis

void IMRdPas(int StreamNum, void *ImgBuffer, int mx, int my, int Column1, int Column2, int Row1, int Row2);

Fortran Synopsis

subroutine irdpas(StreamNum, ImgBuffer, mx, my, Column1, Column2, Row1, Row2, *line)
integer StreamNum,mx,my,Column1,Column2,Row1,Row2
real ImgBuffer(size to read in)
line: branch to Fortran line # on error

Description

Reads part of the next section into ImgBuffer and advances the file pointer to the start of the section after that. The result is undefined if the file pointer is not at the beginning of a section. If the resolution index is ires (0 is the highest resolution), then the zero-based positions, (i, j), read from the section are those for which:

    Column1 / 2^ires <= i < Column1 / 2^ires + (Column2 - Column1 + 1) / 2^ires
and
    Row1 / 2^ires <= j < Row1 / 2^ires + (Row2 - Row1 + 1) / 2^ires

The value read from (i, j) is stored at (i - Column1 / 2^ires, j - Column2 / 2^ires) in ImgBuffer. If mx is less than (Column2 - Column1 + 1) / 2^ires or ImgBuffer has less than mx * (Row2 - Row1 + 1) / 2^ires elements, the result is undefined. When mx or my is larger than the dimensions of the partial section read, the additional elements in ImgBuffer are not modified.

In most cases, ImgBuffer will contain floating-point data. When image conversion is off, however, the data type of ImgBuffer should correspond to whatever data type is actually stored. For example, if the image data are stored as 16-bit integers, then ImgBuffer should point to a 16-bit buffer. See IMAlCon.


IMRdSec

Name

IMRdSec - Read the next section.

C Synopsis

void IMRdSec(int StreamNum, void *ImgBuffer);

Fortran Synopsis

subroutine irdsec(StreamNum, ImgBuffer, *line)
integer StreamNum
real ImgBuffer(size to read in)
line: branch to Fortran line # on error

Description

Reads the next section into ImgBuffer and advances the file pointer to the section after that. The results are undefined if ImgBuffer does not have at least nx * ny elements or the file pointer does not point to the beginning of a section.

In most cases, ImgBuffer will contain floating-point data. When image conversion is off, however, the data type of ImgBuffer should correspond to whatever data type is actually stored. For example, if the image data are stored as 16-bit integers, then ImgBuffer should point to a 16-bit buffer. See IMAlCon.


IMRdSecl

Name

IMRdSecl - Read a number of lines from the next section.

C Synopsis

void IMRdSecl(int StreamNum, void *ImgBuffer, int *NumLines);

Fortran Synopsis

subroutine irdsecl(StreamNum, ImgBuffer, NumLines, *line)
integer StreamNum, NumLines
real ImgBuffer(size to read in)
line: branch to Fortran line # on error

Description

If the current resolution index is ires (0 is the highest resolution, reads the next NumLines / 2^ires lines into ImgBuffer and advances the pointer by that many lines. The results are undefined if ImgBuffer has less than nx * NumLines / 2^ires elements or the read would span more than one section.

In most cases, ImgBuffer will contain floating-point data. When image conversion is off, however, the data type of ImgBuffer should correspond to whatever data type is actually stored. For example, if the image data are stored as 16-bit integers, then ImgBuffer should point to a 16-bit buffer. See IMAlCon.


Write Image Information - "Wr"

Write image data to the storage device.

IMWrLin - Write a line of image data.
IMWrPal - Write part of an image line to the storage device.
IMWrPas - Write part of the next section to the storage device.
IMWrSec - Write the next section to the storage device.
IMWrSecl - Write a number of lines to the next section.


IMWrLin

Name

IMWrLin - Write a line of image data.

C Synopsis

void IMWrLin(int StreamNum, const void *ImgBuffer);

Fortran Synopsis

subroutine iwrlin( StreamNum, ImgBuffer)
integer StreamNum
real ImgBuffer(size of data to write)

Description

Writes a line of data from ImgBuffer to the storage device and advances the file pointer by one line. The values written are drawn sequentially from the start of ImgBuffer. If ires is the current resolution (0 is the highest), then the results of the write are undefined if ImgBuffer has less than (number of columns in image) / 2^ires elements.

In most cases, ImgBuffer will contain floating-point data. When image conversion is off, however, the data type of ImgBuffer should be whatever data type is actually stored. For example, if PixelType indicates that the image data should be stored as 16-bit integers, then ImgBuffer should also contain 16-bit integer data. See IMAlCon.


IMWrPal

Name

IMWrPal - Write part of an image line to the storage device.

C Synopsis

void IMWrPal(int StreamNum, const void *ImgBuffer, int Column1, int Column2);

Fortran Synopsis

subroutine iwrpal( StreamNum, ImgBuffer, Column1, Column2)
integer StreamNum,Column1,Column2
real ImgBuffer(size of data to write)

Description

Writes part of the next line and advances the file pointer by one full line. If the resolution index is ires (0 is the highest resolution), then the write starts at Column1 / 2^ires and (Column2 - Column1 + 1) / 2^ires values are written. The values are drawn sequentially from the start of ImgBuffer

In most cases, ImgBuffer will contain floating-point data. When image conversion is off, however, the data type of ImgBuffer should be whatever data type is actually stored. For example, if PixelType indicates that the image data should be stored as 16-bit integers, then ImgBuffer should also contain 16-bit integer data. See IMAlCon.


IMWrPas

Name

IMWrPas - Write part of the next section to the storage device.

C Synopsis

void IMWrPas(int StreamNum, const void *ImgBuffer, int mx, int my, int Column1, int Column2, int Row1, int Row2);

Fortran Synopsis

subroutine iwrpas( StreamNum, ImgBuffer, mx, my, Column1, Column2, Row1, Row2)
integer StreamNum,mx,my,Column1,Column2,Row1,Row2
real ImgBuffer(size of data to write)

Description

Writes part of the next section using data from ImgBuffer and advances the file pointer to the start of the section after that. The result is undefined if the file pointer is not at the beginning of a section. If the resolution index is ires (0 is the highest resolution), then the zero-based positions, (i, j), whose values are changed are those for which:

    Column1 / 2^ires <= i < Column1 / 2^ires + (Column2 - Column1 + 1) / 2^ires
and
    Row1 / 2^ires <= j < Row1 / 2^ires + (Row2 - Row1 + 1) / 2^ires

The value written to (i, j) is drawn from (i - Column1 / 2^ires, j - Column2 / 2^ires) in ImgBuffer. If mx is less than (Column2 - Column1 + 1) / 2^ires or ImgBuffer has less than mx * (Row2 - Row1 + 1) / 2^ires elements, the result is undefined.

In most cases, ImgBuffer will contain floating-point data. When image conversion is off, however, the data type of ImgBuffer should be whatever data type is actually stored. For example, if PixelType indicates that the image data should be stored as 16-bit integers, then ImgBuffer should also contain 16-bit integer data. See IMAlCon.


IMWrSec

Name

IMWrSec - Write the next section to the storage device.

C Synopsis

void IMWrSec(int StreamNum, const void *ImgBuffer);

Fortran Synopsis

subroutine iwrsec(StreamNum, ImgBuffer)
integer StreamNum
real ImgBuffer(size of data to write)

Description

Writes the next section using data from ImgBuffer and advances the file pointer to the section after that. The results are undefined if ImgBuffer does not have at least nx * ny elements or the file pointer does not point to the beginning of a section.

In most cases, ImgBuffer will contain floating-point data. When image conversion is off, however, the data type of ImgBuffer should be whatever data type is actually stored. For example, if PixelType indicates that the image data should be stored as 16-bit integers, then ImgBuffer should also contain 16-bit integer data. See IMAlCon.


IMWrSecl

Name

IMWrSecl - Write a number of lines to the next section.

C Synopsis

void IMWrSecl(int StreamNum, const void *ImgBuffer, int NumLines);

Fortran Synopsis

subroutine iwrsecl(StreamNum, ImgBuffer, NumLines)
integer StreamNum, NumLines
real ImgBuffer(size of data to write)

Description

If the current resolution index is ires (0 is the highest resolution, writes NumLines / 2^ires lines starting from the current pointer position and advances the pointer by that many lines. The size of ImgBuffer should be nx*NumLines elements.

In most cases, ImgBuffer will contain floating-point data. When image conversion is off, however, the data type of ImgBuffer should be whatever data type is actually stored. For example, if PixelType indicates that the image data should be stored as 16-bit integers, then ImgBuffer should also contain 16-bit integer data. See IMAlCon.


Stream Pointer Functions

When reading and writing to and from streams, the underlying stream pointer is automatically repositioned either to the next section, or the next line of the same section, depending on the call used. For more random access to the image data, it is necessary to reposition the pointer using one of these calls.

IMPosn - Position the read/write pointer of a stream to a particular section and row number.
IMPosnRes - Position the read/write pointer at the start of a particular resolution data set.
IMPosnZWT - Position the read/write point at a particular Z, W, T section.


IMPosn

Name

IMPosn - Position the read/write pointer of a stream to a particular section and row number.

C Synopsis

int IMPosn(int StreamNum, int SecNum, int Row);

Fortran Synopsis

integer function imposn( StreamNum, SecNum, Row)
integer StreamNum,SecNum,Row

Description

Position the read/write pointer of StreamNum to section number SecNum, row number Row. As usual, row numbers start at 0. In most cases Row=0. If the stream points to a scratch window, IMPosn can only change the destination wavelength.

Return Values

IMPosn returns 0 if successful and 1 if not.


IMPosnRes

Name

IMPosnRes - Position the read/write pointer at the start of a particular resolution data set.

C Synopsis

int IMPosnRes(int StreamNum, int ResolutionNum);

Fortran Synopsis

subroutine imposn_res( StreamNum, ResolutionNum)
integer StreamNum, ResolutionNum

Description

Some images contain sub-resolution images. To position the read/write pointer at the beginning of a particular resolution, use this function with the appropriate value of ResolutionNum.


IMPosnZWT

Name

IMPosnZWT - Position the read/write point at a particular Z, W, T section.

C Synopsis

int IMPosnZWT(int StreamNum, int ZSecNum, int WaveNum, int TimeNum);

Fortran Synopsis

integer function imposn_zwt( StreamNum, ZSecNum, WaveNum, TimeNum)
integer StreamNum,ZSecNum,WaveNum,TimeNum

Description

Position the read/write pointer of StreamNum to Z section number ZSecNum, wavelength number WaveNum, and time-point number TimeNum. If the stream points to a scratch window, IMPosnZWT can only change the destination wavelength.

Return Values

IMPosnZWT returns 0 if successful and 1 if not.


Stream Identification

In some instances, it is useful to determine if a stream is attached to a file or a window or which stream corresponds to a given window number. These functions assist with those tasks.

IMUnit - Returns the Unix file descriptor for a stream.
IMRtWID - Returns the window number for a stream.
IMRtStream - Returns the stream number attached to a window.


IMUnit

Name

IMUnit - Returns the Unix file descriptor for a stream.

C Synopsis

int IMUnit(int StreamNum);

Fortran Synopsis

integer function imunit(StreamNum)
integer StreamNum

Description

Returns -1 if the given stream is not open or is not attached to a file; otherwise the Unix file descriptor value is returned (this is the number used with the Unix system calls open, close, read, write, lseek, ...).


IMRtWID

IMRtWID - Returns the window number for a stream.

C Synopsis

int IMRtWID(int StreamNum);

Fortran Synopsis

integer function irtwid(StreamNum)
integer StreamNum

Description

Returns 0 if the stream is not open or is not attached to a window; otherwise, returns the number of the window to which the stream is attached.


IMRtStream

IMRtStream - Returns the stream number attached to a window.

C Synopsis

int IMRtWID(int WindowNumber);

Fortran Synopsis

integer function irtstream(WindowNumber)
integer WindowNumber

Description

Returns 0 if the given window number is not attached to any stream that the application currently has open; otherwise, the smallest stream number which is attached to the given window is returned.