Open topic with navigation

IDLffDicomEx::Init

The IDLffDicomEx::Init method initializes a IDLffDicomEx object. The IDLffDicomEx object allows you to read and write DICOM files, or create a new DICOM file based on keyword settings. This method can be used to create any type of DICOM file, including files without image data as defined by the SOP Class. See Creating a New DICOM File for more information. The original DICOM file is always preserved. To change the attributes of a DICOM file, you must either clone the original file or create a new file. See the following sections for details on using keywords to control how a file can be modified:

• Accessing a DICOM File in Read-Only Mode
• Cloning a DICOM File
• Creating a New DICOM File
• Accessing an Incomplete DICOM File

Note: If you don’t need pixel data, you can set the IDLffDicomEx property when creating an IDLffDicomEx object. This offers a significant performance improvement and should be used when you only need access to attribute information. To initialize the value of a property, specify the property name as a keyword set equal to the appropriate property value.

Note: Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: if you write your own subclass of this class, you can call the Init method from within the Init method of the subclass.

Accessing a DICOM File in Read-Only Mode

To open an existing DICOM file in read-only mode, create a new IDLffDicomEx object and specify only a value for the Filename argument, indicating the file to open. You can access all of the DICOM file attributes, but any attempt to write changes to the file using the IDLffDicomEx::Commit method will fail. The following code opens a selected DICOM file in read-only mode:

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

• Set the Filename argument to specify the path and name of the new file
• Set CLONE to the name of the existing DICOM file to be cloned

Init will fail if the file defined by Filename already exists.

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)

; Write the file into the temp directory and then

; create a clone (aImgClone.dcm) of the selected file (sfile).

clonefile = GETENV('IDL_TMPDIR')+PATH_SEP()+'aImgClone.dcm'

oImg = OBJ_NEW('IDLffDicomEx', clonefile, 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.

Note: It may also be necessary to modify the Series Instance UID (0020,000E) when cloning a file so that when the cloned file is pushed to a PACS workstation it stored in a new series.

Creating a New DICOM File

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

• Set the Filename argument to specify the path and name of the new file
• Set the SOP_CLASS keyword to an appropriate value to indicate the type of DICOM file to create
• Set CREATE keyword to indicate this is a new DICOM file

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.

Note: A new instance UID (0002,0003) is created for the recovered file since the IDLffDicomEx object never modifies the original input 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.

Note: Use files with odd-length sections with extreme caution. Files with an odd number of bytes are not valid DICOM files.

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:

• If no keywords are set, FileName indicates the existing DICOM file to open in read-only mode. Any attempt to commit changes to this file (using the IDLffDicomEx::Commit method) will fail. An error is issued if the specified file does not exist.
• If the CLONE keyword is set, FileName specifies the name of the new, cloned file. This file will contain a copy of the file specified by the CLONE keyword. An error is issued if the value specified for FileName already exists.
• If the CREATE keyword is set, FileName specifies the name of the new DICOM file to be created. An error is issued if the value specified for FileName already exists.

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

Examples

The following examples show various ways of initializing an IDLffDicomEx object.

Open a DICOM File in Read-only Mode

The following opens a file in read-only mode:

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

See the IDLffDicomEx::EnumerateTags method “Examples” section for a complete example.

Open and Clone a DICOM File

The following clones the selected file:

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

See Cloning a DICOM File for details on what DICOM attributes are modified. See the IDLffDicomEx::GetPixelData method “Examples” section for a complete example.

Create a New DICOM File

The following code creates a new file of modality 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 )

See Creating a New DICOM File for details on what DICOM attributes are automatically defined when you create a new file. See the IDLffDicomEx::SetPixelData method “Examples” section for a complete example that creates new monochrome and RGB images.

Version History