The basic functions are used to open and close DICOM files and to read elements from them. The DICOM files are automatically uncompressed when needed. The basic routines keep track of encapsulated data and the hierarchy of sequences. Endian conversion is performed whenever neccesary, and value multiplicities are calculated. Characters strings are always null terminated and split up into multiple values.
The following DICOM value representations are handled by the basic functions:
Elements are obtained using dicom_element(). An element contains the following items:
Use this function to open a DICOM file. It returns 0 on success. dicom_open() checks the endian type of your processor. It also checks for a DICOM metaheader. If no metaheader is found, dicom_open() tries to guess the used transfer syntax.
If the filename ends with ".Z" or ".gz" decompression is tried using "gzip -cd". If you want to enable this feature, make sure that "gzip" is in your $PATH.
The decompression uses a temporary file. See the manual page on "tmpnam" to control the location and the name of the tempory file.
This function reads an element from a previous opened DICOM file. It returns 0L (NULL) on failure. The returned ELEMENT struct is changed when dicom_element is called again.
The data and vm items of the returned ELEMENT struct are not filled in. On basis of the other items, you can deceide if you want to skip (dicom_skip()) or load (dicom_load()) the element.
With implicit transfer syntaxes, the VR will be set to UN or SQ.
Libdicom needs to recongnize SQ tags, so there is only a small
dictionary with DICOM and Papyrus SQ tags.
int dicom_skip(void)
Use this function to skip the last element.
Use this function to read the last element. You have to supply the VR if the transfer syntax is implicit. You do know what you want to read, don't you? If the transfer syntax is explicit, any giver VR is discarted and the VR from the DICOM file is used.
Once the VR is known, endian corrections are made to the data. The value multiplicity is calculated. If the element.vr is a character string, data is of type char**, so you can read multiple values. all character strings are null-terminated.
The user is supposed to free the data himself.
The function closes an open dicom file. it is not neccesary to use this use this only when not all object are read, thus dicom_object still not returning 0L. dicom_transfer syntax is only filled in when read 0002 0010 and before dicom_close. (or dicom_object ==0L or dicom_skip==-1 or dicom_load==-1) dicom_version is a staticly allocated version string.
This function can generate the following messages:
typedef enum { AE=('A'<<8)|'E', AS=('A'<<8)|'S', AT=('A'<<8)|'T', CS=('C'<<8)|'S', DA=('D'<<8)|'A', DS=('D'<<8)|'S', DT=('D'<<8)|'T', FL=('F'<<8)|'L', FD=('F'<<8)|'D', IS=('I'<<8)|'S', LO=('L'<<8)|'O', LT=('L'<<8)|'T', OB=('O'<<8)|'B', OW=('O'<<8)|'W', PN=('P'<<8)|'N', SH=('S'<<8)|'H', SL=('S'<<8)|'L', SQ=('S'<<8)|'Q', SS=('S'<<8)|'S', ST=('S'<<8)|'T', TM=('T'<<8)|'M', UI=('U'<<8)|'I', UL=('U'<<8)|'L', US=('U'<<8)|'S', UN=('U'<<8)|'N' } VR; typedef struct { u_short group,element; VR vr; u_long length; int encapsulated; u_char sequence; void *data; long vm; } ELEMENT; extern char dicom_version[],**dicom_transfer_syntax; int dicom_open(const char *); ELEMENT *dicom_element(void); int dicom_skip(void); int dicom_read(VR); void dicom_close(void);