ILTDicWrt Interface

This is the interface for the LEAD DICOM Writer.

Interface Properties

HRESULT put_DICOMTemplateFile(const OLECHAR *pszFileName)

Parameters

pszFileName

Pointer to an OLECHAR string that contains the input DICOM template file.

Description

Use this function to specify an input template file name. The template file will be used to fill all of the data elements except for the ImagePixel element, which will be filled from the source stream. This function does not affect DICOM file creation when it is done by inserting one’s own DICOM dataset using the SetDicomDS() function. To use the assigned DICOM class as a source for all data elements except for the ImagePixel data if no user data has been set, set pszFileName to NULL so the function will set the input template file name to blank. The function fails under the following conditions:

during streaming
if the file does not exist
if the file is not a valid DICOM File
if the length of the file name exceeds 260 characters.

Returns

S_OK	SUCCESS
< 0	An error occurred.

HRESULT get_DICOMTemplateFile(OLECHAR **ppszFileName)

Parameters

ppszFileName

Address of a pointer to the returned DICOM input template file name.

Description

Retrieves the file name of the input template. The function allocates memory for this pointer. It is the responsibility of the user to free it using SysFreeString().

Returns

S_OK	SUCCESS
< 0	An error occurred.

HRESULT put_OutputFileName(const OLECHAR *pszFileName)

Parameters

pszFileName

Pointer to an OLECHAR string that contains the name of the output DICOM template file.

Description

Sets the name of the file to which the DICOM dataset will be saved.

If pszFileName is NULL, the function sets the output file name to blank. At save time if the output file name is blank, a temporary file name is generated and the user is informed about it. The output file name can be the same as the input template file name. If the output file already exists, its contents will be replaced. The function fails under the following conditions:

during streaming
if the length of the file name exceeds 260 characters.

Returns

S_OK	SUCCESS
< 0	An error occurred.

HRESULT get_OutputFileName(OLECHAR **ppszFileName)

Parameters

ppszFileName

Address of a pointer to the returned DICOM output file name.

Description

Retrieves the output file name. The function allocates memory for this pointer and it is the user responsibility to free it using SysFreeString().

Returns

S_OK	SUCCESS
< 0	An error occurred.

HRESULT put_DefaultDICOMClass(int nDICOMClass)

Parameters

nDICOMClass	The class type of the dataset to be initialized. Possible values depend on whether the input stream is MPEG2, as follows:
	Input Stream is MPEG2	Input Stream is not MPEG2
	VL_ENDOSCOPIC_IMAGE_STORAGE	NM_IMAGE_STORAGE
	VL_MICROSCOPIC_IMAGE_STORAGE	US_MULTI_FRAME_IMAGE_STORAGE
	VL_PHOTOGRAPHIC_IMAGE_STORAGE	XA_IMAGE_STORAGE
	SC_MULTI_FRAME_TRUE_COLOR_IMAGE_STORAGE	XRF_IMAGE_STORAGE
		SC_MULTI_FRAME_GRAYSCALE_BYTE_IMAGE_STORAGE
		SC_MULTI_FRAME_GRAYSCALE_WORD_IMAGE_STORAGE
		SC_MULTI_FRAME_TRUE_COLOR_IMAGE_STORAGE
		UNKNOWN

Description

Sets the default DICOM class that will be used to set the DICOM output file data elements except for the ImagePixel data. This function will not affect the DICOM file creation if you insert your own DICOM dataset using the SetDicomDS() function, or if the input template file is set.

This function always fails during streaming.

Returns

S_OK	SUCCESS
< 0	An error occurred.

HRESULT get_DefaultDICOMClass(int *nDICOMClass)

Parameters

nDICOMClass	Pointer to a variable that will receive the class type used to initialize the DICOM dataset. Possible values depend on whether the input stream is MPEG2, as follows:
	Input Stream is MPEG2	Input Stream is not MPEG2
	VL_ENDOSCOPIC_IMAGE_STORAGE	NM_IMAGE_STORAGE
	VL_MICROSCOPIC_IMAGE_STORAGE	US_MULTI_FRAME_IMAGE_STORAGE
	VL_PHOTOGRAPHIC_IMAGE_STORAGE	XA_IMAGE_STORAGE
	SC_MULTI_FRAME_TRUE_COLOR_IMAGE_STORAGE	XRF_IMAGE_STORAGE
		SC_MULTI_FRAME_GRAYSCALE_BYTE_IMAGE_STORAGE
		SC_MULTI_FRAME_GRAYSCALE_WORD_IMAGE_STORAGE
		SC_MULTI_FRAME_TRUE_COLOR_IMAGE_STORAGE
		UNKNOWN

Description

Retrieves the DICOM class used to construct the output file data elements except for the ImageData element. If nDICOMClass is NULL the function fails.

Returns

S_OK	SUCCESS
< 0	An error occurred.

***HRESULT get_InputPinStreamingState(int * pbStreaming)***

Parameters

pbStreaming	Pointer to a variable that will receive the streaming state of the input pin. Possible values are:
	Value	Meaning
	TRUE	The input pin is streaming.
	FALSE	The input pin is stopped.

Description

Retrieves the input pin streaming state.

Returns

S_OK	SUCCESS
< 0	An error occurred.

HRESULT get_DicomDS(long * pDS)

Parameters

pDS	Address of a pointer to the returned dataset.

Description

Retrieves the currently initialized DICOM dataset. Typecast this pointer to LDicomDS before using it. Be careful not to use this DICOM dataset if it becomes invalid or after it is destroyed. If you insert your own DICOM dataset into the filter using the SetDicomDS() function with the bCopy flag set to FALSE, it is safe to use this dataset even after the termination of the filter, since the filter will not destroy the original, user-defined DICOM dataset.

Returns

S_OK	SUCCESS
< 0	An error occurred.

HRESULT put_CompressionFormat(int nFormat)

Parameters

nFormat	An integer enumerator that sets the compression type for the pixel data in the DICOM file. Possible values are:
	Value	Meaning
	COMP_UNCOMPRESSED	Do not use compression.
	COMP_LOSSLESSJPEG	Use lossless JPEG compression.
	COMP_JPEG422	Use JPEG 4:2:2 compression.
	COMP_JPEG2000	Use JPEG 2000 compression.
	COMP_LOSSLESSJPEG2000	Use Lossless JPEG 2000 compression.

Description

This function sets the compression type to be used for the pixel data in the DICOM file. The allowed compression types are JPEG lossless, JPEG 4:2:2, and uncompressed. The JPEG lossless and JPEG 4:2:2 compression types need either the YUY2, or UYVY input media type.

Returns

S_OK	SUCCESS
E_INVALIDARG	The input pointer is invalid.

HRESULT get_CompressionFormat(int *pnFormat)

Parameters

pnFormat	An integer enumerator that indicates which compression type for the pixel data in the DICOM file is being used. Possible values are:
	Value	Meaning
	COMP_UNCOMPRESSED	No compression is being used.
	COMP_LOSSLESSJPEG	Lossless JPEG compression is being used.
	COMP_JPEG422	JPEG 4:2:2 compression is being used.
	COMP_JPEG2000	JPEG 2000 compression is being used.
	COMP_LOSSLESSJPEG2000	Lossless JPEG 2000 compression is being used.

Description

This function returns a value that indicates which compression type is being used for the pixel data in the DICOM file.

Returns

S_OK	SUCCESS
E_FAIL.	An error occurred.

HRESULT put_CompressionQuality(int nQFactor)

Parameters

nQFactor

An integer value that represents the compression quality to be used for the file.

Description

Sets the compression quality that will be used. The compression quality is the factor that balances the compression ratio with the quality: more compression means less quality. Possible values range from 2 to 255. Values out of this range will be rejected. An nQFactor of 2 has the highest quality and lowest compression ratio. As the nQFactor increases, the quality decreases and the compression ratio increases. A nQFactor of 255 has the lowest quality and highest compression ratio.

Returns

S_OK	SUCCESS
E_INVALIDARG.	The input pointer is invalid.

HRESULT get_CompressionQuality(int *pnQFactor)

Parameters

pnQFactor

Pointer to an integer value that indicates what compression quality factor is being used.

Description

Gets a pointer to a value that indicates what compression quality is being used for the file. The compression quality is the factor that balances the compression ratio with the quality: more compression means less quality. Possible values range from 2 to 255. Values out of this range will be rejected. An nQFactor of 2 has the highest quality and lowest compression ratio. As the nQFactor increases, the quality decreases and the compression ratio increases. An nQFactor of 255 has the lowest quality and highest compression ratio.

Returns

S_OK	SUCCESS
E_INVALIDARG.	The input pointer is invalid.

HRESULT put_MPEG2DicomCompatibilityOption(MPEG2DicomCompatibilityConstants newVal)

Parameters

newVal	An enumerated value that specifies how to handle MPEG2 encoder Also known as compressor Also known as an encoder, this is a module or algorithm to compress data. Playing that data back requires a decompressor, or decoder., this is a module or algorithm to compress data. Playing that data back requires a decompressor, or decoder Also known as a decompressor, this is a module or algorithm to decompress data.. settings. Possible values are:
	Value	Meaning
	MPEG2DICOMCOMP_FORCE	Force MPEG2 encoder settings to be compatible with the MPEG2 DICOM standard.
	MPEG2DICOMCOMP_IGNORE	Do not change the MPEG2 encoder settings if they are not compatible with the MPEG2 DICOM standard.
	MPEG2DICOMCOMP_STOPGRAPH	Stop the graph if the MPEG2 encoder settings are not compatible with the MPEG2 DICOM standard.

Description

Sets the MPEG2 DICOM compatibility option, which specifies how to handle MPEG2 encoder settings that conflict with the DICOM standard.

Returns

S_OK	SUCCESS
E_INVALIDARG	The input pointer is invalid.

**HRESULT get_MPEG2DicomCompatibilityOption(MPEG2DicomCompatibilityConstants *pVal)**

Parameters

pVal	A pointer to an enumerated value that specifies how MPEG2 encoder settings are being handled. Possible values are:
	Value	Meaning
	MPEG2DICOMCOMP_FORCE	Force MPEG2 encoder settings to be compatible with the MPEG2 DICOM standard.
	MPEG2DICOMCOMP_IGNORE	Do not change the MPEG2 encoder settings if they are not compatible with the MPEG2 DICOM standard.
	MPEG2DICOMCOMP_STOPGRAPH	Stop the graph if the MPEG2 encoder settings are not compatible with the MPEG2 DICOM standard.

Description

Gets a value which specifies how to handle MPEG2 encoder settings that conflict with the DICOM standard.

Returns

S_OK	SUCCESS
E_POINTER	An error occurred.

Interface Methods:

HRESULT SetDicomDS(long pDS, long pPixelData, int bAutoSave, int bCopy)

Parameters

pDS	Pointer to the user dataset. This pointer must be allocated or created through LEADTOOLS version 14 or 14.5 binaries, otherwise calls to this method or subsequent calls to other methods inside this interface will fail and in some cases will have an undefined behavior.
pPixelData	Pointer to the PixelData element in the user dataset. If this parameter is NULL, then the filter will find the first PixelData element automatically, and save the input stream to it.
bAutoSave	Value that specifies whether the filter should save the DICOM dataset to a file or just fill the DICOM dataset with the frames (in which case it is the responsibility of the user to save the dataset or do whatever needs to be done with it). Possible values are:
	Value	Meaning
	TRUE	Save the DICOM dataset to a file.
	FALSE	Fill the DICOM dataset with the frames.
bCopy	Value that specifies whether the filter should make a copy of the passed dataset for future usage. Possible values are:
	Value
	TRUE	The filter will make a copy of the dataset, allocating memory for it and maintaining responsibility for freeing this memory.
	FALSE	The user will take care of the pointer life (and ensure its availability for the Writer as long as it is needed).

Description

Sets the DICOM dataset. This function may fail if it cannot find or insert the PixelData element into the passed dataset. This function always fails during streaming.

Call this method with pDS set to NULL:

when the filter no longer needs to use the passed dataset
before freeing the dataset's memory.

The DICOM dataset passed to this method must be a LEADTOOLS Version 14 or 14.5 dataset. What this means is pDS must be allocated or created through LEADTOOLS version 14 or 14.5 binaries, otherwise calls to this method or subsequent calls to other methods inside this interface will fail and in some cases will have an undefined behavior.

In general it is not recommended to pass a pointer to a DICOM dataset to an ILTDicWrt Interface. The better approach is to use file names through calls to the put_DICOMTemplateFile and put_OutputFileName methods. When using file names, you can create a template DICOM file populated with the required information (like patient name and ID) and then pass the template to this interface by calling put_DICOMTemplateFile. An alternative method is to populate the resultant DICOM dataset with the proper information at any time and not necessarily before the video and audio data gets captured, below is a list of suggested steps to achieve that:

It is assumed that we already have a DICOM dataset that will get populated with DICOM information before, after or during the capture process. Let’s call this dataset “InputDataSet”.
Create a template DICOM file that doesn’t include any DICOM elements except for Transfer Syntax UID (0002,0010) .You can achieve this by using one of the demos that ship with LEADTOOLS or programmatically by initializing a DICOM dataset of type unknown (CLASS_UNKNOWN) and then saving the dataset as a template.
Call put_DICOMTemplateFile and pass it the name of the template file created in the previous step.
Call put_OutputFileName and pass it a temporary file name (let’s call it “DicomVideoOutput.dcm”).
Capture the video and optionally the audio data into the output file (“DicomVideoOutput.dcm”).
Load “DicomVideoOutput.dcm” into a DICOM dataset, let’s call it “OutputDataSet”.
Copy all the DICOM elements from “InputDataSet” to “OutputDataSet” by calling CopyDS, make sure “OutputDataSet” is the destination and “InputDataSet” is the source.
Now “OutputDataSet” will include both the video (and optionally audio) data and the required DICOM information.

Returns

S_OK	SUCCESS
< 0	An error occurred.

HRESULT LockDicomDS(int bLock)

Parameters

bLock	Value that indicates whether to lock or unlock the dataset. Possible values are:
	Value	Meaning
	TRUE	Lock the dataset.
	FALSE	Unlock the dataset.

Description

Locks or unlocks the currently initialized DICOM dataset. Locking the dataset will prevent the filter from making any changes to it. If the dataset is not initialized this function will fail unless the dataset is user-defined. Use this feature to block adding any frames to the dataset while streaming.

Returns

S_OK	SUCCESS
< 0	An error occurred.