| FSL Programmer's Manual - libavwio(3l)
|
|
NAME
libavwio - a low-level library for accessing AVW (Analyse) files.
SYNOPSIS
#include <avwio.h>
cc -I /usr/local/fsl/include/avwio file.c -lavwio
DESCRIPTION
This library of routines allows the user to open, read, manipulate and
write Analyse format 4D image files. The functions are mostly volume
based to enable the programmer to deal with large data files in a
convenient manner.
IMPORTANT NOTES
Limited support is provided to read & write non-native binaries, ie.
the library can read little-endian files on big-endian machines and
vise-versa. The following features should be noted:
-
Endian-ness support works automatically so the programmer needn't change
his/her source code to take advantage of it.
-
One can read any combination of big/little-endian files in the same
session. Just code as if it isn't an issue.
-
Endian-ness is preserved on modification of a file.
-
Natural byte ordering is used for any new file.
CONSTANTS
#define AVW_READ 0
#define AVW_WRITE 1
DATA TYPES
typedef struct
{
FILE *imgfp;
FILE *hdrfp;
int mode, sameorder;
struct dsr header;
} AVW;
The Analyse "file" format consists of two actual files: a header file,
with the ".hdr" extension, and a 4D image data file, with the ".img"
file extension. The AVW structure stores pointers to the open files
hdrfp and imgfp along with the mode (either AVW_READ or AVW_WRITE) and
the dsr header information. A pointer to one of these data structures
should be passed to the functions in libavwio to get/set values in the
open AVW "file".
Please do not try to access the file or dsr header pointers
directly. If it can't be done using the functions provided then the
library should be extended appropriately.
The following data types are recognised by the avwio library:
#define DT_NONE 0
#define DT_UNKNOWN 0
#define DT_BINARY 1
#define DT_UNSIGNED_CHAR 2
#define DT_SIGNED_SHORT 4
#define DT_SIGNED_INT 8
#define DT_FLOAT 16
#define DT_COMPLEX 32
#define DT_DOUBLE 64
#define DT_RGB 128
#define DT_ALL 255
FUNCTIONS
-
AVW * AvwOpen
(
const char * filename,
const char * opts
);
Returns a pointer to an initialised AVW structure representing the
open file stored in the filename.img and filename.hdr pair. The opts
string is used to indicate open for reading "r" or writing
"w". Returns NULL if the open calls fail.
- filename - the filename (without any
extension) of the AVW pair you wish to open.
- opts - options to be passed to open(3) when opening the files. Use "r" for reading and
"w" for writing.
- Return - pointer to the newly created AVW structure.
-
int AvwClose
(
AVW * avw
);
commit the changes to the specified AVW file.
- avw - pointer to the AVW structure returned
by AvwOpen.
- Return - The bitwise or of the return values when calling fclose(3) on the two file pointers of the .img and .hdr
pair.
-
void AvwInitHeader
(
AVW * avw,
short t,
size_t x,
size_t y,
size_t z,
const char * units
);
Used to (re)initialise an AVW structure to sensible default values (in
practice you will need to address more of the header structure than
just these simple dimensions but its a start).
- avw - pointer to the AVW structure returned
by AvwOpen.
- t - the data type identifier.
- x, y,
z - The dimensions (number of voxels in x, y and
z).
- units - A string indicating the units,
eg. "mm".
- Return - N/A.
Deprecated March, 31st 2000
-
void AvwInitHeader
(
AVW * avw,
short t,
size_t x,
size_t y,
size_t z,
size_t v,
float vx,
float vy,
float vz,
float tr,
size_t dim,
const char * units
);
Used to (re)initialise an AVW structure to sensible default values (in
practice you will need to address more of the header structure than
just these simple dimensions but its a start).
- avw - pointer to the AVW structure returned
by AvwOpen.
- t - the data type identifier.
- x, y,
z - The dimensions (number of voxels in x, y and
z).
- v - the number of volumes.
- vx, vy,
vz - The voxel sizes.
- tr - The time (in secs) between volumes.
- dim - The dimensionality.
- units - A string indicating the units,
eg. "mm", for any dimensions.
- Return - N/A.
-
void AvwCloneHeader
(
AVW * d,
const AVW * s
);
Use this function to clone one AVW header from
another. This preserves all of the settings of the source header.
- d - The destination AVW header.
- s - The source AVW header.
Added March 31st 2000
-
size_t AvwReadVolumes
(
AVW * avw,
void * buffer,
size_t nvols
);
size_t AvwWriteVolumes
(
AVW * avw,
const void * buffer,
size_t nvols
);
Read/write nvols volumes to/from the buffer buffer at the
current file position. Use AvwSeekVolume to set the file
position. Returns the number of files read/written.
- avw - pointer to the AVW structure returned
by AvwOpen.
- buffer - pointer to memory containing the
volumes to be written or to recieve the volumes requested.
- Return - the number of volumes read/written.
-
int AvwSeekVolume
(
AVW * avw,
size_t vol
);
Position the next read/write to take place at the
beggining of a specified volume in the AVW file.
- avw - pointer to the AVW structure returned
by AvwOpen.
- vol - the volume to be seeked to.
- Return - the byte offset of the current file position.
-
size_t AvwGetVolSize
(
AVW * avw
);
- avw - pointer to the AVW structure returned
by AvwOpen.
- Return - the number of elements (voxels) in each volume.
-
void AvwSetDim
(
AVW * avw,
short x,
short y,
short z,
short v
);
void AvwGetDim
(
AVW * avw,
short * x,
short * y,
short * z,
short * v
);
Sets/gets the dimensions of the given AVW
file.
- avw - a pointer to the AVW structure
returned by AvwOpen.
- x, y,
z - the number of voxels in the x, y and z
dimensions respectively.
- v - the number of
volumes in the file.
-
void AvwSetDimensionality
(
AVW * avw,
size_t dim
);
void AvwGetDimensionality
(
AVW * avw,
size_t * dim
);
Sets/gets the dimensionality, ie. 3=3D/4=4D etc, of
the given AVW file.
- avw - a pointer to the AVW structure
returned by AvwOpen.
- dim - the dimensionality of the dataset.
Added March, 31st 2000
-
void AvwSetVoxDim
(
AVW * avw,
float x,
float y,
float z,
float tr
);
void AvwGetVoxDim
(
AVW * avw,
float * x,
float * y,
float * z,
float * tr
);
Set/get the voxel dimension attributes in the header.
- avw - pointer to the AVW structure returned
by AvwOpen.
- x, y,
z - the size of a voxel in the x, y and z
dimensions respectively.
- tr - The time (in seconds) between each
volume in the time series.
-
void AvwSetMinMax
(
AVW * avw,
int min,
int max
);
void AvwGetMinMax
(
AVW * avw,
int * min,
int * max
);
Set/get the min and max attributes of the header associated with a
given AVW file.
- avw - pointer to the AVW structure returned
by AvwOpen.
- min, max - minimum and
maximum (integer) values in the file.
-
void AvwSetVoxUnits
(
AVW * avw,
const char * units
);
void AvwGetVoxUnits
(
AVW * avw,
char * units
);
Set/get the voxel units attribute in the header of a given AVW.
- avw - pointer to the AVW structure returned
by AvwOpen.
- units - character string representing the
units used to measure the voxel dimensions.
-
void AvwSetDataType
(
AVW * avw,
short t
);
size_t AvwGetDataType
(
AVW * avw,
short * t
);
AvwSetDataType sets the type code to t. AvwGetDataType returns the
number of bits per voxel and sets t according to the coding specied in
the dsr header definition.
- avw - pointer to the AVW structure returned
by AvwOpen.
- t -
one of the types defined in the AVW header file.
-
void AvwSetOrientation
(
AVW * avw,
const char orient
);
void AvwGetOrientation
(
AVW * avw,
char * orient
);
void AvwSetOriginator
(
AVW * avw,
const short orig[5]
);
void AvwGetOriginator
(
AVW * avw,
short orig[5]
);
- avw - pointer to the AVW structure returned
by AvwOpen.
- orient - character string description of
the orientation (Max N chars).
- orig - 5 short indication of the location
of the origin in a volume.
-
size_t AvwReadSliceSeries
(
AVW * avw,
void * buffer,
int slice,
size_t nvols
);
size_t AvwWriteSliceSeries
(
AVW * avw,
const void * buffer,
int slice,
size_t nvols
);
Reads/writes a series of slices from a 4D AVW file, one slice from each volume.
AvwSeekVolumes should be used to select the start
of the volume of at which to start. The AVW pointer will be left at
the end of the volume from which the last slice has been read.
- avw - pointer to the AVW structure returned
by AvwOpen.
- buffer - buffer to memory to recieve/containing the
slices requested.
- slice - slice within the volume to read.
- nvols - number of slices to read.
- Return - the number of slices read.
Added June, 7th 2000
-
size_t AvwReadRowSeries
(
AVW * avw,
void * buffer,
int row,
int slice,
size_t nvols
);
size_t AvwWriteRowSeries
(
AVW * avw,
const void * buffer,
int row,
int slice,
size_t nvols
);
Reads/writes a series of rows from a 4D AVW file, one row from each volume.
AvwSeekVolumes should be used to select the start
of the volume of at which to start. The AVW pointer will be left at
the end of the volume from which the last slice has been read.
- avw - pointer to the AVW structure returned
by AvwOpen.
- buffer - buffer to memory to recieve/containing the
slices requested.
- row - row within the slice to read.
- slice - slice within the volume to read.
- nvols - number of rows to read.
- Return - the number of rows read.
Added June, 7th 2000
SEE ALSO
libimage(3),
The FSL Documentation
BUGS
No known bugs at present. All reports should be sent to the
FSL help-desk.
Dave Flitney
FMRIB Centre
Copyright © 2000, University of Oxford