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)
	\depracated. 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)

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...

HRESULT	EncodeJpeg2000 ([in] double compress_ratio)

HRESULT	SetJ2kFrames ([in] BSTR filenames, [in] TRANSFER_SYNTAX transferSynayax)
	Set the pixel data from one or more jpeg images (separate filenames by ;). More...

Properties
long	FrameCount `[get]`
	Get the number of frames in the image. More...

TRANSFER_SYNTAX	TransferSyntax `[set]`
	Set the transfer syntax. This method is usful in combination with saveFile. For an example look at CPPCeateImageExample.

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]`
	\breif Set/Get DCXIMG object More...

ENCAPSULATED_J2K_PROPS	J2KProps `[get]`
	Get ENCAPSULATED_J2K_PROPS structure. More...

Detailed Description

A DICOM Object Interface.

DICOM Object. Use this API to 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

filename Filename 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

quality 0..100 (best) Quality

◆ EncodeJpeg2000()

HRESULT IDCXOBJ::EncodeJpeg2000 ( [in] double compress_ratio )

DICOM Conformance:

Saved file has transfr syntax: 1.2.840.10008.1.2.4.90 or ...91

if compress_ratio==1 or 0, we use reversible wavelet transform CDF 5/3. Otherwise we use irreversible transform CDF 7/9

◆ 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

◆ getNextSequence()

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

Returns a new sequence object for the tag.

Parameters

tag	The DICOM Tag of the Sequence
o	Output 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

tag	The tag of the element to remove
e	The 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

filename	The DICOM file name to save
TransferSyntax	The transfer syntax to use
quality	0..100 (best) Quality, when relevant (for jpeg lossy)
workDir	A 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

◆ SetJ2kFrames()

HRESULT IDCXOBJ::SetJ2kFrames	(	[in] BSTR	filenames,
		[in] TRANSFER_SYNTAX	transferSynayax
	)

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

This method sets the pixel data of the DICOM object from JPEG 2000 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. The user specifies one of the four JPEG2000 related TX, and if lossless-only was chosen for a lossy image, the TX is fixed (s.t lossless images are allowed with lossy&lossless TX).

Parameters

filenames	; separated jpeg files list
transferSynayax	transfer syntax to use

◆ 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

filename	Filename of video file
props	Video 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.

◆ FrameCount

long IDCXOBJ::FrameCount

get

Get the number of frames in the image.

Calculates the number of frames encoded in the data of the PixelData element. The result may differ from the value that is set in the Number of Frames data element value (0028,0008). In the table bellow, for encapsulated pixel data: C - Number of items in pixel data sequence T - Number of values in offset table (length/4) NoF - Number of frames in (0028,0008) F - Fragmented E - Error

Offset Table |      NoF     | Is Fragmented | Result | C    | Is error

---------— | -----— | ----------— | ---— | -— | ------— Zero length | No value | (C>2)? | 1 | C>-2 | False
Zero length | N | False | C-1 | C>=2 | N!=C-1?
T | No value | (T<C)? | T | C>=2 | T>C-1?
T | N | (T<C)? | T | C>=2 | N!=T OR T>C-1

For native format divide pixel data length by frame size in bytes

Returns: The number of frames encoded in the object.

◆ Image

IDCXIMG IDCXOBJ::Image

getsetproperty

\breif Set/Get DCXIMG object

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

◆ J2KProps

ENCAPSULATED_J2K_PROPS IDCXOBJ::J2KProps

getproperty

Get ENCAPSULATED_J2K_PROPS structure.

When the DICOM object includes JPEG 2000 compressed images

Public Member Functions

Properties

Detailed Description

Member Function Documentation

◆ createElement()

◆ Decode()

◆ Dump()

◆ EncodeJpeg()

◆ EncodeJpeg2000()

◆ EncodeLosslessJpeg()

◆ GetElement()

◆ getElementByTag()

◆ getElementsByTag()

◆ getNextSequence()

◆ GetPixelDataRef()

◆ iterator()

◆ openFile()

◆ ReadBuffer()

◆ RemoveElement()

◆ SaveAs()

◆ saveFile()

◆ SetBMPFrames()

◆ SetJ2kFrames()

◆ SetJpegFrames()

◆ SetVideoStream()

Property Documentation

◆ FileMetaInfo

◆ FileMetaInfoExists

◆ FrameCount

◆ Image

◆ J2KProps