Basic Functions

Out of date!!!

Introduction

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.

Value Representation (VR)

The following DICOM value representations are handled by the basic functions:

AE
Application Entity
AS
Age String
AT
Attribute Tag
CS
Code String
DA
Date
DS
Decimal String
DT
Date Time
FL
Floating Point Single
FD
Floating Point Double
IS
Integer String
LO
Long String
LT
Long Text
OB
Other Byte String
OW
Other Word String
PN
Person Name
SH
Short String
SL
Signed Long
SQ
Sequence of Items
SS
Signed Short
ST
Short Text
TM
Time
UI
Unique Identifier
UL
Unsigned Long
US
Unsigned Short
UN
Unknown VR
These definitions are explained in Part 5 of the DICOM standard.

Elements

Elements are obtained using dicom_element(). An element contains the following items:

u_short group
The group number. See DICOM Part 6 for a list of standard groups.
u_short element
The element number. See DICOM Part 6 for a list of standard elements.
VR vr
The Value Representation (VR) of the element. See the previous section for a list of standard VR's. UN means an unknown, or unset VR.
u_long length
The length of the element data. The value 0xFFFFFFFF means "undefined length". You can safely skip an element with undefined length. The following elements will contain the actual data.
int encapsulated
A flag to indicated if the element is encapsulated.
u_char sequence
The hierarchical sequence level of the element. In the top level, sequence is 0.
void *data
A pointer to the element data. It is only set after a dicom_read(). If vr is a character string, data must be interpreted as char**, so that data[i] is the ith string value. All returned character strings are null terminated for easy string handling.
long vm
The Value Multiplicity (VM) of the element. It is only set after a dicom_read(). For example, you could define a "staff" element of VR Person Name (PN) and assign multiple names to it.

Basic Functions

int dicom_open(const char *)

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.

ELEMENT *dicom_element(void)

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.

int dicom_read(VR)

!!!!!!!!!!! OW convertion image data !!!!!!!!!!

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.

void dicom_close(void)

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:

Prototypes from dicom.h

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);