InsertImages Method

Summary

Inserts image(s) in a Pixel Data element.

Syntax

C++/CLI

public void InsertImages( 
   DicomElement element, 
   RasterImage image, 
   int index, 
   DicomImageCompressionType compression, 
   DicomImagePhotometricInterpretationType photometric, 
   int bitsPerPixel, 
   int qualityFactor, 
   DicomSetImageFlags flags 
)

public: 
void InsertImages(  
   DicomElement^ element, 
   RasterImage^ image, 
   int index, 
   DicomImageCompressionType compression, 
   DicomImagePhotometricInterpretationType photometric, 
   int bitsPerPixel, 
   int qualityFactor, 
   DicomSetImageFlags flags 
)

Parameters

element
An item in the Data Set.

image
Image(s) to insert.

index
The zero-based index at which the first image of the specified images should be inserted.

compression
The type of compression to use.

photometric
Photometric constant.

bitsPerPixel
Value that represents the resulting image pixel depth. Possible values are:

Value	Meaning
0	Keep the original file's pixel depth (do not convert).
1 to 8	Use the specified bits per pixel in the resulting image.
12	Use 12 bits per pixel in the resulting image.
16	Use 16 bits per pixel in the resulting image.
24	Use 24 bits per pixel in the resulting image.
32	Use 32 bits per pixel in the resulting image.

qualityFactor
The quality factor (Q factor) is a number that determines the degree of loss in the compression process. You can set a value from 2 to 255, where 2 is the highest quality and 255 is the most compression.

flags
Flags that control the behavior of this method.

Remarks

As an example, if you wish to insert 50 images starting with the 50th frame in the Pixel Data, call this method with index set to 49 (the 50th frame in a zero-based index) and the 50 frames you wish to insert. Most DICOM files will only have one Data Element of type DicomTag.PixelData. Therefore, in most instances you can set element to null, since the method will automatically insert the images into the only Pixel Data Element in the file. If element is not null, it must point to the Pixel Data Element itself.

If the DICOM file is DicomClassType.BasicDirectory, the file may contain more than one Pixel Data Element. In this case you must specify in element the Pixel Data Element in which to insert the images.

For a table of possible Compression, Photometric, BitsPerPixel, and Quality Factor combinations, refer to Compression Table.

For more options when using the JPEG 2000 compression, refer to Jpeg2000Options.

This method will either insert, delete or update one or more of the following elements:

Tag	Name
(7FE0,0010)	Pixel Data.
(0002,0010)	Transfer Syntax UID.
(0028,0101)	Bits Stored.
(0028,0100)	Bits Allocated.
(0028,0102)	High Bit.
(0028,0103)	Pixel Representation.
(0028,0010)	Rows.
(0028,0011)	Columns.
(0028,0002)	Samples per Pixel.
(0028,0006)	Planar Configuration.
(0028,0004)	Photometric Interpretation.
(0028,0106)	Smallest Image Pixel Value.
(0028,0107)	Largest Image Pixel Value.
(0028,1101)	Red Palette Color Lookup Table Descriptor.
(0028,1102)	Green Palette Color Lookup Table Descriptor.
(0028,1103)	Blue Palette Color Lookup Table Descriptor.
(0028,1201)	Red Palette Color Lookup Table Data.
(0028,1202)	Green Palette Color Lookup Table Data.
(0028,1203)	Blue Palette Color Lookup Table Data.
(0028,1199)	Palette Color Lookup Table UID.
(0028,1052)	Rescale Intercept.
(0028,1053)	Rescale Slope.
(0028,1054)	Rescale Type.
(0028,1221)	Segmented Red Palette Color Lookup Table Data.
(0028,1222)	Segmented Green Palette Color Lookup Table Data.
(0028,1223)	Segmented Blue Palette Color Lookup Table Data.
(0028,3010)	VOI LUT Sequence.
(0028,1050)	Window Center.
(0028,1051)	Window Width.
(0028,1055)	Window Center & Width Explanation.
(0028,0008)	Number of Frames.
(0054,0070)	Time Slot Vector.
(5200,9229)	Shared Functional Groups Sequence.
(5200,9230)	Per-frame Functional Groups Sequence .

If the Shared Functional Groups Sequence element or the Per-frame Functional Groups Sequence element is added, an item child element may be added that contains either the (0028,9132) Frame VOI LUT Sequence element or the (0028,9145) Pixel Value Transformation Sequence element. (0028,9132) Frame VOI LUT Sequence Child Elements

Tag	Name
(0028,1050)	Window Center
(0028,1051)	Window Width
(0028,1055)	Window Center & Width Explanation

(0028,9145) Pixel Value Transformation Sequence child elements

Tag	Name
(0028,1052)	Rescale Intercept
(0028,1053)	Rescale Slope
(0028,1054)	Rescale Type

This method is indifferent to the pixel data restrictions imposed by the various DICOM IOD classes; for example, this method will allow the user to insert a colored image into a "Digital X-Ray Image Storage" Data Set.

This method will always insert a "Number of Frames" (0028, 0008) element and set its value.

The Multi-frame Functional Groups module may have a Shared Functional Groups Sequence item, and/or a Per-frame Functional Groups Sequence item. Either of these items may have a Pixel Value Transformation Sequence (0028,9145) item, or a Frame VOI LUT Sequence (0028,9132) item. The five DICOM_SETIMAGE_MFG flags can be used to add or modify existing information in the Pixel Value Transformation Sequence or the Frame VOI LUT Sequence. The following flags are used only if the corresponding sequence (Frame VOI LUT Sequence or Pixel Value Transformation Sequence) does not already exist.

DicomSetImageFlags.MfgVoiLutPerFrame
DicomSetImageFlags.MfgVoiLutShared
DicomSetImageFlags.MfgModalityLutPerFrame
DicomSetImageFlags.MfgModalityLutShared

In this case, the sequence is placed in the sequence indicated by the flag (Per-frame Functional Groups Sequence or Shared Functional Groups Sequence). If a Frame VOI LUT Sequence or a Pixel Value Transformation Sequence already exists in a DICOM dataset, the four above flags are ignored, and the sequence is placed in the location where sequences already exist. For a detailed discussion on Multi-frame Functional Groups see the topic Multi-frame Functional Groups. To insert an image into a dataset without recompressing it, call Leadtools.Dicom.Common.HighLevelServices.HighLevelDicomExtension.InsertImageNoRecompression. To insert a video into a dataset without recompressing it, call Leadtools.Dicom.Common.HighLevelServices.InsertVideoNoRecompression.

Note: DicomSetImageFlags.MfgVoiLutPerFrame cannot be combined with DicomSetImageFlags.MfgVoiLutShared. DicomSetImageFlags.MfgModalityLutPerFrame cannot be combined with DicomSetImageFlags.MfgModalityLutShared. There is no high level functionality to embed MPEG2 into a DICOM dataset. The Multimedia toolkit (DICOM writer can create DICOM files with MPEG2 compression. This method cannot be used to encode DICOM transfer syntaxes (e.g. video compression support) that are not part of the main medical SDK and it is supported only via the LEADTOOLS Medical Module.

Example

using Leadtools; 
using Leadtools.Dicom; 
 
 
public void TestDicomImage() 
{ 
   string dicomFileName = Path.Combine(LEAD_VARS.ImagesDir, "DICOM", "image3.dcm"); 
   //Make sure to initialize the DICOM engine, this needs to be done only once  
   //In the whole application 
   DicomEngine.Startup(); 
   using (DicomDataSet ds = new DicomDataSet()) 
   { 
      //Load DICOM File 
      ds.Load(dicomFileName, DicomDataSetLoadFlags.None); 
 
      DicomElement pixelDataElement = ds.FindFirstElement(null, DicomTag.PixelData, true); 
      if (pixelDataElement == null) 
      { 
         Console.WriteLine("This dataset is missing the pixel data element", "Sample"); 
         return; 
      } 
 
      if (ds.GetImageCount(pixelDataElement) == 0) 
      { 
         Console.WriteLine("Sample: This dataset has no images"); 
         return; 
      } 
 
      DicomImageInformation imageInformation = ds.GetImageInformation(pixelDataElement, 0); 
      if (imageInformation == null) 
      { 
         Console.WriteLine("Sample: Can't retrieve image information"); 
         return; 
      } 
      // Over here we can access the different properties of the DicomImageInformation class to get some 
      // of the image attributes such as bits allocated (DicomImageInformation. BitsAllocated) 
      RasterImage image = ds.GetImage(pixelDataElement, 
         0, 
         0, 
         RasterByteOrder.Gray, 
         DicomGetImageFlags.AllowRangeExpansion | DicomGetImageFlags.AutoApplyModalityLut | DicomGetImageFlags.AutoApplyVoiLut); 
 
      if (image == null) 
      { 
         Console.WriteLine("Sample: Can't retrieve image"); 
         return; 
      } 
 
      //If the image has more than one frame then we can call DicomDataSet.GetImages to get all the frames 
      using (DicomDataSet ds1 = new DicomDataSet()) 
      { 
         ds1.Initialize(DicomClassType.DXImageStoragePresentation, DicomDataSetInitializeType.ExplicitVRLittleEndian); 
         DicomElement pixelDataElement1 = ds1.FindFirstElement(null, DicomTag.PixelData, true); 
         if (pixelDataElement1 != null) 
         { 
            ds1.SetImage(pixelDataElement1, 
               image, 
               DicomImageCompressionType.None, 
               DicomImagePhotometricInterpretationType.Monochrome2, 
               16, 
               2, 
               DicomSetImageFlags.AutoSetVoiLut); 
            //If we have more than one frame then we can call DicomDataSet.SetImages 
 
            //This is an alternative way to set the image, I will first delete the 
            //existing image and then call DicomDataSet.InsertImage 
            ds1.DeleteElement(pixelDataElement1); 
            pixelDataElement1 = ds1.InsertElement(null, false, DicomTag.PixelData, DicomVRType.UN, false, 0); 
            ds1.InsertImage(pixelDataElement1, 
               image, 
               0, 
               DicomImageCompressionType.None, 
               DicomImagePhotometricInterpretationType.Monochrome2, 
               16, 
               2, 
               DicomSetImageFlags.AutoSetVoiLut); 
            //If we have more than one frame then we can call DicomDataSet.InsertImages 
 
            ds1.Save(Path.Combine(LEAD_VARS.ImagesDir, "DICOM", "Test.dcm"), DicomDataSetSaveFlags.None); 
 
         } 
      } 
      //Load DICOM File 
      ds.Load(dicomFileName, DicomDataSetLoadFlags.None); 
   } 
   DicomEngine.Shutdown(); 
} 
 
static class LEAD_VARS 
{ 
   public const string ImagesDir = @"C:\LEADTOOLS23\Resources\Images"; 
}