# Contents

- read_dicom_files
- read_DCMLIST

# read_dicom_files

### Synopsis

> Reads a series of implicite DICOM files and outputs a uniform AVS field reconstructing a volume of data. Further information from the DICOM files is placed the DICOM_Header object.

>       module ReadDicomFile
>       {
>          string+read+notify+req filenames[];
>          int+read flip;
>          int+write+nonotify busy = 0;
>          int+write+nonotify done = 0;
>          IAC_PROJ.ReadDICOM.ReadDICOMData.DICOM_Header+write+nonotify header;
>          IAC_PROJ.ReadDICOM.ReadDICOMData.DICOM_Volume+write+nonotify volume;
>          omethod+req dicom_update = "Read_Dicom_File";
>       };

### Description

> This read_dicom_files module reads a set of DICOM V3 files and outputs a uniform field. Further information from the DICOM files is placed the DICOM_Header object.

> Please note that the original ReadDICOM actually read Papyrus files which is a set of DICOM images wrapped up into a single file. That project is now called ReadPapyrus

> The uniform field is output as a DICOM_Volume object. This object is derived from the Field_Unif module and and can hence be used in the exactly the same way. It can be directly connected to all the standard visualization modules. The information in the image header is output as an DICOM_Header object. This object simply contains references to 4 further objects which actually contain the primitive data values. See below for further information. The extents of the volume (ie points array) are set to the physical dimensions of the volume include the correct slice spacing.

> The read_dicom_files module uses the Papyrus 3.71 toolkit to read DICOM files. This toolkit was developed by the Digital Imaging Unit of the University Hospital of Geneva. More information can be found at the the Papyrus website. The Papyrus toolkit is completely integrated in this Project.

### Input

> filenames

> This is an array of filenames of the DICOM files that make up the volume. They will be read in the order specified (unless flip is set) hence the first image will be placed at z = 0, the next at z = 1 etc. .

> flip

> By default images are read into the volume starting from the bottom. If you wish to reverse the order of the images set this value to 1 before reading the data. An integer.

### Outputs

> busy

> This parameter indicates whether the read_dicom_files module is currently busy processing data. The parameter is of type int. The parameter is set as appropriate by the ReadDicomFile module. It can be used by the user interface to indicate the current state of the module.

> volume

> This object contains the stacked image data contained within the DICOM files. The object is of type DICOM_Volume. This object is derived from Field_Unif and can be used in the exactly the same way as a standard uniform field. The DICOM_Volume object sets the number of dimensions so that only 3D data can be stored in the object. This will not effect how the object can be used.

> header

> This object contains the header information contained within the DICOM file. The object is of type DICOM_Header. This object contains references to 5 further objects. These objects actually contain the information read from the DICOM file. Each of these sub-objects corresponds to the appropriate DICOM module. These modules are patient, generalStudy, generalSeries, generalEquipment & imageSeries and contain the information shown below.

- Patient

- PatientsNameP
- PatientIDP
- PatientsBirthDateP
- PatientsBirthTimeP
- PatientsSexP
- ReferencedPatientSequenceP
- OtherPatientID
- OtherPatientNamesP
- EthnicGroupP
- PatientCommentsP

- General_Study

- StudyInstanceUIDGS
- StudyDateGS
- StudyTimeGS
- ReferringPhysiciansNameGS
- StudyIDGS
- AccessionNumberGS
- StudyDescriptionGS
- NameofPhysiciansReadingStudyGS
- ReferencedStudySequenceGS

- General_Series

- ModalityGS
- SeriesInstanceUIDGS
- SeriesNumberGS
- Laterality
- SeriesDate
- SeriesTime
- PerformingPhysiciansNameGS
- ProtocolName
- SeriesDescription
- OperatorsName
- ReferencedStudyComponentSequenceGS
- BodyPartExaminedGS
- PatientPosition
- SmallestPixelValueinSeries
- LargestPixelValueinSeries

- General_Equipment

- ManufacturerGE
- InstitutionNameGE
- InstitutionAddressGE
- StationName
- InstitutionalDepartmentName
- ManufacturersModelName
- DeviceSerialNumberGE
- SoftwareVersionsGE
- SpatialResolution
- DateofLastCalibration
- TimeofLastCalibration
- PixelPaddingValue

- Image_Series

- Interpretation
- Rows
- Columns
- Slices
- BitsAllocated
- SliceSpacing
- XSpacing
- YSpacing
- WindowCentre
- WindowWidth

> Further information on the purpose of these variables can be found in the Papyrus user manual. This can be found at the Papyrus website.

### Utility Macros

> The low-level read_dicom_files module is used in the User Macro ReadDICOM.

### Example

> Two example applications are provided. They both read in a DICOM format file. The TileDicomEg example uses the tile_volume module to visualize the data whilst the IsoVolDicomEg example uses the isovolume module. The IsoVolDicomEg also uses a downsize module to reduce the amount of data to be visualized. A sample DICOM files set ????? is provided with the distribution of this module.

### Files

> iac_proj/rd_dicom/rddimods.v contains the V definitions for read_dicom_file. iac_proj/rd_dicom/rddidat.v contains the V definitions for DICOM_Volume, DICOM_Header, Patient, General_Study, General_Series, General_Equipment and Image_Series parameter blocks.

### Other Notes

> The ReadDICOM project has substantially changed from previous versions changes are given in changes.html. This verison of read_dicom_files is design to be used in conjunction with read_DCMLIST which provides the array of filenames defining a DICOM series. The low-level ReadDICOMMods library containing the module read_dicom_files does not specify a process. By default the express process will be used.

### Authors

>     Rewrite by James S. Perrin (MVC)
>     Original code by Fernand Alcatrao

### Contact

>     International AVS Centre
>     Manchester Visualization Centre
>     Manchester Computing
>     University of Manchester
>     Oxford Road
>     Manchester
>     United Kingdom
>     M13 9PL

### See Also

> read_DCMLIST, ReadDICOM, TileDicomEg, IsoVolDicomEg, Read_ACR_NEMA (IAC module)

# read_DCMLIST

### Synopsis

> This module is a simple DICOM file manager. It scans a directory of DICOM files and determines the patient, studies and series that they belong to. The information is then written to the DCMLIST file.

>        module read_DCMLIST
>        {
>           string dirname<NEportLevels={2,1}>;
>           int rescan<NEportLevels={2,0}>;
>           int delete<NEportLevels={2,0}>;
>           int nfiles<NEportLevels={0,2}>;
>           int selected_series<NEportLevels={2,0}>;
>           string filenames<NEportLevels={0,2}>[nfiles];
>           int nseries<NEportLevels={0,2}>;
>           string series<NEportLevels={0,2}>[nseries];
>           int series_st_en<NEportLevels={0,2}>[nseries][2];
>           cxxmethod+notify_inst+req read (
>     	 dirname+read+req+notify,
>     	 rescan+read+notify,
>     	 nfiles+write,
>     	 filenames+write,
>     	 nseries+write,
>     	 series+write,
>     	 series_st_en+write
>           );
>           cxxmethod+req remove (
>     	 delete+read+req+notify,
>     	 dirname+read+req,
>     	 selected_series+read+req,
>     	 nfiles+write,
>     	 filenames+write,
>     	 nseries+write,
>     	 series+write,
>     	 series_st_en+write
>           );
>        };

### Description

> The low-level read_DCMLIST module provides a method of handling a directory of DICOM files. It parses a directory of DICOM images and groups the files by patient, study and series. A set of DICOM images, that were obtained sequentially and can be stacked to reconstruct a volume of data, form a series (they are exceptions such as calibration images). The resulting information is written to the directory in a file called DCMLIST which will be read subsequently so that the files do not need to be parsed again, unless of course files are added or removed.

> The module creates an array of strings describing each series (Patient, Study number, Study Date, Series number, Series Date, Number of images). On selecting a series the module provides the indices of the first and last filenames making up the series from and array of all the filenames. These values can be passed to the StringArraySubset module from the IAC, to extract an array of the filenames they constitute the series. Finally these filenames may be passed to the read_dicom_files module to load and reconstruct the volume.

### Input

> dirname

> A string containing the name of the directory holding the DICOM files. When this is changed the module will attempt to find the DCMLIST file. It will report an error if none is found, in which case the directory should be rescanned. Under UN*X's read_DCMLIST expects the DICOM files to appear in a single directory and the DICOM client tools tend to simply dump the files in one location. Under Windows however we used a freeware tool (to acedemia at least) called eFilm to provide the DICOM node. It stores the files in a under a given directory using the patientID and SeriesID to create a further two levels of directory hierachy. Hence dirname should be the directory containing the patient directories. If you do not use eFilm on Windows or have all you DICOM files in a single directory you can simply create three levels of directories and place the files in the bottom one e.g., `C:\my_dicom\pat\series\myfile_1.dcm` etc. and dirname is `"C:\my_dicom"`.

> rescan

> Cause the module to rescan the specified directory if set. This should be performed if new files are added or manually removed from the directory. NOTE Scanning a large number of files can take a few minutes.

> delete

> If set the selected_series will be deleted. This is disabled under Win32 as it assumed an external program (eFilm) will be used to manage the DICOM files.

> selected_series

> The index of the currently selected series. This is used whenever delete is set. It is also the index into the series_st_en.

### Outputs

> filenames

> A string array containing in order all the filenames of the DICOM files found.

> nseries

> The total number of series found.

> series

> An array of strings describing each series.

> series_st_en

> A two dimensional array containing the start and end indices for each series in the filenames array.

### Utility Macros

> The low-level read_dicom_files module is used in the user macro ReadDCMLISTUI, which is subsequently used by ReadDICOM.

### Example

> Two example applications are provided. They both read in a DICOM format file. The TileDicomEg example uses the tile_volume module to visualize the data whilst the IsoSurfaceDicomEg example uses the isosurface module. The IsoSurfaceDicomEg also uses a downsize module to reduce the amount of data to be visualized.

### Files

> iac_proj/rd_dicom/rddimods.v contains the V definitions for read_DCMLIST

### Other Notes

> read_DCMLIST is design to be used in conjunction with read_dicom_files. The low-level ReadDICOMMods library containing the module read_DCMLIST does not specify a process. By default the express process will be used.

### Authors

>     James S. Perrin (MVC)

### Contact

>     International AVS Centre
>     Manchester Visualization Centre
>     Manchester Computing
>     University of Manchester
>     Oxford Road
>     Manchester
>     United Kingdom
>     M13 9PL

### See Also

> read_dicom_files, ReadDICOM, ReadDCMLISTUI, TileDicomEg, IsoVolDicomEg, Read_ACR_NEMA (IAC module)