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:
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 consist of a header, extended header, and image data. Each part is detailed below.
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. The column, row, and section are equivalent to the x, y, and z axes.
|
Byte Numbers |
Variable Type |
Variable Name |
Contents |
| 1 - 4 |
i |
NumCol |
Number of columns. Typically, NumCol represents the number of image elements along the X axis. |
| 5 - 8 |
i |
NumRow |
Number of rows. Typically, NumRow represents the number of image elements along the Y axis. |
| 9 - 12 |
i |
NumSections |
Total number of sections. (NumZSec*NumWave*NumTimes) |
| 13 - 16 |
i |
PixelType |
The format of each pixel value. See the Pixel Data Types table below. |
| 17 - 20 |
i |
mxst |
Starting point along the X axis of sub-image (pixel number). Default is 0. |
| 21 - 24 |
i |
myst |
Starting point along the Y axis of sub-image (pixel number). Default is 0. |
| 25 - 28 |
i |
mzst |
Starting point along the Z axis of sub-image (pixel number). Default is 0. |
| 29 - 32 |
i |
mx |
Sampling frequency in x; commonly set equal to one or the number of columns. |
| 33 - 36 |
i |
my |
Sampling frequency in y; commonly set equal to one or the number of rows. |
| 37 - 40 |
i |
mz |
Sampling frequency in z; commonly set equal to one or the number of z sections. |
| 41 - 44 |
f |
dx |
Cell dimension in x; for non-crystallographic data, set to the x sampling frequency times the x pixel spacing. |
| 45 - 48 |
f |
dy |
Cell dimension in y; for non-crystallographic data, set to the y sampling frequency times the y pixel spacing. |
| 49 - 52 |
f |
dz |
Cell dimension in z; for non-crystallographic data, set to the z sampling frequency times the z pixel spacing. |
| 53 - 56 |
f |
alpha |
Cell angle (alpha) in degrees. Default is 90. |
| 57 - 60 |
f |
beta |
Cell angle (beta) in degrees. Default is 90. |
| 61 - 64 |
f |
gamma |
Cell angle (gamma) in degrees. Default is 90. |
| 65 - 68 |
i |
- |
Column axis. Valid values are 1,2, or 3. Default is 1. |
| 69 - 72 |
i |
- |
Row axis. Valid values are 1,2, or 3. Default is 2. |
| 73 - 76 |
i |
- |
Section axis. Valid values are 1,2, or 3. Default is 3. |
| 77 - 80 |
f |
min |
Minimum intensity of the 1st wavelength image. |
| 81 - 84 |
f |
max |
Maximum intensity of the 1st wavelength image. |
| 85 - 88 |
f |
mean |
Mean intensity of the first wavelength image. |
| 89 - 92 |
i |
nspg |
Space group number. Applies to crystallography data. |
| 93 - 96 |
i |
next |
Extended header size, in bytes. |
| 97 - 98 |
n |
dvid |
ID value. (-16224) |
| 99 - 100 |
n |
nblank |
Unused. |
| 101 - 104 |
i |
ntst |
Starting time index. |
| 105 - 128 |
c24 |
blank |
Blank section. 24 bytes. |
| 129 - 130 |
n |
NumIntegers |
Number of 4 byte integers stored in the extended header per section. |
| 131 - 132 |
n |
NumFloats |
Number of 4 byte floating-point numbers stored in the extended header per section. |
| 133 - 134 |
n |
sub |
Number of sub-resolution data sets stored within the image. Typically, this equals 1. |
| 135 - 136 |
n |
zfac |
Reduction quotient for the z axis of the sub-resolution images. |
| 137 - 140 |
f |
min2 |
Minimum intensity of the 2nd wavelength image. |
| 141 - 144 |
f |
max2 |
Maximum intensity of the 2nd wavelength image. |
| 145 - 148 |
f |
min3 |
Minimum intensity of the 3rd wavelength image. |
| 149 - 152 |
f |
max3 |
Maximum intensity of the 3rd wavelength image. |
| 153 - 156 |
f |
min4 |
Minimum intensity of the 4th wavelength image. |
| 157 - 160 |
f |
max4 |
Maximum intensity of the 4th wavelength image. |
| 161 - 162 |
n |
type |
Image type. See the Image Type table below. |
| 163 - 164 |
n |
LensNum |
Lens identification number. |
| 165 - 166 |
n |
n1 |
Depends on the image type. |
| 167 - 168 |
n |
n2 |
Depends on the image type. |
| 169 - 170 |
n |
v1 |
Depends on the image type. |
| 171 - 172 |
n |
v2 |
Depends on the image type. |
| 173 - 176 |
f |
min5 |
Minimum intensity of the 5th wavelength image. |
| 177 - 180 |
f |
max5 |
Maximum intensity of the 5th wavelength image. |
| 181 - 182 |
n |
NumTimes |
Number of time points. |
| 183 - 184 |
n |
ImgSequence |
Image sequence. 0=ZTW, 1=WZT, 2=ZWT. |
| 185 - 188 |
f |
- |
X axis tilt angle (degrees). |
| 189 - 192 |
f |
- |
Y axis tilt angle (degrees). |
| 193 - 196 |
f |
- |
Z axis tilt angle (degrees). |
| 197 - 198 |
n |
NumWaves |
Number of wavelengths. |
| 199 - 200 |
n |
wave1 |
Wavelength 1, in nm. |
| 201 - 202 |
n |
wave2 |
Wavelength 2, in nm. |
| 203 - 204 |
n |
wave3 |
Wavelength 3, in nm. |
| 205 - 206 |
n |
wave4 |
Wavelength 4, in nm. |
| 207 - 28 |
n |
wave5 |
Wavelength 5, in nm. |
| 209 - 212 |
f |
z0 |
Z origin, in um. |
| 213 - 216 |
f |
x0 |
X origin, in um. |
| 217 - 220 |
f |
y0 |
Y origin, in um. |
| 221 - 224 |
i |
NumTitles |
Number of titles. Valid numbers are between 0 and 10. |
| 225 - 304 |
c80 |
- |
Title 1. 80 characters long. |
| 305 - 384 |
c80 |
- |
Title 2. 80 characters long. |
| 385 - 464 |
c80 |
- |
Title 3. 80 characters long. |
| 465 - 544 |
c80 |
- |
Title 4. 80 characters long. |
| 545 -624 |
c80 |
- |
Title 5. 80 characters long. |
| 625-704 |
c80 |
- |
Title 6. 80 characters long. |
| 705-784 |
c80 |
- |
Title 7. 80 characters long. |
| 785-864 |
c80 |
- |
Title 8. 80 characters long. |
| 865-944 |
c80 |
- |
Title 9. 80 characters long. |
| 945-1024 |
c80 |
- |
Title 10. 80 characters long. |
| Code | Variable Type |
| n | 2-byte, signed integer |
| i | 4-byte, signed integer |
| f | 4-byte, floating-point |
| cn | n-byte, character string |
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 four byte integer in header bytes 93-96. Bytes 89 - 92 (nspg) indicate how the extended header should be interpreted. Nonzero values of nspg are used for crystallographic data. Priism data files have nspg set to zero.
For Priism data files, the extended header contains NumInts 4-byte integers (see bytes 129-130) and NumFloats 4-byte floating-point values (see bytes 131-132) per section so the size of the extended header should be at least
(NumInts + NumFloats) * NumSections * 4
where NumSections is the value 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. For more details about the extended header for image data, see IMRtExHdrType and IMRtExHdrValueZWT.
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.
Immediately following the extended header are the image data.
The type of a Priism image is given by the two byte integer in
header bytes 161-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.
The data type of an image, stored in header bytes 13-16, is designated
by one of the code numbers in the following table.
| Code | C/C++ Macro | Description |
| 0 | IW_BYTE | 1-byte unsigned integer |
| 1 | IW_SHORT | 2-byte signed integer |
| 2 | IW_FLOAT | 4-byte floating-point (IEEE) |
| 3 | IW_COMPLEX_SHORT | 4-byte complex value as 2 2-byte signed integers |
| 4 | IW_COMPLEX | 8-byte complex value as 2 4-byte floating-point values |
| 5 | IW_EMTOM | 2-byte signed integer |
| 6 | IW_USHORT | 2-byte unsigned integer |
| 7 | IW_LONG | 4-byte signed integer |
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 (header bytes 13-16). If necessary, use the IWAlCon function to prevent conversion to and from floating-point data.
Type codes 5, 6, and 7 are not standard MRC types and are not likely to be correctly interpreted by other software that uses MRC files.
| Code | C/C++ Macro | Comments |
| 0 | ZTW_SEQUENCE | This is the normal arrangement for processed images. Sometimes referred to as "non-interleaved". |
| 1 | WZT_SEQUENCE | This is the typical arrangement for images acquired from a microscope. Sometimes referred to as "interleaved". |
| 2 | ZWT_SEQUENCE | Although not widely used, ZWT will find uses with certain processing algorithms. |
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 (starting with the March 2000 release of IVE 3.3, if the application only uses IM functions (no IWL calls), then you can include IMInclude.h rather than IWInclude.h). Programs written in Fortran which use IMRtExHdrType or IMRtExHdrValueZWT should include exhdr.inc to define constants for the different extended header types and values.
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). 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.
In IVE versions since 3.3, the IM libraries are in the n32 object format. Therefore, you will need to compile and link your application so that it is in the n32 format as well. Supplying the -n32 option to the compiler and linker is one way to do this; see the pe_environ (5) man page for others.
The headers are located in the IRIX/INCLUDE directory and the libraries in the IRIX/LIB directory of the Priism distribution. If you use the archive versions of the libraries (libimlib.a or libIWL.a), you should link with the MIPS Pro C++ compiler (the libraries contain C++ code and linking with the C++ compiler ensures that the C++ libraries are included are properly initialized).
When linking against libimlib.a you will also need to link against the math library:
-lm
When linking against libIWL.a, you will also need to link against libive which is available in shared or archive versions in the same directory as libIWL.a. The other library options you may need to specify are:
-lX11 -lm -lpthread
For Fortran programs, the name mangling of the libraries is compatible with the default name mangling done by the MIPS Pro Fortran compiler. The library also includes alternate entry points which are compatible with the default name mangling done by g77. The libimcompat.a that is provided uses the name mangling of the MIPS Pro Fortran compiler. If you use libimcompat.a to parse the command-line, your main program will have to be in Fortran and it must be compiled with the MIPS Pro Fortran compiler. When using something other than the MIPS Pro Fortran compiler to perform the link against libimcompat.a, the other library options necessary may be specified as
-lftn -lm
To use the x86 Linux libraries, you will need an x86 Linux system that supports compiling ELF executables and has glibc2.1. To use the IW library and headers, the X libraries and headers must be installed. To use the archive libraries you will also need access to a C++ compiler compatible with the egcs-2.91 g++ compiler and a C++ library compatible with libstdc++ 6.1-1.
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.
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
-lstdc++ -lm -lc
(the egcs-2.91 g++ compiler and version 6.1-1 of libstdc++ were used when building the archive libraries). For libIWL.a, the additional libraries can be specified on the command line as
-lX11 -lstdc++ -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 Portland Group Fortran compiler. 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 the Portland Group's Fortran compiler (version 3.2-3 was used to generate the library) and the one in install_dir/Linux/x86/LIB/g77 is for GNU's g77 (egcs-2.91.66 was used to generate the library).
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. To use the archive libraries you will also need access to a C++ compiler compatible with the gcc 3.3.5's g++ and C++ library compatible with libstdc++.so.6.
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.
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
-lstdc++ -lm -lc
(the gcc 3.3.5 g++ compiler and the archive library equivalent of libstdc++.so.6 were used when building the archive libraries). For libIWL.a, the additional libraries can be specified on the command line as
-lX11 -lstdc++ -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 (name are converted to lower case and a single underscore is 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 the Intel compiler (version 9 was used to generate the library; when linking against the library also link against Intel's libifport, i.e. add -lifport to the link options) and the one in install_dir/Linux/x86_64/LIB/g77 is for GNU's g77 (the version in gcc 3.3.5 was used to generate the library).
To use the IW library on Mac OS X, it is necessary to have the X libraries and include files installed.
The headers are located in the Darwin/INCLUDE directory of the Priism distribution. 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 libraries are located in the Darwin/LIB directory of the Priism distribution. If you link against libIWL.dylib, it is necessary to link against libive which is in the same directory as libIWL.dylib, i.e. add
-live
to the link options. If you use libimlib.a on a PowerPC system, it is necessary to link against the gcc 3.1 version of the C++ libraries. One way to pull those libraries in is to add
/usr/lib/gcc/darwin/3.1/libstdc++.a /usr/lib/gcc/darwin/3.1/libgcc.a
to the link options. If you use libIWL.a, it is also necessary to link against libive and the X library, libX11, i.e. add
-live /usr/lib/gcc/darwin/3.1/libstdc++.a /usr/lib/gcc/darwin/3.1/libgcc.a -lX11
to the link options. With XFree86 or Apple's X11, the X library is in /usr/X11R6/lib. If you use libimlib.a on an Intel system, it is necessary to link against the gcc 4.0 version of the C++ libraries. One way to pull those libraries in is to add
-lstdc++.6 -lgcc_s
to the link options. If you use libIWL.a, it is also necessary to link against libive and the X library, libX11, i.e. add
-live -lstdc++.6 -lgcc_s -lX11
to the link options.
For Fortran programs, the name mangling of the libraries is compatible with typical Unix behavior (names converted to all lowercase with an underscore appended). When using the Absoft Fortran compiler, the options
-N15 -f
are necessary to force that style of name mangling. With the IBM XL Fortran compiler, use the option
-qextname
to enforce that style of name mangling. The library includes alternate
entry points which are compatible with the default name mangling done by g77.
Three versions of libimcompat.a are included. The one in
install_dir/Darwin/LIB is for Absoft's Fortran compiler (version 8.0
was used to generate the library) on PowerPC systems and for version 9.1 of
Intel's Fortran compiler on Intel systems. When linking with that version of
libimcompat on PowerPC systems, you will need Absoft's U77 library which, if
you are linking with the Absoft compiler, can be linked in by including
-lU77 in the linker options after the reference to libimcompat.a.
When linking with that version of libimcompat on Intel systems, you will need
to link in the Intel Fortran support library, libifport, and its dependencies.
When you use the Intel Fortran compiler, those additional libraries can be
linked in by including -lifport -lifcore -limf -lirc in the
linker options after the reference to libimcompat.a. The version of
libimcompat.a in install_dir/Darwin/LIB/g77 is for GNU's g77 on
Power PC systems(version 2.95.2 was used to generate the library). The
version of libimcompat.a in install_dir/Darwin/LIB/xlf is for the
IBM XL Fortran compiler on PowerPC systems (version 8.1 was used to generate
the library).
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 functions have been added in IVE 4:
Other changes made between IVE 4 and IVE 3.3 are:
Changed made in IVE 3.3:
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:
Alter Image Information - "IMAl"
Return Image Information - "IMRt"
Read Image Information - "IMRd"
Write Image Information - "IMWr"
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.
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 - Open an image file and attach it to a stream.
int IMOpen(int StreamNum, const char *Name, const char *Attributes);
Fortran Synopsis
integer function imopen(streamnum,name,attributes)
integer istream
character name*(*)
character attributes*(*)
Open an image file named Name and attach it to stream number StreamNum. 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:
IMOpen returns TRUE when an error has occurred, and otherwise returns FALSE. See also IMClose.
IMClose - Close the stream and associated image file.
void IMClose(int StreamNum);
Fortran Synopsis
subroutine imclose(streamnum)
integer streamnum
To ensure that all buffers are emptied, use IMClose when finished with StreamNum. See also IMOpen.
IMRdHdr - Read the header from the stored image.
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
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 - Write the image header to the storage device.
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
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 - Get the entire header in a single block of memory.
void IMGetHdr(int StreamNum, void *Header);
Fortran Synopsis
subroutine igethdr(istream, header)
integer istream
character header*1024
Get the header of StreamNum and put it into Header. Header should point to a memory location with 1024 bytes allocated.
IMPutHdr - Put an entire header into a stream.
void IMPutHdr(int StreamNum, const void *Header);
Fortran Synopsis
subroutine iputhdr(istream, header)
integer istream
char header*1024
Header should point to a memory location that contains a complete image header.
IMGetExHdr - Retrieves the entire extended header into a single block of memory.
void IMGetExHdr(int StreamNum, void *Extended);
Fortran Synopsis
subroutine igetexhdr(istream, extended)
integer istream
real extended(*)
The complete contents of the extended header are copied to Extended.
IMTrHdr - Transfer a header from one stream to another.
void IMTrHdr(int StreamNum, int StreamNum2);
Fortran Synopsis
subroutine itrhdr(istream, istream2)
integer istream,istream2
Transfer the header (including the extended header, if any) associated with StreamNum2 to the header associated with StreamNum.
IMTrLab - Transfer image titles from one stream to another.
void IMTrLab(int StreamNum, int StreamNum2);
Fortran Synopsis
subroutine itrlab(istream,istream2)
integer istream,istream2
Transfer the image titles associated with StreamNum2 to those associated with StreamNum.
IMTrCel - Transfer the cell properties from one stream to another.
void IMTrCel(int StreamNum, int StreamNum2);
subroutine itrcel(istream,istream2)
integer istream,istream2
Transfer the cell properties associated with StreamNum2 to those associated with StreamNum.
IMCrHdr - Create a new header with certain user defined properties. The remaining properties are determined by default.
void IMCrHdr(int StreamNum, const int ixyz[3],
const int mxyz[3], int PixelType, const char *Titles,
int NumTitles);
subroutine icrhdr(istream, ixyz, mxyz, iPixelType, Titles,
NumTitles)
integer istream,ixyz(3),mxyz(3),iPixelType,NumTitles
character Titles(80,NumTitles)
Creates a new header for StreamNum. 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.
IMTrExHdr2 - Transfer the extended header from one stream to another.
int IMTrExHdr2(int OutStream, int InStream, int ZSec1,
int ZSec2, int ZInc,
int WaveTable[IW_MAX_WAVE], int Time1, int Time2,
int TimeInc)
integer function itrexhdr2(OutStream, InStream, ZSec1,
ZSec2, ZInc, WaveTable, Time1, Time2,
TimeInc)
integer OutStream,InStream,ZSec1,ZSec2,Zinc,WaveTable(5),Time1,Time2,Timeinc
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 - Fix extended header values.
void IMFixExHdr(int StreamNum, int ZStart, int ZEnd, int ZSkip, int isizeflag);
subroutine ifixexhdr( StreamNum, ZStart, ZEnd, ZSkip,
isizeflag)
integer StreamNum, ZStart,ZEnd,ZSkip
logical isizeflag
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 - Fix extended header values.
void IMFixExHdrZWT(int StreamNum, int ZStart, int ZEnd, int NumWaves, const int Waves[], int TStart, int TEnd, int TInc, int isizeflag);
subroutine ifixexhdr_zwt(StreamNum, ZStart, ZEnd, NumWaves,
Waves, TStart, TEnd, TInc, isizeflag)
integer StreamNum,ZStart,Zend,NumWaves,Waves(5),TStart,TEnd,Tinc
logical isizeflag
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 - Transfer the extended header corresponding to a single section from one stream to another.
void IMTrExHdr(int StreamNum, int StreamNum2, int SectionNum, int SectionNum2);
subroutine itrexhdr(StreamNum, StreamNum2, SectionNum, SectionNum2)
integer StreamNum,StreamNum2,SectionNum,SectionNum2
Transfer the extended header of StreamNum2, section number SectionNum2 to StreamNum, section number SectionNum.
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
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 - Set the cell properties.
void IMAlCel(int StreamNum, const float CellProps[6]);
subroutine ialcel( StreamNum, CellProps)
integer StreamNum
real cellprops(6)
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 - Set the image conversion mode during read/write operations from image storage.
void IMAlCon(int StreamNum, int ConversionFlag);
subroutine ialcon( StreamNum, ConversionFlag)
integer StreamNum
logical ConversionFlag
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 - Set various data values in the header.
void IMAlDat(int StreamNum, int ImageType, int LensNum, int n1, int n2, float v1, float v2);
subroutine ialdat( StreamNum, ImageType, LensNum, n1,
n2, v1, v2)
integer StreamNum,ImageType,LensNum,n1,n2
real v1,v2
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 - Set the (x,y,z) voxel size.
void IMAlDel(int StreamNum, const float PixelSize[3]);
subroutine ialdel(StreamNum, PixelSize)
integer StreamNum
real PixelSize(3)
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 - Enable or disable image display.
void IMAlDis(int Flag);
subroutine ialdis( Flag)
logical Flag
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 - Change the extended header values of a particular section.
void IMAlExHdr(int StreamNum, int SectionNum, const int *IntValues, const float *FloatValues);
subroutine ialexhdr( StreamNum, SectionNum, IntValues, FloatValues)
integer StreamNum,SectionNum,IntValues(nints)
real FloatValues(nreals)
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 - Set the extended header size for a new stream.
void IMAlExHdrSize(int StreamNum, int NumIntegers, int NumFloats, int NumSections);
subroutine ialexhdr_size(StreamNum, NumIntegers, NumFloats,
NumSections)
integer StreamNum,NumIntegers,NumFloats,NumSections
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 - Alter a value in the extended header.
int IMAlExHdrValueZWT(int StreamNum, int ZSecNum, int WaveNum, int TimeNum, int Field, double Value)
ialexhdrvaluezwt( StreamNum, ZSecNum, WaveNum,
TimeNum, Field, Value)
integer StreamNum,ZSecNum,WaveNum,TimeNum,Field
double Value
For a table of what fields are available, see IMRtExHdrValueZWT.
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 - Change all the extended header values for a particular Z,W,T section.
void IMAlExHdrZWT(int StreamNum, int ZSecNum, int WaveNum, int TimeNum, const int *IntValues, const float *FloatValues);
subroutine ialexhdr_zwt( StreamNum, ZSecNum, WaveNum, TimeNum,
IntValues, FloatValues)
integer StreamNum,ZSecNum,WaveNum,TimeNum,IntValues(nint)
real FloatValues(nreals)
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 -Alter extra information stored in unused portions of file header (8 words max)
int IMAlExt(int istream, const void *extra, int istart, int nextra)
subroutine ialext(istream, extra, istart, nextra)
integer istream,istart,nextra
char extra(nextra * 4)
char *extra: buffer containing data to be placed in extra slot
int istart:which extra element to start at (1-8); elements 1 and 2 overlap with other header entries so it is best to only use elements 3 and above
int nextra: number of 4 byte words to transfer
IMAlFmt - Change the formatting assumed for an image file.
IMAlFmt(int StreamNum, int Format);
subroutine ialfmt( StreamNum, Format)
integer StreamNum,Format
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 small-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 - Change the image titles.
void IMAlLab(int StreamNum, const char *Titles, int NumTitles);
subroutine iallab( StreamNum, Titles,NumTitles)
integer StreamNum,NumTitles
char Titles(80,NumTitles)
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- Change the columns rows sections to xyz mapping
void IMAlMap(int StreamNum, const int map[3]);
subroutine ialmap(StreamNum, map)
integer StreamNum,map(3)
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 - Change the image data type.
void IMAlMode(int StreamNum, int PixelType);
subroutine ialmod(StreamNum, PixelType)
integer StreamNum,PixelType
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 - Change the coordinate origin of the image.
void IMAlOrig(int StreamNum, float x0, float y0, float z0);
subroutine ialorg( StreamNum, x0, y0, z0);
integer StreamNum
real x0,y0,z0
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 - Enable or disable printing to standard output ("stdout").
void IMAlPrt(int Flag);
subroutine ialprt( Flag)
logical Flag
Certain IM functions will print information to stdout if Format=TRUE, which is the default. To disable printing, set flag=FALSE.
IMAlRes - Alter multi-resolution information
void IMAlRes(int istream, int mres, int mzfact);
subroutine ialres(istream, mres, mzfact)
integer istream,mres,mzfact
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.
IMAlSam - Alter sampling size information
void IMAlSam(int istream, const int mxyz[3]);
subroutine ialsam( istream, mxyz)
integer istream, mxyz(3)
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.
IMAlSiz - Change the image size and starting point.
void IMAlSiz(int StreamNum, const int ixyz[3], const int nxyzst[3]);
subroutine ialsiz( StreamNum, ixyz, nxyzst )
integer StreamNum,ixyz(3),nxyzst(3)
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 - Change the crystallography space group number.
void IMAlSpg(int StreamNum, int nspg, int mbsym);
subroutine ialspg( StreamNum, nspg, mbsym)
integer StreamNum,nspg,mbsym
Change the space group number with nspg (set to 0 for image data), and number of bytes in the extended header with mbsym. It is advisable to allocate space in units of 1024 bytes.
IMAlSym - Change the symmetry information in the extended header.
void IMAlSym(int StreamNum, int mbsym, const void *jbsym);
subroutine ialsym( StreamNum, mbsym, jbsym)
integer StreamNum,mbsym
char jbsym(mbsym)
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 - Change the tilt angles.
void IMAlTlt(int StreamNum, const float vals[3]);
subroutine ialtlt( StreamNum, vals)
integer StreamNum
real vals(3)
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 - Change the tilt angles by rotating the existing tilt angles by the new rotation angles.
void IMAlTltRot(int StreamNum, const float vals[3]);
subroutine ialtlt_rot( StreamNum, vals)
integer StreamNum
real vals(3)
The existing tilt angles are modified by the new xyz tilt angles (vals). (premultiply)
IMAlTSt-Change the time start field in the header of a data set
void IMAlTSt(int StreamNum, int itst);
subroutine ialtst(StreamNum, itst)
integer StreamNum,itst
Alters the starting time to be itst in file StreamNum,
IMAlWav - Change the number of wavelengths in the stream and the wavelength.
void IMAlWav(int StreamNum, int NumWaves, const float *Wavelength);
subroutine ialwav(StreamNum, NumWaves, Wavelength)
integer StreamNum,NumWaves
real Wavelengths(5)
Change the number of wavelengths (NumWaves), up to a maximum of 5. Wavelength contains the wavelengths in nm.
IMAlWavMM - Change the minimum and maximum intensity for a particular wavelength number.
void IMAlWavMM(int StreamNum, int WaveNum, float MinInten, float MaxInten);
subroutine ialwav_mm(StreamNum, WaveNum, MinInten, MaxInten)
integer StreamNum,WaveNum
real MinInten, MaxInten
Update the minimum (MinInten) and maximum (MaxInten) intensities for a particular wavelength (WaveNum). Wavelength numbers range from 0 to 4.
IMAlZWT - Change the number of Z sections, wavelengths, and time-points in the image.
void IMAlZWT(int StreamNum, int NumZSec, int NumWaves, int NumTimes, int ImgSequence);
subroutine ialzwt( StreamNum, NumZSec, NumWaves, NumTimes,
ImgSequence)
integer StreamNum, NumZSec,NumWaves,NumTimes,ImgSequence
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.
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.
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 - Return cell information: size and axis separation angles.
void IMRtCel(int StreamNum, float CellProps[6]);
subroutine irtcel( StreamNum, CellProps)
integer StreamNum
real cellprops(6)
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 - Return various information about the image, such as the image type and lens ID number.
void IMRtDat(int StreamNum, int *ImageType, int *LensNum, int *n1, int *n2, float *v1, float *v2);
subroutine irtdat( StreamNum, ImageType, LensNum, n1,
n2, v1, v2)
integer StreamNum,ImageType,LensNum,n1,n2
real v1,v2
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 - Return the pixel size, in microns.
void IMRtDel(int StreamNum, float PixelSize[3]);
subroutine irtdel(StreamNum, PixelSize)
integer StreamNum
real PixelSize(3)
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 - Return extended header values for a particular section.
void IMRtExHdr(int StreamNum, int SectionNum, int *IntValues, float *FloatValues);
subroutine irtexhdr( StreamNum, SectionNum, IntValues, FloatValues)
integer StreamNum,SectionNum, IntValues(nints)
real FloatValues(nreals)
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.
Name
IMRtExHdrSize - Return the number of integer and floating-point values stored for each section of the image.
void IMRtExHdrSize(int StreamNum, int *NumInts, int *NumFloats);
subroutine irtexhdr_size(StreamNum, NumInts, NumFloats)
integer StreamNum,NumIntegers,NumFloats
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 - Return the extended type.
int IMRtExHdrType(int StreamNum, int *ExtHeaderType, int *NumInts, int *NumFloats)
subroutine irtexthdrtype(StreamNum, ExtHeaderType, NumInts, NumFloats)
integer StreamNum,ExtHeaderType,NumInts,NumFloats
There are five possible values of *iExtHeaderType. The types are defined in IWApiConstants.h.
The function also returns the number of integer (*NumInts) and floating point (*NumFloats) values stored for each section of the image.
IMRtExHdrType returns TRUE when an error has occurred. For example, when there is no extended header. Otherwise the function returns FALSE.
IMRtExHdrValueZWT - Return a value from the extended header.
int IMRtExHdrValueZWT(int StreamNum, int ZSecNum, int WaveNum, int TimeNum, int Field, double *Value)
irtexhdrvaluezwt(StreamNum, ZSecNum, WaveNum, TimeNum,
Field, Value)
integer StreamNum,ZSecNum,WaveNum,TimeNum, Field
double Value
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.
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 - Return extended header values for a particular Z section, wavelength, and time-point.
void IMRtExHdrZWT(int StreamNum, int ZSecNum, int WaveNum, int TimeNum, int *IntValues, float *FloatValues);
subroutine irtexhdr_zwt( StreamNum, ZSecNum, WaveNum, TimeNum,
IntValues, FloatValues)
integer StreamNum,ZSecNum,WaveNum,TimeNum,IntValues(nint)
real FloatValues(nreals)
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 - Return extra information stored in header
void IMRtExt(int istream, void *extra, int istart, int nextra);
ialext(istream, extra, istart, nextra)
integer istream,istart,nextra
char extra(nextra * 4)
The image file header contains space for extra (unassigned)information. IMRtExt returns up to 8 extra 4 byte words from the header of the file referenced by istream, to the character array extra. istart tells which extra word to start with (1-8; words 1 and 2 are used for other purposes so it is best to only worry about the contents of words 3 and above), and nextra tells how many 4 byte words to get.
IMRtFmt - Return the formatting assumed for an image file.
void IMRtFmt(int StreamNum, int *iformat);
subroutine irtfmt(StreamNum, iformat)
integer StreamNum, iformat
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 - Return the title strings and number of active titles.
void IMRtLab(int StreamNum, char Titles[10][80], int *NumTitles);
subroutine irtlab( StreamNum, Titles, NumTitles)
integer StreamNum,NumTitles
char Titles(80,NumTitles)
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 - Return the column, row, section mapping info.
void IMRtMap(int StreamNum, int map[3]);
subroutine irtmap(StreamNum, map)
integer StreamNum,map(3)
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 - Return the image data type.
void IMRtMode(int StreamNum, int *PixelType);
subroutine irtmod(StreamNum, PixelType)
integer StreamNum, PixelType
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 - Return the starting coordinates of the image array.
void IMRtMst(int StreamNum, int StartCoordinates[3]);
subroutine irtmst( StreamNum, StartCoordinates)
integer StreamNum, StartCoordinates
Returns the xyz data coordinates of the starting position of the image file into StartCoordinates .
IMRtOrig - Return the coordinate origin, in microns.
void IMRtOrig(int StreamNum, float *x0, float *y0, float *z0);
subroutine irtorg( StreamNum, x0, y0, z0);
integer StreamNum
real x0,y0,z0
The coordinate origin, usually in microns, of the image stream is returned into (x0, y0, z0).
IMRtRes - Return multi-resolution information
void IMRtRes(int istream, int *mres, int *mzfact);
subroutine irtres(istream, mres, mzfact)
integer istream,mres,mzfact
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 - Return absolute information about the current resolution setting.
void IMRtResInfo(int istream, int *nx, int *ny, int *nz, int *mxyfact, int *mzfact);
subroutine irtres_info( istream, nx, ny, nz, mxyfact,
mzfact)
integer istream,nx,ny,nz, mxyfact, mzfact
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.
IMRtSam - Return the sampling size.
void IMRtSam(int StreamNum, int mxyz[3]);
subroutine irtsam(StreamNum, mxyz )
integer StreamNum, mxyz(3)
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 - Return size information about the image stream.
void IMRtSiz(int StreamNum, int nxyz[3], int mxyz[3], int StartCoordinates[3]);
subroutine irtsiz( StreamNum, nxyz, mxyz, StartCoordinates)
integer StreamNum,nxyz(3),mxyz(3),StartCoordinates(3)
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 - Return the section number for a given the Z, W, and T position.
int IMRtSecNum(int StreamNum,int ZSecNum, int WaveNum, int TimeNum, int *SecNum)
irtsecnum(StreamNum, ZSecNum, WaveNum, TimeNum,SecNum)
integer StreamNum, ZSecNum,WaveNum,TimeNum,SecNum
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.
The function returns TRUE if ZSecNum, WaveNum, or TimeNum are inappropriate for StreamNum. Otherwise the function returns FALSE.
IMRtSpg - Return the crystallography space group information.
void IMRtSpg(int StreamNum, int *nspg, int *mbsym);
subroutine irtspg( StreamNum, nspg, mbsym)
integer StreamNum,nspg,mbsym
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 - Return the symmetry information.
void IMRtSym(int StreamNum, int *NumSymBytes, void *SymmetryInfo);
subroutine irtsym(StreamNum, NumSymBytes, SymmetryInfo)
integer StreamNum,NumSymBytes
char SymmetryInfo(numSymBytes)
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.
Return the tilt angles.
void IMRtTlt(int StreamNum, float TiltAngles[3]);
subroutine irttlt( StreamNum, TiltAngles)
integer StreamNum
real TiltAngles(3)
Return the tilt angles about xyz into TiltAngles.
IMAlTSt-Return the time start field from the header of a data set
void IMRtTSt(int StreamNum, int *itst);
subroutine irttst(StreamNum, itst)
integer StreamNum,itst
The starting time value for the image stream is returned in itst .
Return information about the image stream's wavelengths.
void IMRtWav(int StreamNum, int *NumWaves, float Wavelengths[IW_MAX_WAVE]);
subroutine irtwav(StreamNum, NumWaves, Wavelengths)
integer StreamNum,NumWaves
real Wavelengths(5)
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 - Return the minimum and maximum intensity of a particular wavelength.
void IMRtWavMM(int StreamNum, int WaveNum, float *MinIntensity, float *MaxIntensity);
subroutine irtwav_mm(StreamNum, WaveNum, MinIntensity, MaxIntensity)
integer StreamNum,WaveNum
real MinInten, MaxInten
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 - Return the number of Z sections, wavelengths, and time-points.
void IMRtZWT(int StreamNum, int *NumZSec, int *NumWaves, int *NumTimes, int *ImgSequence);
subroutine irtzwt( StreamNum, NumZSec, NumWaves, NumTimes,
ImgSequence)
integer StreamNum, NumZSec,NumWaves,NumTimes,ImgSequence
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 - Return the ZWT positions given the section number.
int IMRtZWTNum(int iStream,int *iz, int *iw, int *it, int iSecNum)
irtzwtnum( iStream,iz, iw, it, iSecNum)
integer iStream,iz,iw,it,iSecNum
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 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 - Read the next line in the image stream.
void IMRdLin(int StreamNum, void *ImgBuffer);
subroutine irdlin(StreamNum, ImgBuffer, *line)
integer StreamNum
real ImgBuffer(size to read in)
line: branch to Fortran line # on error
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 - Read part of the next line.
void IMRdPal(int StreamNum, void *ImgBuffer, int *Column1, int *Column2);
subroutine irdpal( StreamNum, ImgBuffer, Column1, Column2,
*line)
integer StreamNum,Column1,Column2
real ImgBuffer(size to read in)
line: branch to Fortran line # on error
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 - Read part of the next section.
void IMRdPas(int StreamNum, void *ImgBuffer, int mx, int my, int Column1, int Column2, int Row1, int Row2);
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
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 - Read the next section.
void IMRdSec(int StreamNum, void *ImgBuffer);
subroutine irdsec(StreamNum, ImgBuffer, *line)
integer StreamNum
real ImgBuffer(size to read in)
line: branch to Fortran line # on error
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 - Read a number of lines from the next section.
void IMRdSecl(int StreamNum, void *ImgBuffer, int *NumLines);
subroutine irdsecl(StreamNum, ImgBuffer, NumLines, *line)
integer StreamNum, NumLines
real ImgBuffer(size to read in)
line: branch to Fortran line # on error
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 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.
Name
IMWrLin - Write a line of image data.
void IMWrLin(int StreamNum, const void *ImgBuffer);
subroutine iwrlin( StreamNum, ImgBuffer)
integer StreamNum
real ImgBuffer(size of data to write)
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 - Write part of an image line to the storage device.
void IMWrPal(int StreamNum, const void *ImgBuffer, int Column1, int Column2);
subroutine iwrpal( StreamNum, ImgBuffer, Column1, Column2)
integer StreamNum,Column1,Column2
real ImgBuffer(size of data to write)
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 - Write part of the next section to the storage device.
void IMWrPas(int StreamNum, const void *ImgBuffer, int mx, int my, int Column1, int Column2, int Row1, int Row2);
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)
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 - Write the next section to the storage device.
void IMWrSec(int StreamNum, const void *ImgBuffer);
subroutine iwrsec(StreamNum, ImgBuffer)
integer StreamNum
real ImgBuffer(size of data to write)
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 - Write a number of lines to the next section.
void IMWrSecl(int StreamNum, const void *ImgBuffer, int NumLines);
subroutine iwrsecl(StreamNum, ImgBuffer, NumLines)
integer StreamNum, NumLines
real ImgBuffer(size of data to write)
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.
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 - Position the read/write pointer of a stream to a particular section and row number.
int IMPosn(int StreamNum, int SecNum, int Row);
integer function imposn( StreamNum, SecNum, Row)
integer StreamNum,SecNum,Row
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.
IMPosn returns 0 if successful and 1 if not.
IMPosnRes - Position the read/write pointer at the start of a particular resolution data set.
int IMPosnRes(int StreamNum, int ResolutionNum);
subroutine imposn_res( StreamNum, ResolutionNum)
integer StreamNum, ResolutionNum
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 - Position the read/write point at a particular Z, W, T section.
int IMPosnZWT(int StreamNum, int ZSecNum, int WaveNum, int TimeNum);
integer function imposn_zwt( StreamNum, ZSecNum, WaveNum, TimeNum)
integer StreamNum,ZSecNum,WaveNum,TimeNum
Position the read/write pointer of Stream