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 to the number of colums. |
| 33 - 36 |
i |
my |
Sampling frequency in y; commonly set to the number of rows. |
| 37 - 40 |
i |
mz |
Sampling frequency in z; commonly set to the number of 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.
|
Image type |
Var | Description |
|
0 |
Normal image data | |
|
1 |
Tilt-series | |
|
n1 |
Tilt-axis, 1=x, 2=y, 3=z | |
|
n2 |
Center of rotation is z origin + n2 times one half the z pixel spacing | |
|
v1 |
Tilt angle, degrees | |
|
v2 |
Always 0 | |
|
2 |
Stereo tilt-series | |
|
n1 |
Tilt-axis, 1=x, 2=y, 3=z | |
|
n2 |
Always 0 | |
|
v1 |
Tilt angle, degrees | |
|
v2 |
Angular separation of the stereo pair, degrees | |
|
3 |
Averaged images | |
|
n1 |
Number of averaged sections | |
|
n2 |
Sections between averaged sections | |
|
v1 |
Always 0 | |
|
v2 |
Always 0 | |
|
4 |
Averaged stereo pairs | |
|
n1 |
Number of averaged sections | |
|
n2 |
Sections between averaged sections | |
|
v1 |
Angular separation of the stereo pair, degrees | |
|
v2 |
Always 0 | |
|
8000 |
Pupil function image | |
|
n1 |
Not used | |
|
n2 |
Not used | |
|
v1 |
Numerical aperture times 10 | |
|
v2 |
Immersion media refractive index times 100 |
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 |
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.
|
Sequence |
Comments |
|
ZTW_SEQUENCE |
A common sequence of processed images. Sometimes referred to as "non-interleaved". |
|
WZT_SEQUENCE |
The typical sequence of images acquired from a microscope. Sometimes referred to as "interleaved". |
|
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, 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. Both of these include files are in the INCLUDE directory in the top level of the Priism distribution.
When linking your application, link against IWL.a or libIWL.so to get the extended IM functions which can operate on image windows; otherwise, link against imlib.a or libimlib.so.
In IVE3.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 libraries are located in LIB_IRIX directory in the top level directory of the Priism distribution. They can also be found in LIB in the same directory. If you use the archive versions of the libraries (IWL.a or imlib.a), you may need to link against additional libraries that are used by the IM functions. When linking against IWL.a the additional options that you may need to supply are
-lX11 -lGLU -lGL -lm -lftn -lC -lCsup -lc
When linking against imlib.a the additional options are
-lm -lftn -lc
You may not need to specify all of these additional options above. If you link your application with the Fortran compiler, you should omit -lm, -lftn and -lc. If you link your application with the C compiler, you should omit -lc. If you link with the C++ compiler, -lC, -lCsup, and -lc should be omitted. The other libraries may be omitted if you do not call an IM or IW function that uses them. If you find that your application does need to be linked against -lC and -lCsup, you should link using the C++ compiler to ensure that the C++ runtime environment is properly initialized when your program is launched.
On these systems the libraries are in the LIB_OSF1 directory in top level directory of the Priism distribution. IW calls and the ability for IM functions to operate on image windows are not supported so IWL.a is identical to imlib.a and libIWL.so is identical to libimlib.so. If you use the archive libraries, you may need to link against additional libraries used by the IM functions. The additional options that could be needed are
-lm -lfor -lUfor -lc
You may not need to specify all of these additional options. If you link your application with the Fortran compiler, you should not specify any of them. If you link your application with the C or C++ compiler, you should omit -lc. The other libraries may be omitted if you do not call an IM function that uses them.
To use the x86 Linux libraries you will need an x86 Linux system that supports compiling ELF executables and has glibc2. You will also need access to the Portland Group Fortran libraries.
IW calls and the ability for IM functions to operate on image windows are not supported in the Linux release; therefore, the IM library (imlib.a) is identical to the IWL library (IWL.a). At this time, the libraries are not available as shared libraries.
There are two versions of the Linux libraries. The one in the LIB_Linux86 directory should be used by programs written in C, C++, or those in Fortran that are compiled with the Portland Group Fortan compiler. The one in the LIB_Linux86/g77 directory should be used with Fortran programs compiled with g77. When linking against one of these libraries with something other than the Portland Group Fortran compiler you should add
-L$PGI/linux86/lib -lpgftnrtl -lpgc -lm
to the link options where $PGI is an environment variable that points to the base directory where the Portland Group software is installed.
To use the Alpha Linux libraries you will need an Alpha Linux system that supports compiling ELF executables and has glibc2. You will also need the libraries installed for Compaq's compilers (the Fortran libraries, libcpml, and libots are needed).
On these systems the libraries are in the LIB_LinuxAlpha directory in top level directory of the Priism distribution. IW calls and the ability for IM functions to operate on image windows are not supported so IWL.a is identical to imlib.a and libIWL.so is identical to libimlib.so. At this time, the libraries are not available as shared libraries.
The libraries use the default mangling for Compaq's Fortran compiler on Alpha Linux, fort, which happens to be the same as g77. When linking against the libraries with soething other than the Compaq Fortran compiler, you should add
-lUfor
to the link options.
Described below are the IM library functions. Functions prototypes are provided in IWL.h, and the functions themselves can be obtained by linking with IWL.a (or IWL.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.
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(const int StreamNum, char *Name, char *Attributes);
Fortran Synopsis
integer*4 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 preceeded 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 in the following table:
| Attribute | File Type |
| "ro" | read only |
| "new" | new file |
| "old" | old file, can be read and/or modified |
| "scratch" | similar to new, except that the file will be deleted when closed |
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(const int StreamNum);
Fortran Synopsis
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(const 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 so for regular image data these values will be identical to ixyz.
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.
IMWrHdr - Write the image header to the storage device.
void IMWrHdr(const int StreamNum, char Title[80], const int TitleFlag, const float Min, const float Max, const 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(const 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(const int StreamNum, 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.
IMTrHdr - Transfer a header from one stream to another.
void IMTrHdr(const int StreamNum, const int StreamNum2);
Fortran Synopsis
subroutine itrhdr(istream, istream2)
integer istream,istream2
Transfer the header associated with StreamNum2 to the header associated with StreamNum.
IMTrLab - Transfer image titles from one stream to another.
void IMTrLab(const int StreamNum, const 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(const int StreamNum, const 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(const int StreamNum, int ixyz[3], int mxyz[3],
int PixelType, char *Titles,
int NumTitles);
subroutine icrhdr(istream, ixyz, mxyz, iPixelType, Titles,
NumTitles)
integer istream,ixyz(3),mxyz(3),iPixelType,NumTitles
character Titles(80,NumTitles)
Create a new header for StreamNum with image dimensions ixyz and sub-image dimensions of mxyz. Assign image data type of PixelType to the header and add up to 10 Titles that contain exactly 80 characters each. The number of Titles added is determined by NumTitles. Use the IMAl functions to completely define the header and be sure to use IMWrHdr when finished setting up the header.
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(const 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(const int StreamNum, int ZStart, int ZEnd, int NumWaves, 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(const int StreamNum, const int StreamNum2, const int SectionNum, const 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(const int StreamNum, 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(const int StreamNum, const 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(const int StreamNum, const int ImageType, const int LensNum, const int n1, const int n2, const float v1, const 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(const int StreamNum, 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(const 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(const int StreamNum, const int SectionNum, int *IntValues, 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(const 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(const int StreamNum, const int ZSecNum, const int WaveNum, const int TimeNum, int *IntValues, 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(const int istream, char *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 thery 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(const int StreamNum, 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(const int StreamNum, 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(const int StreamNum, const 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(const int StreamNum, const float x0, const float y0, const 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(const 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(const int istream, const int mres, const 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.
IMAlSam - Alter sampling size information
void IMAlSam(const int istream, 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 thru mxyz.
IMAlSiz - Change the image size and starting point.
void IMAlSiz(const int StreamNum, int ixyz[3], 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(const int StreamNum, const int nspg, const 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(const int StreamNum, const int mbsym, char *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(const int StreamNum, 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(const int StreamNum, 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(const int StreamNum, const 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(const int StreamNum, const int NumWaves, 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(const int StreamNum, const int WaveNum, const float MinInten, const 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(const int StreamNum, const int NumZSec, const int NumWaves, const int NumTimes, const 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.
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
IMRtLab - Return the title strings and number of
active titles.
IMRtMap - Return the column, row, section mapping
info.
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 sub-image 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(const 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(const 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(const 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(const int StreamNum, const 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(const 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(const int StreamNum, const int ZSecNum, const int WaveNum, const 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(const int istream, char *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.
IMRtLab - Return the title strings and number of active titles.
void IMRtLab(const 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(const 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.
IMRtMst - Return the starting coordinates of the image array.
void IMRtMst(const 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(const 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(const 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(const 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 sub-image size.
void IMRtSam(const int StreamNum, int SubSize[3]);
subroutine irtsam(StreamNum, SubSize )
integer StreamNum, SubSize
The xyz dimensions of the sub-image is returned into SubSize.
IMRtSiz - Return size information about the image stream.
void IMRtSiz(const 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)
Three size related arrays are returned by IMRtSiz. nxyz contains
the file xyz image dimensions. mxyz contains the full map columns,
rows, sections. This is for X-ray data, For image data
mxyz is set to same as nxyz. 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(const 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(const int StreamNum, int *NumSymBytes, unsigned char *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(const 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(const 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(const 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(const int StreamNum, const 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(const 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, float *ImgBuffer);
subroutine irdlin(StreamNum, ImgBuffer, *line)
integer StreamNum
real ImgBuffer(size to read in)
line: branch to Fortran line # on error
Read the next line of the image stream into ImgBuffer. The size of ImgBuffer should be at least the number of columns in the image.
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, float *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
Read part of the next line into ImgBuffer. Start at Column1 and end at Column2. The size required for ImgBuffer is (Column2 - Column1 + 1) 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.
IMRdPas - Read part of the next section.
void IMRdPas(int StreamNum, float *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
Read part of the next section into ImgBuffer. Start at (Column1, Row1) and continue until (Column2, Row2). mx, my correspond to the x, y dimensions of ImgBuffer. Often, mx = (Column2 - Column1 + 1) and my = (Row2 - Row1 + 1), however, they may be larger. Under no circumstances should they be smaller.
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, float *ImgBuffer);
subroutine irdsec(StreamNum, ImgBuffer, *line)
integer StreamNum
real ImgBuffer(size to read in)
line: branch to Fortran line # on error
Read the next section into ImgBuffer. The size of ImgBuffer should be nx*ny 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.
IMRdSecl - Read a number of lines from the next section.
void IMRdSecl(int StreamNum, float *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
Read NumLines from the next section and put them in ImgBuffer. 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 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, float *ImgBuffer);
subroutine iwrlin( StreamNum, ImgBuffer)
integer StreamNum
real ImgBuffer(size of data to write)
Write a line of data from ImgBuffer to the storage device. The
size of ImgBuffer should be nx elements. The data will be
written out to the current position of the pointer. The pointer is
set to start at the next line after this call.
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, float *ImgBuffer, int Column1, int Column2);
subroutine iwrpal( StreamNum, ImgBuffer, Column1, Column2)
integer StreamNum,Column1,Column2
real ImgBuffer(size of data to write)
Write part of the next line, from Column1 to Column2. The size of ImgBuffer should be (Column2 - Column1 + 1). The data will be written out to the current position of the pointer. The pointer is set to start at the next line after this call.
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, float *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)
Write part of ImgBuffer as the next section. Start at (Column1, Row1) and continue until (Column2, Row2). mx, my correspond to the x, y dimensions of ImgBuffer. The size of [(Column2 - Column1 + 1), (Row2 - Row1 + 1)] should be less than or equal to the image dimensions.. Data is written starting at the current position of the pointer. The pointer is set to the beginning of the next section after this call.
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(const int StreamNum, void *ImgBuffer);
subroutine iwrsec(StreamNum, ImgBuffer)
integer StreamNum
real ImgBuffer(size of data to write)
Write ImgBuffer to the next section. The size of ImgBuffer should be nx*ny elements. Data will be written to current position of pointer.Pointer is set to start of next section after this call.
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(const int StreamNum, float *ImgBuffer, int NumLines);
subroutine iwrsecl(StreamNum, ImgBuffer, NumLines)
integer StreamNum, NumLines
real ImgBuffer(size of data to write)
Write NumLines from ImgBuffer to the next section. The size of ImgBuffer should be nx*NumLines elements. Data is written to current position of pointer. Pointer is set to the beginning of the next section after this call.
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(const int StreamNum, const int SecNum, const 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.
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(const int StreamNum, const 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(const int StreamNum, const int ZSecNum, const int WaveNum, const int TimeNum);
integer function imposn_zwt( StreamNum, ZSecNum, WaveNum, TimeNum)
integer StreamNum,ZSecNum,WaveNum,TimeNum
Position the read/write pointer of StreamNum to Z section number ZSecNum, wavelength number WaveNum, and time-point number TimeNum.
IMPosnZWT returns 0 if successful and 1 if not.