In This Topic ▼

ILTDicWrt Interface

This is the interface for the LEAD DICOM Writer.

Data Types

MPEG2DicomCompatibilityConstants

Summary

Lists the possible values for the MPEG2DICOM compatibility constants.

Syntax

typedef enum  
{ 
   MPEG2DICOMCOMP_FORCE, 
   MPEG2DICOMCOMP_IGNORE, 
   MPEG2DICOMCOMP_STOPGRAPH, 
} MPEG2DicomCompatibilityConstants;

Enumeration	Description
MPEG2DICOMCOMP_FORCE	Force encoder settings to be compatible with the MPEG2 DICOM standard.
MPEG2DICOMCOMP_IGNORE	Do not change the encoder settings if they are not compatible with the MPEG2 DICOM standard.
MPEG2DICOMCOMP_STOPGRAPH	Stop the graph if the encoder settings are not compatible with the MPEG2 DICOM standard.

DICOMCOMPRESSION

Summary

Lists the possible values for the compression types used in DICOM file's pixel data.

Syntax

typedef enum  
{ 
   COMP_UNCOMPRESSED, 
   COMP_JPEG422, 
   COMP_LOSSLESSJPEG, 
   COMP_JPEG2000, 
   COMP_LOSSLESSJPEG2000, 
} DICOMCOMPRESSION;

Enumeration	Description
COMP_UNCOMPRESSED	Do not use compression.
COMP_JPEG422	Use JPEG 4:2:2 compression.
COMP_LOSSLESSJPEG	Use lossless JPEG compression.
COMP_JPEG2000	Use JPEG 2000 compression.
COMP_LOSSLESSJPEG2000	Use Lossless JPEG 2000 compression.

DICOMCLASS

Summary

Lists Possible values for DICOM class types.

Syntax

typedef enum  
{ 
   NM_IMAGE_STORAGE, 
   US_MULTI_FRAME_IMAGE_STORAGE, 
   XA_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, 
   VL_ENDOSCOPIC_IMAGE_STORAGE, 
   VL_MICROSCOPIC_IMAGE_STORAGE, 
   VL_PHOTOGRAPHIC_IMAGE_STORAGE, 
   DEFAULT, 
   UNKNOWN, 
} DICOMCLASS;

Properties

Type	Name	Description
VARIANT_BOOL	IsMPEG2Stream	A read-only property that indicates whether the stream is MPEG multiplexed. A value of VARIANT_TRUE indicates that the stream is either MPEG-2, MPEG-4, or MPEG-TS. Otherwise, the value is VARIANT_FALSE.
LONG_PTR	DicomDSPtr	Retrieves the currently initialized DICOM dataset. Typecast this pointer to LDicomDS before using it. Do not make changes to the dataset after the filter is connected, since this might cause problems with the LEAD DICOM Writer. Use this property, instead of get_DicomDS, to obtain the dataset. It is compatible with both 32 and 64 bit platforms.

Methods

HRESULT SetDicomDSPtr(LONG_PTR newVal, LONG_PTR pPixelData, int bAutoSave, int bCopy);

Description

Sets the DICOM dataset inside the LEAD DICOM Writer filter.

Parameters

newVal

Pointer to the user dataset.

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

Comments

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

Call this method with newVal set to NULL:

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

Returns

Return	Description
S_OK	Successful.
< 0	An error occurred.

HRESULT put_DICOMTemplateFile(const OLECHAR *pszFileName)

Description

Specifies an input template file name.

Parameters

pszFileName

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

Comments

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 method does not affect DICOM file creation when it is done by inserting one's own DICOM dataset using the SetDicomDS() method. 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 method will set the input template file name to blank. The method fails under the following conditions:

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

Returns

Return	Description
S_OK	SUCCESS
< 0	An error occurred.

HRESULT get_DICOMTemplateFile(OLECHAR **ppszFileName)

Description

Retrieves the file name of the input template.

Parameters

ppszFileName

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

Comments

The method allocates memory for this pointer. It is the responsibility of the user to free it using SysFreeString().

Returns

Return	Description
S_OK	SUCCESS
< 0	An error occurred.

HRESULT put_OutputFileName(const OLECHAR *pszFileName)

Description

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

Parameters

pszFileName

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

Comments

If pszFileName is NULL, the method 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 method fails under the following conditions:

During streaming
The length of the file name exceeds 260 characters.

Returns

Return	Description
S_OK	SUCCESS
< 0	An error occurred.

HRESULT get_OutputFileName(OLECHAR **ppszFileName)

Description

Retrieves the output file name.

Parameters

ppszFileName

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

Comments

The method allocates memory for this pointer and it is the user responsibility to free it using SysFreeString().

Returns

Return	Description
S_OK	SUCCESS
< 0	An error occurred.

HRESULT put_DefaultDICOMClass(int nDICOMClass)

Description

Sets the default DICOM class that will be used to set the DICOM output file data elements except for the ImagePixel data.

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

Comments

This method will not affect the DICOM file creation if you insert your own DICOM dataset using the SetDicomDS() method, or if the input template file is set.

This method always fails during streaming.

Returns

Return	Description
S_OK	SUCCESS
< 0	An error occurred.

HRESULT get_DefaultDICOMClass(int *nDICOMClass)

Description

Retrieves the DICOM class used to construct the output file data elements except for the ImageData element.

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

Comments

If nDICOMClass is NULL the method fails.

Returns

Return	Description
S_OK	SUCCESS
< 0	An error occurred.

HRESULT get_InputPinStreamingState(int * pbStreaming)

Description

Retrieves the input pin streaming state.

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.

Returns

Return	Description
S_OK	SUCCESS
< 0	An error occurred.

HRESULT get_DicomDS(long * pDS)

Description

Retrieves the currently initialized DICOM dataset.

Parameters

pDS

Address of a pointer to the returned dataset.

Comments

Typecast pDS 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() method 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

Return	Description
S_OK	SUCCESS
< 0	An error occurred.

HRESULT put_CompressionFormat(int nFormat)

Description

Sets the compression type to be used for the pixel data in the DICOM file.

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.

Comments

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

Return	Description
S_OK	SUCCESS
E_INVALIDARG	The input pointer is invalid.

HRESULT get_CompressionFormat(int *pnFormat)

Description

Indicates which compression type is being used for the pixel data in the DICOM file.

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.

Returns

Return	Description
S_OK	SUCCESS
E_FAIL.	An error occurred.

HRESULT put_CompressionQuality(int nQFactor)

Description

Sets the compression quality that will be used.

Parameters

nQFactor

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

Comments

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

Return	Description
S_OK	SUCCESS
E_INVALIDARG.	The input pointer is invalid.

HRESULT get_CompressionQuality(int *pnQFactor)

Description

Gets the compression quality is being used for the file.

Parameters

pnQFactor

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

Comments

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

Return	Description
S_OK	SUCCESS
E_INVALIDARG.	The input pointer is invalid.

HRESULT put_MPEG2DicomCompatibilityOption(MPEG2DicomCompatibilityConstants newVal)

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.

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.

Returns

Return	Description
S_OK	SUCCESS
E_INVALIDARG	The input pointer is invalid.

HRESULT get_MPEG2DicomCompatibilityOption(MPEG2DicomCompatibilityConstants *pVal)

Description

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

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.

Returns

Return	Description
S_OK	SUCCESS
E_POINTER	An error occurred.

HRESULT get_RasterVersion(long *pVal)

Description

Gets the version of the raster toolkit that is used by the DICOM writer.

Parameters

pVal

Pointer to an long value that indicates which version of the LEADTOOLS raster toolkit is being used. The possible values are:

Value	Meaning
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, etc)
16	LEADTOOLS 16.5 DLLs are being used (LTDICU, etc)
17	LEADTOOLS 17 DLLs are being used (LTDICU, etc)

Returns

Return	Description
S_OK	SUCCESS
E_INVALIDARG.	The input pointer is invalid.

HRESULT ResetToDefaults();

Description

Resets the filter properties to their default values.

Returns

Return	Description
S_OK	Successful.
< 0	An error occurred.

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

Description

Sets the DICOM dataset.

Parameters

newVal

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

Comments

This method may fail if it cannot find or insert the PixelData element into the passed dataset. This method 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:

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-.
Create a template DICOM file that does 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.
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 (for instance, -DicomVideoOutput.dcm-).
Capture the video and optionally the audio data into the output file (-DicomVideoOutput.dcm-).
Load -DicomVideoOutput.dcm- into a DICOM dataset. Call it -OutputDataSet-.
Copy all of 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

Return	Description
S_OK	SUCCESS
< 0	An error occurred.

HRESULT LockDicomDS(int bLock)

Description

Locks or unlocks the currently initialized DICOM dataset.

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.

Comments

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

Returns

Return	Description
S_OK	SUCCESS
< 0	An error occurred.

This filter is included as part of LEADTOOLS Medical Module module.