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:
If you don’t need pixel data, you can set the NO_PIXEL_DATA 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.
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:
sFile = DIALOG_PICKFILE( $
PATH=FILEPATH('',SUBDIRECTORY=['examples','data']), $
TITLE='Select DICOM Patient File', FILTER='*.dcm')
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
Note: Init will fail if the file defined by Filename already exists.
The following clones the selected file:
sFile = DIALOG_PICKFILE( $
PATH=FILEPATH('',SUBDIRECTORY=['examples','data']), $
TITLE='Select DICOM Patient File', FILTER='*.dcm', $
GET_PATH=path)
clonefile = GETENV('IDL_TMPDIR')+PATH_SEP()+'aImgClone.dcm'
oImg = OBJ_NEW('IDLffDicomEx', clonefile, CLONE=sfile)
oImg.commit
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.
|
DICOM Tag |
Modification |
|
(0002,0003) |
Media Storage SOP Instance UID is set to a new NV5 Geospatial Solutions-generated value.
|
|
(0002,0012) |
Implementation Class UID is set to a new NV5 Geospatial Solutions-generated value.
|
|
(0002,0013) |
Implementation Version Name is set to the NV5 Geospatial Solutions value.
|
|
(0002,0016) |
Source Application Entity Title is set to the NV5 Geospatial Solutions value.
|
|
(0008,0018) |
SOP Instance UID is set to a new NV5 Geospatial Solutions-generated value.
|
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.
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):
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:
|
DICOM Tag |
Modification |
|
(0002,0002) |
Media Storage SOP Class UID is set to the unique identifier associated with the SOP_CLASS keyword.
|
|
(0002,0003) |
Media Storage SOP Instance UID is set to a new NV5 Geospatial Solutions-generated value.
|
|
(0002,0010) |
Transfer Syntax UID is set to Explicit VR Little Endian by default. After pixel data has been set on the new image, you can use the IDLffDicomEx::ChangeTransferSyntax method to change the file compression.
|
|
(0002,0012) |
Implementation Class UID is set to a new NV5 Geospatial Solutions-generated value.
|
|
(0002,0013) |
Implementation Version Name is set to theNV5 Geospatial Solutions value.
|
|
(0002,0016) |
Source Application Entity Title is set to the NV5 Geospatial Solutions value.
|
|
(0008,0016) |
SOP Class UID is set to the unique identifier associated with the SOP_CLASS keyword.
|
|
(0008,0018) |
SOP Instance UID is set to a newNV5 Geospatial Solutions-generated value.
|
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.
|
DICOM Tag |
Description |
|
(0010,0010) |
Patient Name. |
|
(0010,0020) |
Patient ID. |
|
(0020,000D) |
Study Instance UID. When creating a new study the Image Instance UID can be used as a based value to which a unique suffix can be added. When adding an image to an existing study the existing study instance UID can be used.
|
|
(0020,000E) |
Series Instance UID. When creating a new series the Image Instance UID can be used as a based value to which a unique suffix can be added. When adding an image to an existing series the existing series instance UID can be used.
|
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:
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.
|
Image Type / Transfer Syntax
|
Recoverable |
|
Implicit VR Little Endian
|
Yes |
|
Explicit VR Little Endian
|
Yes |
|
Explicit VB Big Endian
|
Yes |
|
JPEG Baseline |
Yes |
|
JPEG Extended (Process 2 and 4)
|
Yes |
|
JPEG Lossless, Non-Hierarchical
|
Yes |
|
JPEG 2000 Lossless
|
Yes |
|
JPEG 2000 |
Yes |
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.
|
Image Type / Transfer Syntax
|
Recoverable |
|
Implicit VR Little Endian
|
Yes |
|
Explicit VR Little Endian
|
Yes |
|
Explicit VB Big Endian
|
Yes |
|
JPEG Baseline |
No |
|
JPEG Extended (Process 2 and 4)
|
No |
|
JPEG Lossless, Non-Hierarchical
|
No |
|
JPEG 2000 Lossless
|
No |
|
JPEG 2000 |
No |
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.
|
DICOM Tag |
Modification |
|
(0002,0002) |
Media Storage SOP Class UID is set to the unique identifier associated with the SOP_CLASS keyword.
|
|
(0002,0003) |
Media Storage SOP Instance UID is set to a new NV5 Geospatial Solutions-generated value.
|
|
(0002,0010) |
Transfer Syntax UID is set to Implicit VR Little Endian, Explicit VR Little Endian, or Explicit VB Big Endian based on byte ordering and VR type of the first tag in the file.
|
|
(0002,0012) |
Implementation Class UID is set to a new NV5 Geospatial Solutions-generated value.
|
|
(0002,0013) |
Implementation Version Name is set to the NV5 Geospatial Solutions value.
|
|
(0002,0016) |
Source Application Entity Title is set to the NV5 Geospatial Solutions value.
|
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 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.
|
SOP Class Name |
SOP Class UID |
|
STANDARD_CR (Computed Radiography)
|
1.2.840.10008.5.1.4.1.1.1
|
|
STANDARD_DX_PRESENT (Digital X-ray)
|
1.2.840.10008.5.1.4.1.1.1.1
|
|
STANDARD_DX_PROCESS (Digital X-ray)
|
1.2.840.10008.5.1.4.1.1.1.1.1
|
|
STANDARD_MG_PRESENT (Digital Mammography)
|
1.2.840.10008.5.1.4.1.1.1.2
|
|
STANDARD_MG_PROCESS (Digital Mammography)
|
1.2.840.10008.5.1.4.1.1.1.2.1
|
|
STANDARD_IO_PRESENT (Digital Intra-oral)
|
1.2.840.10008.5.1.4.1.1.1.3
|
|
STANDARD_IO_PROCESS (Digital Intra-Oral)
|
1.2.840.10008.5.1.4.1.1.1.3.1
|
|
STANDARD_CT |
1.2.840.10008.5.1.4.1.1.2
|
|
STANDARD_US_MF_RETIRED
|
1.2.840.10008.5.1.4.1.1.3
|
|
STANDARD_US_MF |
1.2.840.10008.5.1.4.1.1.3.1
|
|
STANDARD_MR |
1.2.840.10008.5.1.4.1.1.4
|
|
ENHANCED_MR_IMAGE
|
1.2.840.10008.5.1.4.1.1.4.1
|
|
MR_SPECTROSCOPY |
1.2.840.10008.5.1.4.1.1.4.2
|
|
STANDARD_NM_RETIRED
|
1.2.840.10008.5.1.4.1.1.5
|
|
STANDARD_US_RETIRED
|
1.2.840.10008.5.1.4.1.1.6
|
|
STANDARD_US |
1.2.840.10008.5.1.4.1.1.6.1
|
|
STANDARD_SEC_CAPTURE
|
1.2.840.10008.5.1.4.1.1.7
|
|
SC_MULTIFRAME_SINGLE_BIT
|
1.2.840.10008.5.1.4.1.1.7.1
|
|
SC_MULTIFRAME_GRAYSCALE_BYTE
|
1.2.840.10008.5.1.4.1.1.7.2
|
|
SC_MULTIFRAME_GRAYSCALE_WORD
|
1.2.840.10008.5.1.4.1.1.7.3
|
|
SC_MULTIFRAME_TRUE_COLOR
|
1.2.840.10008.5.1.4.1.1.7.4
|
|
STANDARD_OVERLAY
|
1.2.840.10008.5.1.4.1.1.8
|
|
STANDARD_CURVE |
1.2.840.10008.5.1.4.1.1.9
|
|
STANDARD_MODALITY_LUT
|
1.2.840.10008.5.1.4.1.1.10
|
|
STANDARD_VOI_LUT
|
1.2.840.10008.5.1.4.1.1.11
|
|
STANDARD_GRAYSCALE_SOFTCOPY_PS
|
1.2.840.10008.5.1.4.1.1.11.1
|
|
STANDARD_XRAY_ANGIO
|
1.2.840.10008.5.1.4.1.1.12.1
|
|
STANDARD_XRAY_RF
|
1.2.840.10008.5.1.4.1.1.12.2
|
|
STANDARD_XRAY_ANGIO_BIPLANE (retired)
|
1.2.840.10008.5.1.4.1.1.12.3
|
|
STANDARD_NM |
1.2.840.10008.5.1.4.1.1.20
|
|
RAW_DATA |
1.2.840.10008.5.1.4.1.1.66
|
|
STANDARD_VL_ENDOSCOPIC
|
1.2.840.10008.5.1.4.1.1.77.1.1
|
|
STANDARD_VL_MICROSCOPIC
|
1.2.840.10008.5.1.4.1.1.77.1.2
|
|
STANDARD_VL_SLIDE_MICROSCOPIC
|
1.2.840.10008.5.1.4.1.1.77.1.3
|
|
STANDARD_VL_PHOTOGRAPHIC
|
1.2.840.10008.5.1.4.1.1.77.1.4
|
|
STANDARD_BASIC_TEXT_SR
|
1.2.840.10008.5.1.4.1.1.88.11
|
|
STANDARD_ENHANCED_SR
|
1.2.840.10008.5.1.4.1.1.88.22
|
|
STANDARD_COMPREHENSIVE_SR
|
1.2.840.10008.5.1.4.1.1.88.33
|
|
STANDARD_PET (Positron Emission Tomography)
|
1.2.840.10008.5.1.4.1.1.128
|
|
STANDARD_PET_CURVE
|
1.2.840.10008.5.1.4.1.1.129
|
|
STANDARD_RT_IMAGE
|
1.2.840.10008.5.1.4.1.1.481.1
|
|
STANDARD_RT_DOSE
|
1.2.840.10008.5.1.4.1.1.481.2
|
|
STANDARD_RT_STRUCTURE_SET
|
1.2.840.10008.5.1.4.1.1.481.3
|
|
STANDARD_RT_BEAMS_TREAT
|
1.2.840.10008.5.1.4.1.1.481.4
|
|
STANDARD_RT_PLAN
|
1.2.840.10008.5.1.4.1.1.481.5
|
|
STANDARD_RT_BRACHY_TREAT
|
1.2.840.10008.5.1.4.1.1.481.6
|
|
STANDARD_RT_TREAT_SUM
|
1.2.840.10008.5.1.4.1.1.481.7
|
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:
sFile = DIALOG_PICKFILE( $
PATH=FILEPATH('',SUBDIRECTORY=['examples','data']), $
TITLE='Select DICOM Patient File', FILTER='*.dcm')
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:
sFile = DIALOG_PICKFILE( $
PATH=FILEPATH('',SUBDIRECTORY=['examples','data']), $
TITLE='Select DICOM Patient File', FILTER='*.dcm', $
GET_PATH=path)
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:
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