ImageGear Professional for Unix
Writing Data to Data Elements
| ImageGear Professional v18.2 > User Guide > Using ImageGear > Advanced Image Formats > DICOM > Working with DICOM Non-Image Data > Writing Data to Data Elements |
The following API functions allow you to write or overwrite the data of a Data field, respectively:
| MED_DCM_DS_DE_insert() | Inserts a new DE to the Data Set. Its placement are determined automatically according to its Tag value. Your only power of placement is in specifying what level in the hierarchy of the Data Set to place the new DE. |
| MED_DCM_DS_curr_data_set() | Overwrites the Data Field of an existing Data Element. |
Whether you are inserting a new DE or overwriting the Data Field of an existing DE, you may need to query the VR and VM by calling MED_DCM_util_tag_info_get(). With the VR in hand, you can call MED_DCM_util_VR_info_mode()which tells you the length that each item can have, and whether the items are of fixed or variable length. See the previous section "Reading Data From Data Elements" for how to interpret the value returned to you in VM.
A Data Set is composed entirely of Data Elements. In DICOM, all stored data, including the images themselves, is stored in fundamental DICOM building blocks calledData Elements.
Access to the Data Set is achieved by moving an internal Data Element index called the "Current Data Element" from Data Element to Data Element. There is a set of API functions, which just move the Current Data Element about the Data Set. Another group of API functions will allow you to retrieve or set the Value Field of the Current Data Element.
The internal Data Set is similar to but not exactly like the Data Set found in the DICOM file. The DICOM standard has many options and various methods of storing its data. As the internal Data Set is being filled, the vital information is stored in an abstract form. The new form of this information makes it easier for you to work with. Most of this internal storage is completely transparent for you and your application, but there are a few items you should be aware of.
First of all, as you move to see the internal Data Set and inspect its contents you may notice that some items that were in the original Data Set are missing. One example of this are the "Group Lengths" (all of which have Element Numbers of 0000). Group Lengths which are optional in the DICOM specification, are placed in the Data Set to aid to quickly find certain Data Elements by allowing the parser to skip over large blocks of Data Elements that do not contain the Data Element being searched for. They serve no other purpose and are therefore removed. If you are going to save the Data Set back out to disk you may request that Group Lengths should be included in the new disk file. If you do so, ImageGear recalculates the Group Lengths in case any Data Elements have been added, removed or altered.
Also missing from the data is the Data Field for Pixel Data (7FE0,0010). It is the Data Element that holds the image. This Data Element is actually present but his Data Field is empty. This is because the image has been read and loaded into an ImageGear DIB.
Another difference from the internal Data Set and the original file version is that regardless of what the original encoding scheme was, the internal Data Set always are "Explicit VR." That is, the Value Representations (VRs) of each Tag are looked up in the Data Dictionary and recorded along with the other information. If you later write the Data Set to disk you may choose whether the Data Set should be Explicit or Implicit VR.
"Critical Data Elements" are those DEs whose values are taken from the image not regarding to whether the Data Set has values for these DEs or not. Two examples of such DEs are the height (Rows) and width (Columns) of the image. Note that the Critical Data Elements in the internal Data Set are always kept consistent with the HIGEAR. For example, if you have resized the image, the DCM_TAG_Columns and DCM_TAG_Rows Data Elements are set to the new Width and Height of the image. When an image processing function, such as Resize or Rotate, is applied to the DICOM image, the values for Rows and Columns will be updated from the HIGEAR.
A certain type of Data Element can be hierarchical meaning that it can have other groups of Data Elements "under" it similarly to the way files are stored under the directory structure. This special type of Data Element has a Value Representation of Sequence Delimiter (SQ). This Data Element l marks a set of Data Elements called "Items." This set can contain 0 or more embedded Data Elements. The hierarchical structure can make it difficult to keep track of where you are as you move through the Data Set. This is the reason of using the Current Data Element - to keep track of index you are positioned at in the array of Data Elements.
You may notice that many of the Data Set Navigation API contain a parameter of level_op. This argument tells whether the Data Set index should remain in the current level or can be moved to another level. The possible values for this argument are:
When a DICOM image file is loaded it may or may not begin with a Part 10 Header. The Part 10 Header consists of 2 parts: a free-form block of 128 bytes called a Preamble, and a fixed list of 9 Data Elements, all of which have a Group Number of 0002. Both of these parts are stored in the Part 10 Template mentioned earlier. The use of the Preamble is up to the application and can be used to store anything you like, as long as it is 128 bytes or less. A blank or empty Preamble is indicated by 128 bytes of 0x00.
If the original image has a Part 10 header, the data from it is extracted and placed in the internal template mentioned earlier. If there is no header, the template is empty except for 2 fields: the File Meta Information Version (0002,0001) and the Transfer Syntax UID (0002,0010). Default values are assigned to these fields - File Meta Information Version is set to 0x0001, and Transfer Syntax UID is set to the Transfer Syntax detected by ImageGear when the image was loaded. The Version number is called for the DICOM specification and it value never need to be altered.
Access to the values in the Part 10 Template is done using a small set of methods or functions, which include either "Part10" or "preamble" in their names.
| MED_DCM_DS_preamble_get() | get Part 10 Header Preamble |
| MED_DCM_DS_preamble_set() | set Part 10 Header Preamble |
| MED_DCM_DS_part10_get() | get Part 10 Header Data Elements, except Preamble |
| MED_DCM_DS_part10_set() | set Part 10 Header Data Elements, except Preamble |