; Select a DICOM file to examine.   
sFile = DIALOG_PICKFILE( $  
    PATH=FILEPATH('',SUBDIRECTORY=['examples','data']), $  
    TITLE='Select DICOM Patient File', FILTER='*.dcm')  
  
; Open the selected file in read-only mode.  
 oImg = OBJ_NEW('IDLffDicomEx', sfile)  

Cloning a DICOM File

To modify an existing DICOM file, you must clone the file by setting the following keywords and arguments:

The following clones the selected file:

; Select a DICOM file to clone.  
sFile = DIALOG_PICKFILE( $  
    PATH=FILEPATH('',SUBDIRECTORY=['examples','data']), $  
    TITLE='Select DICOM Patient File', FILTER='*.dcm', $  
    GET_PATH=path)  
  
; Create a clone (aImgClone.dcm) of the selected file (sfile).  
 oImg = OBJ_NEW('IDLffDicomEx', path+'\'+'aImgClone.dcm', $  
    CLONE=sfile)  

When you clone a file, attributes shown in the following table are modified. Unless the internally-generated values equal the number of characters in the original tags, the value of the metadata Group Length tag (0002,0000) is also updated. All other DICOM attribute values are identical to the original attributes.

Note These attributes are written to the cloned DICOM file when you call the IDLffDicomEx::Commit method.

The resulting cloned file will allow you to modify any attributes that belong to the specified SOP Class for the cloned file. If the NON_CONFORMING keyword is set, then you can set any attribute regardless of the SOP Class of the cloned file.

Creating a New DICOM File

To create a new DICOM file, you must set the following:

The following code creates a new file with a SOP Class of standard Magnetic Resonance (MR):

; Create a new image named aMRImg.dcm in the current  
; working directory.   
oImage = OBJ_NEW('IDLffDicomEx', 'aMRImg.dcm', $  
   SOP_CLASS = 'STANDARD_MR', /CREATE, /NON_CONFORMING )  

When a new file is created, all defined tags for the chosen SOP Class are present, but do not have a value. You must use IDLffDicomEx::SetValue or IDLffDicomEx::SetProperty to set valid values prior to calling the GetValue or GetProperty methods. These methods will return an error if you attempt to return information for an attribute that does not have a value. Any attribute that you have not set a value for will not be persisted in the file when you call Commit. Use SetValue to configure the attributes required to create a valid DICOM file for the chosen SOP class. (Complete details can be found in Digital Imaging and Communications in Medicine (DICOM) - Part 3: Information Object Definitions.) To set attributes that are not defined for the SOP class, set the NON_CONFORMING keyword. Creating a new file sets values for the following attributes:

Note These attributes are written to the new DICOM file when you call the IDLffDicomEx::Commit method.

When creating a new DICOM file it is also a good idea to set the following tags. These tags are commonly needed when transmitting a file over a DICOM network.

The file is written when the IDLffDicomEx::Commit method is called. Attempting to overwrite a file with an existing file name will fail.

Creating New Files That Use Alternative Character Sets

Several Value Representations accept ESC characters from alternative character sets. In such instances, the text will be interpreted as specified by Specific Character Set attribute (0008,0005). For example, if you are setting Japanese escape characters to an attribute value in a new file, you first need to specify your character sets as in the following code:

; Given a IDLffDicomEx object named oDCM:  
val = STRARR(2)  
val[0] = 'ISO 2022 IR 87'  
val[1] = 'ISO 2022 IR 13'   
oDCM->SetValue, '0008,0005', 'CS', val  

See Annex H of Digital Imaging and Communications in Medicine (DICOM) - Part 5: Data Structures and Encoding) for more information on Japanese character sets.

Accessing an Incomplete DICOM File

A file that conforms to the DICOM Part 10 standard consists of a preamble, metadata, and a body section. Each section contains an even number of bytes. Not all files have all three sections; some files may be missing the preamble, or the preamble and metadata. Not all files contain an even number of bytes in each section. Files that do not conform to the DICOM Part 10 standard are considered invalid, but it is possible to access the data in these files using the IDLffDicomEx object as described in the following sections.

Files With a Missing Preamble

The IDLffDicomEx object will attempt to read the transfer syntax from the (0002, 0010) tag and open a file with a missing preamble. The following table shows each file type that can be opened when the preamble section is missing.

Files With Missing Preamble and Metadata Sections

The IDLffDicomEx object will attempt to read a file that is missing the preamble and metadata by determining the transfer syntax from the byte ordering and VR type of the first tag in the file. A file containing JPEG pixel data cannot be opened as it is impossible to determine the compression format of the pixel data when the metadata tags are not in the file. The following table shows each file type that can be opened when missing preamble and metadata sections.

The IDLffDicomEx object will add metadata tags to the file so that the file can be successfully saved as a part 10 DICOM file using the IDLffDicomEx::Commit method. The following tags will be written in the metadata section of the recovered file.

Files With an Odd Number of Bytes

A file that conforms to the DICOM Part 10 standard always includes an even number of bytes in each section. If the IDLffDicomEX object encounters a file with a section that consists of an odd number of bytes, IDL will append a zero at the end of the last block of data read and issue a warning message noting that the section contained an odd number of bytes.

Syntax

Obj = OBJ_NEW('IDLffDicomEx' (Filename, [, CLONE=string] [, /CREATE] [, SOP_CLASS=string] [, /NON_CONFORMING] )

or

Result = Obj->[IDLffDicomEx::]Init( Filename [, CLONE=string] [, /CREATE] [, SOP_CLASS=string] [, /NON_CONFORMING] ) (In a lifecycle method only.)

Return Value

When this method is called indirectly, as part of the call to the OBJ_NEW function, the return value is an object reference to the newly-created object.

When called directly within a subclass Init method, the return value is 1 if initialization was successful, or 0 otherwise.

Arguments

FileName

Set this keyword to a string indicating the filename of a DICOM file. This can either be an absolute path (`C:\my_dcm_file.dcm'), or simply a filename (`my_dcm_file.dcm'). When only a filename is provided, the file is located in the IDL working directory. The exact meaning of the FileName argument depends on what keywords are set as follows:

Keywords

CLONE

Set this keyword to a string specifying path and name of the existing DICOM file to be cloned. Define the name of the new, cloned file using the FileName argument. See Cloning a DICOM File for details.

CREATE

Set this keyword to create a new DICOM image with a name specified by the FileName argument. See Creating a New DICOM File for details. You must also set the SOP_CLASS keyword when creating a new image.

SOP_CLASS

This keyword is set when creating a new DICOM file using the CREATE keyword.

Set this keyword to a string consisting of a value from the SOP Class Name column in the following table to define the type of DICOM file that is created.

NON_CONFORMING

This keyword is set only when the CLONE or CREATE keyword is also set.

Set this keyword to be able to add any DICOM attribute to a DICOM file regardless of whether or not the attribute is supported by the SOP Class (as defined in Digital Imaging and Communications in Medicine (DICOM) - Part 3: Information Object Definitions).

If this keyword is not set, attempting to use IDLffDicomEx::SetValue to set non-standard attributes will result in an invalid tag error similar to the following:

IDLFFDICOMEX::SETVALUE:  Error: Failed to set value (tag/err), 
0018,603F, Tag parameter invalid  

; Select a DICOM file to examine.   
sFile = DIALOG_PICKFILE( $  
    PATH=FILEPATH('',SUBDIRECTORY=['examples','data']), $  
    TITLE='Select DICOM Patient File', FILTER='*.dcm')  
  
; Open the selected file in read-only mode.  
oImg = OBJ_NEW('IDLffDicomEx', sfile)  

; Select a DICOM file.  
sFile = DIALOG_PICKFILE( $  
    PATH=FILEPATH('',SUBDIRECTORY=['examples','data']), $  
    TITLE='Select DICOM Patient File', FILTER='*.dcm', $  
    GET_PATH=path)  
  
; Create a clone (aImgClone.dcm) of the selected file (sfile).  
oImg = OBJ_NEW('IDLffDicomEx', path + 'aImgClone.dcm', $  
    CLONE=sfile)  

; Create a new image named aMRImg.dcm in the current  
; working directory.   
oImage = OBJ_NEW('IDLffDicomEx', 'aMRImg.dcm', $  
   SOP_CLASS = 'STANDARD_MR', /CREATE, /NON_CONFORMING )