IDLffAnalyze Class. Ron Kneusel RSI

Transcription

1 IDLffAnalyze Class Ron Kneusel RSI December 2004

2 Table of Contents 1 Purpose Assumptions Unsupported Features Using the IDLffAnalyze Class IDLffAnalyze and Data Orientation Radiological Order The ORIENT field The HEADER structure Method Reference Class Initialization Syntax Description GetProperty Syntax Description SetProperty Syntax Description GetNCols Syntax Description GetNRows Syntax Description GetNSlices Syntax Description GetNVolumes Syntax Description GetOrientation Syntax Description GetVoxelDims Syntax Description SetVoxelDims Syntax Description of 24

3 7.11 SetBitPix Syntax Description SetOrientation Syntax Description QueryPixelData Syntax Description GetPixelData Syntax Description GetVolume Syntax Description GetImage Syntax Description SetPixelData Syntax Description SetVolume Syntax Description SetImage Syntax Description ReadHeaderFile Syntax Description ReadFile Syntax Description WriteFile Syntax Description of 24

4 1 Purpose This document describes the IDLffAnalyze class. This class implements code to read and write files in the ANALYZE 7.5 format developed by the Mayo clinic. This format is widely used in medical imaging research. 2 Assumptions This document assumes that the reader is at least modestly familiar with the ANALYZE format. The documents will describe the IDLffAnalyze class and how it works but will not detail the ANALYZE 7.5 format explicitly. 3 Unsupported Features The current implementation of IDLffAnalyze does not support the following features of the ANALYZE 7.5 standard: 1. BINARY data type, packed bits for binary images. 2. RGB data type, RGB images. These will be added in a future version of this class. 4 Using the IDLffAnalyze Class This class operates syntactically like all other IDL classes. But in order to use it properly certain things need to be kept in mind: 1. The IDLffAnalyze class stores data internally in what is known as radiological order. This ordering is used regardless of the ordering used to store the data on disk. 2. Input is always adjusted so that it is 4 dimensional, columns, rows, slices and volumes such that a single slice would be n-columns x m-rows x 1-slice x 1-volume. Many methods assume the volume number is zero if it is not given. 3. Many of the major and most commonly used properties are available through the GetProperty method, but full header access is only available by using the ALL property to get and update 4 of 24

5 the header. 4. There is a one-to-one correspondence between most of the ANALYZE data types and native IDL types with the exception of the ANALYZE RGB format. 5. The ANALYZE format is a loose standard. It is not rigorously enforced and many variations exist. The IDLffAnalyze class implements a few common variations to support using the class with files generated by the SPM99 and SPM2 functional neuroimaging analysis applicationis. (SPM = Statistical Parametric Mapping ). 6. IDLffAnalyze only reads standard 348 byte headers. Extended headers (allowed by SPM2) or NifTI headers (for.nii files) are not read. 7. IDLffAnalyze reads data in big-endian or little-endian order and converts it to the native order of the machine running the code if necessary. Output can be in either byte order as indicated by the ENDIAN property. 5 IDLffAnalyze and Data Orientation Data orientation on disk and in memory is an often confusing area, partly due to the lack of conformity in regards to implementing the ANALYZE 7.5 format. The choices made here for the IDLffAnalyze class are: 1. Internally, all data will be stored in radiological order (see below). This is the format used by the Analyze application. 2. The ORIENT field of the history structure will be used by default. This can be overridden when reading a file. 5.1 Radiological Order Radiological order refers to a certain way of looking at the data. It is used to define the three common image views: transverse (or axial), coronal, and sagittal. These names are used even when, in the case of MRI, the actual orientation could be at any angle to the orthogonal planes. Within each view, the data may thought of as being viewed in one of two ways. For axial planes, the image may be viewed from the top down ( neurological order ) or the bottom up ( radiological order ). The order used by IDLffAnalyze is best understood visually: 5 of 24

6 Y A S to the scanner Z P I Patient on his back with head towards the scanner R L X In this figure, the directions are measured from the patient, ie, R to L refers to from the patient's right to the patient's left. The three orthogonal axes are referred to as 'X', 'Y' and 'Z' but in reality they may be obliqued and therefore are best understood as 1 st, 2 nd, and 3 rd where the 'X' is the fastest running (ie, columns), 'Y' is the next fastest (rows), and 'Z' is the slowest (slices). Not shown is volumes, there may be more than one volume in the dataset, in which case it is the next slowest, after 'Z'. The letters in the figure are R-L for right to left, P-A for posterior to anterior, and I-S for inferior to superior. The latter is sometimes referred to as F-H for foot to head. This arrangement is sometimes known as LAS using the final direction letter for each axis. The advantage of this view is that the lower-left corner of each orthogonal plane is (0,0). Axial (transverse) slices then are viewed as if standing at the patient's feet and looking up towards the scanner. This assumes the patient is supine (on his back). Coronal slices are viewed from under the patient table up towards the ceiling and saggital slices are viewed across the patient as if standing next to the patient's right shoulder. 5.2 The ORIENT field The ANALYZE 7.5 standard defines an optional history structure. While optional in the sense that it can be left empty, it must be present in the.hdr file to that the header file is 348 bytes long, always. 6 of 24

7 There are 6 allowed values for the ORIENT field: 0 transverse (default) 1 coronal 2 sagittal 3 transverse, flipped 4 coronal, flipped 5 sagittal, flipped the flipped orientations flip one of the axes directions and are used by the Analyze software movie application. Their appearance should be rare and while supported, they should probably not be used for new data. The only reason to use anything other than the default ordering would be to create data files compatible with some pre-existing software. It is important to recall that the ORIENT field specifies how to properly read the.img file, once read by IDLffAnalyze it will be converted to use the ordering in the previous section. Therefore, taking the same data set and writing it out to separate files in differing orientation will still result in the same data set being read back in through IDLffAnalyze. 6 The HEADER structure The HEADER structure holds all the information found in a.hdr file. It's IDL definition is: ; ; Analyze 7.5 header structure - incorporates the ; header_key, image_dimension, and data_history structures. ; void = {header, $ ; struct header_key { sizeof_hdr : 348, $ ; int sizeof_hdr; data_type : bytarr(10), $ ; char data_type[10]; db_name : bytarr(18), $ ; char db_name[18]; extents : 16384, $ ; int extents; session_error : 0s, $ ; short int session_error; regular : byte('r'), $ ; char regular; hkey_un0 : 0b, $ ; char hkey_un0; } $ ; $ ; Analyze 7.5 image_dimension structure: $ ; ; struct image_dimension { dim : fix(intarr(8),type=2), $ ; short int dim[8]; vox_units : bytarr(4), $ ; char vox_units[4]; cal_units : bytarr(8), $ ; char cal_units[4]; unused1 : 0s, $ ; short int unused1; datatype : 0s, $ ; short int datatype; bitpix : 0s, $ ; short int bitpix; dim_un0 : 0s, $ ; short int dim_un0; pixdim : fltarr(8), $ ; float pixdim[8]; vox_offset: FLOAT(0.0), $ ; float vox_offset; roi_scale : FLOAT(0.0), $ ; float roi_scale; funused1 : FLOAT(0.0), $ ; float funused1; // scalefactor in SPM funused2 : FLOAT(0.0), $ ; float funused2; // dcoff in SPM2 cal_max : FLOAT(0.0), $ ; float cal_max; cal_min : FLOAT(0.0), $ ; float cal_min; compressed: 0, $ ; int compressed; verified : 0, $ ; int verified; glmax : 0, $ ; int glmax; 7 of 24

8 glmin : 0, $ ; int glmin; } $ ; $ ; Analyze 7.5 data_history structure: $ ; ; struct data_history { descrip : bytarr(80), $ ; char descrip[80]; aux_file : bytarr(24), $ ; char aux_file[24]; orient : 0b, $ ; char orient; originator : bytarr(10), $ ; char originator[10]; // image_origin, SPM generated : bytarr(10), $ ; char generated[10]; scannum : bytarr(10), $ ; char scannum[10]; patient_id : bytarr(10), $ ; char patient_id[10]; exp_date : bytarr(10), $ ; char exp_date[10]; exp_time : bytarr(10), $ ; char exp_time[10]; hist_un0 : bytarr(3), $ ; char hist_un0[3]; views : 0, $ ; int views; vols_added : 0, $ ; int vols_added; start_field: 0, $ ; int start_field; field_skip : 0, $ ; int field_skip; omax : 0, $ ; int omax; omin : 0, $ ; int omin; smax : 0, $ ; int smax; smin : 0 $ ; int smin; } ; } This structure is stored in the IDLffAnalyze object and written to a.hdr file on output. It can be updated through various methods below. This single structure contains the three structures referred to in the ANALYZE 7.5 standard. The length is 348 bytes and no deviation in length from the standard is tolerated. 7 Method Reference A detailed description of each public method is given below along with valid syntax. For the syntax the following are true: Required values are in bold Optional values are in italics Keywords are in CAPS (bold if required) The method name is underlined Each method is described along with all appropriate syntax. 7.1 Class Initialization Syntax obj = obj_new('idlffanalyze' [, f][, DATA=d, ORIENTATION=orient]) Parameters: 8 of 24

9 f A string giving the name of the existing header file (.hdr extension requried) to load into the new object. DATA ORIENTATION An array of data used to fill in the new object. Must be of an IDL type that has an ANALYZE analogue. Two, three, or four dimensions. An integer, 0..5, or a string, 'TRS', 'COR', 'SAG' or with a '-' in front for flipped. Specifies an orientation to assume about the.img file regardless of what is in the header orient field. Return value: Returns a new IDLffAnalyze object Description This is the IDLffAnalyze class constructor. It builds a new IDLffAnalyze object and optionally reads an existing data file from disk (.hdr/.img pair in same directory) or fills in the new object with data from an IDL array. If DATA is specified any argument is ignored. DATA sets the pixel data and a minimum set of header fields to their proper values for the type of data given. Allowed IDL types are 2, 3, and 4 dimensional arrays of byte, integer, longs, floats, doubles, and single-precision complex. If set, the ORIENTATION keyword specifies an orientation to use regardless of any given in the header file. 7.2 GetProperty Syntax obj->getproperty,[all=all, DIM=dim, GLMIN=glmin, GLMAX=glmax, PIXDIM=pixdim, VOX_UNITS=vox_units, CAL_UNITS=cal_units, DATATYPE=datatype, BITPIX=bitpix, VOX_OFFSET=vox_offset, CAL_MIN=cal_min, CAL_MAX=cal_max, ORIENT=orient, SCALEFACTOR=scalefactor, IMAGE_ORIGIN=image_origin, ENDIAN=endian, DCOFF=dcoff] Parameters: None. 9 of 24

10 ALL The header structure containing all fields. DIM Dimension array (8 elements), dim[1:4] are pertinent, dim[0] = 4. GLMIN The global minimum for the entire file (all volumes). GLMAX The global maximum for the entire file. PIXDIM Pixel dimension array (physical dims). Mirrors dim above. VOX_UNITS A string giving the voxel units, if any. CAL_UNITS A string giving the calibration units, if any. DATATYPE ANALYZE datatype (not IDL). BITPIX Number of bits per pixel. VOX_OFFSET Byte offset into.img file for start of image data. Usually 0. CAL_MIN CAL_MAX ORIENT SCALEFACTOR IMAGE_ORIGIN ENDIAN DCOFF Minimum calibration level. Maximum calibration level. Integer, 0..5, describing the orientation of the data in the.img file. SPM99 and SPM2 scale factor. NOT AUTOMATICALLY APPLIED. SPM99 and SPM2 image origin, 3-element vector of short ints. Overwrites the ORIGINATOR field (10 element vector of bytes). 1 if data is big-endian, 0 if data is little-endian. SPM2 DC offset. Return value: None Description Use GetProperty to return the current value of IDLffAnalyze properties. The current value of the given properties is assigned to the input variable. 10 of 24

11 7.3 SetProperty Syntax obj->setproperty, [ALL=all, DIM=dim, GLMIN=glmin, GLMAX=glmax, PIXDIM=pixdim, VOX_UNITS=vox_units, CAL_UNITS=cal_units, DATATYPE=datatype, BITPIX=bitpix, VOX_OFFSET=vox_offset, CAL_MIN=cal_min, CAL_MAX=cal_max, ORIENT=orient, SCALEFACTOR=scalefactor, IMAGE_ORIGIN=image_origin, ENDIAN=endian, DCOFF=dcoff] Parameters: None. ALL The header structure containing all fields. DIM Dimension array (8 elements), dim[1:4] are pertinent, dim[0] = 4. GLMIN The global minimum for the entire file (all volumes). GLMAX The global maximum for the entire file. PIXDIM Pixel dimension array (physical dims). Mirrors dim above. VOX_UNITS A string giving the voxel units, if any. CAL_UNITS A string giving the calibration units, if any. DATATYPE ANALYZE datatype (not IDL). BITPIX Number of bits per pixel. VOX_OFFSET Byte offset into.img file for start of image data. Usually 0. CAL_MIN CAL_MAX ORIENT SCALEFACTOR IMAGE_ORIGIN ENDIAN DCOFF Minimum calibration level. Maximum calibration level. Integer, 0..5, describing the orientation of the data in the.img file. SPM99 and SPM2 scale factor. NOT AUTOMATICALLY APPLIED. SPM99 and SPM2 image origin, 3-element vector of short ints. Overwrites the ORIGINATOR field (10 element vector of bytes). 1 if data is big-endian, 0 if data is little-endian. SPM2 DC offset. Return value: None. 11 of 24

12 7.3.2 Description Use SetProperty to set the new value of IDLffAnalyze properties. 7.4 GetNCols Syntax ans = obj->getncols() Parameters: None. None. Return value: The number of columns in a row of data (value of dim[1] field) Description Use GetNCols to get the number of columns in a row of pixel data (dim[1] value). 7.5 GetNRows Syntax ans = obj->getnrows() Parameters: None. None. Return value: The number of rows in a slice of data (value of dim[2] field) Description Use GetNRows to get the number of rows in a slice of pixel data (dim[2] value). 12 of 24

13 7.6 GetNSlices Syntax ans = obj->getnslices() Parameters: None. None. Return value: The number of slices in a volume of data (value of dim[3] field) Description Use GetNSlices to get the number of slices in a volume of pixel data (dim[3] value). 7.7 GetNVolumes Syntax ans = obj->getnvolumes() Parameters: None. None. Return value: The number of volumes in the data set (value of dim[4] field) Description Use GetNVolumes to get the number of volumes in the data set (dim[4] value). 13 of 24

14 7.8 GetOrientation Syntax ans = obj->getorientation([/text]) Parameters: None. TEXT Return the orientation as a text string. A leading '-' implies flipped (3..5) Return value: The orientation as an integer or a string Description Use GetOrientation to see the orientation that will be used when the data is written to disk. The possible values are: Value String Meaning 0 TRS Transverse, default 1 COR Coronal 2 SAG Sagittal 3 -TRS Transverse, flipped 4 -COR Coronal, flipped 5 -SAG Sagittal, flipped 14 of 24

15 7.9 GetVoxelDims Syntax obj->getvoxeldims, [VOXEL_WIDTH=w, VOXEL_HEIGHT=h, SLICE_THICKNESS=s, TIME_POINTS=t] Parameters: None. VOXEL_WIDTH The voxel width from the header (pixdim[1] value) VOXEL_HEIGHT The voxel height from the header (pixdim[2] value) SLICE_THICKNESS The slice thickness from the header (pixdim[3] value) TIME_POINTS The interval or time of the volume (pixdim[4] value) Return value: None Description Use GetVoxelDims to retrieve the physical voxel dimensions. By convention, VOXEL_WIDTH, VOXEL_HEIGHT, and SLICE_THICKNESS are in mm and TIME_POINTS is in msec. These values are not required and some applications will not make use of them nor given them meaningful values SetVoxelDims Syntax obj->setvoxeldims, [VOXEL_WIDTH=w, VOXEL_HEIGHT=h, SLICE_THICKNESS=s, TIME_POINTS=t] Parameters: None. VOXEL_WIDTH The voxel width from the header (pixdim[1] value) 15 of 24

16 VOXEL_HEIGHT The voxel height from the header (pixdim[2] value) SLICE_THICKNESS The slice thickness from the header (pixdim[3] value) TIME_POINTS The interval or time of the volume (pixdim[4] value) Return value: None Description Use SetVoxelDims to assign the physical voxel dimensions. By convention, VOXEL_WIDTH, VOXEL_HEIGHT, and SLICE_THICKNESS are in mm and TIME_POINTS is in msec. These values are not required and some applications will not make use of them nor given them meaningful values SetBitPix Syntax obj->setbitpix, bitpix Parameters: bitpix The number of bits per pixel in the data (1,8,16,32, or 64). None. Return value: None Description SetBitPix sets the number of bits per pixel field in the header. This must be one of the values listed above or an error will occur. 16 of 24

17 7.12 SetOrientation Syntax obj->setorientation, orient Parameters: orient An integer, 0..5, or 'TRS', 'COR', or 'SAG' with optional '-' to indicate flipped version. None. Return value: None Description SetOrientation sets orientation that will be used when writing the data to disk. It may be an integer, 0..5, or a string with a leading '-' to indicate the flipped version QueryPixelData Syntax ans = obj->querypixeldata() Parameters: None. None. Return value: True (1) if there is pixel data, false (0) otherwise Description Use QueryPixelData to check if there is assigned pixel data. An IDLffAnalyze object created without data or a file name will return a 0 (false). 17 of 24

18 7.14 GetPixelData Syntax ans = obj->getpixeldata([pointer=p]) Parameters: None. POINTER If set, the returned value is a pointer to the pixel data, not a copy of it. This has its associated hazzards but is useful when the data set is large. Return value: A copy of the image data or a pointer to it Description Use GetPixelData to access all the image pixel data. If POINTER is not set, return a copy of the image data in its entirety. If POINTER is set, return a pointer to the image data in memory GetVolume Syntax ans = obj->getvolume(v) Parameters: v The volume number to return, indexed from zero. None. Return value: A copy of the image data for a specific volume Description GetVolume to return a copy of the image data for a specific volume. 18 of 24

19 7.16 GetImage Syntax ans = obj->getimage(i [,v] [,AXIAL=axial, TRANSVERSE=transverse, TRS=trs, CORONAL=cor, SAGITTAL=sag]) Parameters: i v The image number, indexed from zero. The volume number, indexed from zero. Defaults to zero if not given. AXIAL TRANSVERSE TRS CORONAL SAGITTAL Return an axial image, the default. Synonym for AXIAL Synonym for AXIAL Return a coronal image Return a sagittal image Return value: A copy of the pixel data for the specified image Description GetImage allows access to the pixel data of a specific image from a specific volume. The keywords allow a desired orientation to be selected, the default is axial SetPixelData Syntax obj->setpixeldata, d [, NO_COPY=no_copy] Parameters: 19 of 24

20 d The image data to assign to the IDLffAnalyze object. NO_COPY If set pass /NO_COPY when allocating new memory for the input data. Useful to prevent copying of large arrays. Return value: None Description SetPixelData assigns new image data to the IDLffAnalyze object. Any existing data and associated header information is destroyed. A new minimal header is defined based on the dimensions and data type of the input array. The input array must be of 2, 3, or 4 dimensions SetVolume Syntax obj->setpixeldata, v, vol Parameters: v vol The volume number to update, indexed from zero. The new volume data. None. Return value: None Description SetVolume assigns new volume to the IDLffAnalyze object. The new volume replaces the data for an existing volume (ie, cannot extend the dataset) and must be of the same dimensions and data type. 20 of 24

21 7.19 SetImage Syntax obj->setimage, i, v, img, [,AXIAL=axial, TRANSVERSE=transverse, TRS=trs, CORONAL=cor, SAGITTAL=sag]) Parameters: i v img The image number, indexed from zero. The volume number, indexed from zero. The new image data. AXIAL TRANSVERSE TRS CORONAL SAGITTAL Return an axial image, the default. Synonym for AXIAL Synonym for AXIAL Return a coronal image Return a sagittal image Return value: None Description SetImage updates an existing image in a particular volume. If not given, the image is assumed to be axial, otherwise it is coronal or sagittal according to the keywords given. The input image, img, must match the data type and dimensions of the image that it is replacing. 21 of 24

22 7.20 ReadHeaderFile Syntax ans = obj->readheaderfile(f [,ENDIAN=endian]) Parameters: f Pathname to the.hdr file to read. ENDIAN If set to a named variable the byte order of the header file will be returned, 1 for big-endian, 0 for little-endian Return value: A HEADER structure containing the file's information Description ReadHeaderFile returns a new HEADER structure containing the information read from a given header file. This does not affect any existing information in the IDLffAnalyze object. The returned header is swapped to the byte order of the system if necessary. ENDIAN will return the byte order used by the file itself (and, consequently, the associated.img file) ReadFile Syntax obj->readfile, [f] [,ORIENTATION=orient, _EXTRA=extra]) Parameters: f Pathname to the.hdr file to read. If not given an open file dialog is used. ORIENTATION If set to a named variable the byte order of the header file will be returned, 1 for big-endian, 0 for little-endian 22 of 24

23 _EXTRA Extra keywords passed to dialog_pickfile if no filename given. Eg, DIALOG_PARENT for an application. Return value: None Description ReadFile reads the data stored in a.hdr/.img pair into the IDLffAnalyze object. Any existing data is destroyed. If given, f, is a pathname to a.hdr file, if not given an open file dialog is issued. No error is given if the user cancels the dialog box, and existing data is not removed. The ORIENTATION keyword can be set to read the data in a given ANALYZE orientation overriding the orientation given in the.hdr file. The value assigned may be an integer, 0..5, or a string, 'TRS', 'COR', 'SAG' with a leading '-' if necessary to indicated flipped axes (ANALYZE orient types 3..5) WriteFile Syntax obj->writefile, [f] [,MULTIPLE_FILES=mult, _EXTRA=extra]) Parameters: f Base name for the output file, no extension. Ie, 'data' will generate 'data.hdr' and 'data.img'. If not given a save file dialog is used. MULTIPLE_FILES _EXTRA If set the data is output as a series of axial images regardless of any setting in the header. Extra keywords passed to dialog_pickfile if no filename given. Eg, DIALOG_PARENT for an application. Return value: None. 23 of 24

24 Description WriteFile writes the image data to disk. If no filename is given a save file dialog is used. If given, f, must be a base name, ie, without extension. The data is then written to disk, the header in the.hdr file, and the image data in the.img file according to the orientation in the header file. If MULTIPLE_FILES is set the data is output as a series of axial images regardless of any orientation setting in the header. The files follow this naming convention: if the base name is 'img' and there is one volume only the files are named 'img000n.hdr/img000n.img' where n counts the image number. If there is more than one volume the files are named 'img0v_000n.hdr' where n is the image number of volume v. 24 of 24