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 compressed in MPEG2 or H.264/AVC, as follows:
	Input Stream is compressed in MPEG2 or H.264/AVC	Input Stream is not compressed in MPEG2 or H.264/AVC
	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
		DEFAULT

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 compressed in MPEG2 or H.264/AVC, as follows:
	Input Stream is compressed in MPEG2 or H.264/AVC	Input Stream is not compressed in MPEG2 or H.264/AVC
	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
		DEFAULT

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 the 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 the encoder settings when the input stream is MPEG-2, MPEG-2 Transport or ISO(MP4). Possible values are:
	Value	Meaning if input stream is MPEG-2 with MPEG2 Compression	Meaning if input stream is MPEG-2 Transport or ISO(MP4) with H.264/AVC Compression
	MPEG2DICOMCOMP_FORCE	Force MPEG2 encoder settings to be compatible with the MPEG2 DICOM standard.	Force H264 encoder settings to be compatible with the MPEG2 Transport or ISO(MP4) DICOM standard. Force AAC encoder settings to be compatible with the MPEG2 Transport or ISO(MP4) DICOM standard, if the encoder was used. Force AC3 encoder settings to be compatible with the MPEG2 Transport DICOM standard, if the encoder was used.
	MPEG2DICOMCOMP_IGNORE	Do not change the MPEG2 encoder settings if they are not compatible with the MPEG2 DICOM standard.	Do not change the H264 encoder settings if they are not compatible with the MPEG2 Transport or ISO(MP4) DICOM standard. Do not change AAC or AC3 encoders settings if they were selected and not compatible with MPEG2 Transport or ISO(MP4).
	MPEG2DICOMCOMP_STOPGRAPH	Stop the graph if the MPEG2 encoder settings are not compatible with the MPEG2 DICOM standard.	Stop the graph if the H264 video encoder or any of the selected audio encoders settings are not compatible with the MPEG2 Transport or ISO(MP4) DICOM standard.

Description

Sets the MPEG2 DICOM compatibility option, which specifies how to handle MPEG2/H.264/AAC/AC3 encoders 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 encoder settings are being handled when the input stream is MPEG-2, MPEG-2 Transport or ISO(MP4). Possible values are:
	Value	Meaning if input stream is MPEG-2 with MPEG2 Compression	Meaning if input stream is MPEG-2 Transport or ISO(MP4) with H.264/AVC Compression
	MPEG2DICOMCOMP_FORCE	Force MPEG2 encoder settings to be compatible with the MPEG2 DICOM standard.	Force H264 encoder settings to be compatible with the MPEG2 Transport DICOM standard. Force AAC encoder settings to be compatible with the MPEG2 Transport or ISO(MP4) DICOM standard, if the encoder was used. Force AC3 encoder settings to be compatible with the MPEG2 Transport DICOM standard, if the encoder was used.
	MPEG2DICOMCOMP_IGNORE	Do not change the MPEG2 encoder settings if they are not compatible with the MPEG2 DICOM standard.	Do not change the H264 encoder settings if they are not compatible with the MPEG2 Transport DICOM standard. Do not change AAC or AC3 encoders settings if they were selected and not compatible with MPEG2 Transport or ISO(MP4). Accept video or audio compression settings even if they were not compatible with DICOM standards.
	MPEG2DICOMCOMP_STOPGRAPH	Stop the graph if the MPEG2 encoder settings are not compatible with the MPEG2 DICOM standard.	Stop the graph if the H264 video encoder or any of the selected audio encoders settings are not compatible with the MPEG2 Transport DICOM standard.

Description

Gets a value which specifies how to handle MPEG2/H.264/AAC/AC3 encoders encoder settings that conflict with the DICOM standard.

Returns

S_OK	SUCCESS
E_POINTER	An error occurred.

HRESULT get_RasterVersion(int *pnVersion)

Parameters

pnVersion

Pointer to an integer value that indicates which version of the LEADTOOLS raster toolkit is being used.

Description

Gets the version of the raster toolkit that is used by the DICOM writer. The possible values are:

0	The supporting LEADTOOLS raster DLLs are missing. The DICOM writer will not be able to create any files.
15	LEADTOOLS 15 DLLs are being used (LTDIC15U.DLL, etc)
16	LEADTOOLS 16.5 DLLs are being used (LTDICU.DLL, etc)
17	LEADTOOLS 17 DLLs are being used (LTDICU.DLL, etc)

Returns

S_OK	SUCCESS
E_INVALIDARG.	The input pointer is invalid.

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:

1. Assume we already have a DICOM dataset that will get populated with DICOM information before, after or during the capture process. Call this dataset -InputDataSet-.

2. Create a template DICOM file that doess not include any DICOM elements except for the Transfer Syntax UID (0002,0010).You can either use one of the demos that ship with LEADTOOLS, or initialize your own DICOM dataset of type unknown (CLASS_UNKNOWN) and then save the dataset as a template.

3. Call put_DICOMTemplateFile and pass it the name of the template file created in the previous step.

4. Call put_OutputFileName and pass it a temporary file name (for instance, -DicomVideoOutput.dcm-).

5. Capture the video and optionally the audio data into the output file (-DicomVideoOutput.dcm-).

6. Load -DicomVideoOutput.dcm- into a DICOM dataset. Call it -OutputDataSet-.

7. Copy all of the DICOM elements from -InputDataSet- to -OutputDataSet- by calling CopyDS. Make sure -OutputDataSet- is the destination and -InputDataSet- is the source.

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

This filter is included as part of the following modules:

LEADTOOLS Medical Multimedia Module