SECTION 3.1 - IMAGE FILE READING ROUTINES
3.1.1 INTRODUCTION
These are a set of routines for reading film image and image plate (i2) files (without header information) or MAR image plate files. The routines are written in C. Fortran interfaces are provided. They were written, in particular, for use with programs using XDL_VIEW routines.The following sets of routines are available:
Film Image File Routines
Image-Plate Image File Routines
MAR Image-Plate File Routines
Axis Order Decoding Routines
3.1.2 FILM IMAGE FILE ROUTINES
3.1.2.1 Introduction
These are routines for reading a film image binary file without header information and with one unsigned byte per pixel.
The following routines are available:
Open a film image file - xdl_open_film_file
Read a full film image file - xdl_read_full_film
Close a film image file - xdl_close_film_file
3.1.2.2 Open a film image file - xdl_open_film_file
The routine xdl_open_film_file (xdlf_open_film_file) is used to open a film image file and return the file descriptor.
Fortran call:
CALL XDLF_OPEN_FILM_FILE (XDLSTR(FILNAM), LENF, IFD, IERR)
Parameters:
FILNAM (R) Character string holding the filename
(see filename)
** Pass address using the XDLSTR routine **
LENF (R) Length of the filename string (see lenf)
IFD (W) Returns the file descriptor (see fd)
IERR (W) Returns the status from the xdl_open_film_file
call
'C' call: int xdl_open_film_file (filename, lenf, fd)
Parameters:
char * filename; /* The name of the film image file (R)*/
int lenf; /* Length of the file name. If the filename is a
null terminated string then the length will be
determined by the routine if lenf is 0 (R)*/
int * fd; /* Returns the file descriptor (W)*/
Return: =0 OK; =1 Unable to open the file;
3.1.2.3 Read a full film image file - xdl_read_full_film
The routine xdl_read_full_film (xdlf_read_full_film) is used to read a complete film image file and return the image data in an array. The film file may have its data in any of the eight possible orders (the default is assumed to have yf moving fastest and xf slowest) and is in unsigned byte format without any header. The number of x rasters and the number of y rasters must be supplied.
Fortran call:
CALL XDLF_READ_FULL_FILM (IFD, IORD, NXRASTS, NYRASTS,
+ IVH_BAR, IXROOT, IYROOT, IMG_FULL,
+ IERR)
Parameters:
IFD (R) The file descriptor (see fd)
IORD (R) Order of the data in the film image file (1 to 8)
(see order)
NXRASTS (R) The number of x rasters (see nxrasts)
NYRASTS (R) The number of y rasters (see nyrasts)
IVH_BAR (R) View-object handle for displaying a read progress
bar >0 on 0 if none required (see vh_bar)
IXROOT (R) x root position for progress bar display if
required (see xroot)
IYROOT (R) y root position for progress bar display if
required (see yroot)
IMG_FULL (W) Array to hold the read data (pass as an
integer array sufficiently large to hold the
returned image data) (see img_full)
IERR (W) Returns the status from the xdl_read_full_film call
'C' call:
int xdl_read_full_film (fd, order,nxrasts, nyrasts, vh_bar,
xroot, yroot, img_full)
Parameters:
int fd; /* The file descriptor of the opened film format
file (R)*/
int order; /* Order of the data in the input film image file
in terms of the xf, yf coordinate system as
a number from 1 to 8.
1 +xf slow +yf fast
2 +xf slow -yf fast
3 -xf slow +yf fast
4 -xf slow -yf fast
5 +yf slow +xf fast
6 +yf slow -xf fast
7 -yf slow +xf fast
8 -yf slow -xf fast
(R)*/
int nxrasts; /* The number of x rasters (R)*/
int nyrasts; /* The number of y rasters (R)*/
int vh_bar; /* View-object handle (>0) for display bar showing the
progress of the read, 0 if none required (R) */
int xroot; /* The root x position for the top left of the display
bar area if required (R)*/
int yroot; /* The root y position for the top left of the display
bar area if required (R)*/
unsigned char img_full[];
/* Array returning the read image data;
The slower moving index in
the returned data is x going from low x to
high x and the faster moving index is y going
from low y to high y. (W)*/
Return: =0 OK; >0 Record number where a read error occurred; -1 unable
to allocate temporary buffer space.
3.1.2.4 Close a film image file - xdl_close_film_file
The routine xdl_close_film_file (xdlf_close_film_file) is used to close a film image file.
Fortran call:
CALL XDLF_CLOSE_FILM_FILE (IFD, IERR)
Parameters:
IFD (R) The file descriptor (see fd)
IERR (W) Returns the status from the xdl_close_film_file
call
'C' call: int xdl_close_film_file (fd)
Parameters: int fd; /* The file descriptor (R)*/
Return: =0 OK; =1 Unable to close the file;
3.1.3 IMAGE-PLATE IMAGE FILE ROUTINES
3.1.3.1 Introduction
These are routines for reading a image-plate image binary file without header information and with one unsigned two-byte integer per pixel.
The following routines are available:
Open an image plate (i2) file - xdl_open_i2
Read a full image-plate image file - xdl_read_full_i2
Close an image plate (i2) file - xdl_close_i2
3.1.3.2 Open an image plate (i2) file - xdl_open_i2
The routine xdl_open_i2 (xdlf_open_i2) is used to open an 'i2' unsigned 16 bit integer format image file and return the file descriptor. It can in fact be used with any format (image) file.
Fortran call:
CALL XDLF_OPEN_I2 (XDLSTR(FILNAM), LENF, IFD, IERR)
Parameters:
FILNAM (R) Character string holding the filename
(see filename)
** Pass address using the XDLSTR routine **
LENF (R) Length of the filename string (see lenf)
IFD (W) Returns the file descriptor (see fd)
IERR (W) Returns the status from the xdl_open_i2 call
'C' call: int xdl_open_i2 (filename, lenf, fd)
Parameters:
char * filename; /* The name of the 'i2' format image file (R)*/
int lenf; /* Length of the file name. If the filename is a
null terminated string then the length will be
determined by the routine if lenf is 0 (R)*/
int * fd; /* Returns the file descriptor (W)*/
Return: =0 OK; =1 Unable to open the file,
=2 error in reading the file header
3.1.3.3 Read a full image-plate image file - xdl_read_full_i2
The routine xdl_read_full_i2 (xdlf_read_full_i2) is used to read a complete image-plate image file and return the image data in an array. The image-plate file may have its data in any of the eight possible orders and may be byte swapped if necessary (the default is assumed to have yf moving fastest and xf slowest) and is in unsigned two byte integer format without any header. The number of x rasters and the number of y rasters must be supplied.
Fortran call:
CALL XDLF_READ_FULL_I2 (IFD, IORD, NXRASTS, NYRASTS,
+ IVH_BAR, IXROOT, IYROOT, IMG_FULL,
+ MINVAL, MAXVAL, IERR)
Parameters:
IFD (R) The file descriptor (see fd)
IORD (R) Order of the data in the film image file (1 to 8)
(-IORD can be given to swap bytes in the data as
well as re-order it ) (see order)
NXRASTS (R) The number of x rasters (see nxrasts)
NYRASTS (R) The number of y rasters (see nyrasts)
IVH_BAR (R) View-object handle for displaying a read progress
bar >0 on 0 if none required (see vh_bar)
IXROOT (R) x root position for progress bar display if
required (see xroot)
IYROOT (R) y root position for progress bar display if
required (see yroot)
IMG_FULL (W) Array to hold the read data (pass as an
integer array sufficiently large to hold the
returned image data) (see img_full)
MINVAL (W) The minimum pixel value in the image (see minval)
MAXVAL (W) The maximum pixel value in the image (see maxval)
IERR (W) Returns the status from the xdl_read_full_film call
'C' call:
int xdl_read_full_i2 (fd, order, nxrasts, nyrasts, vh_bar, xroot, yroot,
img_full, minval, maxval)
Parameters:
int fd; /* The file descriptor of the opened film format
file (R)*/
int order; /* Order of the data in the input film image file
in terms of the xf, yf coordinate system as
a number from 1 to 8. (-order can be given to
byte swap the data as well as change the order)
1 +xf slow +yf fast
2 +xf slow -yf fast
3 -xf slow +yf fast
4 -xf slow -yf fast
5 +yf slow +xf fast
6 +yf slow -xf fast
7 -yf slow +xf fast
8 -yf slow -xf fast
(R)*/
int nxrasts; /* The number of x rasters (R)*/
int nyrasts; /* The number of y rasters (R)*/
int vh_bar; /* View-object handle (>0) for display bar showing the
progress of the read, 0 if none required (R) */
int xroot; /* The root x position for the top left of the display
bar area if required (R)*/
int yroot; /* The root y position for the top left of the display
bar area if required (R)*/
unsigned short img_full[];
/* Array returning the read image data;
The slower moving index in
the returned data is x going from low x to
high x and the faster moving index is y going
from low y to high y i.e. the same order as in the
file. (W)*/
int *minval; /* Returns the minimum pixel value in the image (W)*/
int *maxval; /* Returns the maximum pixel value in the image (W)*/
Return: =0 OK; >0 Record number where a read error occurred.
3.1.3.4 Close an image plate (i2) file - xdl_close_i2
The routine xdl_close_i2 (xdlf_close_i2) is used to close an image plate 'i2' format file. It can in fact be used with any format (image) file.
Fortran call:
CALL XDLF_CLOSE_I2 (IFD, IERR)
Parameters: IFD (R) The file descriptor (see fd) IERR (W) Returns the status from the xdl_close_i2 call
'C' call: int xdl_close_i2 (fd)
Parameters: int fd; /* The file descriptor (R)*/
Return: =0 OK; =1 Unable to close the file;
3.1.4 MAR IMAGE-PLATE FILE ROUTINES
3.1.4.1 Introduction
These are routines for reading a MAR image-plate system image file including the header information and overflow data.
The following routines are available:
Read a MAR image plate file - xdl_read_mar
Read and squash a MAR image plate file - xdl_rdsquash_mar
Read a Photon Factory Log Byte File - xdl_read_pfbyte
3.1.4.2 Read a MAR image plate file - xdl_read_mar
The routine xdl_read_mar (xdlf_read_mar) is used to read a complete MAR image-plate image file and return the image data in an array. Overload data are include. The returned image contains signed integer*4 data. The data will be byte swapped on input if required.
Fortran call:
CALL XDLF_READ_MAR (IFD, IVH_BAR, IXROOT, IYROOT,
+ IMG_FULL, NXPIX, NYPIX, NS_RAS, NF_RAS,
+ MINVAL, MAXVAL, IERR)
Parameters:
IFD (R) The file descriptor (see fd)
IVH_BAR (R) View-object handle for displaying a read progress
bar >0 on 0 if none required (see vh_bar)
IXROOT (R) x root position for progress bar display if
required (see xroot)
IYROOT (R) y root position for progress bar display if
required (see yroot)
IMG_FULL (W) Array to hold the read data (pass as an
integer array sufficiently large to hold the
returned image data) (see img_full)
NXPIX (W) Returns no. of 'x' pixels
NYPIX (W) Returns no. of 'y' pixels
NS_RAS (W) Returns no. of slow rasters
NF_RAS (W) Returns no. of fast rasters
MINVAL (W) The minimum pixel value in the image (see minval)
MAXVAL (W) The maximum pixel value in the image (see maxval)
IERR (W) Returns the status from the xdl_read_mar call
'C' call:
int xdl_read_mar (fd, vh_bar, xroot, yroot, img_full,
nxpix, nypix, ns_ras, nf_ras, minval, maxval)
Parameters:
int fd; /* The file descriptor of the opened film format
file (R)*/
int vh_bar; /* View-object handle (>0) for display bar showing the
progress of the read, 0 if none required (R) */
int xroot; /* The root x position for the top left of the display
bar area if required (R)*/
int yroot; /* The root y position for the top left of the display
bar area if required (R)*/
int img_full[]; /* Array returning the read image data (W) */
int *nxpix; /* Returns the no. of 'x' pixels (W)*/
int *nypix; /* Returns the no. of 'y' pixels (W)*/
int *ns_ras; /* Returns the no. of 'slow' rasters */
int *nf_ras; /* Returns the no. of 'fast' rasters */
int *minval; /* Returns the minimum pixel value in the image (W)*/
int *maxval; /* Returns the maximum pixel value in the image (W)*/
Return: =0 OK; >0 Record number where a read error occurred.
-1 error in allocating memory
-2 error reading header
-3 error reading overflow data
3.1.4.3 Read and squash a MAR image plate file - xdl_rdsquash_mar
The routine xdl_rdsquash_mar (xdlf_rdsquash_mar) is used to read a complete MAR image-plate image file and return the image data in an array. Overload data are included. The returned image contains each data item packed into two bytes with intensities>32767 being stored as (65536-intensity/8) (unsigned) values. The data will be byte swapped on input if required.
Fortran call:
CALL XDLF_RDSQUASH_MAR (IFD, IVH_BAR, IXROOT, IYROOT,
+ IMG_FULL, NXPIX, NYPIX, NS_RAS, NF_RAS,
+ MINVAL, MAXVAL, IERR)
Parameters:
IFD (R) The file descriptor (see fd)
IVH_BAR (R) View-object handle for displaying a read progress
bar >0 on 0 if none required (see vh_bar)
IXROOT (R) x root position for progress bar display if
required (see xroot)
IYROOT (R) y root position for progress bar display if
required (see yroot)
IMG_FULL (W) Array to hold the read data (pass as an
integer array sufficiently large to hold the
returned image data) (see img_full)
NXPIX (W) Returns no. of 'x' pixels
NYPIX (W) Returns no. of 'y' pixels
NS_RAS (W) Returns no. of slow rasters
NF_RAS (W) Returns no. of fast rasters
MINVAL (W) The minimum pixel value in the image (see minval)
MAXVAL (W) The maximum pixel value in the image (see maxval)
IERR (W) Returns the status from the xdl_rdsquash_mar call
'C' call:
int xdl_rdsquash_mar (fd, vh_bar, xroot, yroot, img_full,
nxpix, nypix, ns_ras, nf_ras, minval, maxval)
Parameters:
int fd; /* The file descriptor of the opened film format
file (R)*/
int vh_bar; /* View-object handle (>0) for display bar showing the
progress of the read, 0 if none required (R) */
int xroot; /* The root x position for the top left of the display
bar area if required (R)*/
int yroot; /* The root y position for the top left of the display
bar area if required (R)*/
unsigned short img_full[]; /* Array returning the read image data as
squashed two-byte data (W) */
int *nxpix; /* Returns the no. of 'x' pixels (W)*/
int *nypix; /* Returns the no. of 'y' pixels (W)*/
int *ns_ras; /* Returns the no. of 'slow' rasters */
int *nf_ras; /* Returns the no. of 'fast' rasters */
int *minval; /* Returns the minimum pixel value in the image (W)*/
int *maxval; /* Returns the maximum pixel value in the image (W)*/
Return: =0 OK; >0 Record number where a read error occurred.
-1 error in allocating memory
-2 error reading header
-3 error reading overflow data
3.1.4.4 Read a Photon Factory Log Byte File - xdl_read_pfbyte
The routine xdl_read_pfbyte (xdlf_read_pfbyte) is used to read a complete Photon Fcatory image plate file and return the image data in an array. The file may have its data in any of the eight possible orders (the default is assumed to have yf moving fastest and xf slowest). Each pixel stores a log value for the pixel intensity (unsigned byte). The file has no header. The number of x rasters and the number of y rasters must be supplied. The data are returned in a packed integer array with
Fortran call:
CALL XDLF_READ_PFBYTE (IFD, IORD, NXRASTS, NYRASTS,
+ IVH_BAR, IXROOT, IYROOT, IMG_FULL,
+ IERR)
Parameters:
IFD (R) The file descriptor (see fd)
IORD (R) Order of the data in the image file (1 to 8)
(see order)
NXRASTS (R) The number of x rasters (see nxrasts)
NYRASTS (R) The number of y rasters (see nyrasts)
IVH_BAR (R) View-object handle for displaying a read progress
bar >0 on 0 if none required (see vh_bar)
IXROOT (R) x root position for progress bar display if
required (see xroot)
IYROOT (R) y root position for progress bar display if
required (see yroot)
IMG_FULL (W) Array to hold the read data (pass as an
integer array sufficiently large to hold the
returned image data) (see img_full)
IERR (W) Returns the status from the xdl_read_pfbyte call
'C' call:
int xdl_read_pfbyte (fd, order, nxrasts, nyrasts, vh_bar,
xroot, yroot, img_full)
Parameters:
int fd; /* The file descriptor of the opened film format
file (R)*/
int order; /* Order of the data in the input film image file
in terms of the xf, yf coordinate system as
a number from 1 to 8.
1 +xf slow +yf fast
2 +xf slow -yf fast
3 -xf slow +yf fast
4 -xf slow -yf fast
5 +yf slow +xf fast
6 +yf slow -xf fast
7 -yf slow +xf fast
8 -yf slow -xf fast
(R)*/
int nxrasts; /* The number of x rasters (R)*/
int nyrasts; /* The number of y rasters (R)*/
int vh_bar; /* View-object handle (>0) for display bar showing the
progress of the read, 0 if none required (R) */
int xroot; /* The root x position for the top left of the display
bar area if required (R)*/
int yroot; /* The root y position for the top left of the display
bar area if required (R)*/
unsigned short img_full[];
/* Array returning the read image data as two byte
unsigned quantities;
The slower moving index in
the returned data is x going from low x to
high x and the faster moving index is y going
from low y to high y. (W)*/
Return: =0 OK; >0 Record number where a read error occurred; -1 unable
to allocate temporary buffer space.
3.1.5 AXIS ORDER DECODING ROUTINES
3.1.5.1 Introduction
These are routines for decoding the axis order codes use to indicate the order of the data in an image file.
The following routines are available:
Interpret axis order string - xdl_axord
3.1.5.2 Interpret axis order string - xdl_axord
The routine xdl_axord (xdlf_axord) is used to interpret a user supplied string defining the axis order in an input film or image-plate file. An option to request or nullify byte swapping (only relevant for image plate data) may also be given. The string defines the axis order in terms of x and y (the film xf, yf axes). The slower moving axis is given first followed by the faster moving axis. Minus signs are used when the order of an axis is reversed. The code 's' if present indicates that byte swapping is to be done and the code 'n' indicates that no byte swapping is to be done (byte swapping only relevant for image plate data). Characters, other than 'x', 'y', '-', '+', 's' and 'n', or their upper case equivalents, are ignored. Some examples follow and the returned flags are indicated: . xy order = 1, swaptyp = 0 +x+y order = 1, swaptyp = 0 -xy order = 3, swaptyp = 0 x-y s order = 2, swaptyp = 2 -Y, +X, n order = 7, swaptyp = 1 S order = 0, swaptyp = 2 +yf, +xf order = 4, swaptyp = 0 Invalid strings: +x-x (Same axis defined twice) +x+y-x (More than two axes defined) xysn (Byte swapping and no byte swapping both defined) .
Fortran call:
CALL XDLF_AXORD (STR, LEN, IORD, ISWAP, IERR)
Parameters:
STR (R) Character string containing the axis order
(and byte swapping option) definition
(see str)
** Pass address using the XDLSTR routine **
LEN (R) The length of the character string
IORD (W) Returns the axis order as a number from 1-8
(0 if not specified or syntax error)
(see order)
ISWAP (W) Returns the byte swap flag =1 no byte swap
=2 byte swap data
=0 not specified (or
syntax error)
IERR (W) Returns the status from the xdl_axord call
'C' call: int xdl_axord (str,len,order,swaptyp)
Parameters:
char *str; /* String containing the axes order and byte swap flags
(R)*/
int len; /* Length of the string; if 0 then assume a null
terminated string was passed (R) */
int *order; /* Returns the axis order given as a number from 1 to 8
(If none specified (or syntax error) return 0)
1 +xf slow +yf fast
2 +xf slow -yf fast
3 -xf slow +yf fast
4 -xf slow -yf fast
5 +yf slow +xf fast
6 +yf slow -xf fast
7 -yf slow +xf fast
8 -yf slow -xf fast
(W)*/
int *swaptyp; /* Returns byte swap type =1 do not swap bytes
=2 swap bytes
=0 not specified (or syntax
error)
(W)*/
Return: Error flag =0 no error;
>0 syntax error =1 Only one axis defined.
=2 Both axes the same.
=3 More than two axes defined.
=4 Byte swapping and no byte
swapping defined.
John W. Campbell
CCLRC Daresbury Laboratory
Last update 4 Feb 1998