Additional Topics > Medical Imaging in IDL > IDL DICOM Reference > IDLffDicomEx Properties

# IDLffDicomEx Properties

The IDLffDicomEx object has the following properties.

BITS_ALLOCATED | BITS_STORED
COLUMNS | FILENAME
HIGH_BIT | IMAGE_TYPE
INSTANCE_NUMBER | MODALITY
NO_PIXEL_DATA | NUMBER_OF_FRAMES
PHOTOMETRIC_INTERPRETATION | PIXEL_ASPECT_RATIO
PIXEL_MAX | PIXEL_MIN
PIXEL_REPRESENTATION | PIXEL_SPACING
PLANAR_CONFIGURATION | ROWS
SAMPLES_PER_PIXEL | SOP_CLASS_UID
SOP_INSTANCE_UID | TRANSFER_SYNTAX

### About Object Property Descriptions

Each property description includes a table similar to the following one.

Property Type | Integer
Name String | not displayed
DICOM Attribute | (0028,0100) | VR:US | Multi-value: No
Get: Yes | Set: Yes | Init: No | Registered: No

The fields contain the following information:

- Property Type describes the property type associated with the property. If the property is registered, the property type will be one of the types described in Registered Property Data Types. If the property is not registered, this field will describe the generic IDL data type of the property value.
- Name String is the default value of the Name property attribute. If the property is registered, this is the value that appears in the left-hand column when the property is displayed in a property sheet widget. If the property is not registered, this field will contain the words not displayed.
- DICOM Attribute is the (group,element) tag number of the attribute. See DICOM Attributes for a list of attributes.
- VR is the Value Representation, which describes the data type of the attribute. See Value Representations for definitions of the available VRs.
- Multi-value indicates whether the attribute has more than a single value in its value field.
- See IDLffDicomEx Overview for more information about structure of a DICOM attribute.
- Get, Set, and Init describe whether the property can be specified as a keyword to the GetProperty, SetProperty, and Init methods, respectively.
- Registered describes whether the property is registered for display in a property sheet widget.

Properties with the word “Yes” in the “Get” column of the property table can be retrieved via IDLffDicomEx::GetProperty. Properties with the word “Yes” in the “Set” column in the property table can be set via IDLffDicomEx::SetProperty. Properties with the word “Yes” in the “Init” column of the property table can be specified during object initialization via IDLffDicomEx::Init.

### Guidelines for Modifying IDLffDicomEx Properties

Several IDLffDicomEx object properties need to be set only when creating a new image object. There is no need to change these properties on an existing image, which can be a cloned image, or a read-only image. In fact, changing these properties on an existing image can result in the defined property values being inconsistent with the pixel data stored in the existing image, and the acceptable property values for the SOP Class of the image. Changing these properties does not change the characteristics of existing pixel data. To avoid propagating incorrect property values, set these properties only on a new image, and only prior to (or while) setting pixel data. See Specifying Pixel Data For a New Image for a list of properties that must be set when assigning pixel data to a brand new image.

### BITS_ALLOCATED

An integer that indicates the total number of bits allocated for each pixel sample. A pixel cell is made up of the pixel sample value as well as other pixel-related information, such as overlay indications. The structure of each pixel sample value can be determined by the number of bits allocated (BITS_ALLOCATED property), the number of bits stored (BITS_STORED property), and the location of the most significant bit (HIGH_BIT property).

Property Type | Integer
Name String | not displayed
DICOM Attribute | (0028,0100) | VR:US | Multi-value: No
Get: Yes | Set: Yes | Init: No | Registered: No

Note: This property should be set only on an image just created using the CREATE keyword of the IDLffDicomEx::Init method. See Guidelines for Modifying IDLffDicomEx Properties for details.

### BITS_STORED

An integer that indicates the number of bits stored for each pixel sample. The number of bits stored is less than or equal to the number of bits allocated, which determines the size of each pixel sample. A pixel cell is made up of the pixel sample value and other pixel-related information, such as overlay indications. The structure of each pixel sample value can be determined by the number of bits allocated (BITS_ALLOCATED property), the number of bits stored (BITS_STORED property), and the location of the most significant bit (HIGH_BIT property).

Property Type | Integer
Name String | not displayed
DICOM Attribute | (0028,0101) | VR:US | Multi-value: No
Get: Yes | Set: Yes | Init: No | Registered: No

This property should be set only on an image just created using the CREATE keyword of the IDLffDicomEx::Init method. See Guidelines for Modifying IDLffDicomEx Properties for details.

### COLUMNS

An integer that indicates the number of columns of pixels in an image.

Property Type | Integer
Name String | not displayed
DICOM Attribute | (0028,0011) | VR:US | Multi-value: No
Get: Yes | Set: Yes | Init: No | Registered: No

This property should be set only on an image just created using the CREATE keyword of the IDLffDicomEx::Init method. See Guidelines for Modifying IDLffDicomEx Properties for details.

### FILENAME

A string that contains the filename associated with the object. The filename is defined when a new IDLffDicomEx object is created. The FILENAME property provides a convenient way to retrieve the filename passed in during object initialization.

Property Type | String
Name String | not displayed
DICOM Attribute | n/a | VR: n/a | Multi-value: No
Get: Yes | Set: No | Init: No | Registered: No

### HIGH_BIT

An integer that specifies the most significant bit within a zero-based pixel sample and determines the starting position of the bits used to store the pixel's value. A pixel cell is made up of the pixel sample value and other pixel-related information, such as overlay indications. The structure of each pixel sample value can be determined by the number of bits allocated (BITS_ALLOCATED property), the number of bits stored (BITS_STORED property), and the location of the most significant bit (HIGH_BIT property).

Property Type | Integer
Name String | not displayed
DICOM Attribute | (0028,0102) | VR:US | Multi-value: No
Get: Yes | Set: Yes | Init: No | Registered: No

Note: This property should be set only on an image just created using the CREATE keyword of the IDLffDicomEx::Init method. See Guidelines for Modifying IDLffDicomEx Properties for details.

### IMAGE_TYPE

A string array that describes the type of image associated with a particular series. The string array can contain 2, 3, or 4 elements, the first two of which are required. The first and second elements describe the Pixel Data and Patient Examination characteristics. The third and fourth elements, which are optional, provide modality-specific and implementation-specific information.

Note: The value provided must be in all upper case letters. Lower or mixed case values will cause an error.

The following table shows allowable values for these elements.

Field | Possible String Values | Description
Pixel Data Characteristics | ORIGINAL | Pixel values are based on initial data.
DERIVED | Pixel values have been generated from one or more other images.
Patient Examination Characteristics | PRIMARY | Image created from direct patient examination.
SECONDARY | Image created after patient examination.
Modality Specific Characteristics | Optional information object definitions related to the modality. | See the DICOM standard, DICOM Part 3: Information Object Definitions, for details.
Implementation Specific Characteristics | Other optional values. | This is a user-defined field.

Property Type | String
Name String | not displayed
DICOM Attribute | (0008,0008) | VR:CS | Multi-value: Yes (2 or more)
Get: Yes | Set: Yes | Init: No | Registered: No

Note: This property should be set only on an image just created using the CREATE keyword of the IDLffDicomEx::Init method. See Guidelines for Modifying IDLffDicomEx Properties for details.

### INSTANCE_NUMBER

A string that contains the identification (ID) number for an image.

Property Type | String
Name String | not displayed
DICOM Attribute | (0020,0013) | VR:IS | Multi-value: No
Get: Yes | Set: Yes | Init: No | Registered: No

Note: This property should be set only on an image just created using the CREATE keyword of the IDLffDicomEx::Init method. See Guidelines for Modifying IDLffDicomEx Properties for details.

### MODALITY

A string that contains the type of equipment that acquired the data used to create the images in the series. See the DICOM standard, DICOM Part 3: Information Object Definitions, (PS 3.3-2003) C.7.3.1.1.1, for a list of the Modality Defined Terms.

Property Type | String
Name String | not displayed
DICOM Attribute | (0008,0060) | VR: CS | Multi-value: No
Get: Yes | Set: Yes | Init: No | Registered: No

Note: This property should be set only on an image just created using the CREATE keyword of the IDLffDicomEx::Init method. See Guidelines for Modifying IDLffDicomEx Properties for details.

### NO_PIXEL_DATA

A scalar integer that determines whether pixel data is returned when you create an IDLffDicomEx object. Set this property to 1 to prevent pixel data from being loaded into memory and only return the tag information. Do not set this property or set the property value equal to zero return all DICOM file information including pixel data.

Setting this property provides a significant performance improvement when you only need attribute information. However, the pixel data is unavailable. If you attempt to access pixel data for an object that has this property set, IDL generates an error. You must create a new object in order access pixel data.

This property is not set by default.

Property Type | INTEGER
Name String | not displayed
Get: Yes | Set: No | Init: Yes | Registered: No

### NUMBER_OF_FRAMES

An integer that specifies the number of frames contained within an image file. A DICOM image file can contain one image (frame) or multiple images (frames). When a DICOM image file contains more than one frame, the pixel data is concatenated into one array in the DICOM file. All related properties, such as SAMPLES_PER_PIXEL and BITS_ALLOCATED, apply to all the frames. Some SOP Classes only support single frame images; consequently, this DICOM tag is not part of the set of tags that make up the class.

Property Type | String
Name String | not displayed
DICOM Attribute | (0028,0008) | VR:IS | Multi-value: No
Get: Yes | Set: Yes | Init: No | Registered: No

Note: This property should be set only on an image just created using the CREATE keyword of the IDLffDicomEx::Init method. See Guidelines for Modifying IDLffDicomEx Properties for details. There is no need to set this for a new single-frame image as the default value is 1.

### PHOTOMETRIC_INTERPRETATION

A string that contains the photometric interpretation of the pixel data. Photometric interpretation refers to how color (and/or intensity) is shown within an image. The following table provides a list of possible string values.

Note: The value provided must be in all upper case letters. Lower or mixed case values will cause an error.

String Value | Description
MONOCHROME1 | Represents a monochrome (grayscale) image plane where the minimum pixel value is white. The SAMPLES_PER_PIXEL property equals 1.
MONOCHROME2 | Represents a monochrome (grayscale) image plane where the minimum pixel value is black. The SAMPLES_PER_PIXEL property equals 1.
PALETTE COLOR | Represents a color (indexed) image plane. Each pixel value is mapped through a color look-up table (LUT). The SAMPLES_PER_PIXEL property equals 1.
RGB | Represents a color image containing red, green, and blue (RGB) planes. The SAMPLES_PER_PIXEL property equals 3.
HSV | Represents a color image containing hue, saturation, and value planes. The SAMPLES_PER_PIXEL property equals 3.
ARGB | Represents a color image described by RGB planes and an additional alpha plane (channel), which is used to control transparency. The SAMPLES_PER_PIXEL property equals 4.
CMYK | Represents a color image described by cyan, magenta, yellow, and black planes. The SAMPLES_PER_PIXEL property equals 4.

Property Type | String
Name String | not displayed
DICOM Attribute | (0028,0004) | VR:CS | Multi-value: No
Get: Yes | Set: Yes | Init: No | Registered: No

Note: This property should be set only on an image just created using the CREATE keyword of the IDLffDicomEx::Init method. See Guidelines for Modifying IDLffDicomEx Properties for details.

### PIXEL_ASPECT_RATIO

This is a multi-valued property that is stored as a one dimensional array. The first element is the vertical size of each pixel in millimeters. The second element is the horizontal size of each pixel in millimeters.

Property Type | String
Name String | not displayed
DICOM Attribute | (0028,0034) | VR:IS | Multi-value: Yes (2)
Get: Yes | Set: Yes | Init: No | Registered: No

Note: This property should be set only on an image just created using the CREATE keyword of the IDLffDicomEx::Init method. See Guidelines for Modifying IDLffDicomEx Properties for details.

### PIXEL_MAX

An integer that indicates the maximum pixel value within an image. This value (also known as Largest Image Pixel Value) is read from the attribute (0028,0107) in the DICOM file when an object is created. This value may not match the data’s maximum pixel value. The value of this tag reflects the value assigned to it, which may be a user-assigned value other than the data’s actual maximum pixel value. You can use IDL’s MAX function to return the largest value in the pixel data array. The pixel value of this property is either an unsigned or signed integer based on the value of the PIXEL_REPRESENTATION property.

Property Type | Integer
Name String | not displayed
DICOM Attribute | (0028,0107) | VR:US or SS | Multi-value: No
Get: Yes | Set: Yes | Init: No | Registered: No

Note: This property should be set only on an image just created using the CREATE keyword of the IDLffDicomEx::Init method. See Guidelines for Modifying IDLffDicomEx Properties for details.

### PIXEL_MIN

An integer that indicates the minimum pixel value within an image. This value (also known as Smallest Image Pixel Value) is read from the attribute (0028,0106) in the DICOM file when an object is created. This value may not match the data’s minimum pixel value. The value of this tag reflects the value assigned to it, which may be a user-assigned value other than the data’s actual minimum pixel value. You can use IDL’s MIN function to return the smallest value in the pixel data array. The pixel value of this property is either an unsigned or signed integer based on the value of the PIXEL_REPRESENTATION property.

Property Type | Integer
Name String | not displayed
DICOM Attribute | (0028,0106) | VR:US or SS | Multi-value: No
Get: Yes | Set: Yes | Init: No | Registered: No

Note: This property should be set only on an image just created using the CREATE keyword of the IDLffDicomEx::Init method. See Guidelines for Modifying IDLffDicomEx Properties for details.

### PIXEL_REPRESENTATION

An integer that indicates the data representation of the pixels within an image as follows:

- 0 = Unsigned Integer
- 1 = Signed Integer

Property Type | Integer
Name String | not displayed
DICOM Attribute | (0028,0103) | VR:US | Multi-value: No
Get: Yes | Set: Yes | Init: No | Registered: No

Note: This property should be set only on an image just created using the CREATE keyword of the IDLffDicomEx::Init method. See Guidelines for Modifying IDLffDicomEx Properties for details.

### PIXEL_SPACING

A two-element array in which the first value is the physical distance within the patient between the center of each adjacent row pixel in millimeters (mm). The second value of the property is the physical distance within the patient between the center of each adjacent column pixel in millimeters (mm).

Property Type | String
Name String | not displayed
DICOM Attribute | (0028,0030) | VR:DS | Multi-value: Yes (2)
Get: Yes | Set: Yes | Init: No | Registered: No

Note: This property should be set only on an image just created using the CREATE keyword of the IDLffDicomEx::Init method. See Guidelines for Modifying IDLffDicomEx Properties for details.

### PLANAR_CONFIGURATION

A value that indicates whether the pixel data of three- or four-plane images are sent color-by-pixel or color-by-plane. The pixel data has three or four planes if the value for the SAMPLES_PER_PIXEL property is greater than one.

Value | Description
0 | Color-by-pixel or pixel interleaving – the value for the first pixel within the plane is sent, followed by the value for the first pixel in the second plane (R1, G1, B1, R2, G2, B2, ...).
1 | Color-by-plane or image interleaving – values for all of the first plane's pixels are sent, followed by all of the pixel values in the next plane (R1, R2, R3, ..., G1, G2, G3, ... and B1, B2, B3, ...).

Property Type | Integer
Name String | not displayed
DICOM Attribute | (0028,0006) | VR:US | Multi-value: No
Get: Yes | Set: Yes | Init: No | Registered: No

Note: This property should be set only on an image just created using the CREATE keyword of the IDLffDicomEx::Init method. See Guidelines for Modifying IDLffDicomEx Properties for details.

### ROWS

An integer that indicates the number of rows of pixels in an image.

Property Type | Integer
Name String | not displayed
DICOM Attribute | (0028,0010) | VR:US | Multi-value: No
Get: Yes | Set: Yes | Init: No | Registered: No

Note: This property should be set only on an image just created using the CREATE keyword of the IDLffDicomEx::Init method. See Guidelines for Modifying IDLffDicomEx Properties for details.

### SAMPLES_PER_PIXEL

The number of separate planes in the image. The image can contain either one, three, or four planes.

Value | Description
1 | Contains a single plane representing a monochrome (grayscale) image or an indexed image with an associated color look-up table (LUT).
3 | Contains three planes representing an RGB (red, green, blue), or HSV (hue, saturation, and value) image.
4 | Contains four planes representing a CMYK (cyan, magenta, yellow, black) image.

Property Type | Integer
Name String | not displayed
DICOM Attribute | (0028,0002) | VR:US | Multi-value: No
Get: Yes | Set: Yes | Init: No | Registered: No

Note: This property should be set only on an image just created using the CREATE keyword of the IDLffDicomEx::Init method. See Guidelines for Modifying IDLffDicomEx Properties for details.

### SOP_CLASS_UID

The unique identifier (UID) of the class of the service-object pair (SOP) associated with a source image. See SOP_CLASS for available SOP class options.

Property Type | String
Name String | not displayed
DICOM Attribute | (0008,0016) | VR:UI | Multi-value: No
Get: Yes | Set: Yes | Init: No | Registered: No

Note: This property should be set only on an image just created using the CREATE keyword of the IDLffDicomEx::Init method and should not need to be further modified. See Guidelines for Modifying IDLffDicomEx Properties for details.

### SOP_INSTANCE_UID

The unique identifier (UID) of the image. This identifier is used when the image is transferred to or from a database and to identify the image within a hierarchical tree of information. An unique identifier is generated for each newly created or cloned image.

Property Type | String
Name String | not displayed
DICOM Attribute | (0008,0018) | VR: UI | Multi-value: No
Get: Yes | Set: Yes | Init: No | Registered: No

Note: This property should be set only on an image just created using the CREATE keyword of the IDLffDicomEx::Init method and should not need to be further modified. See Guidelines for Modifying IDLffDicomEx Properties for details.

### TRANSFER_SYNTAX

This property returns two values: the transfer syntax UID (unique identifier) and its description. Use the IDLffDicomEx::ChangeTransferSyntax method to modify the file syntax. There is no support for the JPEG compression algorithms on Macintosh. See File Compression and Transfer Syntax Support for information on supported transfer syntaxes.

Property Type | String
Name String | not displayed
DICOM Attribute | (0002,0010) | VR: UI | Multi-value: Yes (2)
Get: Yes | Set: No | Init: No | Registered: No