RZDCX - Fast Strike DICOM Toolkit  Release 2.0.7.4
IDCXOBJ Interface Reference

A DICOM Object Interface. More...

Inherits IDispatch.

Public Member Functions

HRESULT getElementByTag ([in] DICOM_TAG tag, [out, retval] IDCXELM **e)
 Get an element by its tag. More...
 
HRESULT createElement ([in] DICOM_TAG tag, [out, retval] IDCXELM **e)
 Creates a new element. More...
 
HRESULT insertElement ([in] IDCXELM *e)
 Inserts the element to the object.
 
HRESULT iterator ([out, retval] IDCXELMIterator **i)
 Get an iterator to go over the object elements. More...
 
HRESULT Dump ([in] BSTR filename)
 Write content to text file. More...
 
HRESULT openFile ([in] BSTR filePath)
 Read a DICOM Object from a file. More...
 
HRESULT saveFile ([in] BSTR storagePath)
 Write a DICOM Object to a file. More...
 
HRESULT GetPixelDataRef ([out, retval] unsigned __int3264 *pVal)
 Get the Pixel address. More...
 
HRESULT Decode ()
 Decode the Image. More...
 
HRESULT ClipImage ([in] int left, [in] int top, [in] int right, [in] int bottom, [in] int z, [out, retval] IDCXOBJ **o)
 Creates a new DCXOBJ with a region of the original image.
 
HRESULT insertNextElement ([in] IDCXELM *e)
 . Use insertElement.
 
HRESULT getNextSequence ([in] DICOM_TAG tag, [out, retval] IDCXOBJ **o)
 Returns a new sequence object for the tag. More...
 
HRESULT getElementsByTag ([in] DICOM_TAG tag, [out, retval] IDCXELMIterator **i)
 Get elements by tag. More...
 
HRESULT ReadBuffer ([in] int buffer, [in]long length)
 Read dicom data from a memory buffer. More...
 
HRESULT EncodeLosslessJpeg ()
 
HRESULT EncodeJpeg (long quality)
 
HRESULT MakePaletteColor (void)
 Converts a Color Image into a Palette Color Image.
 
HRESULT SaveAs ([in] BSTR filename, [in] TRANSFER_SYNTAX TransferSyntax, [in] int quality, [in] BSTR workDir)
 Save file with specific transfer syntax using temporary files for intermediate compressed frames buffers in low memory cases. More...
 
HRESULT SetJpegFrames ([in] BSTR filenames)
 Set the pixel data from one or more jpeg images (separate filenames by ;). More...
 
HRESULT SetBMPFrames ([in] BSTR filenames)
 Set the pixel data from one or more BITMAP images (separate filenames by ;). More...
 
HRESULT RemoveElement ([in] DICOM_TAG tag, [out, retval] IDCXELM **e)
 Remove an element. More...
 
HRESULT ScaleImage ([in] int newWidth, [in] int newHeight)
 Scale Image.
 
HRESULT ReadBufferEx ([in] unsigned __int3264 bufPtr, [in] unsigned int bufLen)
 Same as ReadBuffer but compatible with x64 pointers.
 
HRESULT GetEncapsulatedFrameLength ([in] long frameNumber, [out, retval] long *length)
 Get the length in bytes of a frame. More...
 
HRESULT GetEncapsulatedFrameData ([in] long frameNumber, [in] unsigned __int3264 bufPtr, [in] long bufLen)
 Get the data of one encapsulated frame. More...
 
HRESULT GetEncapsulatedFrameRef ([in] long frameNumber, [out] unsigned __int3264 *ptr, [out, retval] long *length)
 Get a reference to the memory of one encapsulated frame. More...
 
HRESULT Write ([in] IStream *stream)
 Write the object to an IStream.
 
HRESULT GetElement ([in] DICOM_TAG tag, [out, retval] IDCXELM **e)
 Similar to IDCXOBJ::getElementByTag but doesn't throw exception if element not found If Element found, get it (return S_OK), else get NULL (return S_FALSE) More...
 
HRESULT SetVideoStream ([in] BSTR filename, [in] ENCAPSULATED_VIDEO_PROPS props)
 Convert MPEG to DICOM. More...
 

Properties

long FrameCount [get]
 Get the number of frames in the image.
 
TRANSFER_SYNTAX TransferSyntax [set]
 Set the transfer syntax. This method is usful in combination with saveFile. For an example look at CPPCeateImageExample. More...
 
IDCXOBJ FileMetaInfo [get, set]
 Set/Get DICOM File Meta Information. More...
 
VARIANT_BOOL FileMetaInfoExists [get]
 Check if file meta info was loaded with the file or previously set using the FileMetaInfo property (put). More...
 
IDCXIMG Image [get, set]
 Set/Get DCXIMG object More...
 

Detailed Description

A DICOM Object Interface.

The DICOM Object is one of the core interfaces of RZDCX SDK. It is used to read, write, create and modify DICOM Objects.

Member Function Documentation

◆ createElement()

HRESULT IDCXOBJ::createElement ( [in] DICOM_TAG  tag,
[out, retval] IDCXELM **  e 
)

Creates a new element.

Use this method to create new DICOM elements. This method is actually identical to IDCXELM::Init. The element is not added to the object. To add it, use insertElement after the element data is set.

Returns
a IDCXELM with no data.

◆ Decode()

HRESULT IDCXOBJ::Decode ( )

Decode the Image.

This method changes the internal representation of the pixel data from compressed to uncompressed.

◆ Dump()

HRESULT IDCXOBJ::Dump ( [in] BSTR  filename)

Write content to text file.

Parameters
filenameFilename to write to (overwritten)

◆ EncodeJpeg()

HRESULT IDCXOBJ::EncodeJpeg ( long  quality)
DICOM Conformance:
Saved file has transfr syntax: 1.2.840.10008.1.2.4.50
Parameters
quality0..100 (best) Quality

◆ EncodeLosslessJpeg()

HRESULT IDCXOBJ::EncodeLosslessJpeg ( )
DICOM Conformance:
Saved file has transfr syntax: 1.2.840.10008.1.2.4.70

◆ GetElement()

HRESULT IDCXOBJ::GetElement ( [in] DICOM_TAG  tag,
[out, retval] IDCXELM **  e 
)

Similar to IDCXOBJ::getElementByTag but doesn't throw exception if element not found If Element found, get it (return S_OK), else get NULL (return S_FALSE)

Returns
S_OK if element found, S_FALSE if element not found.

◆ getElementByTag()

HRESULT IDCXOBJ::getElementByTag ( [in] DICOM_TAG  tag,
[out, retval] IDCXELM **  e 
)

Get an element by its tag.

Get an element from the object by giving its DICOM_TAG. If element not found, throws an exception ("Element Not Found").

Returns
IDCXELM of the requested element.
See also
GetElement

◆ getElementsByTag()

HRESULT IDCXOBJ::getElementsByTag ( [in] DICOM_TAG  tag,
[out, retval] IDCXELMIterator **  i 
)

Get elements by tag.

Returns
IDCXELMIterator of the requested elements or NULL if not found

◆ GetEncapsulatedFrameData()

HRESULT IDCXOBJ::GetEncapsulatedFrameData ( [in] long  frameNumber,
[in] unsigned __int3264  bufPtr,
[in] long  bufLen 
)

Get the data of one encapsulated frame.

See GetEncapsulatedFrameLength

Parameters
frameNumberThe requested frame number
bufPtrA pointer to a pre-allocated buffer where the data should be copied to
bufLenThe length in bytes of bufPtr (the pre-allocated buffer)

◆ GetEncapsulatedFrameLength()

HRESULT IDCXOBJ::GetEncapsulatedFrameLength ( [in] long  frameNumber,
[out, retval] long *  length 
)

Get the length in bytes of a frame.

See GetEncapsulatedFrameData This method is useful when implementing a viewer for faster processing of encapsulated formats. For example if the object encapsulates a multi-frame jpeg sequence, you can use this call to extract the jpeg frames directly from the file into buffer and display them. There's an assumption here that the entire frame is stored in one fragment.

Parameters
frameNumberThe requested frame number
length(out) The length in bytes of the requested frame

◆ GetEncapsulatedFrameRef()

HRESULT IDCXOBJ::GetEncapsulatedFrameRef ( [in] long  frameNumber,
[out] unsigned __int3264 *  ptr,
[out, retval] long *  length 
)

Get a reference to the memory of one encapsulated frame.

This call is similar to GetEncapsulatedFrameData but instead of making a copy of the data it return a pointer to the internal memory of the object where the frame is stored. See GetEncapsulatedFrameLength and GetEncapsulatedFrameData

◆ getNextSequence()

HRESULT IDCXOBJ::getNextSequence ( [in] DICOM_TAG  tag,
[out, retval] IDCXOBJ **  o 
)

Returns a new sequence object for the tag.

Parameters
tagThe DICOM Tag of the Sequence
oOutput DICOM Object holding the

◆ GetPixelDataRef()

HRESULT IDCXOBJ::GetPixelDataRef ( [out, retval] unsigned __int3264 *  pVal)

Get the Pixel address.

Returns
pointer to pixel address

◆ iterator()

HRESULT IDCXOBJ::iterator ( [out, retval] IDCXELMIterator **  i)

Get an iterator to go over the object elements.

Returns
IDCXELMIterator

◆ openFile()

HRESULT IDCXOBJ::openFile ( [in] BSTR  filePath)

Read a DICOM Object from a file.

The content of the DICOM Object in the file is loaded into memory. Some elements with large data may be loaded partially to conserve memory. The data is loaded into memory when required but the file is not locked. When calling saveFile with the same file name that was used in openFile all data is first loaded into memory and only then the file is written again. If the file has a file meta information, it can be read using the FileMetaInfo property.

See also
FileMetaInfo, saveFile

◆ ReadBuffer()

HRESULT IDCXOBJ::ReadBuffer ( [in] int  buffer,
[in] long  length 
)

Read dicom data from a memory buffer.

Deprecated:
See ReadBufferEx

◆ RemoveElement()

HRESULT IDCXOBJ::RemoveElement ( [in] DICOM_TAG  tag,
[out, retval] IDCXELM **  e 
)

Remove an element.

The element content is returned If the element is not found, the method succeed and the output element is null

Parameters
tagThe tag of the element to remove
eThe element that was removed (if was found or null if not found)

◆ SaveAs()

HRESULT IDCXOBJ::SaveAs ( [in] BSTR  filename,
[in] TRANSFER_SYNTAX  TransferSyntax,
[in] int  quality,
[in] BSTR  workDir 
)

Save file with specific transfer syntax using temporary files for intermediate compressed frames buffers in low memory cases.

SaveAs uses temporary working directory to save the compressed frames instead of holding them in memory. When working with very large cine loops this will hold only 1-2 frames in memory. This method will work for the following transfer syntaxes:

  • TS_LOSSLESS_JPEG_DEFAULT
  • TS_JPEG
    Postcondition
    The work directory may be full with temporary files. Caller should consider deleting the files after calling this method.
Parameters
filenameThe DICOM file name to save
TransferSyntaxThe transfer syntax to use
quality0..100 (best) Quality, when relevant (for jpeg lossy)
workDirA directory that can be used to save temporary files in order not to take to much memory

◆ saveFile()

HRESULT IDCXOBJ::saveFile ( [in] BSTR  storagePath)

Write a DICOM Object to a file.

If the FileMetaInfo was set, then it is used, otherwise a new file meta information is created. If the object was opened from file using openFile, then the FileMetaInfo of the new file will be different then the one written by this method.

See also
FileMetaInfo, saveFile

◆ SetBMPFrames()

HRESULT IDCXOBJ::SetBMPFrames ( [in] BSTR  filenames)

Set the pixel data from one or more BITMAP images (separate filenames by ;).

See also
SetJpegFrames
Postcondition
All attributes
Parameters
filenames; separated bitmap files list

◆ SetJpegFrames()

HRESULT IDCXOBJ::SetJpegFrames ( [in] BSTR  filenames)

Set the pixel data from one or more jpeg images (separate filenames by ;).

This method sets the pixel data and related elements (rows, columns, number of frames, transfer syntax ...) from jpeg images. The object that is created is a Secondary Capture object. If the filenames parameter contain multiple filenames separated by ;, then the object that is created is a multiframe object. All the images must have the same attributes of size (rows and columns), color sapce, compression (baseline, progressive) and quality.

Postcondition
All attributes
Parameters
filenames; separated jpeg files list

◆ SetVideoStream()

HRESULT IDCXOBJ::SetVideoStream ( [in] BSTR  filename,
[in] ENCAPSULATED_VIDEO_PROPS  props 
)

Convert MPEG to DICOM.

Insert MPEG2/MPEG4 video stream as encapsulated format pixel data. Use this method to convert MPEG2/MPEG4 video stream to DICOM. The video stream is not parsed or validated. User provides information about resolution and encoding through the ENCAPSULATED_VIDEO_PROPS structure. DICOM allows MPEG2 and MPEG4 encoding in four transfer syntaxes. Transfer syntax is determined by VIDEO_FORMAT property. The video file should be left on disk until the object is disposed.

Parameters
filenameFilename of video file
propsVideo Stream Properties

Property Documentation

◆ FileMetaInfo

IDCXOBJ IDCXOBJ::FileMetaInfo
getsetproperty

Set/Get DICOM File Meta Information.

Note
The get property requires special license and is not included in the default license. For more information please contact us.

There is no validation of the set File Meta Information content. It should be valid and in particular match the transfer syntax of the object. When setting File Meta Information, only elements of group 0002 are inserted. All other elements are discarded.

For objects that were not read from file (e.g. recived through network or created programatically) there's no File Meta Information unless explicitly set. Calling the get property for these objects returns null (with HRESULT S_FALSE).

The File Meta Information includes identifying information on the encapsulated Data Set. This header consists of a 128 byte File Preamble, followed by a 4 byte DICOM prefix, followed by the File Meta Elements shown in Table 7.1-1 of the DICOM Standard chapter 10 (see for example ftp://medical.nema.org/medical/dicom/2009/09_10pu.pdf) The value returned by the FileMetaInfo property is a DCXOBJ that is a copy of the file meta info. This DICOM object can be modified like any other DICOM Object. You should only set elements of group 0002 into this object and that there's no validations on that. The set property copies all data elements of group 0002 from the provided object to the file meta information of the object. If the transfer syntax in the new file meta information is different then the current one, this will lead to representation change in the same way as setting the TransferSyntax property.

According to the DICOM Standard, the file meta info identifies the application that created the file, thus when reading a file using loadFile and then writing it back using saveFile, the original meta info is replaced with a new one carrying the information of the creating application.

According to the above, when reading information from a file, the get property returns original file meta info from the file that was opened but when calling saveFile a new file meta info is generated.

If the set property was called before the saveFile then this file meta header will be used.

See also
openFile, saveFile

◆ FileMetaInfoExists

VARIANT_BOOL IDCXOBJ::FileMetaInfoExists
get

Check if file meta info was loaded with the file or previously set using the FileMetaInfo property (put).

This is a simple helper property to prevent cases when an exeption is thrown when using C++ COM Auto Pointers that throws exceptions when interface is not returned.

◆ Image

IDCXIMG IDCXOBJ::Image
getsetproperty

Set/Get DCXIMG object

When the image is set back, only the image pixel group elements (group 0028 are set)

◆ TransferSyntax

TRANSFER_SYNTAX IDCXOBJ::TransferSyntax
setproperty

Set the transfer syntax. This method is usful in combination with saveFile. For an example look at CPPCeateImageExample.