Introduction to DicomObjects COM version

DicomObjects.COM.v8
Introduction to DicomObjects COM version

DicomObjects consists of an inter-related, but independent, set of “Objects” that enable developers quickly and easily to add DICOM functionality to their products without needing to understand or program the intricacies of the DICOM standard.
This help file provides full reference
Almost any aspect of DICOM image/data manipulation can be performed using DicomObjects, including:

  • Image display and manipulation
  • Network transmission of images and associated data, including worklists
  • Printing to DICOM and windows printers
  • Normalised operations including storage commitment
  • Image creation from scratch and import/export to/from non-DICOM formats

The main Components of the DicomObjects Collection are:

DicomViewer Control

An ActiveX control that may be embedded into any suitable control container such as Visual Basic, standard development environments such as C++ (Microsoft or Borland), Delphi, Microsoft Access, and can even be used in Internet Explorer. I t has extensive display capabilities for DICOM images, whether read from files, received over the network, or from numerous other sources, and these include a wide range of annotations, and full DICOM greyscale presentation state support.

It also provides service class provider (SCP) functionality for verification, storage, query/retrieve and normalised operations.

DicomServer Object

An automation object without a user interface that provides storage, query/retrieve and normalised facilities as a service class provider (SCP).

DicomQuery Object

A non-visual automation object that handles the query/retrieve parts of the DICOM standard as a service class user (SCU).

DicomPrint Object

An automation object that simplifies DICOM printing as a service class user (SCU).

DicomGlobal Object

Used for certain global operations such as over-riding registry values

DicomConnection Object

A DicomConnection Object represents an association, and may either be created automatically in response to an incoming query request, or explicitly by the client program. Methods of this object are used to send data, images, and verification requests, and this object is central to DicomObject’s asynchronous operation capabilities. As of version 4.1, there is also a DicomConnections collection.

Other dependent automation objects and collections are created and used by the above, and some may also be created directly. They are:

Object Description | Single Item | Collection
SOP instance, containing an image | DicomImage | DicomImages
Generic SOP instance, used for results of DICOM queries or as a sub-element of a Sequence | DicomDataSet | DicomDataSets
Attribute (Data Element) of either of the above | DicomAttribute | DicomAttributes
DICOM Presentation context | DicomContext | DicomContexts
Image Annotation | DicomLabel | DicomLabels

© 2016 Medical Connections Ltd

Send feedback


Version 8 Release Notes

DicomObjects.COM.v8
Version 8 Release Notes

This new version of DicomObjects COM consolidates numerous incremental changes and cleans up some of the unused remnants, as well as adding significant new features, the main one being the 2D and 3D GPU rendering. The main changes are:

2D/3D GPU rendering using DirectX (HLSL)

The big advancement in this version is the GPU powered 2D and 3D rendering of images, which not only makes it a more stable option but also has a massive performance improvement with very impressive test results. Few fundamental changes to the rendering process are:

  • 3D images now have a single class, and hence it is possible to move between the types (MPR, Slab, MIP & VR) by changing the Mode property, without remaking the object.
  • A DicomVolume object can be used to make multiple 3D image objects, improving memory efficiency and saving CPU cycles.
DICOM Fusion Image
This is a totally new feature which can be utilised by using the DicomImages' MakeFusion method. It allows spatial transformations, which are passed on simultaneously to all the images in the collection. Fusion specific properties are accessible using the image's PropertiesForFusion property.
Video support using FFmpeg

Starting with version 8 we have added video support with the help of FFmpeg, a well established video Codec, for handling all sorts of popular video formats. This allows importing of supported video formats, embedding them into DICOM and exporting them using the appropriate transfer syntax.

FFmpeg is licensed under the GNU Lesser Public license(LGPL). We comply with the rules as stated in FFmpeg's licensing terms (https://www.ffmpeg.org/legal.html) for using this open-source Codec in our product and would urge our users to be aware of the legal responsibilities of using it. For development status on this feature please check our webpage http://www.medicalconnections.co.uk/kb/Video_support_with_FFmpeg

DicomLabel update
There is a single major update in this new version as a result of our effort to have a consistent API for DicomLabel handling. We have fully documented the changes in our article.

There have been many internal code changes that are related to code normalization, efficiency and readability and some of them affect deep rooted routines like handling sequences, writing to disk, network transmission, etc. Most of these don't directly affect our API but some changes were unavoidable. If you have any problems with this version please contact us our Support Team.


Project Overview

DicomObjects Reference
Project Overview
Description

This package consists of an inter-related, but independent, set of “Objects” that enable developers quickly and easily to add DICOM functionality to their products without needing to understand or program the intricacies of the DICOM standard.
This help file provides full reference
Almost any aspect of DICOM image/data manipulation can be performed using DicomObjects, including:

  • Image display and manipulation
  • Network transmission of images and associated data, including worklists
  • Printing to DICOM and windows printers
  • Normalised operations including storage commitment
  • Image creation from scratch and import/export to/from non-DICOM formats

The main Components of the DicomObjects Collection are:

DicomViewer Custom Control

A 32-bit ActiveX control that may be embedded into any suitable control container such as Visual Basic, standard development environments such as C++ (Microsoft or Borland), Delphi, Microsoft Access, and can even be used in Internet Explorer. I t has extensive display capabilities for DICOM images, whether read from files, received over the network, or from numerous other sources, and these include a wide range of annotations, and full DICOM greyscale presentation state support.

It also provides service class provider (SCP) functionality for verification, storage, query/retrieve and normalised operations.

DicomServer Object

An automation object without a user interface that provides storage, query/retrieve and normalised facilities as a service class provider (SCP).

DicomQuery Object

A non-visual automation object that handles the query/retrieve parts of the DICOM standard as a service class user (SCU).

DicomPrint Object

An automation object that simplifies DICOM printing as a service class user (SCU).

DicomGlobal Object

Used for certain global operations such as over-riding registry values

DicomConnection Object

A DicomConnection Object represents an association, and may either be created automatically in response to an incoming query request, or explicitly by the client program. Methods of this object are used to send data, images, and verification requests, and this object is central to DicomObject’s asynchronous operation capabilities. As of version 4.1, there is also a DicomConnections collection.

Other dependent automation objects and collections are created and used by the above, and some may also be created directly. They are:

Object Description | Single Item | Collection
SOP instance, containing an image | DicomImage | DicomImages
Generic SOP instance, used for results of DICOM queries or as a sub-element of a Sequence | DicomDataSet | DicomDataSets
Attribute (Data Element) of either of the above | DicomAttribute | DicomAttributes
DICOM Presentation context | DicomContext | DicomContexts
Image Annotation | DicomLabel | DicomLabels

Classes
Class Module | Description
Constants

In order to improve code reliability, and as a service to programmers, DicomObjects includes constants for some of the commonly used DICOM well-known UIDs, which are listed here, by category. Note that the import procedures for some languages (including Microsoft Visual C++) do not include string constants. If you wish to use these constants in such environments, then you are advised to copy this list from the help file into a header file, and edit to suit the requirements of your language.

DicomAttribute | Each DicomAttribute corresponds to one data element within a DICOM Data Set or Image
DicomAttributes | This is a collection of DicomAttribute objects, including that represented by a DicomImage’s or DicomDataSet’s Attributes Property.
DicomConnection

A DicomConnection Object represents the current state of an association, and may either be created automatically in response to an incoming query request, or explicitly by the client program. Methods of this object are used to send data, images, and verification requests. There is not a one-to-one correspondence between DicomConnections and associations, as one incoming association may cause several DicomConnection objects to be produced, one in response to each incoming command, and likewise, an outgoing DicomConnection object may (if synchronous) during its life serve more than one association, but at a given time, each association is represented by one, and only one DicomConnection.

As most clients in which DicomObjects will be used are single-threaded, the DicomConnection object is structured so as to allow asynchronous operation, permitting multiple operations to be performed simultaneously. For incoming C-FIND, C-GET or C-MOVE requests, details of the request are found in the Operation, Root and Request properties. The client then finds the data and/or images required, and returns them through one or more SetDestination, SendData and SendImages methods. The SendStatus method is used both to return pending status messages for C-GET and C-MOVE operations, and the final status for all operations.

For incoming Normalised operations, details of the request are less “interpreted”, as handling such commands as an SCP is an advanced technique for knowledgeable users only. The main incoming command is found, as a DicomDataSet, in the Command property, and the associated identifier is, as for the composite operations, in Request.

DicomConnection objects may be created under user control either directly (e.g. using Visual Basic’s ‘new’ command, or using the OLE name DicomObjects.DicomConnection) or via the New method of DicomViewer or DicomServer objects. The method used for creation controls the allowable values for the Mode property. When created directly, the Mode is always doSync, and cannot be modified, as there would be no mechanism for ActionComplete events to be fired in these circumstances. When created via the DicomViewer or DicomServer objects, then Mode is initially doAsync, but this may be modified before the first operation is initiated. In this case, if Mode is left as doSync, or changed to doAsync, then the object through which the DicomConnection is created receives the ActionComplete events. The Close method should be applied to such all user created DicomConnection objects before allowing them to be destroyed.

See the Mode property for details of synchronising options.

DicomConnections | This is a true OLE collection, a consisting of DicomConnection objects.
DicomContext | A DicomContext represents a DICOM presentation context, and is used in association negotiation, and in the selection of transmission formats (transfer syntaxes). DicomContext items only exist within a DicomContexts collection, and more information on the use of DicomContext items may be found in the DicomContexts entry.
DicomContexts

A DicomContexts collection consists of DicomContext objects, and represents the set of DICOM presentation contexts offered or accepted for an association negotiation.

Most applications will not need to use this collection, as appropriate defaults are provided in most circumstances, and even these may be modified via registry entries, but this collection may prove useful where it is necessary to use different presentation contexts (giving different transfer syntaxes) for different remote entities, such as in teleradiology. When used on incoming connections, it can also be very useful for debugging purposes.

DicomDataSet

A DicomDataSet represents a series of Data Elements, and some associated properties.

DicomDataSets

This is a true OLE collection, a collection of DicomDataSet objects, such as that returned by a DicomQuery Object’s DoQuery method.

This data type is also used to represent data elements of the sequence (SQ) type.

DicomGlobal | This object supports various operations which are not related to other specific objects
DicomImage | In general, a DicomImage is a superset of the DicomDataSet type, which also contains a collection of attributes, the distinction being that a DicomImage contains pixel data, and is therefore displayable within a DicomViewer control, whereas a DicomDataSet does not contain pixel data, and is not displayable. The different properties and methods reflect this difference.
DicomImages | This is a true OLE collection, comprising DicomImage objects, including that represented by the DICOM viewer control’s Images Property.
DicomLabel

A DicomLabel item represents a label, or annotation, to be displayed over an image in a DicomViewer control, or in derived copies of the image.
Labels may be ellipses (or circles), rectangles (or squares), lines, text or bitmaps, or other shapes (see LabelType for a full list), and the properties control not only the type and size of the object, but many other properties such as colour and line thickness.

Labels may be tied to the viewer control, to the display area in which an image is displayed, or to the image itself, this latter distinction being controlled by the RotateModeWithImage property.
All properties have default values, which are suitable for many uses, and each is documented with the appropriate property. The same label may be added into several DicomLabels collections if necessary, but where this is done, subsequent labels will be “cloned” when added, so that they may later be manipulated independently. Also, unambiguous association of each DicomLabel with one image is necessary for the ROI functions.

DicomLabels

This is a true OLE collection, a consisting of DicomLabel objects.

Although it may be instantiated independently, the most common examples of such collections are the Labels properties of DicomViewer and DicomImage objects, representing the labels to be drawn over that viewer or image respectively.

DicomLicense | An object which represents a single license allowing specific use of DicomObjects on this machine.
DicomLicenseGlobal | This object supports various operations related to the licensing of DicomObjects.
DicomPrint | Object to simplify printing to DICOM printers
DicomProjection | This class provides a "view" of an image, including both 3D images and Fusion image.
DicomQuery

A DicomQuery Object is an externally creatable OLE automation object that facilitates the querying of information and retrieval of images from DICOM servers that support the Query/Retrieve protocols as a Service Class Provider (SCP)

A useful feature of this object is that is re-usable, so as the user descends though a hierarchical search, new constraints may be added, and the search repeated, with having to re-set those already used.

DicomServer | Automation object providing SCP functionality
DicomViewer

The primary purpose of this control is the display of DICOM images, and extensive facilities are available to allow images to be obtained from a variety of sources, including files and network operations. There is extensive control over how the images are displayed, including not only the normal width/level controls, but also use of DICOM greyscale presentation states, a wide range of annotations, flipping, zooming etc.

DicomVolume | An object holding a set of slices which can be used as the basis for 3D reconstructions.
Public Enumerations
Enumeration | Description
do3DMode | Modes used by the DicomImage Mode Property
doAutoSizeMode

Mode available for DicomLabel.AutoSizeMode

doCineMode | The mode used by the DicomImage.CineMode Property
doConnectionMode | Modes available for the DicomConnection's Mode Property
doFilterMode | The list of spacing filtering modes available for use in the DicomImage MagnificationMode and MinificationMode properties.
doFlipState

Modes available for DicomImage.FlipState

doLabelAlignment | Where to align text in labels, as used in the DicomLabel's Alignment Property
doLabelType | Types of DicomLabel, as specified by the LabelType Property
doMonitorMode | Special monitor modes
doPlane
Common planes used to display 3D images
doPresentationStateFeatures
Flags to control which features of presentation states are used and/or converted
doRotateState | Modes available for DicomImage.RotateState
doRotationBehaviour | Rotation behaviour of the Image
doRotationCentre | Possible values for controlling the centre of rotation of a text label
doRotationMode | Possible values for controlling the rotation behaviour of a label
doScaleMode
How Label's dimensions should be interpreted and scaled
doSelectMode | Controls how "selection" handles are drawn on DicomLabels
doShadowType | Control the shadowing of DicomLabel Objects
doStretchModes
Controls how an image is displayed
doViewerMode | The modes which can be used for displaying DICOM images in a DicomViewer
doVoiLUTFunction | Enumeration used to control whether simple width level has sharp corners (linear) or rounded ends (sigmoid)


Constants Object

Constants Object
Members
DicomObjects Reference : Constants Object
Description

In order to improve code reliability, and as a service to programmers, DicomObjects includes constants for some of the commonly used DICOM well-known UIDs, which are listed here, by category. Note that the import procedures for some languages (including Microsoft Visual C++) do not include string constants. If you wish to use these constants in such environments, then you are advised to copy this list from the help file into a header file, and edit to suit the requirements of your language.

Remarks

Transfer Syntaxes

doTS_ImplicitVRLittleEndian | 1.2.840.10008.1.2
doTS_ExplicitVRLittleEndian | 1.2.840.10008.1.2.1
doTS_ExplicitVRBigEndian | 1.2.840.10008.1.2.2
doTS_JPEGBaseline | 1.2.840.10008.1.2.4.50
doTS_JPEGExtended | 1.2.840.10008.1.2.4.51
doTS_JPEGLossless | 1.2.840.10008.1.2.4.57
doTS_JPEGLosslessFirstOrder | 1.2.840.10008.1.2.4.70
doTS_JPEGLS_Lossless | 1.2.840.10008.1.2.4.80
doTS_JPEGLS_Lossy | 1.2.840.10008.1.2.4.81
doTS_RLELossless | 1.2.840.10008.1.2.5

SOP Classes

doSOP_Verification | 1.2.840.10008.1.1
doSOP_MediaStorageDirectory | 1.2.840.10008.1.3.10
doSOP_BasicStudyContentNotification | 1.2.840.10008.1.9
doSOP_StorageCommitmentPush | 1.2.840.10008.1.20.1
doSOP_StorageCommitmentPull | 1.2.840.10008.1.20.2
doSOP_DICOMApplicationContext | 1.2.840.10008.3.1.1.1
doSOP_DetachedPatientManagement | 1.2.840.10008.3.1.2.1.1
doSOP_DetachedVisitManagement | 1.2.840.10008.3.1.2.2.1
doSOP_DetachedStudyManagement | 1.2.840.10008.3.1.2.3.1
doSOP_StudyComponentManagement | 1.2.840.10008.3.1.2.3.2
doSOP_ModalityPerformedProcedureStep | 1.2.840.10008.3.1.2.3.3
doSOP_ModalityPerformedProcedureStepRetrieve | 1.2.840.10008.3.1.2.3.4
doSOP_ModalityPerformedProcedureStepNotification | 1.2.840.10008.3.1.2.3.5
doSOP_DetachedResultsManagement | 1.2.840.10008.3.1.2.5.1
doSOP_DetachedInterpretationManagement | 1.2.840.10008.3.1.2.6.1
doSOP_BasicFilmSession | 1.2.840.10008.5.1.1.1
doSOP_BasicFilmBox | 1.2.840.10008.5.1.1.2
doSOP_BasicGrayscaleImageBox | 1.2.840.10008.5.1.1.4
doSOP_BasicColorImageBox | 1.2.840.10008.5.1.1.4.1
doSOP_ReferencedImageBox | 1.2.840.10008.5.1.1.4.2
doSOP_PrintJob | 1.2.840.10008.5.1.1.14
doSOP_BasicAnnotationBox | 1.2.840.10008.5.1.1.15
doSOP_Printer | 1.2.840.10008.5.1.1.16
doSOP_PrinterConfigurationRetrieval | 1.2.840.10008.5.1.1.16.376
doSOP_VOILUTBox | 1.2.840.10008.5.1.1.22
doSOP_PresentationLUT | 1.2.840.10008.5.1.1.23
doSOP_ImageOverlayBox | 1.2.840.10008.5.1.1.24
doSOP_BasicPrintImageOverlayBox | 1.2.840.10008.5.1.1.24.1
doSOP_PrintQueueManagement | 1.2.840.10008.5.1.1.26
doSOP_StoredPrint | 1.2.840.10008.5.1.1.27
doSOP_HardcopyGrayscale | 1.2.840.10008.5.1.1.29
doSOP_HardcopyColor | 1.2.840.10008.5.1.1.30
doSOP_PullPrintRequest | 1.2.840.10008.5.1.1.31
doSOP_ComputedRadiography | 1.2.840.10008.5.1.4.1.1.1
doSOP_DigitalXRay_Presentation | 1.2.840.10008.5.1.4.1.1.1.1
doSOP_DigitalXRay_Processing | 1.2.840.10008.5.1.4.1.1.1.1.1
doSOP_DigitalMammographyXRay_Presentation | 1.2.840.10008.5.1.4.1.1.1.2
doSOP_DigitalMammographyXRay_Processing | 1.2.840.10008.5.1.4.1.1.1.2.1
doSOP_DigitalIntraoralXRay _Presentation | 1.2.840.10008.5.1.4.1.1.1.3
doSOP_DigitalIntraoralXRay _Processing | 1.2.840.10008.5.1.4.1.1.1.3.1
doSOP_CT | 1.2.840.10008.5.1.4.1.1.2
doSOP_OldUltrasoundMultiframe | 1.2.840.10008.5.1.4.1.1.3
doSOP_UltrasoundMultiframe | 1.2.840.10008.5.1.4.1.1.3.1
doSOP_MR | 1.2.840.10008.5.1.4.1.1.4
doSOP_OldNuclearMedicine | 1.2.840.10008.5.1.4.1.1.5
doSOP_OldUltrasound | 1.2.840.10008.5.1.4.1.1.6
doSOP_Ultrasound | 1.2.840.10008.5.1.4.1.1.6.1
doSOP_SecondaryCapture | 1.2.840.10008.5.1.4.1.1.7
doSOP_StandaloneOverlay | 1.2.840.10008.5.1.4.1.1.8
doSOP_StandaloneCurve | 1.2.840.10008.5.1.4.1.1.9
doSOP_12leadECGWaveform | 1.2.840.10008.5.1.4.1.1.9.1.1
doSOP_GeneralECGWaveform | 1.2.840.10008.5.1.4.1.1.9.1.2
doSOP_AmbulatoryECGWaveform | 1.2.840.10008.5.1.4.1.1.9.1.3
doSOP_HemodynamicWaveform | 1.2.840.10008.5.1.4.1.1.9.2.1
doSOP_CardiacElectrophysiologyWaveform | 1.2.840.10008.5.1.4.1.1.9.3.1
doSOP_BasicVoiceAudioWaveform | 1.2.840.10008.5.1.4.1.1.9.4.1
doSOP_StandaloneModalityLUT | 1.2.840.10008.5.1.4.1.1.10
doSOP_GrayscaleSoftcopyPresentationState | 1.2.840.10008.5.1.4.1.1.11.1
doSOP_StandaloneVOILUT | 1.2.840.10008.5.1.4.1.1.11
doSOP_XRayAngiographic | 1.2.840.10008.5.1.4.1.1.12.1
doSOP_XRayRadiofluoroscopic | 1.2.840.10008.5.1.4.1.1.12.2
doSOP_XRayAngiographicBiPlane | 1.2.840.10008.5.1.4.1.1.12.3
doSOP_NuclearMedicine | 1.2.840.10008.5.1.4.1.1.20
doSOP_VLEndoscopic | 1.2.840.10008.5.1.4.1.1.77.1.1
doSOP_VLMicroscopic | 1.2.840.10008.5.1.4.1.1.77.1.2
doSOP_VLSlideCoordinatesMicroscopic | 1.2.840.10008.5.1.4.1.1.77.1.3
doSOP_VLPhotographic | 1.2.840.10008.5.1.4.1.1.77.1.4
doSOP_BasicTextSR | 1.2.840.10008.5.1.4.1.1.88.11
doSOP_EnhancedSR | 1.2.840.10008.5.1.4.1.1.88.22
doSOP_ComprehensiveSR | 1.2.840.10008.5.1.4.1.1.88.33
doSOP_PositronEmissionTomography | 1.2.840.10008.5.1.4.1.1.128
doSOP_StandalonePETCurve | 1.2.840.10008.5.1.4.1.1.129
doSOP_RT | 1.2.840.10008.5.1.4.1.1.481.1
doSOP_RTDose | 1.2.840.10008.5.1.4.1.1.481.2
doSOP_RTStructureSet | 1.2.840.10008.5.1.4.1.1.481.3
doSOP_RTBeamsTreatmentRecord | 1.2.840.10008.5.1.4.1.1.481.4
doSOP_RTPlan | 1.2.840.10008.5.1.4.1.1.481.5
doSOP_RTBrachyTreatmentRecord | 1.2.840.10008.5.1.4.1.1.481.6
doSOP_RTTreatmentSummaryRecord | 1.2.840.10008.5.1.4.1.1.481.7
doSOP_PatientRootQR_FIND | 1.2.840.10008.5.1.4.1.2.1.1
doSOP_PatientRootQR_MOVE | 1.2.840.10008.5.1.4.1.2.1.2
doSOP_PatientRootQR_GET | 1.2.840.10008.5.1.4.1.2.1.3
doSOP_StudyRootQR_FIND | 1.2.840.10008.5.1.4.1.2.2.1
doSOP_StudyRootQR_MOVE | 1.2.840.10008.5.1.4.1.2.2.2
doSOP_StudyRootQR_GET | 1.2.840.10008.5.1.4.1.2.2.3
doSOP_PatientStudyOnlyQR_FIND | 1.2.840.10008.5.1.4.1.2.3.1
doSOP_PatientStudyOnlyQR_MOVE | 1.2.840.10008.5.1.4.1.2.3.2
doSOP_PatientStudyOnlyQR_GET | 1.2.840.10008.5.1.4.1.2.3.3
doSOP_ModalityWorklist_FIND | 1.2.840.10008.5.1.4.31

Meta SOP Classes

doMeta_DetachedPatient | 1.2.840.10008.3.1.2.1.4
doMeta_DetachedResults | 1.2.840.10008.3.1.2.5.4
doMeta_DetachedStudy | 1.2.840.10008.3.1.2.5.5
doMeta_BasicGrayscalePrint | 1.2.840.10008.5.1.1.9
doMeta_ReferencedGrayscalePrint | 1.2.840.10008.5.1.1.9.1
doMeta_BasicColorPrint | 1.2.840.10008.5.1.1.18
doMeta_ReferencedColorPrint | 1.2.840.10008.5.1.1.18.1
doMeta_PullStoredPrint | 1.2.840.10008.5.1.1.32

Well-known Instances

doInstance_StorageCommitmentPush | 1.2.840.10008.1.20.1.1
doInstance_StorageCommitmentPull | 1.2.840.10008.1.20.2.1
doInstance_Printer | 1.2.840.10008.5.1.1.17
doInstance_PrinterConfigurationRetrieval | 1.2.840.10008.5.1.1.17.376
doInstance_PrintQueue | 1.2.840.10008.5.1.1.25

See Also

Constants Members


Constants Object Members

Constants Object Members
Overview
DicomObjects Reference : Constants Object
See Also

Constants Object


DicomAttribute Object

DicomAttribute Object
Members
DicomObjects Reference : DicomAttribute Object
Description
Each DicomAttribute corresponds to one data element within a DICOM Data Set or Image
Remarks

As explained in relation to the Value property, attributes may be of varying types, including sequence items, and may also be Null or even non-existent.

For details of the meanings of DICOM attributes, see the Element Reference section.

See Also

DicomAttribute Members


DicomAttribute Object Members

DicomAttribute Object Members
Overview
DicomObjects Reference : DicomAttribute Object
Public Methods
Public Method VariantValue Value of an element, always as a variant, or array of variants, with optional elimination of single-dimension array bounds
Public Properties
Public Property _Value | The value of a Data Element
Public Property AllowableVM | The allowable VM range (as in part 6)
Public Property DateTimeFrom | The date to return for an open ended date
Public Property DateTimeTo | End of a date and/or time range
Public Property Description | Human readable description of an attribute's meaning
Public Property Element | The element index of a data element
Public Property Exists | Determines whether an attribute actually exists
Public Property Group | The group index of a data element
Public Property Multiple | Determines whether an attribute has a potential value multiplicity of greater than 1
Public Property ObjectType | Describes the nature of an automation object
Public Property RawData | The raw value of a Data Element, as an array of bytes.
Public Property UnicodeValue | Unicode version of the string value, using character set data
Public Property UnicodeValue2 | Unicode version of the string value, using character set data
Public Property Value | The value of a Data Element
Public Property ValueByIndex | Direct access to one of the values of a (potentially) multi-valued attribute
Public Property VM | Number of elements in a multi-valued element
Public Property VR | Gets or changes the value representation of an attribute
See Also

DicomAttribute Object


VariantValue Method

VariantValue Method
DicomObjects Reference > DicomAttribute Object : VariantValue Method
Whether to simply the output for some environments - see remarks below for details.
Description
Value of an element, always as a variant, or array of variants, with optional elimination of single-dimension array bounds
Syntax
Visual Basic
Public Function VariantValue( _
   ByVal Simplify As Boolean _
) As Variant
Parameters
Simplify
Whether to simply the output for some environments - see remarks below for details.
Return Type
Variant
Remarks

For non-array data, this method always returns the same result as Value.

The value returned by an attribute’s default Value property is itself always a variant, but for reasons of space and efficiency, the elements of an array are of a fixed, non-variant type. This method, on the other hand, guarantees that the array elements will themselves also be variants. This is not very efficient, but is necessary for some scripting languages (e.g. VBScript & MatLab), which can ONLY handle variants.

To further cope with the deficiencies in some languages, which cannot cope with degenerate array dimensions (1..1), this method will eliminate such dimensions completely if the Simplify parameter is TRUE.

See Also

DicomAttribute Object | DicomAttribute Members


_Value Property

_Value Property
DicomObjects Reference > DicomAttribute Object : _Value Property
Description
The value of a Data Element
Property type
Read-only property
Syntax
Visual Basic
Public Property _Value As Variant
See Also

DicomAttribute Object | DicomAttribute Members


AllowableVM Property

AllowableVM Property
DicomObjects Reference > DicomAttribute Object : AllowableVM Property
Description
The allowable VM range (as in part 6)
Property type
Read-only property
Syntax
Visual Basic
Public Property AllowableVM As String
See Also

DicomAttribute Object | DicomAttribute Members


DateTimeFrom Property

DateTimeFrom Property
DicomObjects Reference > DicomAttribute Object : DateTimeFrom Property
The date/Time to return where the DICOM value has no lower bound
Description
The date to return for an open ended date
Property type
Read-only property
Syntax
Visual Basic
Public Property DateTimeFrom( _
   ByVal MinDateTime As Date _
) As Date
Parameters
MinDateTime
The date/Time to return where the DICOM value has no lower bound
Remarks

The dateTimeFrom and DateTimeTo properties are intended for use in servers which need to interpret date and time values which may (or may not) be expressed as a range. In previous versions of DicomObjects such values have been presented simply as strings, leaving the programmer to interpret them, but these methods make such use much easier.
The properties are designed to used where it is necessary to convert DICOM request date or time ranges to SQL or similar, and allow the programmer to supply a suitable “default” date, which should be a reasonable maximum or minimum supported by the database. e.g. the following SQL may be useful :

“WHERE examdate >=” & range.DataTimeFrom(#1/1/1800#) & “ AND examdate <=” & range.DateTimeTo(#31/12/2099#)”
The efficiency could be improved by checking for default values and excluding the superfluous clauses, but the above general form should always work.
These properties successfully handle all standard forms of range, including a single value, and if a null range is passed, then both properties return their default values. This can be summarised as follows:

Range form | DateTimeFrom | DateTimeTo
Null | MinDateTime | MaxDateTime
SINGLEVALUE | SINGLEVALUE | SINGLEVALUE
-UPPER | MinDateTime | UPPER
LOWER- | LOWER | MaxDateTime
LOWER-UPPER | LOWER | UPPER

See Also

DicomAttribute Object | DicomAttribute Members


DateTimeTo Property

DateTimeTo Property
DicomObjects Reference > DicomAttribute Object : DateTimeTo Property
The date/Time to return where the DICOM value has no upper bound
Description
End of a date and/or time range
Property type
Read-only property
Syntax
Visual Basic
Public Property DateTimeTo( _
   ByVal MaxDateTime As Date _
) As Date
Parameters
MaxDateTime
The date/Time to return where the DICOM value has no upper bound
Remarks

The dateTimeFrom and DateTimeTo properties are intended for use in servers which need to interpret date and time values which may (or may not) be expressed as a range. In previous versions of DicomObjects such values have been presented simply as strings, leaving the programmer to interpret them, but these methods make such use much easier.
The properties are designed to used where it is necessary to convert DICOM request date or time ranges to SQL or similar, and allow the programmer to supply a suitable “default” date, which should be a reasonable maximum or minimum supported by the database. e.g. the following SQL may be useful :

“WHERE examdate >=” & range.DataTimeFrom(#1/1/1800#) & “ AND examdate <=” & range.DateTimeTo(#31/12/2099#)”
The efficiency could be improved by checking for default values and excluding the superfluous clauses, but the above general form should always work.
These properties successfully handle all standard forms of range, including a single value, and if a null range is passed, then both properties return their default values. This can be summarised as follows:

Range form | DateTimeFrom | DateTimeTo
Null | MinDateTime | MaxDateTime
SINGLEVALUE | SINGLEVALUE | SINGLEVALUE
-UPPER | MinDateTime | UPPER
LOWER- | LOWER | MaxDateTime
LOWER-UPPER | LOWER | UPPER

See Also

DicomAttribute Object | DicomAttribute Members


Description Property

Description Property
DicomObjects Reference > DicomAttribute Object : Description Property
Description
Human readable description of an attribute's meaning
Property type
Read-only property
Syntax
Visual Basic
Public Property Description As String
Remarks
The known elements in version 4 are current as of the 2000 edition of the DICOM standard.
See Also

DicomAttribute Object | DicomAttribute Members


Element Property

Element Property
DicomObjects Reference > DicomAttribute Object : Element Property
Description
The element index of a data element
Property type
Read-only property
Syntax
Visual Basic
Public Property Element As Long
Remarks
Although these properties would be redundant if accessing the elements by group and element number, the ability to iterate thought the elements using the "for each" and ItemByIndex constructs requires these properties to be exposed, in order to identify the nature of each attribute.
These properties are presented as long rather than short integers, to avoid ambiguities in the range 8000-FFFF.
See Also

DicomAttribute Object | DicomAttribute Members


Exists Property

Exists Property
DicomObjects Reference > DicomAttribute Object : Exists Property
Description
Determines whether an attribute actually exists
Property type
Read-only property
Syntax
Visual Basic
Public Property Exists As Boolean
Remarks
This property returns True if this attribute exists within the image.
If an attempt is made to access a non-existent element of a DicomAttributes collection, then no error is generated, but the DicomAttribute item returned is a unique “error element”, which has an Exists property of False, and returns a Value of Null
See Also

DicomAttribute Object | DicomAttribute Members


Group Property

Group Property
DicomObjects Reference > DicomAttribute Object : Group Property
Description
The group index of a data element
Property type
Read-only property
Syntax
Visual Basic
Public Property Group As Long
Remarks
Although these properties would be redundant if accessing the elements by group and element number, the ability to iterate thought the elements using the "for each" and ItemByIndex constructs requires these properties to be exposed, in order to identify the nature of each attribute.
These properties are presented as long rather than short integers, to avoid ambiguities in the range 8000-FFFF.
See Also

DicomAttribute Object | DicomAttribute Members


Multiple Property

Multiple Property
DicomObjects Reference > DicomAttribute Object : Multiple Property
Description
Determines whether an attribute has a potential value multiplicity of greater than 1
Property type
Read-only property
Syntax
Visual Basic
Public Property Multiple As Boolean
Remarks
If true, then the element has a potential value multiplicity of > 1, and its value will be an array not a scalar.
See Also

DicomAttribute Object | DicomAttribute Members


ObjectType Property

ObjectType Property
DicomObjects Reference > DicomAttribute Object : ObjectType Property
Description
Describes the nature of an automation object
Property type
Read-only property
Syntax
Visual Basic
Public Property ObjectType As String
Remarks

The possible values are as follows:

“DicomViewer”
“DicomQuery”
“DicomImage”
“DicomImages”
“DicomDataSet”
“DicomDataSets”
“DicomAttribute”
“DicomConnection”
“DicomConnections”
“DicomContext”
“DicomContexts”
“DicomLabel”
“DicomLabels”
“DicomGlobal”
“DicomLog”
“DicomPrint”

See Also

DicomAttribute Object | DicomAttribute Members


RawData Property

RawData Property
DicomObjects Reference > DicomAttribute Object : RawData Property
The lower bound of the array to be returned
Description
The raw value of a Data Element, as an array of bytes.
Property type
Read-only property
Syntax
Visual Basic
Public Property RawData( _
   ByVal Base As Integer _
) As Variant
Parameters
Base
The lower bound of the array to be returned
See Also

DicomAttribute Object | DicomAttribute Members


UnicodeValue Property

UnicodeValue Property
DicomObjects Reference > DicomAttribute Object : UnicodeValue Property
Description
Unicode version of the string value, using character set data
Property type
Read-only property
Syntax
Visual Basic
Public Property UnicodeValue As Variant
Remarks

In many cases, where the image has been generated in a country using the same character set as that in which it is being viewed, characters can normally be used without direct reference to the DICOM character set (0008,0005), but this is not always the case, especially when images are sent internationally. This method therefore uses the known character set to produce an unambiguous Unicode version of any text string, translated according to the appropriate encoding.
The DICOM rules only require the character set identifier (0008,0005) in the “top level” dataset, and this is presumed to apply to any nested datasets in sequences, but in DicomObjects, a DicomDataSet is not uniquely associated with any particular sequence, and a sequence (DicomDataSets object) could be incorporated into many other datasets, so when finding the value of a Unicode string in a nested item, it is important to specify also the “top level” dataset to be used for interpretation, and this is what the new UnicodeValue2 property permits.

For more details, please see the section on Extended Character sets in DicomObjects

See Also

DicomAttribute Object | DicomAttribute Members


UnicodeValue2 Property

UnicodeValue2 Property
DicomObjects Reference > DicomAttribute Object : UnicodeValue2 Property
The top level dataset from which to extract and 0008,0005 value to guide interpretation.
Description
Unicode version of the string value, using character set data
Property type
Read-only property
Syntax
Visual Basic
Public Property UnicodeValue2( _
   ByVal RootDataSet As DicomDataSet _
) As Variant
Parameters
RootDataSet
The top level dataset from which to extract and 0008,0005 value to guide interpretation.
Remarks

In many cases, where the image has been generated in a country using the same character set as that in which it is being viewed, characters can normally be used without direct reference to the DICOM character set (0008,0005), but this is not always the case, especially when images are sent internationally. This method therefore uses the known character set to produce an unambiguous Unicode version of any text string, translated according to the appropriate encoding.
The DICOM rules only require the character set identifier (0008,0005) in the “top level” dataset, and this is presumed to apply to any nested datasets in sequences, but in DicomObjects, a DicomDataSet is not uniquely associated with any particular sequence, and a sequence (DicomDataSets object) could be incorporated into many other datasets, so when finding the value of a Unicode string in a nested item, it is important to specify also the “top level” dataset to be used for interpretation, and this is what the new UnicodeValue2 property permits.

For more details, please see the section on Extended Character sets in DicomObjects

See Also

DicomAttribute Object | DicomAttribute Members


Value Property

Value Property
DicomObjects Reference > DicomAttribute Object : Value Property
Description
The value of a Data Element
Property type
Read-only property
Syntax
Visual Basic
Public Property Value As Variant
Remarks

The type of variant returned depends on the value representation of the data element, and may be a string, date (for time, date or date-time), or a numeric type, including floating point values where appropriate. Where not known in advance, the Vartype function may be of use.
Data elements of types not known to the program, whether private elements, or attributes recently defined by DICOM return the string " Unknown Data Type".
The pixel data attribute(7FE0,0010) is handled slightly differently, and returns a three dimensional array. See the Pixels attribute for further details.

If the data dictionary lists the element as having the possibility of a value multiplicity of >1, then an single dimensional array of the appropriate type is returned, the size of the array reflecting the actual number of elements present (which may be just one).
If the element is a sequence then an Object of type DicomDataSets is returned. As this is the only possible result of type Object, it can easily be identified using Visual Basic’s “Vartype” function or equivalent.

Non-existent Elements have a value of Null
As would be expected, this is the default property, so
attributes.Item(x, y).value
may be shorted to simply
attributes(x, y)
For details of the meanings of DICOM attributes, see DICOM standard Part 6.
Dates are returned as variant dates, and conversion to other formats (notably strings) is the responsibility of client programs and/or Windows. If you are unhappy with the format returned (e.g. 2 digit years), then changing the “Short Date” format in the control panel regional settings may cure the problem. Alternatively, your development environment may provide a means to specify explicit variant to date conversion formats.

For some applications which can only handle variants (VBScript, MatLab etc.) VariantValue may be more appropriate.

See Also

DicomAttribute Object | DicomAttribute Members


ValueByIndex Property

ValueByIndex Property
DicomObjects Reference > DicomAttribute Object : ValueByIndex Property
The 1-based index of the value to retrieve
Description
Direct access to one of the values of a (potentially) multi-valued attribute
Property type
Read-only property
Syntax
Visual Basic
Public Property ValueByIndex( _
   ByVal Index As Long _
) As Variant
Parameters
Index
The 1-based index of the value to retrieve
Remarks

Attribute.ValueByIndex(n) is equivalent to selecting the nth item of the array returned by Attribute.Value. However, some languages have poor support for Variant Arrays, and even in Visual Basic the form “Attribute.Value(n)” cannot be used, as n is mistaken for a (superfluous) parameter to the Value property.

Note that arrays rather than single items are returned whenever the VM for an item is anything other than “1” – i.e. when there is the possibility of more than one item, even though in a particular case only a single item may be present.

If the attribute represents a sequence, then the value returned is a DicomDataSet item, representing the nth dataset in the sequence.

The range of values which can be retrieved using this property ranges from 1 to the VM attribute, and the result of attempting to obtain a value outside this range is undefined – depending on the VR an error may or may not be produced.

See Also

DicomAttribute Object | DicomAttribute Members


VM Property

VM Property
DicomObjects Reference > DicomAttribute Object : VM Property
Description
Number of elements in a multi-valued element
Property type
Read-only property
Syntax
Visual Basic
Public Property VM As Long
Remarks

This property returns the actual number of items which will be returned by a call to the Attribute’s Value property. If the attribute has zero length, then the value will be 0, and if it is only allowed to have a single value then it will be 1, but for other cases the value depends on the data itself. If the Value property returns an array, then the value of this property equals the upper bound of the array.
If the underlying attribute is a sequence, then this property returns the number of items in the sequence.

Whatever the type of attribute, this provides the upper limit of the permissible index for the ValueByIndex property, and the two are normally used together.

See Also

DicomAttribute Object | DicomAttribute Members


VR Property

VR Property
DicomObjects Reference > DicomAttribute Object : VR Property
Description
Gets or changes the value representation of an attribute
Property type
Read-write property
Syntax
Visual Basic
Public Property VR As String
Remarks
This property is normally used as read-only and may be useful in determining the type of an element.
Changing the type of an element is not normally needed or a good idea, but may be required occasionally, such as when private data has been read though the implicit VR transfer syntax. Where it is known that this will occur, it is often better to update DicomObject’s dictionary before the data is read, using the AddDictionaryElement method.
See Also

DicomAttribute Object | DicomAttribute Members


DicomAttributes Collection

DicomAttributes Collection
Members
DicomObjects Reference : DicomAttributes Collection
Description
This is a collection of DicomAttribute objects, including that represented by a DicomImage’s or DicomDataSet’s Attributes Property.
Remarks

In addition to the above public properties, the DicomAttributes collection also supports the "NewEnumVariant" restricted method. This allows suitable clients such as Visual Basic to iterate through the Attributes it contains using the following syntax:

Enumeration
Copy Code
Dim a as DicomAttribute
Dim image as DicomImage
For each a in image.Attributes
   MsgBox a.name
Next
See Also

DicomAttributes Members


DicomAttributes Collection Members

DicomAttributes Collection Members
Overview
DicomObjects Reference : DicomAttributes Collection
Public Methods
Public Method Add | Adds a DicomAttribute to a DicomAttributes Collection
Public Method AddExplicit | Adds a DicomAttribute with a defined VR to a DicomAttributes Collection
Public Method Remove | Removes a DicomAttribute froma DicomAttributes Collection
Public Properties
Public Property Count | Indicates the number of items in a collection
Public Property Item | Provides access to the individual DicomAttribute items of a DicomAttributes collection
Public Property ItemByIndex | Access DicomAttribute objects by sequential index
Public Property ObjectType | Describes the nature of an automation object
See Also

DicomAttributes Collection


Add Method

Add Method
DicomObjects Reference > DicomAttributes Collection : Add Method
The tags which define the meaning of the attribute
The tags which define the meaning of the attribute
The Value to be assigned
Description
Adds a DicomAttribute to a DicomAttributes Collection
Syntax
Visual Basic
Public Sub Add( _
   ByVal Group As Long, _
   ByVal Element As Long, _
   ByVal Value As Variant _
)
Parameters
Group
The tags which define the meaning of the attribute
Element
The tags which define the meaning of the attribute
Value
The Value to be assigned
Remarks

Standard elements should be added using Add, which will determine the VR from the internal dictionary. AddExplicit should only be used for private elements (or possibly new elements not yet known to DicomObjects) for which the VR needs explicit definition.
The type of value required for the “Value” parameter depends on the value representation of the attribute, as defined by either by the VR parameter, or by the values of group and element. Values of the types returned by Attribute.Value are always acceptable, as are values of other types that can be suitably coerced. Variants of type “null” are also accepted, resulting a zero-length data element, which can be useful in raw queries and for “type 2” elements. There are some special conditions relating to date and time types.

To create a sequence, value may be a DicomDataSets collection.
If the data element being added has a potential value multiplicity (VM) of >1, then value may be either an array or scalar, but if the element’s VM is always 1, then an attempt to assign an array will generate an error.
Any existing attribute with the same group and element will be silently replaced, even if it is an array.

See Also

DicomAttributes Collection | DicomAttributes Members


AddExplicit Method

AddExplicit Method
DicomObjects Reference > DicomAttributes Collection : AddExplicit Method
The tags which define the meaning of the attribute
The tags which define the meaning of the attribute
The value representation (2 character string) of the attribute to be added
The Value to be assigned
Description
Adds a DicomAttribute with a defined VR to a DicomAttributes Collection
Syntax
Visual Basic
Public Sub AddExplicit( _
   ByVal Group As Long, _
   ByVal Element As Long, _
   ByVal VR As String, _
   ByVal Value As Variant _
)
Parameters
Group
The tags which define the meaning of the attribute
Element
The tags which define the meaning of the attribute
VR
The value representation (2 character string) of the attribute to be added
Value
The Value to be assigned
Remarks

Standard elements should be added using Add, which will determine the VR from the internal dictionary. AddExplicit should only be used for private elements (or possibly new elements not yet known to DicomObjects) for which the VR needs explicit definition.
The type of value required for the “Value” parameter depends on the value representation of the attribute, as defined by either by the VR parameter, or by the values of group and element. Values of the types returned by Attribute.Value are always acceptable, as are values of other types that can be suitably coerced. Variants of type “null” are also accepted, resulting a zero-length data element, which can be useful in raw queries and for “type 2” elements. There are some special conditions relating to date and time types.

To create a sequence, value may be a DicomDataSets collection.
If the data element being added has a potential value multiplicity (VM) of >1, then value may be either an array or scalar, but if the element’s VM is always 1, then an attempt to assign an array will generate an error.
Any existing attribute with the same group and element will be silently replaced, even if it is an array.

See Also

DicomAttributes Collection | DicomAttributes Members


Remove Method

Remove Method
DicomObjects Reference > DicomAttributes Collection : Remove Method
The tags of the attribute to be removed
The tags of the attribute to be removed
Description
Removes a DicomAttribute froma DicomAttributes Collection
Syntax
Visual Basic
Public Sub Remove( _
   ByVal Group As Long, _
   ByVal Element As Long _
)
Parameters
Group
The tags of the attribute to be removed
Element
The tags of the attribute to be removed
Remarks
If the appropriate data element exists in the collection, it is removed.
No error is generated is the requested item is not present in the collection.
See Also

DicomAttributes Collection | DicomAttributes Members


Count Property

Count Property
DicomObjects Reference > DicomAttributes Collection : Count Property
Description
Indicates the number of items in a collection
Property type
Read-only property
Syntax
Visual Basic
Public Property Count As Integer
Return Type
This is useful both for checking the value of indexes into the collection, and for iterating thought the images numerically, though as all collections in this product provide true iterators (allowing for instance the For Each construct in Visual Basic), this should rarely be necessary in such languages.
Where it is necessary to iterate through collections by integer index this can be done using ItemByIndex for DicomAttributes collections, and the Item property for the others.
See Also

DicomAttributes Collection | DicomAttributes Members


Item Property

Item Property
DicomObjects Reference > DicomAttributes Collection : Item Property
The Group number (even for official elements) of the attribute to retrieve
The Element number of the attribute to retrieve
Description
Provides access to the individual DicomAttribute items of a DicomAttributes collection
Property type
Read-only property
Syntax
Visual Basic
Public Property Item( _
   ByVal Group As Long, _
   ByVal Element As Long _
) As DicomAttribute
Parameters
Group
The Group number (even for official elements) of the attribute to retrieve
Element
The Element number of the attribute to retrieve
Remarks

Use of this property allows direct access to any of the Attributes of a DicomImage or DicomDataSet
Attempts to access a non-existent attribute will not produce an error, but the attribute returned will have a value of Null, and it’s Exists property will be false.

As this is the default property, the term "Item" is rarely used in languages which support default items, as Image.Attributes.Item(3), may rather more concisely be written in VB as Image.Attributes(3)

This property is used primarily to access a known specific item in a collection. To iterate through all items, either the language’s iterator (such as “for each” in Visual Basic) should be used, or the ItemByIndex property may be used.

See Also

DicomAttributes Collection | DicomAttributes Members


ItemByIndex Property

ItemByIndex Property
DicomObjects Reference > DicomAttributes Collection : ItemByIndex Property
The sequential index of the attribute to retrieve.
Description
Access DicomAttribute objects by sequential index
Property type
Read-only property
Syntax
Visual Basic
Public Property ItemByIndex( _
   ByVal Index As Integer _
) As DicomAttribute
Parameters
Index
The sequential index of the attribute to retrieve.
Remarks

Use of this property allows direct access to any of the Attributes of a DicomImage or DicomDataSet.

This property is provided for users of languages such as Delphi, which do not have iterators of the type available in Visual Basic. It is therefore possible to iterate through all items in the collection using a simple integer counter.
The items returned by this property are indexed in ascending order of group and then element number

See Also

DicomAttributes Collection | DicomAttributes Members


ObjectType Property

ObjectType Property
DicomObjects Reference > DicomAttributes Collection : ObjectType Property
Description
Describes the nature of an automation object
Property type
Read-only property
Syntax
Visual Basic
Public Property ObjectType As String
Remarks

The possible values are as follows:

“DicomViewer”
“DicomQuery”
“DicomImage”
“DicomImages”
“DicomDataSet”
“DicomDataSets”
“DicomAttribute”
“DicomConnection”
“DicomConnections”
“DicomContext”
“DicomContexts”
“DicomLabel”
“DicomLabels”
“DicomGlobal”
“DicomLog”
“DicomPrint”

See Also

DicomAttributes Collection | DicomAttributes Members


DicomConnection Object

DicomConnection Object
Members
DicomObjects Reference : DicomConnection Object
Description

A DicomConnection Object represents the current state of an association, and may either be created automatically in response to an incoming query request, or explicitly by the client program. Methods of this object are used to send data, images, and verification requests. There is not a one-to-one correspondence between DicomConnections and associations, as one incoming association may cause several DicomConnection objects to be produced, one in response to each incoming command, and likewise, an outgoing DicomConnection object may (if synchronous) during its life serve more than one association, but at a given time, each association is represented by one, and only one DicomConnection.

As most clients in which DicomObjects will be used are single-threaded, the DicomConnection object is structured so as to allow asynchronous operation, permitting multiple operations to be performed simultaneously. For incoming C-FIND, C-GET or C-MOVE requests, details of the request are found in the Operation, Root and Request properties. The client then finds the data and/or images required, and returns them through one or more SetDestination, SendData and SendImages methods. The SendStatus method is used both to return pending status messages for C-GET and C-MOVE operations, and the final status for all operations.

For incoming Normalised operations, details of the request are less “interpreted”, as handling such commands as an SCP is an advanced technique for knowledgeable users only. The main incoming command is found, as a DicomDataSet, in the Command property, and the associated identifier is, as for the composite operations, in Request.

DicomConnection objects may be created under user control either directly (e.g. using Visual Basic’s ‘new’ command, or using the OLE name DicomObjects.DicomConnection) or via the New method of DicomViewer or DicomServer objects. The method used for creation controls the allowable values for the Mode property. When created directly, the Mode is always doSync, and cannot be modified, as there would be no mechanism for ActionComplete events to be fired in these circumstances. When created via the DicomViewer or DicomServer objects, then Mode is initially doAsync, but this may be modified before the first operation is initiated. In this case, if Mode is left as doSync, or changed to doAsync, then the object through which the DicomConnection is created receives the ActionComplete events. The Close method should be applied to such all user created DicomConnection objects before allowing them to be destroyed.

See the Mode property for details of synchronising options.

Remarks
This property is useful when extra operations are required over a print association, and enables you to use the simplified interface provided by DicomPrint, yet still have flexibility to make arbitrary requests. In particular, it can be used to N-GET the well-known printer instance during an association to check for the printer’s status.
The Mode property will always be doSync, and cannot be changed.
See Also

DicomConnection Members


DicomConnection Object Members

DicomConnection Object Members
Overview
DicomObjects Reference : DicomConnection Object
Public Methods
Public Method Abort | Abort the association
Public Method Cancel | Send a C-CANCEL request
Public Method CheckForEvents | Check for N-EVENT-REPORTs
Public Method Close | Close the association
Public Method Find | Send an asynchronous C-FIND request
Public Method Get | Send an asynchronous C-GET request
Public Method Move | Send an asynchronous C-MOVE request
Public Method NAction | Send an N-ACTION request
Public Method NCreate | Send an N-CREATE request
Public Method NDelete | Send an N-DELETE request
Public Method NEventReport | Send an N-EVENT-REPORT
Public Method NGet | Send an N-GET request
Public Method NSet | Send an N-SET request
Public Method ReadURL | Reads an image asynchronously from a network URL
Public Method SaveImage | Save an image to a file, field or stream asynchronously
Public Method SendData | Send a DicomDataSets object listing results of a C-FIND query
Public Method SendImages | Send images over a DicomConnection
Public Method SendModifiedImages | Sends images over a DicomConnection, updating specified attributes.
Public Method SendStatus | Send query status
Public Method SendVerify | Send a verification request
Public Method SetDestination | Open outgoing DICOM association
Public Method SetDestinationIStream | Open outgoing DICOM association
Public Method SetQuality | Set the compression quality for a given transfer context
Public Method SetRejectionCode | Set the values which will be passed to the initiator if this application rejects an incoming association.
Public Method Wait | Wait for data transmission to complete
Public Properties
Public Property Association | The association number on which the query operation was requested
Public Property BytesReceived | Approximate bytes received on this connection
Public Property BytesReceivedDouble | Approximate bytes received on this connection
Public Property BytesSent | Approximate bytes sent on this connection
Public Property BytesSentDouble | Approximate bytes sent on this connection
Public Property CalledAET | Called AET used for this association
Public Property CallingAET | Calling Application's AET
Public Property Cancelled | Indicates that a C-CANCEL request has been received
Public Property ChangeLossyUIDs | Controls whether to change UIDs when sending compressed images
Public Property CoercionSOP | SOP class to which images should be coerced if peer does not accept true SOP class
Public Property Command | The full request dataset received
Public Property Contexts | Presentation contexts in use on this association
Public Property Destination | Destination for C-MOVE requests
Public Property Errors | DicomDataSet used to return errors identified in the query request
Public Property Failures | DicomDataSet containing list of failed SOP instances
Public Property isReady | Test whether the last asynchronous operation has completed
Public Property LastAction | Last action to have been performed on this connection
Public Property LastError | Human readable form of last error reported on this connection
Public Property LastInstanceUID | InstanceUID returned following outgoing normalised operations
Public Property LastStatus | Status of last operation (equivalent to Status(1))
Public Property LocalCertificate | X509 (CAPICOM) certificate to be used in negotiation
Public Property LocalIP | Local IP address called
Public Property LocalPort | Local port Called
Public Property MetaSOPClass | Meta SOP class to be used for outgoing normalised operations
Public Property Mode | Controls whether connection works synchronously with the container
Public Property MoveOriginator | Identifies the DicomConnection object which initated (via C-MOVE) this C-STORE
Public Property NumberCompleted | Number of completed move/get operations
Public Property NumberFailed | Number of failed move/get operations
Public Property NumberRemaining | Number of remaining move/get operations
Public Property NumberWarning | Number of warning move/get operations
Public Property ObjectType | Describes the nature of an automation object
Public Property Operation | The type of query operation requested
Public Property PreferredPCID | Preferred presentation context to be used (where possible)
Public Property PreferredTS | Preferred transfer syntax to be used (where possible)
Public Property PresentationContextID | Presentation Context ID used for current operation
Public Property RemoteCertificate | X509 (CAPICOM) certificate provided by remote entity
Public Property RemoteIP | Remote Application's IP
Public Property Request | DicomDataSet containing the query details
Public Property ReturnedDataSet | DataSet returned following outgoing normalised operations
Public Property ReturnedDataSets | DataSet returned following outgoing normalised operations
Public Property ReturnedImages | Images returned following asynchronous C-GET operation
Public Property ReturnedResponses | DicomDataSets Returned in responses to outgoing requests
Public Property Root | The Root of the query operation requested
Public Property Status | Array of status values returned by last operation
Public Property Tag | General Purpose Tag
Public Property ThrottleRate | Maximum data rate in bytes/second
Public Property UseTLS | Controls whether to negotiate a secure association using TLS
See Also

DicomConnection Object


Abort Method

Abort Method
DicomObjects Reference > DicomConnection Object : Abort Method

The “cause” of the Abort

The source of the abort - as below
Description
Abort the association
Syntax
Visual Basic
Public Sub Abort( _
   ByVal Reason As Integer, _
   ByVal Source As Integer _
)
Parameters
Reason

The “cause” of the Abort

Source
The source of the abort - as below
Remarks

An A-ABORT request is sent, and the association is then terminated.
The full meanings of the parameters are defined in DICOM part 8, but they are defined as:

Source:

0 - DICOM UL service-user (initiated abort)
1 - reserved
2 - DICOM UL service-provider (initiated abort)

Reason:

0 - reason-not-specified
1 - unrecognized-PDU
2 - unexpected-PDU
3 - reserved
4 - unrecognized-PDU parameter
5 - unexpected-PDU parameter
6 - invalid-PDU-parameter value

See Also

DicomConnection Object | DicomConnection Members


Cancel Method

Cancel Method
DicomObjects Reference > DicomConnection Object : Cancel Method
Description
Send a C-CANCEL request
Syntax
Visual Basic
Public Sub Cancel()
Remarks
This method is only useful following an asynchronous Find, Move or Get method, Note, however, that most implementations only check for C-CANCEL requests intermittently, so a single image transfer may not be affected.
See Also

DicomConnection Object | DicomConnection Members


CheckForEvents Method

CheckForEvents Method
DicomObjects Reference > DicomConnection Object : CheckForEvents Method
Description
Check for N-EVENT-REPORTs
Syntax
Visual Basic
Public Sub CheckForEvents()
Remarks

This method is only useful when:

  • A DicomConnection’s Mode property is doSync
  • An association is in progress which may generate N-EVENT-REPORTs

Calling this method causes DicomObjects to check for an incoming N-EVENT-REPORT. As Mode is doSync, the EventReport, event cannot be called asynchronously, so the report will be handled internally by DicomObjects returning a default status. If the DicomConnection has an attached DicomViewer or DicomServer, then an EventReport event will still be generated at the next opportunity, but the return value from that event will be ignored.

See Also

DicomConnection Object | DicomConnection Members


Close Method

Close Method
DicomObjects Reference > DicomConnection Object : Close Method
Description
Close the association
Syntax
Visual Basic
Public Sub Close()
Remarks
After a close method, a DicomConnection object may be re-used, using SetDestination to establish a new association.
See Also

DicomConnection Object | DicomConnection Members


Find Method

Find Method
DicomObjects Reference > DicomConnection Object : Find Method
The query root
The identifier for the request
Description
Send an asynchronous C-FIND request
Syntax
Visual Basic
Public Sub Find( _
   ByVal Root As String, _
   ByVal dataset As DicomDataSet _
)
Parameters
Root
The query root
dataset
The identifier for the request
Remarks

The query to be performed is defined by the DataSet parameter, and this method is functionally equivalent to the DoRawQuery method of the DicomQuery object, except that it can operate asynchronously.
Note that the QueryLevel value (0008,0052), must be included in the data set.
Once the operation has completed, the result may be found in the ReturnedDataSets collection, and they may also be available during the operation – see the ActionUpdate event for more details.

This method is particularly useful for “aggregating” servers, which may query several other machines, and return a unified results list to the user. By keeping the operation asynchronous, other operations of the server are not interrupted.
Where a query is being initiated “from scratch”, the QueryDataSet of the DicomQuery Object may be useful to create a suitable identifier dataset.

See Also

DicomConnection Object | DicomConnection Members


Get Method

Get Method
DicomObjects Reference > DicomConnection Object : Get Method
The query root
The identifier for the request
Description
Send an asynchronous C-GET request
Syntax
Visual Basic
Public Sub Get( _
   ByVal Root As String, _
   ByVal dataset As DicomDataSet _
)
Parameters
Root
The query root
dataset
The identifier for the request
Remarks
The images to be retrieved are defined by the DataSet parameter, which must include the Query Level (0008,0052).
Once the operation has completed, the images retrieved may be found in the ReturnedImages collection, and they may also be available during the operation – see the ActionUpdate event for more details.
See Also

DicomConnection Object | DicomConnection Members


Move Method

Move Method
DicomObjects Reference > DicomConnection Object : Move Method
The query root
The destination AE Title
The identifier for the request
Description
Send an asynchronous C-MOVE request
Syntax
Visual Basic
Public Sub Move( _
   ByVal Root As String, _
   ByVal Destination As String, _
   ByVal dataset As DicomDataSet _
)
Parameters
Root
The query root
Destination
The destination AE Title
dataset
The identifier for the request
Remarks
The images to be moved are defined by the DataSet parameter, which must include the Query Level (0008,0052).
Once the operation has completed, the result codes may be found in the Status property, and they may also be available during the operation – see the ActionUpdate event for more details.
See Also

DicomConnection Object | DicomConnection Members


NAction Method

NAction Method
DicomObjects Reference > DicomConnection Object : NAction Method
The requested SOP Class UID
The requested SOP InstanceUID
Context dependent Action code
The attributes to be set, with their values
Description
Send an N-ACTION request
Syntax
Visual Basic
Public Sub NAction( _
   ByVal classUID As String, _
   ByVal InstanceUID As String, _
   ByVal Action As Integer, _
   ByVal dataset As DicomDataSet _
)
Parameters
classUID
The requested SOP Class UID
InstanceUID
The requested SOP InstanceUID
Action
Context dependent Action code
dataset
The attributes to be set, with their values
Remarks
This method sends an N-ACTION request, using the quoted SOP Class and Instance UIDs, ActionID and DataSet.
In many cases, a dataset is not required, in which case an empty dataset should be used.
See Also

DicomConnection Object | DicomConnection Members


NCreate Method

NCreate Method
DicomObjects Reference > DicomConnection Object : NCreate Method
The requested SOP Class UID
The requested SOP InstanceUID
The attributes to be set, with their values
Description
Send an N-CREATE request
Syntax
Visual Basic
Public Sub NCreate( _
   ByVal classUID As String, _
   ByVal InstanceUID As String, _
   ByVal dataset As DicomDataSet _
)
Parameters
classUID
The requested SOP Class UID
InstanceUID
The requested SOP InstanceUID
dataset
The attributes to be set, with their values
Remarks
This method sends an N-CREATE request, using the quoted SOP Class and Instance UIDs.
If appropriate, the SCP may use the values in DataSet to initialise the object.
If the operation succeeds, then the UID of the object created may be found, once the operation has completed, in the LastInstanceUID property
See Also

DicomConnection Object | DicomConnection Members


NDelete Method

NDelete Method
DicomObjects Reference > DicomConnection Object : NDelete Method
The requested SOP Class UID

The requested SOP InstanceUID

Description
Send an N-DELETE request
Syntax
Visual Basic
Public Sub NDelete( _
   ByVal classUID As String, _
   ByVal InstanceUID As String _
)
Parameters
classUID
The requested SOP Class UID
InstanceUID

The requested SOP InstanceUID

Remarks
This method sends an N-DELETE request, using the quoted SOP Class and Instance UIDs.
No other information is permitted in an N-DELETE command.
See Also

DicomConnection Object | DicomConnection Members


NEventReport Method

NEventReport Method
DicomObjects Reference > DicomConnection Object : NEventReport Method
Requested SOP Class UID
Requested Instance UID
Event ID, as defined by the Class UID
Associated Data
Description
Send an N-EVENT-REPORT
Syntax
Visual Basic
Public Sub NEventReport( _
   ByVal classUID As String, _
   ByVal InstanceUID As String, _
   ByVal EventID As Integer, _
   ByVal dataset As DicomDataSet _
)
Parameters
classUID
Requested SOP Class UID
InstanceUID
Requested Instance UID
EventID
Event ID, as defined by the Class UID
dataset
Associated Data
Remarks
Before using this method, it is important to ensure that the required SOP Class UID has been negotiated with the remote entity. In some cases such as when using Storage Commitment, reverse role SCU/SCP negotiation may also be necessary.
As with other DicomConnection methods, the result is sent synchronously or asynchronously according to the value of Mode. The result (once isReady is true), is available in LastStatus or Status.
See Also

DicomConnection Object | DicomConnection Members


NGet Method

NGet Method
DicomObjects Reference > DicomConnection Object : NGet Method
The requested SOP Class UID
The requested SOP InstanceUID
The attributes requested
Description
Send an N-GET request
Syntax
Visual Basic
Public Sub NGet( _
   ByVal classUID As String, _
   ByVal InstanceUID As String, _
   ByVal dataset As DicomDataSet _
)
Parameters
classUID
The requested SOP Class UID
InstanceUID
The requested SOP InstanceUID
dataset
The attributes requested
Remarks
This method sends an N-GET request, using the quoted SOP Class and Instance UIDs. The values of the attributes in the DataSet are irrelevant, as it is used solely as a list of attributes whose values are to be retrieved.
The returned values may be found, once the operation has completed, in the ReturnedDataSet property.
See Also

DicomConnection Object | DicomConnection Members


NSet Method

NSet Method
DicomObjects Reference > DicomConnection Object : NSet Method
The requested SOP Class UID
The requested SOP InstanceUID

The attributes to be set, with their values

Description
Send an N-SET request
Syntax
Visual Basic
Public Sub NSet( _
   ByVal classUID As String, _
   ByVal InstanceUID As String, _
   ByVal dataset As DicomDataSet _
)
Parameters
classUID
The requested SOP Class UID
InstanceUID
The requested SOP InstanceUID
dataset

The attributes to be set, with their values

Remarks
This method sends an N-SET request, using the quoted SOP Class and Instance UIDs.
If values are returned they may be found, once the operation has completed, in the ReturnedDataSet property.
See Also

DicomConnection Object | DicomConnection Members


ReadURL Method

ReadURL Method
DicomObjects Reference > DicomConnection Object : ReadURL Method
The URL to fetch the image from
Description
Reads an image asynchronously from a network URL
Syntax
Visual Basic
Public Sub ReadURL( _
   ByVal URL As Variant _
)
Parameters
URL
The URL to fetch the image from
Remarks

The URL may begin http://, https://, ftp://, gopher:// or file://, and the appropriate access method will be used. Note that for local files, security restrictions apply.
Where authentication is required, the standard format may be used:

ReadURL(“http://username:password@servername/path”)

This method can read either official “Part10” format files with the 128 byte header, or unofficial “Part3” format files without a header, and detection of the type is automatic.
The file may have been written by the WriteFile method or by other DICOM software.

See Also

DicomConnection Object | DicomConnection Members


SaveImage Method

SaveImage Method
DicomObjects Reference > DicomConnection Object : SaveImage Method
The image to be saved
The file, field or stream to which the image is to be Written.
If TRUE, a blank 128 byte header, DICM marker, and meta-header are written at the start of the field.
If FALSE, the field is written in the unofficial, but common format, with no header, and using the little-endian implicit VR transfer syntax.
Specifies the full UID of the transfer syntax used when Part 10 format is specified. If omitted, the little-endian explicit VR transfer syntax is used. For details of the currently supported syntaxes, see the conformance entry.
The quality factor to be used.
Description
Save an image to a file, field or stream asynchronously
Syntax
Visual Basic
Public Sub SaveImage( _
   ByVal Image As DicomImage, _
   ByVal Destination As Variant, _
   ByVal isPart10 As Boolean, _
   Optional ByVal TransferSyntax As Variant, _
   Optional ByVal Quality As Variant _
)
Parameters
Image
The image to be saved
Destination
The file, field or stream to which the image is to be Written.
isPart10
If TRUE, a blank 128 byte header, DICM marker, and meta-header are written at the start of the field.
If FALSE, the field is written in the unofficial, but common format, with no header, and using the little-endian implicit VR transfer syntax.
TransferSyntax
Specifies the full UID of the transfer syntax used when Part 10 format is specified. If omitted, the little-endian explicit VR transfer syntax is used. For details of the currently supported syntaxes, see the conformance entry.
Quality
The quality factor to be used.
Remarks

Destination must one of the following types of Variant:

A String The image is saved to the filename given
An object supporting IStream The image is saved to the stream (as for WriteStream)
An ADO, DAO or RDO field object The image is saved to the field (as for WriteField)
This method differs from the other DicomConnection methods in that it makes no use of an association. It is, nonetheless, included here, as it uses the same model of asynchronous operation, with completion being signaled via the ActionComplete event.
This method is designed for use by multi-tasking servers, preventing the delays to other requests that could otherwise be caused by the processing of a storage request.

See Also

DicomConnection Object | DicomConnection Members


SendData Method

SendData Method
DicomObjects Reference > DicomConnection Object : SendData Method
One or more datasets, to be returned to the requesting application, each describing a single successful match.
The status associated with the above data, indicating the level of matching achieved.
Description
Send a DicomDataSets object listing results of a C-FIND query
Syntax
Visual Basic
Public Sub SendData( _
   ByVal Data As Object, _
   ByVal Status As Long _
)
Parameters
Data
One or more datasets, to be returned to the requesting application, each describing a single successful match.
Status
The status associated with the above data, indicating the level of matching achieved.
Remarks

The data returned by this method is sent to the requesting application as a series of C-FIND responses, each with the status indicated. Once all matches have been returned, a final SendStatus call should be made to terminate the list.
As the status for all returned matches must be “Pending”, only the values 0xFF00 and 0xFF01 are allowed for Status, the meanings being as follows:

0xFF00 : “Optional Keys were supported in the same manner as Required Keys”
0xFF01 : “Warning that one or more Optional Keys were not supported for existence and/or matching for this Identifier”

Unless other operations are pending, this method returns immediately, and the data is sent to the remote application entity asynchronously. An ActionComplete event is generated once data transmission has been completed.
If errors occur during transmission, they are reported via the DicomServer’s InfoMessage event procedure.

See Also

DicomConnection Object | DicomConnection Members


SendImages Method

SendImages Method
DicomObjects Reference > DicomConnection Object : SendImages Method
One or more images, to be transmitted.
Description
Send images over a DicomConnection
Syntax
Visual Basic
Public Sub SendImages( _
   ByVal Images As Variant _
)
Parameters
Images
One or more images, to be transmitted.
Remarks

For automatically generated DicomConnection objects, this method is used in response to a C-GET or C-MOVE request, but it may also be used to send any images the client chooses over a “stand-alone” DicomConnection.
The images sent by this method are sent either to the requesting application (C-GET) or to another (C-MOVE or stand-alone) as a series of C-STORE actions.
Unless Mode=doSync, this method returns immediately, and the images are sent asynchronously. An ActionComplete event is generated once data transmission has been completed.

In order to prevent a multi-tasking server having to wait whilst images are loaded before being sent, Data may be any one of a large number of data types, and if running asynchronously, DicomObjects will fetch the images then send then asynchronously on a separate thread without delaying other operations. The data types allowed are:

DicomImage object The single image is sent
DicomImages collection All images are sent
A String The file referenced by the string is read and sent
An array of strings All are interpreted as filenames, which are read and sent
An object supporting IStream The stream is read (as for ReadStream) and is sent
An ADO, DAO or RDO field object The field is read (as for ReadField) and is sent
For C-MOVE operations, no “pending” responses are generated by this method, and it is the client’s responsibility to make any that it wishes using the SendStatus method. Therefore, if the client wishes to send a pending response after each image is transmitted, only single images should be transmitted by each call to this method. Once all images have been sent, a final SendStatus call with a value of 0 should be made to terminate the association.

The number of images remaining, failed, warning, and successful associated with the request are automatically updated by the method, and the Failures property maintains a list of refused images UIDs. If all images are to be returned via a single call to SendImages, then no specific client action is required, as NumberRemaining is set automatically to the number of images in Data if previously 0. If, however, the client wishes to return images via multiple calls to this method (e.g. to enable pending status messages), then NumberRemaining must be set correctly before the first image is returned.

For a C-MOVE requests, or “stand-alone” DicomConnection objects, SetDestination must be called before this method.

See also SendModifiedImages for when it is necessary to modify demographics “on the fly”.

See Also

DicomConnection Object | DicomConnection Members


SendModifiedImages Method

SendModifiedImages Method
DicomObjects Reference > DicomConnection Object : SendModifiedImages Method
One or more images, to be transmitted.
The attributes to update.
Description
Sends images over a DicomConnection, updating specified attributes.
Syntax
Visual Basic
Public Sub SendModifiedImages( _
   ByVal Images As Variant, _
   ByVal Modifier As DicomDataSet _
)
Parameters
Images
One or more images, to be transmitted.
Modifier
The attributes to update.
Remarks

This method is functionally equivalent to the SendImages method except that all the attributes from the Update dataset are appended to each instance before it is sent over the network. Note that the original data, whether on disk or in memory is not modified in any way – only the data sent is changed. Attributes which are present in both the original data and in the update dataset will be over-written by the update value.
The main usage of this method is to comply with the requirements of the IHE “Patient Information Reconciliation” profile, which requires all data provided by an image archive to reflect the latest known patient demographics, so by using this method it is possible to apply such changes without needing to change the data help on disk.

In typical usage, Update may just contain a single attribute, the patient’s name, though where there has been a patient merge, it may also contain the patient’s ID.
For further details on the data types acceptable for Data, see the SendImages method.

See Also

DicomConnection Object | DicomConnection Members


SendStatus Method

SendStatus Method
DicomObjects Reference > DicomConnection Object : SendStatus Method
The status to be returned.
Description
Send query status
Syntax
Visual Basic
Public Sub SendStatus( _
   ByVal Status As Long _
)
Parameters
Status
The status to be returned.
Remarks

The status returned may be either Pending or Final, and the appropriate values are listed here:

Type | Meaning | Applies to | Status
Final | Success - Sub Operations Complete - No Failures | All | 0000
 | Warning - Sub Operations Complete - One or more Failures | C-MOVE & C-GET | B000
 | Refused - Out of Resources | C-GET | A700
 | Refused - Out of Resources - Unable to calculate number of matches | C-MOVE & C-GET | A701
 | Refused - Out of Resources - Unable to perform sub-operations | C-MOVE & C-GET | A702
 | Refused - Move Destination Unknown | C-MOVE | A801
 | Failed - Identifier Does Not Match SOP Class | All | A900
 | Failed - Unable to process | All | Cxxx
Pending | Sub Operations are continuing | C-MOVE & C-GET | FF00

Unless Mode=doSync, this method returns immediately, and the status is sent asynchronously. A pending status causes an ActionComplete event to be generated once the status has been sent.
Note that “pending” responses are generated for C-FIND queries by the SendData method, and are not permitted for this method, as there would be no method of attaching an identifier.
For a C-MOVE request, SetDestination must be called before this method.

See Also

DicomConnection Object | DicomConnection Members


SendVerify Method

SendVerify Method
DicomObjects Reference > DicomConnection Object : SendVerify Method
Description
Send a verification request
Syntax
Visual Basic
Public Sub SendVerify()
Remarks
As this method returns immediately, it is normally followed by a Wait call, before inspecting the value of LastStatus to determine the response received.
In many cases, the newer DicomGlobal object’s Echo method now provides an easier replacement where synchronous operation is acceptable.
See Also

DicomConnection Object | DicomConnection Members


SetDestination Method

SetDestination Method
DicomObjects Reference > DicomConnection Object : SetDestination Method
Network address (as dotted notation or resolvable name) to which the association is to be made.
Port on which remote application is listening.
Name to quote for this Application Entity
Name of remote Application Entity.
Description
Open outgoing DICOM association
Syntax
Visual Basic
Public Sub SetDestination( _
   ByVal Node As String, _
   ByVal Port As Integer, _
   ByVal CallingAE As String, _
   ByVal CalledAE As String _
)
Parameters
Node
Network address (as dotted notation or resolvable name) to which the association is to be made.
Port
Port on which remote application is listening.
CallingAE
Name to quote for this Application Entity
CalledAE
Name of remote Application Entity.
Remarks

This method can be used either on directly created DicomConnection objects, or on incoming DicomConnections, where a C-MOVE has been requested.
Unless Mode=doSync, this method returns immediately, the association is established with the remote application entity asynchronously, and an ActionComplete event is generated once the association has been established.
If errors occur during association establishment, they are reported via the DicomViewer or DicomServer’s InfoMessage event procedure if Mode is doAsync or doNosync, or as trappable errors if Mode is doSync

As the DICOM standard only permits a C-MOVE request to contain an application entity title, client applications must look up this title in their own tables, to find suitable values for the parameters to this method.

See Also

DicomConnection Object | DicomConnection Members


SetDestinationIStream Method

SetDestinationIStream Method
DicomObjects Reference > DicomConnection Object : SetDestinationIStream Method
Description
Open outgoing DICOM association
Syntax
Visual Basic
Public Sub SetDestinationIStream( _
   ByVal Stream As Unknown, _
   ByVal CallingAE As String, _
   ByVal CalledAE As String _
)
Parameters
Stream
CallingAE
CalledAE
See Also

DicomConnection Object | DicomConnection Members


SetQuality Method

SetQuality Method
DicomObjects Reference > DicomConnection Object : SetQuality Method
The transfer syntax to which this quality factor applies
The quality to be set
Description
Set the compression quality for a given transfer context
Syntax
Visual Basic
Public Sub SetQuality( _
   ByVal TransferSyntax As String, _
   ByVal Quality As Variant _
)
Parameters
TransferSyntax
The transfer syntax to which this quality factor applies
Quality
The quality to be set
Remarks

An application does not necessarily “know” which images will be sent by which transfer syntax, as the remote AE may have accepted different transfer syntaxes for different abstract syntaxes, and a common quality factor for an association would not therefore be appropriate. Instead, this method allows quality to be set for a specific transfer syntax.
The quality is specific to a given association rather than to the connection itself, and this method must therefore be after the call to SetDestination.

The following limitations apply:

  • This method is only meaningful when used in an application actually sending an image (normally the SCP), as there is no official means in DICOM for the SCU to send this information to the SCP.
  • Where an image is already compressed using the transfer syntax required, it is not decompressed and recompressed, so this value is ignored. If absolutely necessary, this can be over-ridden by applying the DecompressAll method to the image before sending it, but multiple compressions do have an adverse effect on image quality

At present, the only syntaxes to which this method applies are doTS_JPEGBaseline (1.2.840.10008.1.2.4.50) and doTS_JPEGExtended (1.2.840.10008.1.2.4.51), though it is also made available to private syntaxes defined through compression DLLs.

The Quality is defined as a variant in order to allow future transfer syntaxes to define their own types of quality factor.

See Also

DicomConnection Object | DicomConnection Members


SetRejectionCode Method

SetRejectionCode Method
DicomObjects Reference > DicomConnection Object : SetRejectionCode Method
The "Result" of the rejection - see remarks for values
The "Source" of the rejection - see remarks for values
The "Reason" for the rejection - see remarks for values
Description
Set the values which will be passed to the initiator if this application rejects an incoming association.
Syntax
Visual Basic
Public Sub SetRejectionCode( _
   ByVal Result As Integer, _
   ByVal Source As Integer, _
   ByVal Reason As Integer _
)
Parameters
Result
The "Result" of the rejection - see remarks for values
Source
The "Source" of the rejection - see remarks for values
Reason
The "Reason" for the rejection - see remarks for values
Remarks

These values are only used is the incoming association is rejected by setting the isOK parameter to false in AssociationRequest2 Event

Values for Result, Source and Reason are as follow:

Result:

  • 1 - rejected-permanent
  • 2 - rejected-transient

Source

  • 1 - DICOM UL service-user
  • 2 - DICOM UL service-provider (ACSE related function)
  • 3 - DICOM UL service-provider (Presentation related function)

Reason:

For Source field value of 1 (DICOM UL service-user)

  • 1 - no-reason-given
  • 2 - application-context-name-not-supported
  • 3 - calling-AE-title-not-recognized
  • 4-6 - reserved
  • 7 - called-AE-title-not-recognized
  • 8-10 - reserved

For Source field value of 2 (DICOM UL service-provider (ACSE related function))

  • 1 - no-reason-given
  • 2 - protocol-version-not-supported

For Source field value of 3 (DICOM UL service-provider (Presentation related function))

  • 0 - reserved
  • 1 - temporary-congestion
  • 2 - local-limit-exceeded
  • 3-7 - reserved
See Also

DicomConnection Object | DicomConnection Members


Wait Method

Wait Method
DicomObjects Reference > DicomConnection Object : Wait Method
Description
Wait for data transmission to complete
Syntax
Visual Basic
Public Sub Wait()
Remarks
This value may used by an application wishing to operate synchronously without using the ActionComplete event or setting Mode to doSync. If Mode is doSync, then this method will always return immediately.
See Also

DicomConnection Object | DicomConnection Members


Association Property

Association Property
DicomObjects Reference > DicomConnection Object : Association Property
Description
The association number on which the query operation was requested
Property type
Read-only property
Syntax
Visual Basic
Public Property Association As Long
Remarks
This is the value as given in a preceding AssociationRequest event.
See Also

DicomConnection Object | DicomConnection Members


BytesReceived Property

BytesReceived Property
DicomObjects Reference > DicomConnection Object : BytesReceived Property
Description
Approximate bytes received on this connection
Property type
Read-write property
Syntax
Visual Basic
Public Property BytesReceived As Long
Remarks
These properties report only approximate values, but are useful for updating of status bars etc. during asynchronous operations.
Some users with large files found that they could exceed the 2GigiByte limit of a signed long variable when transferring large images, so the Double variations were added (internally they are 64 bit integers, but COM does not support 64 bit values)
See Also

DicomConnection Object | DicomConnection Members


BytesReceivedDouble Property

BytesReceivedDouble Property
DicomObjects Reference > DicomConnection Object : BytesReceivedDouble Property
Description
Approximate bytes received on this connection
Property type
Read-write property
Syntax
Visual Basic
Public Property BytesReceivedDouble As Double
Remarks
These properties report only approximate values, but are useful for updating of status bars etc. during asynchronous operations.
Some users with large files found that they could exceed the 2GigiByte limit of a signed long variable when transferring large images, so the Double variations were added (internally they are 64 bit integers, but COM does not support 64 bit values)
See Also

DicomConnection Object | DicomConnection Members


BytesSent Property

BytesSent Property
DicomObjects Reference > DicomConnection Object : BytesSent Property
Description
Approximate bytes sent on this connection
Property type
Read-write property
Syntax
Visual Basic
Public Property BytesSent As Long
Remarks
These properties report only approximate values, but are useful for updating of status bars etc. during asynchronous operations.
Some users with large files found that they could exceed the 2GigiByte limit of a signed long variable when transferring large images, so the Double variations were added (internally they are 64 bit integers, but COM does not support 64 bit values)
See Also

DicomConnection Object | DicomConnection Members


BytesSentDouble Property

BytesSentDouble Property
DicomObjects Reference > DicomConnection Object : BytesSentDouble Property
Description
Approximate bytes sent on this connection
Property type
Read-write property
Syntax
Visual Basic
Public Property BytesSentDouble As Double
Remarks
These properties report only approximate values, but are useful for updating of status bars etc. during asynchronous operations.
Some users with large files found that they could exceed the 2GigiByte limit of a signed long variable when transferring large images, so the Double variations were added (internally they are 64 bit integers, but COM does not support 64 bit values)
See Also

DicomConnection Object | DicomConnection Members


CalledAET Property

CalledAET Property
DicomObjects Reference > DicomConnection Object : CalledAET Property
Description
Called AET used for this association
Property type
Read-write property
Syntax
Visual Basic
Public Property CalledAET As String
Remarks

These properties relate to open associations, and can be accessed at any time after the association has been made. For “outgoing” DicomConnection objects, they refer to the outgoing association and for “incoming” DicomConnection objects such as those created automatically as part of incoming C-STORE (async), C-FIND of C-GET requests, they relate to the association received. For C-MOVE, they continue to refer to the incoming association even once an outgoing association to carry the images has been established.

For details of the interface & port called, see LocalIP & LocalPort
Like other strings in DicomObjects, Application Entity Titles have any trailing spaces trimmed.

See Also

DicomConnection Object | DicomConnection Members


CallingAET Property

CallingAET Property
DicomObjects Reference > DicomConnection Object : CallingAET Property
Description
Calling Application's AET
Property type
Read-write property
Syntax
Visual Basic
Public Property CallingAET As String
Remarks

These properties relate to open associations, and can be accessed at any time after the association has been made. For “outgoing” DicomConnection objects, they refer to the outgoing association and for “incoming” DicomConnection objects such as those created automatically as part of incoming C-STORE (async), C-FIND of C-GET requests, they relate to the association received. For C-MOVE, they continue to refer to the incoming association even once an outgoing association to carry the images has been established.

For details of the interface & port called, see LocalIP & LocalPort
Like other strings in DicomObjects, Application Entity Titles have any trailing spaces trimmed.

See Also

DicomConnection Object | DicomConnection Members


Cancelled Property

Cancelled Property
DicomObjects Reference > DicomConnection Object : Cancelled Property
Description
Indicates that a C-CANCEL request has been received
Property type
Read-only property
Syntax
Visual Basic
Public Property Cancelled As Boolean
Remarks

C-CANCEL requests are handled internally by DicomObjects, with the result that, once a cancel request has been detected, no further images or other data are sent on the connection, and a status of Cancelled is automatically returned to the peer. In order to prevent errors from operations on a closed association, operations such as SendImages, SendData and SendStatus are still accepted, but are silently ignored. This property is therefore provided solely as an optimisation, to prevent unnecessary preparatory work by the client application.

Note that DicomObjects only checks for C-CANCEL requests when it would otherwise be listening for data from the SCU, so this is between images for C-GET/MOVE but does not occur between C-FIND responses, as these are not acknowledged by the SCU.

See Also

DicomConnection Object | DicomConnection Members


ChangeLossyUIDs Property

ChangeLossyUIDs Property
DicomObjects Reference > DicomConnection Object : ChangeLossyUIDs Property
Description
Controls whether to change UIDs when sending compressed images
Property type
Read-write property
Syntax
Visual Basic
Public Property ChangeLossyUIDs As Boolean
Remarks
There are times when the negotiated transfer syntaxes for a DicomConnection require a previously uncompressed (or losslessly compressed) image to be transmitted in a lossy form. Although the DICOM standard is not entirely clear, most people believe that a new instance UID should be generated whenever this happens. This is the normal DicomObjects behaviour, and a reference to the original UID is included in the referenced image sequence. However, some query SCUs having requested a specific image by it’s UID fail to look in the referenced image sequence and reject images with UIDs other than those they had requested. The default value of this property is true, but if set to false, then images sent via SendImages or SendModifiedImages which undergo lossy compression will not have new UIDs allocated.
See Also

DicomConnection Object | DicomConnection Members


CoercionSOP Property

CoercionSOP Property
DicomObjects Reference > DicomConnection Object : CoercionSOP Property
Description
SOP class to which images should be coerced if peer does not accept true SOP class
Property type
Read-write property
Syntax
Visual Basic
Public Property CoercionSOP As String
Remarks

Some equipment can only support a limited range of SOP classes, but there may be a need to send images of other types to it. If this property is set to a non-null value, and if the remote AE does not support the SOP class of an image being sent, (but does support the CoercionSOP class), then a temporary image (with a new UID) is generated with its SOP class set to equal CoercionSOP, and this is transmitted instead.
The most common value for CoercionSOP would be doSOP_SecondaryCapture (1.2.840.10008.5.1.4.1.1.7).

Although this practice is questionable, it is often useful for sending images such as ultrasounds, to display stations primarily designed for CT and MRI etc. but which also support secondary capture.

See Also

DicomConnection Object | DicomConnection Members


Command Property

Command Property
DicomObjects Reference > DicomConnection Object : Command Property
Description
The full request dataset received
Property type
Read-only property
Syntax
Visual Basic
Public Property Command As DicomDataSet
Remarks
An incoming request consists of two parts, a command dataset, containing elements in the 0000 group, and an identifier containing the details. This property equates to the command dataset, and the Request property equates to the identifier.
Whilst this property is available for all incoming requests on a DicomConnection, incoming composite operations are interpreted internally by DicomObjects, and presented via convenient properties such as Operation and Root. The main use for this property is therefore for incoming normalised operations (via NormalisedReceived) for which it provides the only access to the CommandID (0000,0100), and the requested and affected Instance UIDs and SOP Classes
See Also

DicomConnection Object | DicomConnection Members


Contexts Property

Contexts Property
DicomObjects Reference > DicomConnection Object : Contexts Property
Description
Presentation contexts in use on this association
Property type
Read-only property
Syntax
Visual Basic
Public Property Contexts As DicomContexts
Remarks

This is a powerful feature, allowing a client program as much, or as little control over presentation contexts as it wishes. The collection returned by this property may be used for two distinct purposes:

  • To set up a collection of presentation contexts to offer to the peer AE prior to establishing an association.
  • To check the presentation contexts available on an established association (incoming or outgoing).

IMPORTANT:

If this property is accessed and any presentation contexts added before an association is established, then DicomObjects assumes that the client application has taken charge of this entirely, and the normal Abstract/Transfer context lists found in the registry are NOT used.

Note that operations relating to the acceptance of presentation contexts are not possible on this DicomContexts object or its contained DicomContext object. Such operations are only possible from within the AssociationRequest event.

See Also

DicomConnection Object | DicomConnection Members


Destination Property

Destination Property
DicomObjects Reference > DicomConnection Object : Destination Property
Description
Destination for C-MOVE requests
Property type
Read-only property
Syntax
Visual Basic
Public Property Destination As String
Remarks
This property is used in conjunction with the MoveImages , MoveSync and GetUsingMove methods of a DicomQuery object. The Application entity name must be known to the DICOM server to which the request is being sent, as the standard allows no other means of specifying the destination. In particular, it is not possible to direct images to an arbitrary IP address and port using MoveImages.
A Query/Retrieve SCP must use this property of the DicomConnection object to find the values of the IP address, port, and possibly calling AET to use before calling SetDestination.
See Also

DicomConnection Object | DicomConnection Members


Errors Property

Errors Property
DicomObjects Reference > DicomConnection Object : Errors Property
Description
DicomDataSet used to return errors identified in the query request
Property type
Read-only property
Syntax
Visual Basic
Public Property Errors As DicomDataSet
Remarks

If a client identifies errors in a DicomConnection, it should place appropriate values into this property before calling SendStatus with an appropriate error code.
The appropriate elements to be inserted into this dataset are:

(0000,0901) : Offending Element
(0000,0902) : Error Comment

Only the appropriate elements, as defined by the returned status will be transmitted.

See Also

DicomConnection Object | DicomConnection Members


Failures Property

Failures Property
DicomObjects Reference > DicomConnection Object : Failures Property
Description
DicomDataSet containing list of failed SOP instances
Property type
Read-only property
Syntax
Visual Basic
Public Property Failures As DicomDataSet
Return Type
DicomDataSet
Remarks

It is not normally necessary for a client application to access this property, as the list is automatically created by the DicomConnection object when failures occur, and it is automatically passed on to the requesting application in the final status message. It would, however, be necessary for an application to modify the contents if it wished to accomplish C-MOVE operations using the Send method instead of using SendImages.
The list of failed SOP instances is present as

DicomConnection.Failures.Attributes(0008,0058)

which will return a string array.

See Also

DicomConnection Object | DicomConnection Members


isReady Property

isReady Property
DicomObjects Reference > DicomConnection Object : isReady Property
Description
Test whether the last asynchronous operation has completed
Property type
Read-only property
Syntax
Visual Basic
Public Property isReady As Boolean
Remarks
This value may used by an application wishing to operate asynchronously without using the ActionComplete event. If Mode=doSync, then this value is always true.
See Also

DicomConnection Object | DicomConnection Members


LastAction Property

LastAction Property
DicomObjects Reference > DicomConnection Object : LastAction Property
Description
Last action to have been performed on this connection
Property type
Read-only property
Syntax
Visual Basic
Public Property LastAction As String
Remarks
The values possible for this property are listed in the ActionComplete entry.
Unlike the action parameter in the ActionComplete event, this property returns the last action requested, which is not necessarily the same as the last completed. This property now has little use since the modification to the ActionComplete event, and may be withdrawn in future versions
See Also

DicomConnection Object | DicomConnection Members


LastError Property

LastError Property
DicomObjects Reference > DicomConnection Object : LastError Property
Description
Human readable form of last error reported on this connection
Property type
Read-only property
Syntax
Visual Basic
Public Property LastError As String
Remarks
This is the last DicomObjects error reported, which may or may not reflect a DICOM protocol error. It corresponds exactly with the ErrorMessage parameter of the ActionComplete event and with the OLE error reported if Mode=doSync. It is only valid when isReady is true.
See Also

DicomConnection Object | DicomConnection Members


LastInstanceUID Property

LastInstanceUID Property
DicomObjects Reference > DicomConnection Object : LastInstanceUID Property
Description
InstanceUID returned following outgoing normalised operations
Property type
Read-only property
Syntax
Visual Basic
Public Property LastInstanceUID As String
Return Type
String
Remarks
Although this property could be used for checking the UID involved in any normalised operation, its primary purpose is to allow retrieval of the UID of the object created in response to an NCreate operation.
This property contain the result of an outgoing operation on the DicomConnection, and if Mode is doAsync or doNoSync, it is therefore valid only once the operation is signaled as completed, either through the ActionComplete event, use of the Wait method, or when isReady is true.
See Also

DicomConnection Object | DicomConnection Members


LastStatus Property

LastStatus Property
DicomObjects Reference > DicomConnection Object : LastStatus Property
Description
Status of last operation (equivalent to Status(1))
Property type
Read-only property
Syntax
Visual Basic
Public Property LastStatus As Long
Remarks
A useful shortcut which makes it easier to access the result of the last operation performed, where only a single result is expected (e.g. after SendVerify). Like all similar properties, it is only valid when isReady is true.
See Also

DicomConnection Object | DicomConnection Members


LocalCertificate Property

LocalCertificate Property
DicomObjects Reference > DicomConnection Object : LocalCertificate Property
Description
X509 (CAPICOM) certificate to be used in negotiation
Property type
Read-write property
Syntax
Visual Basic
Public Property LocalCertificate As Object
Remarks

The LocalCertificate specifies the certificate to present to the remote entity when initiating an association (when acting as a receiver, use ListenSecure, which includes a certificate in it’s parameters). If UseTLS is true, but this property is null, then an anonymous association attempt will be made, which may or may not be accepted by the remote entity.

RemoteCertificate allows an application to verify the certificate presented by the remote entity, which may be done in 3 ways:

When receiving an incoming association in AssociationRequest2, the remote certificate is available as a property of the new incoming association, allowing an accept/reject decision to be made based on it’s contents (it may be NULL if an anonymous association has been attempted).
After making an outgoing association using SetDestination, the remote certificate is available once this operation has completed (during ActionComplete or one isReady is true). This is the correct place for a client to validate the server before performing sensitive transactions, as it protects against a “man-in-the-middle” attack.

After an outgoing DicomQuery based operation has completed, this property indicates the certificate which has been provided. Note of course, that this is useful only for auditing, not control, as it is available only after data has been exchanged, so in a proper secure application, the DicomQuery based methods should be replaced by their DicomConnection based equivalents, which allow prior validation.

For more information on using X509 certificates in DicomObjects, see Certificates

See Also

DicomConnection Object | DicomConnection Members


LocalIP Property

LocalIP Property
DicomObjects Reference > DicomConnection Object : LocalIP Property
Description
Local IP address called
Property type
Read-write property
Syntax
Visual Basic
Public Property LocalIP As String
Remarks

These properties relate to open incoming associations only, and can be accessed at any time after the association has been made. For “outgoing” DicomConnection objects, they are null and 0. For “incoming” DicomConnection objects such as those created automatically as part of incoming C-STORE (async), C-FIND of C-GET requests, they relate to the association received. For C-MOVE, they continue to refer to the incoming association even once an outgoing association to carry the images has been established.

For remote application details see CallingAET, CalledAET & RemoteIP

See Also

DicomConnection Object | DicomConnection Members


LocalPort Property

LocalPort Property
DicomObjects Reference > DicomConnection Object : LocalPort Property
Description
Local port Called
Property type
Read-write property
Syntax
Visual Basic
Public Property LocalPort As Long
Remarks

These properties relate to open incoming associations only, and can be accessed at any time after the association has been made. For “outgoing” DicomConnection objects, they are null and 0. For “incoming” DicomConnection objects such as those created automatically as part of incoming C-STORE (async), C-FIND of C-GET requests, they relate to the association received. For C-MOVE, they continue to refer to the incoming association even once an outgoing association to carry the images has been established.

For remote application details see CallingAET, CalledAET & RemoteIP

See Also

DicomConnection Object | DicomConnection Members


MetaSOPClass Property

MetaSOPClass Property
DicomObjects Reference > DicomConnection Object : MetaSOPClass Property
Description
Meta SOP class to be used for outgoing normalised operations
Property type
Read-write property
Syntax
Visual Basic
Public Property MetaSOPClass As String
Remarks
Normalised operations, unlike composite operations, are not directly tied to specific abstract syntaxes, but still need to be sent within a negotiated presentation context, which generally relates to a number of related operations, and is known as a Meta SOP Class. This property defines this abstract context, and is therefore used for the selection of an appropriate presentation context, according to those negotiated and available.
If this property is a null string, then the SOP class specified in the normalised operation itself is used, which may be appropriate for some classes, which do not use meta SOP classes for negotiation.
See Also

DicomConnection Object | DicomConnection Members


Mode Property

Mode Property
DicomObjects Reference > DicomConnection Object : Mode Property
Description
Controls whether connection works synchronously with the container
Property type
Read-write property
Syntax
Visual Basic
Public Property Mode As doConnectionMode
Remarks

See Also

DicomConnection Object | DicomConnection Members


MoveOriginator Property

MoveOriginator Property
DicomObjects Reference > DicomConnection Object : MoveOriginator Property
Description
Identifies the DicomConnection object which initated (via C-MOVE) this C-STORE
Property type
Read-only property
Syntax
Visual Basic
Public Property MoveOriginator As Object
Remarks

This property is only valid for incoming DicomConnection objects passed as parameters to ImageReceivedAsync events, where the C-STORE operation was initiated by an asynchronous C-MOVE (DicomConnection’s Move method) from the same program. In addition the remote SCP must include the optional originating MessageID in it’s responses (many appear not to). If these conditions are fulfilled, then this property provides a pointer to the originating DicomConnection.

The property is provided as an IDispatch which in many languages will need to be cast to a DicomConnection. This is to avoid an annoying bug in Visual Basic, which refuses to accept that an object can have a property of the same type as itself!

See Also

DicomConnection Object | DicomConnection Members


NumberCompleted Property

NumberCompleted Property
DicomObjects Reference > DicomConnection Object : NumberCompleted Property
Description
Number of completed move/get operations
Property type
Read-write property
Syntax
Visual Basic
Public Property NumberCompleted As Long
Remarks
These values are returned to the requester as part of pending or final status notifications.
Values are updated automatically as part of SendImages, each operation decrementing NumberRemaining, and incrementing NumberCompleted, NumberWarning or NumberFailed according to the status returned.
If NumberRemaining is less than the number of images sent by a SendImages call, then NumberRemaining is set to the number of images to be returned by that call. Therefore, if an application intends to return all the images for a request in one operation, then it need not manipulate these values at all, as the DicomConnection object will handle then automatically. If however the application wishes to call SendImages more than once, then NumberRemaining must be set correctly before the first call.
See Also

DicomConnection Object | DicomConnection Members


NumberFailed Property

NumberFailed Property
DicomObjects Reference > DicomConnection Object : NumberFailed Property
Description
Number of failed move/get operations
Property type
Read-write property
Syntax
Visual Basic
Public Property NumberFailed As Long
Remarks
These values are returned to the requester as part of pending or final status notifications.
Values are updated automatically as part of SendImages, each operation decrementing NumberRemaining, and incrementing NumberCompleted, NumberWarning or NumberFailed according to the status returned.
If NumberRemaining is less than the number of images sent by a SendImages call, then NumberRemaining is set to the number of images to be returned by that call. Therefore, if an application intends to return all the images for a request in one operation, then it need not manipulate these values at all, as the DicomConnection object will handle then automatically. If however the application wishes to call SendImages more than once, then NumberRemaining must be set correctly before the first call.
See Also

DicomConnection Object | DicomConnection Members


NumberRemaining Property

NumberRemaining Property
DicomObjects Reference > DicomConnection Object : NumberRemaining Property
Description
Number of remaining move/get operations
Property type
Read-write property
Syntax
Visual Basic
Public Property NumberRemaining As Long
Remarks
These values are returned to the requester as part of pending or final status notifications.
Values are updated automatically as part of SendImages, each operation decrementing NumberRemaining, and incrementing NumberCompleted, NumberWarning or NumberFailed according to the status returned.
If NumberRemaining is less than the number of images sent by a SendImages call, then NumberRemaining is set to the number of images to be returned by that call. Therefore, if an application intends to return all the images for a request in one operation, then it need not manipulate these values at all, as the DicomConnection object will handle then automatically. If however the application wishes to call SendImages more than once, then NumberRemaining must be set correctly before the first call.
See Also

DicomConnection Object | DicomConnection Members


NumberWarning Property

NumberWarning Property
DicomObjects Reference > DicomConnection Object : NumberWarning Property
Description
Number of warning move/get operations
Property type
Read-write property
Syntax
Visual Basic
Public Property NumberWarning As Long
Remarks
These values are returned to the requester as part of pending or final status notifications.
Values are updated automatically as part of SendImages, each operation decrementing NumberRemaining, and incrementing NumberCompleted, NumberWarning or NumberFailed according to the status returned.
If NumberRemaining is less than the number of images sent by a SendImages call, then NumberRemaining is set to the number of images to be returned by that call. Therefore, if an application intends to return all the images for a request in one operation, then it need not manipulate these values at all, as the DicomConnection object will handle then automatically. If however the application wishes to call SendImages more than once, then NumberRemaining must be set correctly before the first call.
See Also

DicomConnection Object | DicomConnection Members


ObjectType Property

ObjectType Property
DicomObjects Reference > DicomConnection Object : ObjectType Property
Description
Describes the nature of an automation object
Property type
Read-only property
Syntax
Visual Basic
Public Property ObjectType As String
Remarks

The possible values are as follows:

“DicomViewer”
“DicomQuery”
“DicomImage”
“DicomImages”
“DicomDataSet”
“DicomDataSets”
“DicomAttribute”
“DicomConnection”
“DicomConnections”
“DicomContext”
“DicomContexts”
“DicomLabel”
“DicomLabels”
“DicomGlobal”
“DicomLog”
“DicomPrint”

See Also

DicomConnection Object | DicomConnection Members


Operation Property

Operation Property
DicomObjects Reference > DicomConnection Object : Operation Property
Description
The type of query operation requested
Property type
Read-only property
Syntax
Visual Basic
Public Property Operation As String
Remarks

The values possible for this property are:

“C-FIND”
“C-MOVE”
“C-GET”

In order to define the request fully, this property should be used in conjunction with the Root and Request properties.

See Also

DicomConnection Object | DicomConnection Members


PreferredPCID Property

PreferredPCID Property
DicomObjects Reference > DicomConnection Object : PreferredPCID Property
Description
Preferred presentation context to be used (where possible)
Property type
Read-write property
Syntax
Visual Basic
Public Property PreferredPCID As Integer
Remarks

Under some circumstances, DicomObjects may have a choice of presentation contexts to use for a given operation, and these properties provide guidance on which of the available options to use.

DicomObjects cannot, however, guarantee that the values given will be honoured, as the requirements of the standard, and the negotiated presentation contexts available will always take priority. Note also, that they can only be effective at the application actually carrying out the operation involved, normally the SCP.

The default values for these parameters are a null string and zero respectively, and these values are taken to mean “no preference”.

Presentation context will be selected according to the following procedure:

  • If the presentation context given by PreferredPCID is appropriate for the operation, it is used.
  • If not, and if any presentation context, using the transfer syntax given by PreferredTS is available, then that is used.
  • If neither of the above applies, then any suitable and negotiated presentation context is used.

These properties are particularly designed for teleradiology applications, where run-time selection of a compressed syntax may be appropriate.

For a list of the available presentation contexts, see the Contexts property.

See Also

DicomConnection Object | DicomConnection Members


PreferredTS Property

PreferredTS Property
DicomObjects Reference > DicomConnection Object : PreferredTS Property
Description
Preferred transfer syntax to be used (where possible)
Property type
Read-write property
Syntax
Visual Basic
Public Property PreferredTS As String
Remarks

Under some circumstances, DicomObjects may have a choice of presentation contexts to use for a given operation, and these properties provide guidance on which of the available options to use.

DicomObjects cannot, however, guarantee that the values given will be honoured, as the requirements of the standard, and the negotiated presentation contexts available will always take priority. Note also, that they can only be effective at the application actually carrying out the operation involved, normally the SCP.

The default values for these parameters are a null string and zero respectively, and these values are taken to mean “no preference”.

Presentation context will be selected according to the following procedure:

  • If the presentation context given by PreferredPCID is appropriate for the operation, it is used.
  • If not, and if any presentation context, using the transfer syntax given by PreferredTS is available, then that is used.
  • If neither of the above applies, then any suitable and negotiated presentation context is used.

These properties are particularly designed for teleradiology applications, where run-time selection of a compressed syntax may be appropriate.

For a list of the available presentation contexts, see the Contexts property.

See Also

DicomConnection Object | DicomConnection Members


PresentationContextID Property

PresentationContextID Property
DicomObjects Reference > DicomConnection Object : PresentationContextID Property
Description
Presentation Context ID used for current operation
Property type
Read-only property
Syntax
Visual Basic
Public Property PresentationContextID As Byte
See Also

DicomConnection Object | DicomConnection Members


RemoteCertificate Property

RemoteCertificate Property
DicomObjects Reference > DicomConnection Object : RemoteCertificate Property
Description
X509 (CAPICOM) certificate provided by remote entity
Property type
Read-write property
Syntax
Visual Basic
Public Property RemoteCertificate As Object
Remarks

The LocalCertificate specifies the certificate to present to the remote entity when initiating an association (when acting as a receiver, use ListenSecure, which includes a certificate in it’s parameters). If UseTLS is true, but this property is null, then an anonymous association attempt will be made, which may or may not be accepted by the remote entity.

RemoteCertificate allows an application to verify the certificate presented by the remote entity, which may be done in 3 ways:

When receiving an incoming association in AssociationRequest2, the remote certificate is available as a property of the new incoming association, allowing an accept/reject decision to be made based on it’s contents (it may be NULL if an anonymous association has been attempted).
After making an outgoing association using SetDestination, the remote certificate is available once this operation has completed (during ActionComplete or one isReady is true). This is the correct place for a client to validate the server before performing sensitive transactions, as it protects against a “man-in-the-middle” attack.

After an outgoing DicomQuery based operation has completed, this property indicates the certificate which has been provided. Note of course, that this is useful only for auditing, not control, as it is available only after data has been exchanged, so in a proper secure application, the DicomQuery based methods should be replaced by their DicomConnection based equivalents, which allow prior validation.

For more information on using X509 certificates in DicomObjects, see Certificates

See Also

DicomConnection Object | DicomConnection Members


RemoteIP Property

RemoteIP Property
DicomObjects Reference > DicomConnection Object : RemoteIP Property
Description
Remote Application's IP
Property type
Read-write property
Syntax
Visual Basic
Public Property RemoteIP As String
Remarks

These properties relate to open associations, and can be accessed at any time after the association has been made. For “outgoing” DicomConnection objects, they refer to the outgoing association and for “incoming” DicomConnection objects such as those created automatically as part of incoming C-STORE (async), C-FIND of C-GET requests, they relate to the association received. For C-MOVE, they continue to refer to the incoming association even once an outgoing association to carry the images has been established.

For details of the interface & port called, see LocalIP & LocalPort
Like other strings in DicomObjects, Application Entity Titles have any trailing spaces trimmed.

See Also

DicomConnection Object | DicomConnection Members


Request Property

Request Property
DicomObjects Reference > DicomConnection Object : Request Property
Description
DicomDataSet containing the query details
Property type
Read-only property
Syntax
Visual Basic
Public Property Request As DicomDataSet
Remarks
It is the client’s responsibility to interpret the contents of this identifier and ensure that the data or images returned match the data sent, and in the case of C-FIND operations, to ensure that all data elements requested are included in the response.
The “level” of the query may be found in Attributes(0008,0052) of this property.
The handling of Query/Retrieve requests as an SCP is an advanced technique, and the rules to be obeyed are beyond the scope of this help file. See the Access SCP example for a demonstration of a possible implementation.
See Also

DicomConnection Object | DicomConnection Members


ReturnedDataSet Property

ReturnedDataSet Property
DicomObjects Reference > DicomConnection Object : ReturnedDataSet Property
Description
DataSet returned following outgoing normalised operations
Property type
Read-only property
Syntax
Visual Basic
Public Property ReturnedDataSet As DicomDataSet
Remarks

These properties contain the results of outgoing operations on the DicomConnection, and if Mode is doAsync or doNoSync, they are therefore valid only once the operation is signaled as completed, either through the ActionComplete event, use of the Wait method, or when isReady is true. The relevant property depends on the operation performed, and is shown below:

Operation | Property
Find | ReturnedDataSets
Get | ReturnedImages
Normalised operations | ReturnedDataSet

See Also

DicomConnection Object | DicomConnection Members


ReturnedDataSets Property

ReturnedDataSets Property
DicomObjects Reference > DicomConnection Object : ReturnedDataSets Property
Description
DataSet returned following outgoing normalised operations
Property type
Read-only property
Syntax
Visual Basic
Public Property ReturnedDataSets As DicomDataSets
Remarks

These properties contain the results of outgoing operations on the DicomConnection, and if Mode is doAsync or doNoSync, they are therefore valid only once the operation is signaled as completed, either through the ActionComplete event, use of the Wait method, or when isReady is true. The relevant property depends on the operation performed, and is shown below:

Operation | Property
Find | ReturnedDataSets
Get | ReturnedImages
Normalised operations | ReturnedDataSet

See Also

DicomConnection Object | DicomConnection Members


ReturnedImages Property

ReturnedImages Property
DicomObjects Reference > DicomConnection Object : ReturnedImages Property
Description
Images returned following asynchronous C-GET operation
Property type
Read-only property
Syntax
Visual Basic
Public Property ReturnedImages As DicomImages
Remarks

These properties contain the results of outgoing operations on the DicomConnection, and if Mode is doAsync or doNoSync, they are therefore valid only once the operation is signaled as completed, either through the ActionComplete event, use of the Wait method, or when isReady is true. The relevant property depends on the operation performed, and is shown below:

Operation | Property
Find | ReturnedDataSets
Get | ReturnedImages
Normalised operations | ReturnedDataSet

See Also

DicomConnection Object | DicomConnection Members


ReturnedResponses Property

ReturnedResponses Property
DicomObjects Reference > DicomConnection Object : ReturnedResponses Property
Description
DicomDataSets Returned in responses to outgoing requests
Property type
Read-only property
Syntax
Visual Basic
Public Property ReturnedResponses As DicomDataSets
Remarks
In most cases, the useful data returned from an operation will be present once the operation is complete in properties such as Status, LastStatus, ReturnedDataSet, or ReturnedDataSets. However, in some cases, particularly where errors are reported, it is useful to be able to access and parse the associated command (group 0) elements. This property provides that facility, and contains one DicomDataSet for each response received. Like all similar properties, it is only valid when isReady is true.
See Also

DicomConnection Object | DicomConnection Members


Root Property

Root Property
DicomObjects Reference > DicomConnection Object : Root Property
Description
The Root of the query operation requested
Property type
Read-only property
Syntax
Visual Basic
Public Property Root As String
Remarks

The values possible for this property are:

“PATIENT”
“STUDY”
“PATIENT/STUDY”

“WORKLIST”
“GP-WORKLIST”

In order to define the request fully, this property should be used in conjunction with the Operation and Request properties.

See Also

DicomConnection Object | DicomConnection Members


Status Property

Status Property
DicomObjects Reference > DicomConnection Object : Status Property
Description
Array of status values returned by last operation
Property type
Read-only property
Syntax
Visual Basic
Public Property Status As Variant
Remarks

This array is cleared before each operation, and the number of elements therefore reflects the number of images sent.
After a SendVerify operation, the element will contain only one value, so LastStatus is normally more appropriate.
This property contain the result of an outgoing operation on the DicomConnection, and if Mode is doAsync or doNoSync, it is therefore valid only once the operation is signaled as completed, either through the ActionComplete event, use of the Wait method, or when isReady is true.

Note that Visual Basic can have a problem distinguishing between function parameters and array indices if an attempt is made to create the status array and access a specific status value in the same statement. e.g.
x=connection.status(1)
will generate an error, stating that the numbers of parameters is incorrect. If only one status value is expected, then the LastStatus property returns the same value in a simpler manner, but if multiple values are required, then the following solution is available:

stat=connection.status
x=stat(1)

Similar problems may occur in other languages, and same solution is recommended.

See Also

DicomConnection Object | DicomConnection Members


Tag Property

Tag Property
DicomObjects Reference > DicomConnection Object : Tag Property
Description
General Purpose Tag
Property type
Read-write property
Syntax
Visual Basic
Public Property Tag As Variant
Remarks

These values are not used by the associated object, and are available for user use. A special case is the DicomConnection object, where Tag is included in the ActionComplete event procedure, assisting identification of necessary features of the connection, such as pending database operations etc. In this use, the value of Tag is stored at the time an operation is initiated, and it is this stored value which is passed to ActionComplete, simplifying the task of tracking which operations have happened.

The TagObject property holds another object, typically a DicomLabels collection, and this can be useful when arranging DicomLabel objects into groups.

See Also

DicomConnection Object | DicomConnection Members


ThrottleRate Property

ThrottleRate Property
DicomObjects Reference > DicomConnection Object : ThrottleRate Property
Description
Maximum data rate in bytes/second
Property type
Read-write property
Syntax
Visual Basic
Public Property ThrottleRate As Long
Remarks
The rate is in bytes per second and applies to the sum of incoming and outgoing data. The sending/receiving is paused if necessary on each PDU to limit to the required rate.
See Also

DicomConnection Object | DicomConnection Members


UseTLS Property

UseTLS Property
DicomObjects Reference > DicomConnection Object : UseTLS Property
Description
Controls whether to negotiate a secure association using TLS
Property type
Read-write property
Syntax
Visual Basic
Public Property UseTLS As Boolean
Remarks
If true, then new outgoing associations made using this object (using SetDestination for DicomConnection objects, or any of the Q/R methods such as DoQuery, GetImages etc. for DicomQuery) will use a secured connection.
Secure associations can be made with or without a client certificate, and this is controlled by the LocalCertificate property.
See Also

DicomConnection Object | DicomConnection Members


DicomConnections Collection

DicomConnections Collection
Members
DicomObjects Reference : DicomConnections Collection
Description
This is a true OLE collection, a consisting of DicomConnection objects.
Remarks

This collection may be useful for those programmers needing to keep track of all current associations.

Like all other collections in DicomObjects, this collection supports the “NewEnum” property, enabling use for the “for each” construct in Visual Basic.

See Also

DicomConnections Members


DicomConnections Collection Members

DicomConnections Collection Members
Overview
DicomObjects Reference : DicomConnections Collection
Public Methods
Public Method Add | Adds an item
Public Method Clear | Clears the Collection
Public Method IndexOf | Identifes position of an item in a collection
Public Method Move | Moves a Connection item
Public Method Remove | Removes an item from the collection
Public Properties
Public Property Count | The number of items in the collection
Public Property Item | Accesses a Connection item
Public Property ObjectType | Describes the nature of an automation object
Public Property Tag | General Purpose Tag
See Also

DicomConnections Collection


Add Method

Add Method
DicomObjects Reference > DicomConnections Collection : Add Method
DicomConnection to be added to this collection
Description
Adds an item
Syntax
Visual Basic
Public Sub Add( _
   ByVal Connection As DicomConnection _
)
Parameters
Connection
DicomConnection to be added to this collection
Remarks
The new addition is added at the end of the collection.
See Also

DicomConnections Collection | DicomConnections Members


Clear Method

Clear Method
DicomObjects Reference > DicomConnections Collection : Clear Method
Description
Clears the Collection
Syntax
Visual Basic
Public Sub Clear()
Remarks
Immediately clears a collection. The collection object persists, but after the call is empty. The contained objects are only destroyed if there are no other outstanding references to them.
See Also

DicomConnections Collection | DicomConnections Members


IndexOf Method

IndexOf Method
DicomObjects Reference > DicomConnections Collection : IndexOf Method
The object to be located.
Description
Identifes position of an item in a collection
Syntax
Visual Basic
Public Function IndexOf( _
   ByVal Object As DicomConnection _
) As Long
Parameters
Object
The object to be located.
Remarks
The value returned locates the first occurrence of the specified object within the collection. In the case of DicomImages, DicomDataSets or DicomLabels collections, the reference may be to an object derived from the same source, as such objects may be cloned when added to collections.
See Also

DicomConnections Collection | DicomConnections Members


Move Method

Move Method
DicomObjects Reference > DicomConnections Collection : Move Method
The current index in the collection
The new index for the Connection within the collection
Description
Moves a Connection item
Syntax
Visual Basic
Public Sub Move( _
   ByVal Index As Long, _
   ByVal Destination As Long _
)
Parameters
Index
The current index in the collection
Destination
The new index for the Connection within the collection
Remarks
By using Move, Connections may be re-ordered within the collection. The Connection referred to by the index is placed at the position given by "destination", other Connections being kept in sequence but moved as necessary to accommodate the moved item.
See Also

DicomConnections Collection | DicomConnections Members


Remove Method

Remove Method
DicomObjects Reference > DicomConnections Collection : Remove Method
The index of the connection to remove
Description
Removes an item from the collection
Syntax
Visual Basic
Public Sub Remove( _
   ByVal Index As Long _
)
Parameters
Index
The index of the connection to remove
Remarks
Removing DicomConnection from this collection by given index
See Also

DicomConnections Collection | DicomConnections Members


Count Property

Count Property
DicomObjects Reference > DicomConnections Collection : Count Property
Description
The number of items in the collection
Property type
Read-only property
Syntax
Visual Basic
Public Property Count As Long
Remarks
This is useful both for checking the value of indexes into the collection, and for iterating thought the images numerically, though as all collections in this product provide true iterators (allowing for instance the For Each construct in Visual Basic), this should rarely be necessary in such languages.
Where it is necessary to iterate through collections by integer index this can be done using ItemByIndex for DicomAttributes collections, and the Item property for the others.
See Also

DicomConnections Collection | DicomConnections Members


Item Property

Item Property
DicomObjects Reference > DicomConnections Collection : Item Property
The index of the item to be returned - this is normally 1-based, but see DicomGlobal.DotNetMode.
Description
Accesses a Connection item
Property type
Read-only property
Syntax
Visual Basic
Public Property Item( _
   ByVal Index As Long _
) As DicomConnection
Parameters
Index
The index of the item to be returned - this is normally 1-based, but see DicomGlobal.DotNetMode.
Return Type
DicomConnection
Remarks
As this is the default property, the term "Item" is rarely used, as Connections.Item(3)
may rather more concisely be written as Connections(3)
See Also

DicomConnections Collection | DicomConnections Members


ObjectType Property

ObjectType Property
DicomObjects Reference > DicomConnections Collection : ObjectType Property
Description
Describes the nature of an automation object
Property type
Read-only property
Syntax
Visual Basic
Public Property ObjectType As String
Remarks

The possible values are as follows:

“DicomViewer”
“DicomQuery”
“DicomImage”
“DicomImages”
“DicomDataSet”
“DicomDataSets”
“DicomAttribute”
“DicomConnection”
“DicomConnections”
“DicomContext”
“DicomContexts”
“DicomLabel”
“DicomLabels”
“DicomGlobal”
“DicomLog”
“DicomPrint”

See Also

DicomConnections Collection | DicomConnections Members


Tag Property

Tag Property
DicomObjects Reference > DicomConnections Collection : Tag Property
Description
General Purpose Tag
Property type
Read-write property
Syntax
Visual Basic
Public Property Tag As Variant
Remarks

Tag properties are attached to most objects in DicomObjects. The values are not used by the associated object, and are available for user use. A special case is the DicomConnection object, where Tag is included in the ActionComplete event procedure, assisting identification of necessary features of the connection, such as pending database operations etc. In this use, the value of Tag is stored at the time an operation is initiated, and it is this stored value which is passed to ActionComplete, simplifying the task of tracking which operations have happened.

The TagObject property holds another object, typically a DicomLabels collection, and this can be useful when arranging DicomLabel objects into groups.

See Also

DicomConnections Collection | DicomConnections Members


DicomContext Object

DicomContext Object
Members
DicomObjects Reference : DicomContext Object
Description
A DicomContext represents a DICOM presentation context, and is used in association negotiation, and in the selection of transmission formats (transfer syntaxes). DicomContext items only exist within a DicomContexts collection, and more information on the use of DicomContext items may be found in the DicomContexts entry.
See Also

DicomContext Members


DicomContext Object Members

DicomContext Object Members
Overview
DicomObjects Reference : DicomContext Object
Public Methods
Public Method Reject Reject a particular presentation context
Public Properties
Public Property AbstractSyntax | The abstract context of the DicomContext Item
Public Property AcceptedTS | The accepted transfer context of the DicomContext Item
Public Property ContextID | The presentation context ID
Public Property ExtendedNegotiationValues | Enable information about and control over extended negotiation
Public Property ObjectType | Describes the nature of an automation object
Public Property OfferedTS | The array of offered transfer contexts of the DicomContext Item
Public Property RequestorSCPRole | Controls SCU/SCP role negotation
Public Property RequestorSCURole | Controls SCU/SCP role negotation
See Also

DicomContext Object


Reject Method

Reject Method
DicomObjects Reference > DicomContext Object : Reject Method
The reason for rejection.
Description
Reject a particular presentation context
Syntax
Visual Basic
Public Sub Reject( _
   ByVal Reason As Integer _
)
Parameters
Reason
The reason for rejection.
Remarks
This method, and setting of the AcceptedTS property are mutually exclusive, and if both are used, the latest used takes precedence.
The defined reasons are:
1 - user-rejection
2 - no-reason (provider rejection)
3 - abstract-syntax-not-supported (provider rejection)
4 - transfer-syntaxes-not-supported (provider rejection)
See Also

DicomContext Object | DicomContext Members


AbstractSyntax Property

AbstractSyntax Property
DicomObjects Reference > DicomContext Object : AbstractSyntax Property
Description
The abstract context of the DicomContext Item
Property type
Read-only property
Syntax
Visual Basic
Public Property AbstractSyntax As String
Remarks
This value my either be a SOP class, such as doSOP_CT, or a Meta SOP class such as doMeta_BasicGrayscalePrint.
Whilst this property may be set to, or compared with full UID strings, use of UID Constants is advised for better readability.
See Also

DicomContext Object | DicomContext Members


AcceptedTS Property

AcceptedTS Property
DicomObjects Reference > DicomContext Object : AcceptedTS Property
Description
The accepted transfer context of the DicomContext Item
Property type
Read-write property
Syntax
Visual Basic
Public Property AcceptedTS As String
Remarks

This property allows a client program, in an AssociationRequest event, to select which transfer syntax to accept for a given presentation context, the list offered being found in the OfferedTS property. If none of the offered contexts is acceptable, then instead of setting this value, the Reject method should be called.
If no value is set, and Reject is not called, then DicomObjects will automatically select a value, based on the registry settings.

On an established association, whether incoming or outgoing, the client may use this property to check which transfer syntax will be used, especially if the same abstract context exists in more than one presentation context. The DicomConnection’s PreferredPCID property may then be set to the appropriate DicomContext’s ContextID value.

See Also

DicomContext Object | DicomContext Members


ContextID Property

ContextID Property
DicomObjects Reference > DicomContext Object : ContextID Property
Description
The presentation context ID
Property type
Read-only property
Syntax
Visual Basic
Public Property ContextID As Integer
Remarks
The value of this property is normally a small odd integer between 1 and 255, though some faulty public domain software incorrectly uses even values which may be seen, and need to be tolerated.
The value is set when the DicomContext item is created, either implicitly, or by the DicomContexts Add method, and cannot be changed.
This value may be used to set the DicomConnection’s PreferredPCID property, and is also used to index into the DicomContexts collection.
See Also

DicomContext Object | DicomContext Members


ExtendedNegotiationValues Property

ExtendedNegotiationValues Property
DicomObjects Reference > DicomContext Object : ExtendedNegotiationValues Property
Description
Enable information about and control over extended negotiation
Property type
Read-write property
Syntax
Visual Basic
Public Property ExtendedNegotiationValues As Variant
Remarks

This property enable applications to share or negotiate extended information about themselves.

The exact meanings of the various values and byte positions used for extended negotiation vary from one service class to another, and they are all detailed in part 4 of DICOM.

e.g. for C-STORE operations, byte 1 represents the “storage level”, byte 3 the level of digital signature support and byte 5 controls the coercion of data elements (2,4, & 6 are reserved). However, for C-FIND operations, only 1 byte is specified, indicating whether the SCP supports relational queries. In all cases, support is optional, and default values exist if extended negotiation is not performed.

The default behaviour of DicomObjects depends on whether the EnableExtendedNegotiation of DicomGlobal is set, and the default value of this property is false, to ensure backwards compatibility with older versions.

If EnableExtendedNegotiation is false, then no extended negotiation items are proposed or accepted, irrespective of what is done with the ExtendedNegotiationValues property.

If EnableExtendedNegotiation is true, then any extended negotiation items set up before SetDestination are proposed. When incoming associations are received, then incoming values are automatically sent out again (i.e. accepted) unless altered using the ExtendedNegotiationValues property in the AssociationRequest or AssociationRequest2 events.

Once an association is established, this property becomes read-only, but still reflects the arrangement negotiated.

Please note that this property is shared between all contexts with the same Abstract Syntax (SOP class), so changing one will change the value for any other matching contexts.

See Also

DicomContext Object | DicomContext Members


ObjectType Property

ObjectType Property
DicomObjects Reference > DicomContext Object : ObjectType Property
Description
Describes the nature of an automation object
Property type
Read-only property
Syntax
Visual Basic
Public Property ObjectType As String
Remarks

The possible values are as follows:

“DicomViewer”
“DicomQuery”
“DicomImage”
“DicomImages”
“DicomDataSet”
“DicomDataSets”
“DicomAttribute”
“DicomConnection”
“DicomConnections”
“DicomContext”
“DicomContexts”
“DicomLabel”
“DicomLabels”
“DicomGlobal”
“DicomLog”
“DicomPrint”

See Also

DicomContext Object | DicomContext Members


OfferedTS Property

OfferedTS Property
DicomObjects Reference > DicomContext Object : OfferedTS Property
Description
The array of offered transfer contexts of the DicomContext Item
Property type
Read-write property
Syntax
Visual Basic
Public Property OfferedTS As Variant
Remarks

This property holds the list of transfer syntaxes offered as part of association negotiation. As an SCU, it may be set up by a client program prior to calling SetDestination. As an SCP, the values may be inspected during the AssociationRequest event in order to select which one to accept (by setting AcceptedTS).
If not set explicitly by a client program, a default list is used, based on the abstract context, and registry settings
Whilst this property may be set to, or compared with full UID strings, use of UID's is advised for better readability.

Note that Visual Basic can have a problem distinguishing between function parameters and array indices if an attempt is made to create the array and access a specific value in the same statement. e.g.
x=context.OfferedTS(1)
will generate an error, stating that the numbers of parameters is incorrect, and this should therefore be changed to:
ts= context.OfferedTS
x=ts(1)
Similar problems may occur in other languages, and same solution is recommended.

See Also

DicomContext Object | DicomContext Members


RequestorSCPRole Property

RequestorSCPRole Property
DicomObjects Reference > DicomContext Object : RequestorSCPRole Property
Description
Controls SCU/SCP role negotation
Property type
Read-write property
Syntax
Visual Basic
Public Property RequestorSCPRole As Boolean
Remarks

Normally in DICOM, the requester of an association becomes the SCU, and the acceptor becomes the SCP, but there are some situations (notably Storage Commitment), where this relationship needs to be reversed (or it is possible for both applications to adopt both roles). In DicomObjects, this is achieved using these properties, and is only possible (for outgoing operations) using an association based on an explicit DicomConnection.
To propose reverse role negotiation, DicomContext items must be created explicitly, and the context’s RequestorSCURole (default true) should be set to false, and the RequestorSCPRole (default false) should be set to true.

When accepting associations, DicomObjects’ default action is to accept whatever roles are proposed by the requestor, but this may be over-ridden in the AssociationRequest event by modifying these properties of any of the proposed contexts.
Once an association is established, these properties become read-only, but still reflect the arrangement negotiated.
Please note that these properties are shared between all contexts with the same Abstract Syntax (SOP class), so changing one will change the value for any other matching contexts.

See Also

DicomContext Object | DicomContext Members


RequestorSCURole Property

RequestorSCURole Property
DicomObjects Reference > DicomContext Object : RequestorSCURole Property
Description
Controls SCU/SCP role negotation
Property type
Read-write property
Syntax
Visual Basic
Public Property RequestorSCURole As Boolean
Remarks

Normally in DICOM, the requester of an association becomes the SCU, and the acceptor becomes the SCP, but there are some situations (notably Storage Commitment), where this relationship needs to be reversed (or it is possible for both applications to adopt both roles). In DicomObjects, this is achieved using these properties, and is only possible (for outgoing operations) using an association based on an explicit DicomConnection.
To propose reverse role negotiation, DicomContext items must be created explicitly, and the context’s RequestorSCURole (default true) should be set to false, and the RequestorSCPRole (default false) should be set to true.

When accepting associations, DicomObjects’ default action is to accept whatever roles are proposed by the requestor, but this may be over-ridden in the AssociationRequest event by modifying these properties of any of the proposed contexts.
Once an association is established, these properties become read-only, but still reflect the arrangement negotiated.
Please note that these properties are shared between all contexts with the same Abstract Syntax (SOP class), so changing one will change the value for any other matching contexts.

See Also

DicomContext Object | DicomContext Members


DicomContexts Collection

DicomContexts Collection
Members
DicomObjects Reference : DicomContexts Collection
Description

A DicomContexts collection consists of DicomContext objects, and represents the set of DICOM presentation contexts offered or accepted for an association negotiation.

Most applications will not need to use this collection, as appropriate defaults are provided in most circumstances, and even these may be modified via registry entries, but this collection may prove useful where it is necessary to use different presentation contexts (giving different transfer syntaxes) for different remote entities, such as in teleradiology. When used on incoming connections, it can also be very useful for debugging purposes.

Remarks

This collection is used in three very different scenarios:

  • To define the presentation contexts to be offered on an outgoing association. This is achieved by adding DicomContext items to the initially empty Contexts collection of a new DicomConnection object, prior to calling SetDestination.
  • To Select the presentation contexts to be accepted on an incoming association. This can only be done within the AssociationRequest event, and the appropriate changes (using AcceptedTS or Reject) must be made using the Contexts parameter.
  • To check the presentation contexts available on an association, and, where possible, to select which to use. This is achieved using the Contexts property of an incoming or outgoing DicomConnection, and although the contexts may not be altered, the information contained may be used to set the DicomConnection’s PreferredTS and PreferredPCID properties.

For the first two uses above, appropriate defaults exist, based on the registry.
For outgoing contexts the following rules apply:

  • If any DicomContext items are added to the DicomConnection’s Contexts collection, then the client application assumes full responsibility for the presentation contexts, and the following steps are not performed.
  • The list of abstract syntaxes is as found as a space separated list in the AbstractSyntax registry entry.
  • Each is offered with a list of transfer syntaxes, determined as follows:
    • If a registry value TransferSyntax/<TransferSyntaxUID> exists, then that space separated list is used.
    • Otherwise, the TransferSyntax key’s default value is used.
    • In either of the above cases, if a transfer syntax UID in the list is immediately preceded by an asterisk, then that transfer syntax is offered in its own presentation context, potentially allowing later transfer context selection.

For acceptance of incoming contexts the following rules apply:

  • If any proposed context is neither rejected, nor specifically accepted (by setting the AcceptedTS property, then the if a registry value TransferSyntax/<TransferSyntaxUID> exists, the first value in the list, which is also in the proposed list is accepted. As above, if the specific value does not exist, then the TransferSyntax key’s default value is used, and the same rule applies.
  • The AbstractSyntax list is not checked, and by default, all incoming syntaxes are accepted, but is desired, this may be altered for a particular syntax by setting the TransferSyntax/<TransferSyntaxUID> value to a null string.

Like all other collections in DicomObjects, this collection supports the “NewEnum” method, allowing use of the “for each” construct in Visual Basic to iterate through the members. There is no Count property, however, as the iterator Item(n), uses the presentation context ID as the index, such that the highest value is not the same as number of items. Instead, where direct iteration is not possible, take the index from 1 to 255 (in increments of 2), and for each possible index, check the Exists property.

See Also

DicomContexts Members


DicomContexts Collection Members

DicomContexts Collection Members
Overview
DicomObjects Reference : DicomContexts Collection
Public Methods
Public Method Add | Adds a DicomContext item to a DicomContexts collection
Public Method Remove | Removes a DicomContext item from a collection
Public Properties
Public Property Exists | Checks whether a particular presentation context ID exists in a collection
Public Property Item | Provides access to the members of a DicomContexts collection
Public Property ObjectType | Describes the nature of an automation object
See Also

DicomContexts Collection


Add Method

Add Method
DicomObjects Reference > DicomContexts Collection : Add Method
The abstract syntax of the new presentation context
Description
Adds a DicomContext item to a DicomContexts collection
Syntax
Visual Basic
Public Function Add( _
   ByVal AbstractSyntax As String _
) As DicomContext
Parameters
AbstractSyntax
The abstract syntax of the new presentation context
Remarks
This method may only be used on the Contexts property of a DicomConnection before calling SetDestination.
This is the only programmatic means of creating a DicomContext item, and after creation, an appropriate list of transfer contexts to be offered by setting the new item’s OfferedTS property.
Note that in keeping with the DICOM requirement, newly added contexts have odd values, so adding two items to a DicomContexts collection using this method will create item numbers 1 and 3, not 1 and 2.
See Also

DicomContexts Collection | DicomContexts Members


Remove Method

Remove Method
DicomObjects Reference > DicomContexts Collection : Remove Method
The presentation context ID of the DicomContext item to be removed
Description
Removes a DicomContext item from a collection
Syntax
Visual Basic
Public Sub Remove( _
   ByVal ContextID As Integer _
)
Parameters
ContextID
The presentation context ID of the DicomContext item to be removed
Remarks
Like the Item property, this method uses the presentation context ID (a small, short integer), as its index.
This method is not normally used, but is included for completeness.
When accepting an association, unwanted contexts should be rejected using the Reject method instead.
See Also

DicomContexts Collection | DicomContexts Members


Exists Property

Exists Property
DicomObjects Reference > DicomContexts Collection : Exists Property
The Context to check for existence
Description
Checks whether a particular presentation context ID exists in a collection
Property type
Read-only property
Syntax
Visual Basic
Public Property Exists( _
   ByVal ContextID As Integer _
) As Boolean
Parameters
ContextID
The Context to check for existence
Remarks
As it is a presentation context ID, the index must be a small, odd integer (1-255)
See Also

DicomContexts Collection | DicomContexts Members


Item Property

Item Property
DicomObjects Reference > DicomContexts Collection : Item Property
The ID of the context being accessed
Description
Provides access to the members of a DicomContexts collection
Property type
Read-only property
Syntax
Visual Basic
Public Property Item( _
   ByVal ContextID As Integer _
) As DicomContext
Parameters
ContextID
The ID of the context being accessed
Example

As it is a presentation context ID, the index must be a small, odd integer (1-255)
As items may be missing or rejected from the sequence, the best way to access all the members of a DicomContexts collection is using the standard iterator (for each in VB). In languages where this is not available then the Exists property must be tested, and the best method is along the lines:

Copy Code
for i=1 to 255 step 2
if contexts.exists(i) then
   context = contexts(i)
   process context item…
  end if
next
spacer_300be30a-de70-48d1-8002-66a2e2ac7187

As this is the default property, the term "Item" is rarely used, as

Contexts.Item(3)

may rather more concisely be written as

Contexts(3)

See Also

DicomContexts Collection | DicomContexts Members


ObjectType Property

ObjectType Property
DicomObjects Reference > DicomContexts Collection : ObjectType Property
Description
Describes the nature of an automation object
Property type
Read-only property
Syntax
Visual Basic
Public Property ObjectType As String
Remarks

The possible values are as follows:

“DicomViewer”
“DicomQuery”
“DicomImage”
“DicomImages”
“DicomDataSet”
“DicomDataSets”
“DicomAttribute”
“DicomConnection”
“DicomConnections”
“DicomContext”
“DicomContexts”
“DicomLabel”
“DicomLabels”
“DicomGlobal”
“DicomLog”
“DicomPrint”

See Also

DicomContexts Collection | DicomContexts Members


DicomDataSet Object

DicomDataSet Object
Members
DicomObjects Reference : DicomDataSet Object
Description

A DicomDataSet represents a series of Data Elements, and some associated properties.

Remarks

It is directly creatable, either using Visual Basic’s “CreateObject” method (or equivalent) using the name “DicomObjects.DicomDataSet” or via the DicomViewer’s New method.

See Also

DicomDataSet Members


DicomDataSet Object Members

DicomDataSet Object Members
Overview
DicomObjects Reference : DicomDataSet Object
Public Methods
Public Method AddToDirectory | Simplified DICOMDIR creation
Public Method MakeDictionary | Create a Datasets collection containing a null copy of all 'known' possible attributes
Public Method Send | Sends a DataSet to a remote DICOM application
Public Method WriteArray | Writes object into a byte array (analogous to WriteFile)
Public Method WriteDirectory | Writes a dataset to a DICOMDIR file
Public Method WriteField | Writes a dataset into a database field
Public Method WriteFile | Writes a dataset to an external DICOM file
Public Method WriteMemory | Writes a dataset to a global memory block
Public Method WriteStream | Writes a dataset to an IStream
Public Properties
Public Property AccessionNumber | Accession Number
Public Property Attributes | The Collection of Attributes comprising this dataset
Public Property Children | Subordinate items in the directory hierarchy
Public Property Command | The full request dataset received
Public Property DateOfBirth | The patient's date of birth (as a Variant)
Public Property DateOfBirthAsDate | The patient's date of birth
Public Property InstanceUID | Unique Image identifier
Public Property MRDR | References a multiply referenced directory record
Public Property Name | The patient's Name
Public Property ObjectType |
Public Property PatientID | Patient identifier
Public Property ReceivedSyntax | Transfer Syntax with which SOP instance was received or read
Public Property SeriesDescription | Series Description
Public Property SeriesUID | Unique Study identifier
Public Property Sex | The patient's sex
Public Property SOPClass | The dataset's SOP class UID
Public Property StudyDescription | Study Description
Public Property StudyUID | Unique Study identifier
Public Property Tag | General Purpose Tag
See Also

DicomDataSet Object


AddToDirectory Method

AddToDirectory Method
DicomObjects Reference > DicomDataSet Object : AddToDirectory Method
Image from which to extract demographics, and (optionally) create an icon
The path is relative to where the DICOMDIR is to be written, and must conform to ISO9660/DICOM rules, and therefore be composed to up to 6 elements, each no more than 8 characters, with no extensions, separated by backslashes.
The format with which the image is to be written to disk
This defines the size of the icon image to be included in the DICOMDIR – use 0 for no icon
Description
Simplified DICOMDIR creation
Syntax
Visual Basic
Public Function AddToDirectory( _
   ByVal Image As DicomImage, _
   ByVal Path As String, _
   ByVal TransferSyntax As String, _
   ByVal IconSize As Integer _
) As DicomDataSets
Parameters
Image
Image from which to extract demographics, and (optionally) create an icon
Path
The path is relative to where the DICOMDIR is to be written, and must conform to ISO9660/DICOM rules, and therefore be composed to up to 6 elements, each no more than 8 characters, with no extensions, separated by backslashes.
TransferSyntax
The format with which the image is to be written to disk
IconSize
This defines the size of the icon image to be included in the DICOMDIR – use 0 for no icon
Remarks
This method makes the creation of DICOMDIR files much easier than previously. Simply create a new DicomDataSet object, then call this method for each image to be added to the file set. A full 4 level hierarchy is automatically created.
Note that this method does not write the image file to disk, it merely adds demographics from it, and possibly an icon to the dicomdir DicomDataSet
The return value is a DicomDataSets object containing 4 values, referencing the patient, study, series and image levels of the DICOMDIR, allowing optional attributes to be added if wished.
See Also

DicomDataSet Object | DicomDataSet Members


MakeDictionary Method

MakeDictionary Method
DicomObjects Reference > DicomDataSet Object : MakeDictionary Method
Description
Create a Datasets collection containing a null copy of all 'known' possible attributes
Syntax
Visual Basic
Public Sub MakeDictionary()
Remarks
The DicomDataSet to which this method is applied has added to it one item for every official DICOM element known to the internal DicomObjects dictionary. This is useful for those wishing to check what items are known.
If you wish to add new items as if they were part of the included dictionary see the DicomGlobal’s AddDictionaryElement method.
See Also

DicomDataSet Object | DicomDataSet Members


Send Method

Send Method
DicomObjects Reference > DicomDataSet Object : Send Method
Network address (as dotted notation or resolvable name) to which the image is to be sent.
Port on which remote application is listening.
Name of remote Application Entity.
Name to quote for this Application Entity
Description
Sends a DataSet to a remote DICOM application
Syntax
Visual Basic
Public Function Send( _
   ByVal Node As String, _
   ByVal Port As Integer, _
   ByVal CallingAE As String, _
   ByVal CalledAE As String _
) As Long
Parameters
Node
Network address (as dotted notation or resolvable name) to which the image is to be sent.
Port
Port on which remote application is listening.
CallingAE
Name of remote Application Entity.
CalledAE
Name to quote for this Application Entity
Remarks
This method negotiates an association, sends one image/dataset over it, and then closes it. DICOM does not allow SCPs to draw any conclusions about the relationships between images based on the opening and closing of associations, so this should never be a problem (apart from slight network inefficiency). However, there are several badly written applications in the world, which incorrectly assume that the end of an association indicates the end of a series or a study etc., and if interfacing to such a faulty implementation, it is possible to send multiple images on one association by using a DicomConnection object, and its SendImages method.
See Also

DicomDataSet Object | DicomDataSet Members


WriteArray Method

WriteArray Method
DicomObjects Reference > DicomDataSet Object : WriteArray Method
If TRUE, a blank 128 byte header, DICM marker, and meta-header are written at the start of the file, and an appropriate transfer syntax is used, as below.
If FALSE, the file is written in the unofficial, but common format, with no header, and using the little-endian implicit VR transfer syntax.
Specifies the full UID of the transfer syntax with which the file is to be saved when Part 10 format is used. If omitted, the little-endian explicit VR transfer syntax is used. For details of the currently supported syntaxes, see the conformance entry.
The quality factor to be used.
Description
Writes object into a byte array (analogous to WriteFile)
Syntax
Visual Basic
Public Function WriteArray( _
   ByVal isPart10 As Boolean, _
   Optional ByVal TransferSyntax As Variant, _
   Optional ByVal Quality As Variant _
) As Variant
Parameters
isPart10
If TRUE, a blank 128 byte header, DICM marker, and meta-header are written at the start of the file, and an appropriate transfer syntax is used, as below.
If FALSE, the file is written in the unofficial, but common format, with no header, and using the little-endian implicit VR transfer syntax.
TransferSyntax
Specifies the full UID of the transfer syntax with which the file is to be saved when Part 10 format is used. If omitted, the little-endian explicit VR transfer syntax is used. For details of the currently supported syntaxes, see the conformance entry.
Quality
The quality factor to be used.
Remarks
Quality is specific to the compression method being used, and is ignored for non-compressed or lossless JPEG transfer syntaxes. For Lossy JPEG, it is an integer in the range 1-100, the higher the number, the better the quality (and the larger the file) , and for JPEG 2000 lossy, it is a compression ratio. Other compression methods may use this for other purposes in the future.
Data may be read back by the corresponding ReadArray method.
See Also

DicomDataSet Object | DicomDataSet Members


WriteDirectory Method

WriteDirectory Method
DicomObjects Reference > DicomDataSet Object : WriteDirectory Method
The name of the file to write.
This is passed unmodified to the operating system, and it is therefore the container’s responsibility to ensure either that the current directory is set correctly, or that a fully qualified filename is provided.
Description
Writes a dataset to a DICOMDIR file
Syntax
Visual Basic
Public Sub WriteDirectory( _
   ByVal FileName As String _
)
Parameters
FileName
The name of the file to write.
This is passed unmodified to the operating system, and it is therefore the container’s responsibility to ensure either that the current directory is set correctly, or that a fully qualified filename is provided.
Remarks

The file may subsequently be read by the ReadDirectory method or by other DICOM software.
As of version 4 of DicomObjects, the easiest way to create a standard DICOMDIR file is using the AddToDirectory method.
This method is designed for writing the “DICOMDIR” directory file on exchangeable media, though it is the client program’s responsibility to ensure compliance with the requirements for such files.
Before the file is written, the sequence representing the directory entries is replaced by one created from the Children property, giving a true hierarchical directory structure.

Before using this method, the DicomDataSet’s InstanceUID property should be set to a unique value for the directory. Although stored as attribute (0008,0018) (i.e. Image InstanceUID), it is used correctly in this function, being written in the meta header as (0002,0003).
See the security page for details of restrictions on this method.

See Also

DicomDataSet Object | DicomDataSet Members


WriteField Method

WriteField Method
DicomObjects Reference > DicomDataSet Object : WriteField Method

The field into which the image or dataset is to be Written.
This must be from the list of supported interfaces below, and must be of a type capable of holding binary objects. In Microsoft Access, this would be either an OLE or Memo field. The supported object types are:

Object Category | Version | Object Type
ActiveX Data Objects ADO | >=1.5 | Field
Data Access Objects DAO | 3.0 or 3.5 | Field
Remote Data Objects RDO | 2.0 | Column

If TRUE, a blank 128 byte header, DICM marker, and meta-header are written at the start of the field.
If FALSE, the field is written in the unofficial, but common format, with no header, and using the little-endian implicit VR transfer syntax.
Specifies the full UID of the transfer syntax used when Part 10 format is specified. If omitted, the little-endian explicit VR transfer syntax is used.
The quality factor to be used.
Description
Writes a dataset into a database field
Syntax
Visual Basic
Public Sub WriteField( _
   ByVal Field As Object, _
   ByVal isPart10 As Boolean, _
   Optional ByVal TransferSyntax As Variant, _
   Optional ByVal Quality As Variant _
)
Parameters
Field

The field into which the image or dataset is to be Written.
This must be from the list of supported interfaces below, and must be of a type capable of holding binary objects. In Microsoft Access, this would be either an OLE or Memo field. The supported object types are:

Object Category | Version | Object Type
ActiveX Data Objects ADO | >=1.5 | Field
Data Access Objects DAO | 3.0 or 3.5 | Field
Remote Data Objects RDO | 2.0 | Column

isPart10
If TRUE, a blank 128 byte header, DICM marker, and meta-header are written at the start of the field.
If FALSE, the field is written in the unofficial, but common format, with no header, and using the little-endian implicit VR transfer syntax.
TransferSyntax
Specifies the full UID of the transfer syntax used when Part 10 format is specified. If omitted, the little-endian explicit VR transfer syntax is used.
Quality
The quality factor to be used.
Remarks

The field would normally be read by the ReadField method, but may be copied from the field to an external file.
Quality is specific to the compression method being used, and is ignored for non-compressed or lossless JPEG transfer syntaxes. For Lossy JPEG, it is an integer in the range 1-100, the higher the number, the better the quality (and the larger the file) , and for JPEG 2000 lossy, it is a compression ratio. Other compression methods may use this for other purposes in the future.

This method has been provided to allow development of a DICOM servers using Microsoft tools such as Access and SQL server, which have limited facilities for the handling of Binary Large Objects (BLOBs).
Note:
Whilst this method is useful for simple demonstrations and small projects, most database servers do not handle large BLOBs well when stored within the main database, and in a “production” environment, storage in simple files is strongly advised (with storage of just the filename within the database).

See Also

DicomDataSet Object | DicomDataSet Members


WriteFile Method

WriteFile Method
DicomObjects Reference > DicomDataSet Object : WriteFile Method

The name of the file to write.
This is passed unmodified to the operating system, and it is therefore the container’s responsibility to ensure either that the current directory is set correctly, or that a fully qualified filename is provided.

f TRUE, a blank 128 byte header, DICM marker, and meta-header are written at the start of the file, and an appropriate transfer syntax is used, as below.
If FALSE, the file is written in the unofficial, but common format, with no header, and using the little-endian implicit VR transfer syntax.
Specifies the full UID of the transfer syntax with which the file is to be saved when Part 10 format is used. If omitted, the little-endian explicit VR transfer syntax is used.
The quality factor to be used.
Description
Writes a dataset to an external DICOM file
Syntax
Visual Basic
Public Sub WriteFile( _
   ByVal FileName As String, _
   ByVal isPart10 As Boolean, _
   Optional ByVal TransferSyntax As Variant, _
   Optional ByVal Quality As Variant _
)
Parameters
FileName

The name of the file to write.
This is passed unmodified to the operating system, and it is therefore the container’s responsibility to ensure either that the current directory is set correctly, or that a fully qualified filename is provided.

isPart10
f TRUE, a blank 128 byte header, DICM marker, and meta-header are written at the start of the file, and an appropriate transfer syntax is used, as below.
If FALSE, the file is written in the unofficial, but common format, with no header, and using the little-endian implicit VR transfer syntax.
TransferSyntax
Specifies the full UID of the transfer syntax with which the file is to be saved when Part 10 format is used. If omitted, the little-endian explicit VR transfer syntax is used.
Quality
The quality factor to be used.
Remarks

The file may subsequently be read by the ReadFile method or by other DICOM software.
Quality is specific to the compression method being used, and is ignored for non-compressed or lossless JPEG transfer syntaxes. For Lossy JPEG, it is an integer in the range 1-100, the higher the number, the better the quality (and the larger the file), and for JPEG 2000 lossy, it is a compression ratio. Other compression methods may use this for other purposes in the future.
For writing the “DICOMDIR” directory file on exchangeable media, the WriteDirectory method should be used instead.

See the security page for details of restrictions on this method.

See Also

DicomDataSet Object | DicomDataSet Members


WriteMemory Method

WriteMemory Method
DicomObjects Reference > DicomDataSet Object : WriteMemory Method
This must be the handle to a global block of memory, or may be NULL to find the length required
The length of the memory block (i.e. available space for the data), or 0 to find the length required
If TRUE, a blank 128 byte header, DICM marker, and meta-header are written at the start of the data, and an appropriate transfer syntax is used, as below.
If FALSE, the data is written in the unofficial, but common format, with no header, and using the little-endian implicit VR transfer syntax.
Specifies the full UID of the transfer syntax with which the data is to be saved when Part 10 format is used. If omitted, the little-endian explicit VR transfer syntax is used. For details of the currently supported syntaxes, see the conformance entry.
The quality factor to be used.
Description
Writes a dataset to a global memory block
Syntax
Visual Basic
Public Function WriteMemory( _
   ByVal Handle As Integer, _
   ByVal Length As Long, _
   ByVal isPart10 As Boolean, _
   Optional ByVal TransferSyntax As Variant, _
   Optional ByVal Quality As Variant _
) As Long
Parameters
Handle
This must be the handle to a global block of memory, or may be NULL to find the length required
Length
The length of the memory block (i.e. available space for the data), or 0 to find the length required
isPart10
If TRUE, a blank 128 byte header, DICM marker, and meta-header are written at the start of the data, and an appropriate transfer syntax is used, as below.
If FALSE, the data is written in the unofficial, but common format, with no header, and using the little-endian implicit VR transfer syntax.
TransferSyntax
Specifies the full UID of the transfer syntax with which the data is to be saved when Part 10 format is used. If omitted, the little-endian explicit VR transfer syntax is used. For details of the currently supported syntaxes, see the conformance entry.
Quality
The quality factor to be used.
Remarks
The data may subsequently be read by the ReadMemory method or by other DICOM software.
If either Handle is NULL, or Length is 0, then no data is written, but the length is still calculated (applying compression if necessary), so that a suitable memory block may be allocated.
If the length available is not enough for the data to be written, an error is thrown.
Quality is specific to the compression method being used, and is ignored for non-compressed or lossless JPEG transfer syntaxes. For Lossy JPEG, it is an integer in the range 1-100, the higher the number, the better the quality (and the larger the data). Other compression methods may use this for other purposes in the future.
See Also

DicomDataSet Object | DicomDataSet Members


WriteStream Method

WriteStream Method
DicomObjects Reference > DicomDataSet Object : WriteStream Method
The name of the stream object to write to.
Although this object must support an IStream interface, this is retrieved via a QueryInterface call, and any interface to the object may therefore be passed.
If TRUE, a blank 128 byte header, DICM marker, and meta-header are written at the start of the stream, and an appropriate transfer syntax is used, as below.
If FALSE, the stream is written in the unofficial, but common format, with no header, and using the little-endian implicit VR transfer syntax.
Specifies the full UID of the transfer syntax with which the data is to be saved when Part 10 format is used. If omitted, the little-endian explicit VR transfer syntax is used. For details of the currently supported syntaxes, see the conformance entry.
The quality factor to be used.
Description
Writes a dataset to an IStream
Syntax
Visual Basic
Public Sub WriteStream( _
   ByVal Stream As Unknown, _
   ByVal isPart10 As Boolean, _
   Optional ByVal TransferSyntax As Variant, _
   Optional ByVal Quality As Variant _
)
Parameters
Stream
The name of the stream object to write to.
Although this object must support an IStream interface, this is retrieved via a QueryInterface call, and any interface to the object may therefore be passed.
isPart10
If TRUE, a blank 128 byte header, DICM marker, and meta-header are written at the start of the stream, and an appropriate transfer syntax is used, as below.
If FALSE, the stream is written in the unofficial, but common format, with no header, and using the little-endian implicit VR transfer syntax.
TransferSyntax
Specifies the full UID of the transfer syntax with which the data is to be saved when Part 10 format is used. If omitted, the little-endian explicit VR transfer syntax is used. For details of the currently supported syntaxes, see the conformance entry.
Quality
The quality factor to be used.
Remarks

The file may subsequently be read by the ReadStream method or by other DICOM software.
Quality is specific to the compression method being used, and is ignored for non-compressed or lossless JPEG transfer syntaxes. For Lossy JPEG, it is an integer in the range 1-100, the higher the number, the better the quality (and the larger the file) , and for JPEG 2000 lossy, it is a compression ratio. Other compression methods may use this for other purposes in the future.

This method is particularly suitable for use with Delphi, which provides access to streams via classes such as TStreamAdapter.

See Also

DicomDataSet Object | DicomDataSet Members


AccessionNumber Property

AccessionNumber Property
DicomObjects Reference > DicomDataSet Object : AccessionNumber Property
Description
Accession Number
Property type
Read-write property
Syntax
Visual Basic
Public Property AccessionNumber As String
Remarks
This is a shortcut for the Accession Number (0008,0060)
See Also

DicomDataSet Object | DicomDataSet Members


Attributes Property

Attributes Property
DicomObjects Reference > DicomDataSet Object : Attributes Property
Description
The Collection of Attributes comprising this dataset
Property type
Read-only property
Syntax
Visual Basic
Public Property Attributes As DicomAttributes
Remarks
This property provides access to the collection of Attributes that comprise a DicomImage or DicomDataSet.
See Also

DicomDataSet Object | DicomDataSet Members


Children Property

Children Property
DicomObjects Reference > DicomDataSet Object : Children Property
Description
Subordinate items in the directory hierarchy
Property type
Read-only property
Syntax
Visual Basic
Public Property Children As DicomDataSets
Remarks

Recursive use of this property and the datasets contained within it allows representation and manipulation of the hierarchical structure of a DICOMDIR file. The Children property exists for all DicomDataSet objects, but is only created by ReadDirectory or AddToDirectory and is only used by WriteDirectory. There are normally five levels, the objects representing the DICOMDIR file itself, and the four hierarchical levels PATIENT, STUDY, SERIES and IMAGE.

See also: MRDR

See Also

DicomDataSet Object | DicomDataSet Members


Command Property

Command Property
DicomObjects Reference > DicomDataSet Object : Command Property
Description
The full request dataset received
Property type
Read-only property
Syntax
Visual Basic
Public Property Command As Object
Remarks

See Also

DicomDataSet Object | DicomDataSet Members


DateOfBirth Property

DateOfBirth Property
DicomObjects Reference > DicomDataSet Object : DateOfBirth Property
Description
The patient's date of birth (as a Variant)
Property type
Read-write property
Syntax
Visual Basic
Public Property DateOfBirth As Variant
Return Type
Variant
Remarks

This really just a shortcut for attribute (0010,0030).

DateOfBirth is presented as a Variant rather than a Date, in order to accommodate null dates without error - for a Date form see DateOfBirthAsDate Property

See Also

DicomDataSet Object | DicomDataSet Members | DateOfBirthAsDate Property


DateOfBirthAsDate Property

DateOfBirthAsDate Property
DicomObjects Reference > DicomDataSet Object : DateOfBirthAsDate Property
Description
The patient's date of birth
Property type
Read-write property
Syntax
Visual Basic
Public Property DateOfBirthAsDate As Date
See Also

DicomDataSet Object | DicomDataSet Members


InstanceUID Property

InstanceUID Property
DicomObjects Reference > DicomDataSet Object : InstanceUID Property
Description
Unique Image identifier
Property type
Read-write property
Syntax
Visual Basic
Public Property InstanceUID As String
Remarks

This really just a shortcut for attribute (0010,0020).

See Also

DicomDataSet Object | DicomDataSet Members


MRDR Property

MRDR Property
DicomObjects Reference > DicomDataSet Object : MRDR Property
Description
References a multiply referenced directory record
Property type
Read-only property
Syntax
Visual Basic
Public Property MRDR As Object
Remarks

This property allows use of multiply referenced directory records as defined in part 10 of the DICOM standard. Such records are automatically created and used by the ReadDirectory and WriteDirectory methods, but may need to be created programmatically. If so, then a NEW DicomDataSet object must be created and assigned (using VB’s set or equivalent) to this property, as no item exists until this is done (this allows the same value to be used for several objects, as one would expect). Although the offsets in the DICOMDIR file are handled automatically, it is the client program’s responsibility to ensure that the reference count is correct.

This property is not used by the AddToDirectory method, which creates only simple 4 level DICOMDIRs
Unfortunately, Visual Basic cannot properly handle properties which are of the same type as the parent object, regarding them (wrongly) as indicating a circular reference. In order to circumvent this bug, this property is defined in the type library as being a generic IDispatch object rather than a DicomDataSet. As a result, a typecast will be required in most languages.

See Also

DicomDataSet Object | DicomDataSet Members


Name Property

Name Property
DicomObjects Reference > DicomDataSet Object : Name Property
Description
The patient's Name
Property type
Read-write property
Syntax
Visual Basic
Public Property Name As String
Remarks

See Also

DicomDataSet Object | DicomDataSet Members


ObjectType Property

ObjectType Property
DicomObjects Reference > DicomDataSet Object : ObjectType Property
Description

Property type
Read-only property
Syntax
Visual Basic
Public Property ObjectType As String
Remarks

The possible values are as follows:

“DicomViewer”
“DicomQuery”
“DicomImage”
“DicomImages”
“DicomDataSet”
“DicomDataSets”
“DicomAttribute”
“DicomConnection”
“DicomConnections”
“DicomContext”
“DicomContexts”
“DicomLabel”
“DicomLabels”
“DicomGlobal”
“DicomLog”
“DicomPrint”

See Also

DicomDataSet Object | DicomDataSet Members


PatientID Property

PatientID Property
DicomObjects Reference > DicomDataSet Object : PatientID Property
Description
Patient identifier
Property type
Read-write property
Syntax
Visual Basic
Public Property PatientID As String
Remarks

This really just a shortcut for attribute (0010,0020).

See Also

DicomDataSet Object | DicomDataSet Members


ReceivedSyntax Property

ReceivedSyntax Property
DicomObjects Reference > DicomDataSet Object : ReceivedSyntax Property
Description
Transfer Syntax with which SOP instance was received or read
Property type
Read-only property
Syntax
Visual Basic
Public Property ReceivedSyntax As String
Remarks
The value returned is the UID, in dotted numerical form, or the transfer syntax used.
This property may be useful to programs that handle compressed images, that wish to avoid re-compression of images, e.g. when using the WriteFile method.
If an image has been created locally, then a zero-length string is returned
See Also

DicomDataSet Object | DicomDataSet Members


SeriesDescription Property

SeriesDescription Property
DicomObjects Reference > DicomDataSet Object : SeriesDescription Property
Description
Series Description
Property type
Read-write property
Syntax
Visual Basic
Public Property SeriesDescription As String
Remarks
This property provides a human readable description of the Series, being a shortcut to correspond to attribute (0x0008, 0x103e)
See Also

DicomDataSet Object | DicomDataSet Members


SeriesUID Property

SeriesUID Property
DicomObjects Reference > DicomDataSet Object : SeriesUID Property
Description
Unique Study identifier
Property type
Read-write property
Syntax
Visual Basic
Public Property SeriesUID As String
Remarks
This is a shortcut to attribute (0008,000D) - the Study Instance UID
See Also

DicomDataSet Object | DicomDataSet Members


Sex Property

Sex Property
DicomObjects Reference > DicomDataSet Object : Sex Property
Description
The patient's sex
Property type
Read-write property
Syntax
Visual Basic
Public Property Sex As String
Return Type

This really just a shortcut for attribute (0010,0040).

See Also

DicomDataSet Object | DicomDataSet Members


SOPClass Property

SOPClass Property
DicomObjects Reference > DicomDataSet Object : SOPClass Property
Description
The dataset's SOP class UID
Property type
Read-write property
Syntax
Visual Basic
Public Property SOPClass As String
Remarks
This is a shortcut to attribute (0008,0016) - the SOP class of the object as a UID
See Also

DicomDataSet Object | DicomDataSet Members


StudyDescription Property

StudyDescription Property
DicomObjects Reference > DicomDataSet Object : StudyDescription Property
Description
Study Description
Property type
Read-write property
Syntax
Visual Basic
Public Property StudyDescription As String
Remarks
These property provides a human readable description of the Study, being a shortcut to correspond to attribute (0x0008, 0x1030)
See Also

DicomDataSet Object | DicomDataSet Members


StudyUID Property

StudyUID Property
DicomObjects Reference > DicomDataSet Object : StudyUID Property
Description
Unique Study identifier
Property type
Read-write property
Syntax
Visual Basic
Public Property StudyUID As String
Remarks
This is a shortcut to attribute (0008,000D) - the Study Instance UID
See Also

DicomDataSet Object | DicomDataSet Members


Tag Property

Tag Property
DicomObjects Reference > DicomDataSet Object : Tag Property
Description
General Purpose Tag
Property type
Read-write property
Syntax
Visual Basic
Public Property Tag As Variant
Remarks

Tag properties are attached to most objects in DicomObjects. The values are not used by the associated object, and are available for user use. A special case is the DicomConnection object, where Tag is included in the ActionComplete event procedure, assisting identification of necessary features of the connection, such as pending database operations etc. In this use, the value of Tag is stored at the time an operation is initiated, and it is this stored value which is passed to ActionComplete, simplifying the task of tracking which operations have happened.

The TagObject property holds another object, typically a DicomLabels collection, and this can be useful when arranging DicomLabel objects into groups.

See Also

DicomDataSet Object | DicomDataSet Members


DicomDataSets Collection

DicomDataSets Collection
Members
DicomObjects Reference : DicomDataSets Collection
Description

This is a true OLE collection, a collection of DicomDataSet objects, such as that returned by a DicomQuery Object’s DoQuery method.

This data type is also used to represent data elements of the sequence (SQ) type.

Remarks

In addition to the above public properties, the DicomDataSets collection also supports the "NewEnumVariant" restricted method. This allows suitable clients such as Visual Basic to iterate through the DicomDataSet objects it contains using the following syntax:

Enumeration
Copy Code
Dim collection as DicomDataSets
Dim dataset as DicomDataSet
For each dataset in collection.DataSets
  MsgBox dataset.name
Next

It is directly creatable, either using Visual Basic’s “CreateObject” method (or equivalent) using the name “DicomObjects.DicomDataSets” or via the DicomViewer’s New method.

See Also

DicomDataSets Members


DicomDataSets Collection Members

DicomDataSets Collection Members
Overview
DicomObjects Reference : DicomDataSets Collection
Public Methods
Public Method Add | Adds a DicomDataSet to a DicomDataSets Collection
Public Method Clear | Clears the Collection
Public Method IndexOf | Identifes position of an item in a collection
Public Method Move | Moves a DicomDataSet within a DicomDataSets Collection
Public Method ReadArray | Reads a DICOM 'file' from an array.
Public Method ReadDirectory | Reads a dataset from a DICOMDIR file
Public Method ReadField | Reads a dataset from a database field
Public Method ReadFile | Reads a dataset from an external file
Public Method ReadMemory | Reads a DicomDataSet from a global memory handle
Public Method ReadStream | Reads a dataset from an IStream
Public Method ReadURL | Reads a dataset from a network location
Public Method Remove | Removes a DicomDataSet from a DicomDataSets Collection
Public Properties
Public Property Count | Indicates the number of items in a collection
Public Property Count32 | Indicates the number of items in a collection
Public Property Item | Provides access to the individual DicomDataSet items of a DicomDataSets collection
Public Property ObjectType | Describes the nature of an automation object
Public Property Tag | General Purpose Tag
See Also

DicomDataSets Collection


Add Method

Add Method
DicomObjects Reference > DicomDataSets Collection : Add Method
The dataset to add
Description
Adds a DicomDataSet to a DicomDataSets Collection
Syntax
Visual Basic
Public Sub Add( _
   ByVal dataset As Object _
)
Parameters
dataset
The dataset to add
Remarks

The new member is added at the end of the collection (it may subsequently be moved using Move if necessary). If the DicomImages collection to which an image is added belongs to a DicomViewer control, the control’s CurrentIndex property may be adjusted if AutoDisplay is True.
When added to a DicomDataSets collection, a reference to the existing object is added to the collection, as this is then often used for creating dicomdir tree structures etc. However, it is often useful to create multiple displayed versions of a single image, so when used with a DicomImages collection, the display parameters are created as a new object, but still referencing the same underlying DICOM dataset, thereby conserving memory. Using this feature it is possible to show two versions of an image, showing different frames or with different magnification or windowing, without doubling the memory requirements.

The parameter to this method is actually declared as a generic IDispatch object, allowing both DicomImage and DicomDataSet objects to be added to either type of collection. This is particularly useful when manipulating images embedded within sequences such as thumbnails within a DICOMDIR, as the object added acquires the type of the collection to which it is added, whilst retaining the same underlying DICOM dataset.

See Also

DicomDataSets Collection | DicomDataSets Members


Clear Method

Clear Method
DicomObjects Reference > DicomDataSets Collection : Clear Method
Description
Clears the Collection
Syntax
Visual Basic
Public Sub Clear()
Remarks
Immediately clears a collection. The collection object persists, but after the call is empty. The contained objects are only destroyed if there are no other outstanding references to them.
See Also

DicomDataSets Collection | DicomDataSets Members


IndexOf Method

IndexOf Method
DicomObjects Reference > DicomDataSets Collection : IndexOf Method
The object to be located.
Description
Identifes position of an item in a collection
Syntax
Visual Basic
Public Function IndexOf( _
   ByVal Object As DicomDataSet _
) As Long
Parameters
Object
The object to be located.
Remarks
The value returned locates the first occurrence of the specified object within the collection. In the case of DicomImages, DicomDataSets or DicomLabels collections, the reference may be to an object derived from the same source, as such objects may be cloned when added to collections.
See Also

DicomDataSets Collection | DicomDataSets Members


Move Method

Move Method
DicomObjects Reference > DicomDataSets Collection : Move Method

A reference to the image or dataset to be moved, either:
a) An integer referencing the object by its current position in the collection, starting at 1.

or

b) A String referencing the Instance UID of the Image.

The new index for the object within the collection
Description
Moves a DicomDataSet within a DicomDataSets Collection
Syntax
Visual Basic
Public Sub Move( _
   ByVal Index As Variant, _
   ByVal Destination As Integer _
)
Parameters
Index

A reference to the image or dataset to be moved, either:
a) An integer referencing the object by its current position in the collection, starting at 1.

or

b) A String referencing the Instance UID of the Image.

Destination
The new index for the object within the collection
Remarks
By using Move, objects may be re-ordered within the collection. The object referred to by the index is placed at the position given by "destination", other objects being kept in sequence but moved as necessary to accommodate the moved item.
The index is a variant as images may be referred to either by numerical sequence (as used for CurrentIndex), but also by their unique instance UID. An exception is generated if either a numerical argument is out of bounds, or if reference is made to a non-existent instance UID.
See Also

DicomDataSets Collection | DicomDataSets Members


ReadArray Method

ReadArray Method
DicomObjects Reference > DicomDataSets Collection : ReadArray Method
The array to read data from
Description
Reads a DICOM 'file' from an array.
Syntax
Visual Basic
Public Function ReadArray( _
   ByVal Data As Variant _
) As DicomDataSet
Parameters
Data
The array to read data from
Remarks
The array should be 1-based.
See Also

DicomDataSets Collection | DicomDataSets Members


ReadDirectory Method

ReadDirectory Method
DicomObjects Reference > DicomDataSets Collection : ReadDirectory Method
The name of the file to read.
This is passed unmodified to the operating system, and it is therefore the container’s responsibility to ensure either that the file exists within the current directory, or that a fully qualified filename is provided.
Description
Reads a dataset from a DICOMDIR file
Syntax
Visual Basic
Public Function ReadDirectory( _
   ByVal FileName As String _
) As DicomDataSet
Parameters
FileName
The name of the file to read.
This is passed unmodified to the operating system, and it is therefore the container’s responsibility to ensure either that the file exists within the current directory, or that a fully qualified filename is provided.
Remarks

This method is used for reading the “DICOMDIR” files used on exchangeable media. Although such files could simply be read using ReadFile, the item offset information necessary for interpretation of the hierarchical directory structure would be lost. This method preserves such information, placing a copy of each of the entries in the root directory in the Children collection of the returned dataset. Likewise, levels below the root are also represented by the Children property of the level above.

The file may have been written by the WriteDirectory method or by other DICOM software.
See the security page for details of restrictions on this method.

See Also

DicomDataSets Collection | DicomDataSets Members


ReadField Method

ReadField Method
DicomObjects Reference > DicomDataSets Collection : ReadField Method

The field from which the image is to be read.
This must be from the list of supported interfaces below, and must be of a type capable of holding binary objects. In Microsoft Access, this would be either an OLE or Memo field. The supported object types are:

Object Category | Version | Object Type
ActiveX Data Objects ADO | >=1.5 | Field
Data Access Objects DAO | 3.0 or 3.5 | Field
Remote Data Objects RDO | 2.0 | Column
Description
Reads a dataset from a database field
Syntax
Visual Basic
Public Function ReadField( _
   ByVal Field As Object _
) As DicomDataSet
Parameters
Field

The field from which the image is to be read.
This must be from the list of supported interfaces below, and must be of a type capable of holding binary objects. In Microsoft Access, this would be either an OLE or Memo field. The supported object types are:

Object Category | Version | Object Type
ActiveX Data Objects ADO | >=1.5 | Field
Data Access Objects DAO | 3.0 or 3.5 | Field
Remote Data Objects RDO | 2.0 | Column
Remarks

This method can read fields in either the official “Part10” format with the 128 byte header, or the unofficial “Part3” format without a header, and detection of the type is automatic.

The field would normally have been written by the WriteField method, but may have been imported into the field from an external file.

This method has been provided to allow development of a simple DICOM server using Microsoft Access, which has limited facilities for the handling of Binary Large Objects (BLOBs).

Whilst this method is useful for simple demonstrations and small projects, most database servers do not handle large BLOBs well when stored within the main database, and in a “production” environment, storage in simple files is strongly advised (with storage of just the filename within the database).

See Also

DicomDataSets Collection | DicomDataSets Members


ReadFile Method

ReadFile Method
DicomObjects Reference > DicomDataSets Collection : ReadFile Method

The name of the file to read.

This is passed unmodified to the operating system, and it is therefore the container’s responsibility to ensure either that the file exists within the current directory, or that a fully qualified filename is provided.

Description
Reads a dataset from an external file
Syntax
Visual Basic
Public Function ReadFile( _
   ByVal FileName As String _
) As DicomDataSet
Parameters
FileName

The name of the file to read.

This is passed unmodified to the operating system, and it is therefore the container’s responsibility to ensure either that the file exists within the current directory, or that a fully qualified filename is provided.

Remarks

This method can read either official “Part10” format files with the 128 byte header, or unofficial “Part3” format files without a header, and detection of the type is automatic.
The file may have been written by the WriteFile method or by other DICOM software.
See ReadDirectory for an alternative method suitable for reading “DICOMDIR” directory files.

By default, pixel data is read only when it is required, greatly speeding the display of multi-frame images, and reducing memory requirements. However, a side effect of this is that any elements after the pixel data (7FE0,0010) will not be read. This should not affect most applications, but if necessary, this behaviour made be over-ridden using the DisableFileMapping or DisableQuickRead registry entries. See the registry entries page for more details.

Another effect of file mapping is that files read using this method cannot be deleted until the image object is released. This method creates two references to the newly created DicomImage object (one in the collection, and one as the return value), and both must be released before the file can be deleted.

See Also

DicomDataSets Collection | DicomDataSets Members


ReadMemory Method

ReadMemory Method
DicomObjects Reference > DicomDataSets Collection : ReadMemory Method
This must be the handle to a global block of memory
The length of the DICOM data within the memory block
Description
Reads a DicomDataSet from a global memory handle
Syntax
Visual Basic
Public Function ReadMemory( _
   ByVal Handle As Integer, _
   ByVal Length As Long _
) As DicomImage
Parameters
Handle
This must be the handle to a global block of memory
Length
The length of the DICOM data within the memory block
Remarks
This method can read data from either official “Part10” format files with the 128 byte header, or unofficial “Part3” format data without a header, and detection of the type is automatic.
The data may have been written by the WriteMemory method or by other DICOM software.
The memory block will be locked before use, then unlocked after. It is the containing application’s responsibility to free the block when no longer needed.
As DICOM has no mechanism to determine the length of the image/dataset from the data alone, the Length parameter must be accurate.
See Also

DicomDataSets Collection | DicomDataSets Members


ReadStream Method

ReadStream Method
DicomObjects Reference > DicomDataSets Collection : ReadStream Method
The name of the stream from which to read.
Although this object must support an IStream interface, this is retrieved via a QueryInterface call, and any interface to the object may therefore be passed.
Description
Reads a dataset from an IStream
Syntax
Visual Basic
Public Function ReadStream( _
   ByVal Stream As Unknown _
) As DicomDataSet
Parameters
Stream
The name of the stream from which to read.
Although this object must support an IStream interface, this is retrieved via a QueryInterface call, and any interface to the object may therefore be passed.
Remarks
This method can read streams in either official “Part10” format, with the 128 byte header, or unofficial “Part3” format, without a header, and detection of the type is automatic.
The stream may have been written by the WriteStream method or by other DICOM software.
See Also

DicomDataSets Collection | DicomDataSets Members


ReadURL Method

ReadURL Method
DicomObjects Reference > DicomDataSets Collection : ReadURL Method
The fully qualified URL of the object to be read.
This is passed unmodified to the operating system, and it is therefore the container’s responsibility to ensure that a fully qualified, accessible URL is provided.
Description
Reads a dataset from a network location
Syntax
Visual Basic
Public Function ReadURL( _
   ByVal URL As String _
) As DicomDataSet
Parameters
URL
The fully qualified URL of the object to be read.
This is passed unmodified to the operating system, and it is therefore the container’s responsibility to ensure that a fully qualified, accessible URL is provided.
Remarks

The URL may begin http://, https://, ftp://, gopher:// or file://, and the appropriate access method will be used. Note that for local files, security restrictions apply.
Where authentication is required, the standard format may be used:

ReadURL(“http://username:password@servername/path”)

This method can read either official “Part10” format files with the 128 byte header, or unofficial “Part3” format files without a header, and detection of the type is automatic.
The file may have been written by the WriteFile method or by other DICOM software.

See Also

DicomDataSets Collection | DicomDataSets Members


Remove Method

Remove Method
DicomObjects Reference > DicomDataSets Collection : Remove Method
Either:
a) An integer referencing the image by its position in the collection, starting at 1.
or
b) A String referencing the Instance UID of the Image/DataSet.
Description
Removes a DicomDataSet from a DicomDataSets Collection
Syntax
Visual Basic
Public Sub Remove( _
   ByVal Index As Variant _
)
Parameters
Index
Either:
a) An integer referencing the image by its position in the collection, starting at 1.
or
b) A String referencing the Instance UID of the Image/DataSet.
Remarks
The index is a variant as images or datasets may be referred to either by numerical sequence (as used for CurrentIndex), but also by their unique instance UID. An exception is generated if either a numerical argument is out of bounds, or if reference is made to a non-existent instance UID.
See Also

DicomDataSets Collection | DicomDataSets Members


Count Property

Count Property
DicomObjects Reference > DicomDataSets Collection : Count Property
Description
Indicates the number of items in a collection
Property type
Read-only property
Syntax
Visual Basic
Public Property Count As Integer
Remarks
This is useful both for checking the value of indexes into the collection, and for iterating thought the images numerically, though as all collections in this product provide true iterators (allowing for instance the For Each construct in Visual Basic), this should rarely be necessary in such languages.
Where it is necessary to iterate through collections by integer index this can be done using ItemByIndex for DicomAttributes collections, and the Item property for the others.
See Also

DicomDataSets Collection | DicomDataSets Members


Count32 Property

Count32 Property
DicomObjects Reference > DicomDataSets Collection : Count32 Property
Description
Indicates the number of items in a collection
Property type
Read-only property
Syntax
Visual Basic
Public Property Count32 As Integer
Remarks
This is useful both for checking the value of indexes into the collection, and for iterating thought the images numerically, though as all collections in this product provide true iterators (allowing for instance the For Each construct in Visual Basic), this should rarely be necessary in such languages.
Where it is necessary to iterate through collections by integer index this can be done using ItemByIndex for DicomAttributes collections, and the Item property for the others.
See Also

DicomDataSets Collection | DicomDataSets Members


Item Property

Item Property
DicomObjects Reference > DicomDataSets Collection : Item Property
The 1-based index of the item to retrieve
Description
Provides access to the individual DicomDataSet items of a DicomDataSets collection
Property type
Read-only property
Syntax
Visual Basic
Public Property Item( _
   ByVal Index As Variant _
) As DicomDataSet
Parameters
Index
The 1-based index of the item to retrieve
Remarks
As this is the default property, the term "Item" is rarely used in languages which support default properties, as DataSets.Item(3) may rather more concisely be written as DataSets(3)
See Also

DicomDataSets Collection | DicomDataSets Members


ObjectType Property

ObjectType Property
DicomObjects Reference > DicomDataSets Collection : ObjectType Property
Description
Describes the nature of an automation object
Property type
Read-only property
Syntax
Visual Basic
Public Property ObjectType As String
Remarks

The possible values are as follows:

“DicomViewer”
“DicomQuery”
“DicomImage”
“DicomImages”
“DicomDataSet”
“DicomDataSets”
“DicomAttribute”
“DicomConnection”
“DicomConnections”
“DicomContext”
“DicomContexts”
“DicomLabel”
“DicomLabels”
“DicomGlobal”
“DicomLog”
“DicomPrint”

See Also

DicomDataSets Collection | DicomDataSets Members


Tag Property

Tag Property
DicomObjects Reference > DicomDataSets Collection : Tag Property
Description
General Purpose Tag
Property type
Read-write property
Syntax
Visual Basic
Public Property Tag As Variant
Remarks

Tag properties are attached to most objects in DicomObjects. The values are not used by the associated object, and are available for user use. A special case is the DicomConnection object, where Tag is included in the ActionComplete event procedure, assisting identification of necessary features of the connection, such as pending database operations etc. In this use, the value of Tag is stored at the time an operation is initiated, and it is this stored value which is passed to ActionComplete, simplifying the task of tracking which operations have happened.

The TagObject property holds another object, typically a DicomLabels collection, and this can be useful when arranging DicomLabel objects into groups.

See Also

DicomDataSets Collection | DicomDataSets Members


DicomGlobal Object

DicomGlobal Object
Members
DicomObjects Reference : DicomGlobal Object
Description
This object supports various operations which are not related to other specific objects
Remarks
An instance of this object must be created before its members may be used - this is needed as the COM model does not support simple static members.
See Also

DicomGlobal Members


DicomGlobal Object Members

DicomGlobal Object Members
Overview
DicomObjects Reference : DicomGlobal Object
Public Methods
Public Method AddDictionaryElement | Add private or new attribute description to the internal list
Public Method Echo | send a C-ECHO request
Public Method EchoSecure | Secure C-ECHO
Public Method ErrorString | Retrieve error string for a particular error code
Public Method Log | Put entry into DicomObjects' own logging facility
Public Method NewUID | Create a guaranteed unique UID
Public Method Palette | Create a standard DICOM Palette
Public Method ReadFile | Read a DICOM file
Public Method ResetDirectX | Reset DirectX sub-system
Public Properties
Public Property CurrentConnections | All currently Open connections
Public Property DirectionStrings | Direction markers for use with labels of type doLabelSpecial
Public Property DirectXLevel | Current feature level of DirectX
Public Property DotNetMode | If true, improves compatibility with the .NET environment
Public Property EnableExtendedNegotiation | Controls whether extended negotiation is used
Public Property LastRemoteCertificate | Remote certificate presentation during last atomic operation
Public Property MinFontSize | Minimum Font Size used when drawing Text Label
Public Property ObjectType | Describes the nature of an automation object
Public Property RegString | Get DicomObjects current registry value
Public Property RegWord | Get DicomObjects currently registry value
Public Property Version | Current Version of DicomObjects
See Also

DicomGlobal Object


AddDictionaryElement Method

AddDictionaryElement Method
DicomObjects Reference > DicomGlobal Object : AddDictionaryElement Method
Group tag for the new element
Element tag for the new element
A standard 2 character DICOM VR,
e.g. “PN” for personal
Allowed multiplicity
e.g. “1”, “1-n”, “3” etc.
Description of the element, as used in the DicomAttribute’s Description property
Description
Add private or new attribute description to the internal list
Syntax
Visual Basic
Public Sub AddDictionaryElement( _
   ByVal Group As Long, _
   ByVal Element As Long, _
   ByVal VR As String, _
   ByVal VM As String, _
   ByVal Description As String _
)
Parameters
Group
Group tag for the new element
Element
Element tag for the new element
VR
A standard 2 character DICOM VR,
e.g. “PN” for personal
VM
Allowed multiplicity
e.g. “1”, “1-n”, “3” etc.
Description
Description of the element, as used in the DicomAttribute’s Description property
Remarks
This method is equally useful for adding new official attributes added after a release of DicomObjects, or for adding private attributes, to be handled as if they were “official”.
Although any value for VM is allowed, the only value with any special internal significance is “1”, as this causes DicomAttribute’s default Value property to return a single value. Any other value causes an array to be returned.
An alternative, if values only need to be created, is to use the AddExplicit method.
See Also

DicomGlobal Object | DicomGlobal Members


Echo Method

Echo Method
DicomObjects Reference > DicomGlobal Object : Echo Method
Remote entity name as IP address or resolvable name
Port to connect to
Calling and Called Application Entity Titles (AETs)
Certificate to use for user authentication
Description
send a C-ECHO request
Syntax
Visual Basic
Public Function Echo( _
   ByVal Node As String, _
   ByVal Port As Long, _
   ByVal CallingAET As String, _
   ByVal CalledAET As String _
) As Long
Parameters
Node
Remote entity name as IP address or resolvable name
Port
Port to connect to
CallingAET
Calling and Called Application Entity Titles (AETs)
CalledAET
Certificate to use for user authentication
Remarks
These methods are easier to use than the previously available DicomConnection.SendVerify method, but unlike the SendVerify method, these methods are always synchronous.
Although in theory the remote entity may return a status other than 0 to indicate an error, in most circumstances (such as remote machine turned off), this method will fail with a trappable error, such as “Failed to connect at TCP level”.
When EchoSecure is used, a secure association will be attempted using TLS. If Certificate is a valid X509 certificate, then user authentication will be used, but if it is null, then an anonymous client association will be attempted, which may or may not be accepted by the SCP.
See Also

DicomGlobal Object | DicomGlobal Members


EchoSecure Method

EchoSecure Method
DicomObjects Reference > DicomGlobal Object : EchoSecure Method
Remote entity name as IP address or resolvable name
Port to connect to
Called Application Entity Titles (AETs)
Calling and Called Application Entity Titles (AETs)

Certificate to use for user authentication

Description
Secure C-ECHO
Syntax
Visual Basic
Public Function EchoSecure( _
   ByVal Node As String, _
   ByVal Port As Long, _
   ByVal CallingAET As String, _
   ByVal CalledAET As String, _
   ByVal Certificate As Object _
) As Long
Parameters
Node
Remote entity name as IP address or resolvable name
Port
Port to connect to
CallingAET
Called Application Entity Titles (AETs)
CalledAET
Calling and Called Application Entity Titles (AETs)
Certificate

Certificate to use for user authentication

Remarks
These methods are easier to use than the previously available DicomConnection.SendVerify method, but unlike the SendVerify method, these methods are always synchronous.
Although in theory the remote entity may return a status other than 0 to indicate an error, in most circumstances (such as remote machine turned off), this method will fail with a trappable error, such as “Failed to connect at TCP level”.
When EchoSecure is used, a secure association will be attempted using TLS. If Certificate is a valid X509 certificate, then user authentication will be used, but if it is null, then an anonymous client association will be attempted, which may or may not be accepted by the SCP.
See Also

DicomGlobal Object | DicomGlobal Members


ErrorString Method

ErrorString Method
DicomObjects Reference > DicomGlobal Object : ErrorString Method
The error code to look up
Description
Retrieve error string for a particular error code
Syntax
Visual Basic
Public Function ErrorString( _
   ByVal ID As Long _
) As String
Parameters
ID
The error code to look up
Remarks
DicomObjects allows error codes to be localised, and this method is suitable for developers wishing to check that error messages are suitable in their language.
If you wish to add a new language to DicomObjects error codes, please contact Medical Connections.
The string returned may contain standard “C” formatting codes used to insert text or numbers.
See Also

DicomGlobal Object | DicomGlobal Members


Log Method

Log Method
DicomObjects Reference > DicomGlobal Object : Log Method
The category of message
The text to log
Description
Put entry into DicomObjects' own logging facility
Syntax
Visual Basic
Public Sub Log( _
   ByVal Level As Long, _
   ByVal Text As String _
)
Parameters
Level
The category of message
Text
The text to log
Remarks
Although any value may be used for the Level parameter, to avoid conflicts with DicomObjects internal uses, the bits values in the high order word (65536 and higher) should be used for user messages. The messages generated by this method are logged to files in exactly the same way as internally generated messages. See the Level property for details of the normal categories.
See Also

DicomGlobal Object | DicomGlobal Members


NewUID Method

NewUID Method
DicomObjects Reference > DicomGlobal Object : NewUID Method
Description
Create a guaranteed unique UID
Syntax
Visual Basic
Public Function NewUID() As String
Remarks
The methods used is described on the UIDs page.
See Also

DicomGlobal Object | DicomGlobal Members


Palette Method

Palette Method
DicomObjects Reference > DicomGlobal Object : Palette Method
The name of the DICOM defined Palette
Description
Create a standard DICOM Palette
Syntax
Visual Basic
Public Function Palette( _
   ByVal PaletteName As String _
) As Variant
Parameters
PaletteName
The name of the DICOM defined Palette
Remarks
Valid PaletteNames are - HOTIRON, PET20STEP, HOTMETALBLUE and PETCOLOR
See Also

DicomGlobal Object | DicomGlobal Members


ReadFile Method

ReadFile Method
DicomObjects Reference > DicomGlobal Object : ReadFile Method
The name of the file to read.
This is passed unmodified to the operating system, and it is therefore the container’s responsibility to ensure either that the file exists within the current directory, or that a fully qualified filename is provided.
Description
Read a DICOM file
Syntax
Visual Basic
Public Function ReadFile( _
   ByVal FileName As String _
) As DicomImage
Parameters
FileName
The name of the file to read.
This is passed unmodified to the operating system, and it is therefore the container’s responsibility to ensure either that the file exists within the current directory, or that a fully qualified filename is provided.
Remarks

This method can read either official “Part10” format files with the 128 byte header, or unofficial “Part3” format files without a header, and detection of the type is automatic.
The file may have been written by the WriteFile method or by other DICOM software.
See ReadDirectory for an alternative method suitable for reading “DICOMDIR” directory files.
See the security page for details of restrictions on this method.
By default, pixel data is read only when it is required, greatly speeding the display of multi-frame images, and reducing memory requirements. However, a side effect of this is that any elements after the pixel data (7FE0,0010) will not be read. This should not affect most applications, but if necessary, this behaviour made be over-ridden using the DisableFileMapping or DisableQuickRead registry entries. See the registry entries page for more details.

Another effect of file mapping is that files read using this method cannot be deleted until the image object is released. This method creates two references to the newly created DicomImage object (one in the collection, and one as the return value), and both must be released before the file can be deleted.

See Also

DicomGlobal Object | DicomGlobal Members


ResetDirectX Method

ResetDirectX Method
DicomObjects Reference > DicomGlobal Object : ResetDirectX Method
Description
Reset DirectX sub-system
Syntax
Visual Basic
Public Sub ResetDirectX()
Remarks
Forces reinstantiation by deleting current DirectX object
See Also

DicomGlobal Object | DicomGlobal Members


CurrentConnections Property

CurrentConnections Property
DicomObjects Reference > DicomGlobal Object : CurrentConnections Property
Description
All currently Open connections
Property type
Read-write property
Syntax
Visual Basic
Public Property CurrentConnections As DicomConnections
Remarks
DicomConnection objects are automatically added and deleted from an internal list as they are created or deleted, and the collection returned by this property contains all those active at the time it is retrieved, but this collection is not updated subsequently.
There is an automatic mechanism within DicomObjects for performing a graceful shutdown of associations when the corresponding DicomConnection object has no further references to it. This is temporarily inhibited while the object returned by this property is in existence, so the object returned should be used and released reasonably quickly (a few seconds does not matter, but it should not be a global variable).
See Also

DicomGlobal Object | DicomGlobal Members


DirectionStrings Property

DirectionStrings Property
DicomObjects Reference > DicomGlobal Object : DirectionStrings Property
Description
Direction markers for use with labels of type doLabelSpecial
Property type
Read-write property
Syntax
Visual Basic
Public Property DirectionStrings As String
Remarks

This property supplies the strings used by all DicomLabels of type doLabelSpecial. The default value is “R\L\A\P\I\S" , corresponding to the English abbreviations for Right, Left, Anterior, Posterior, Inferior and Superior respectively. If you wish to change this value, please note the following:

  • 6 values are required, in the order indicated above, separated by backslash characters
  • Multiple characters per component are allowed, and may be required to be unambiguous in some languages
  • Unicode is fully supported allowing Chinese or other non-Western direction indicators
See Also

DicomGlobal Object | DicomGlobal Members


DirectXLevel Property

DirectXLevel Property
DicomObjects Reference > DicomGlobal Object : DirectXLevel Property
Description
Current feature level of DirectX
Property type
Read-write property
Syntax
Visual Basic
Public Property DirectXLevel As Single
Return Type
Returns a DirectX defined value for Direct3D feature level
See Also

DicomGlobal Object | DicomGlobal Members


DotNetMode Property

DotNetMode Property
DicomObjects Reference > DicomGlobal Object : DotNetMode Property
Description
If true, improves compatibility with the .NET environment
Property type
Read-write property
Syntax
Visual Basic
Public Property DotNetMode As Boolean
Remarks

In general, arrays in a COM environment are expected to be 1-based, so an array with N elements has an index range from 1 to N. However, in a .NET environment, the expectation is that the range would be 0 to N-1, and if this is not done, then COM arrays cannot easily be cast to their .NET equivalents. Therefore, this property, if set true, changes the behaviour, and causes all arrays generated by DicomObjects (e.g. using the Value property of a DicomAttribute to return zero-based arrays, which can simply be cast to their corresponding .NET types (string[] int[] etc.) Similarly, when true, the zero index items in arrays passed to DicomObjects (e.g. in DicomAttributes.Add) are used, when they would otherwise be ignored.

Note that the indexing of DicomObjects collections (e.g. DicomImages, DicomDataSets) is not affected by this setting.

See Also

DicomGlobal Object | DicomGlobal Members


EnableExtendedNegotiation Property

EnableExtendedNegotiation Property
DicomObjects Reference > DicomGlobal Object : EnableExtendedNegotiation Property
Description
Controls whether extended negotiation is used
Property type
Read-write property
Syntax
Visual Basic
Public Property EnableExtendedNegotiation As Boolean
Remarks
As the default value of this property is false, it enables old applications to run unmodified, but for newer applications, this property should be set true, and extended negotiation should be properly handled using the ExtendedNegotiationValues property of DicomContext objects.
See Also

DicomGlobal Object | DicomGlobal Members


LastRemoteCertificate Property

LastRemoteCertificate Property
DicomObjects Reference > DicomGlobal Object : LastRemoteCertificate Property
Description
Remote certificate presentation during last atomic operation
Property type
Read-write property
Syntax
Visual Basic
Public Property LastRemoteCertificate As Object
Remarks
Secure communication using transport layer security is possible using DicomObjects. Ideally when using TLS, the remote entity’s certificate should be checked between making the association and passing any data, and this can be achieved when using a DicomConnection object. However, this is not possible using methods which establish the association and carry out the transaction in one method (atomic operations), such as those using a DicomQuery object with UseTLS=true, or the EchoSecure method. In all these cases, the remote entity’s certificate is stored into this property, for later checking by an application. It is of course updated every time an outgoing operation occurs, but as these are always synchronous, this causes no ambiguities.
See Also

DicomGlobal Object | DicomGlobal Members


MinFontSize Property

MinFontSize Property
DicomObjects Reference > DicomGlobal Object : MinFontSize Property
Description
Minimum Font Size used when drawing Text Label
Property type
Read-write property
Syntax
Visual Basic
Public Property MinFontSize As Single
See Also

DicomGlobal Object | DicomGlobal Members


ObjectType Property

ObjectType Property
DicomObjects Reference > DicomGlobal Object : ObjectType Property
Description
Describes the nature of an automation object
Property type
Read-write property
Syntax
Visual Basic
Public Property ObjectType As String
Remarks

The possible values are as follows:

“DicomViewer”
“DicomQuery”
“DicomImage”
“DicomImages”
“DicomDataSet”
“DicomDataSets”
“DicomAttribute”
“DicomConnection”
“DicomConnections”
“DicomContext”
“DicomContexts”
“DicomLabel”
“DicomLabels”
“DicomGlobal”
“DicomLog”
“DicomPrint”

See Also

DicomGlobal Object | DicomGlobal Members


RegString Property

RegString Property
DicomObjects Reference > DicomGlobal Object : RegString Property
The name of the registry key to over-ride
Description
Get DicomObjects current registry value
Property type
Read-write property
Syntax
Visual Basic
Public Property RegString( _
   ByVal Name As String _
) As String
Parameters
Name
The name of the registry key to over-ride
Remarks

Many obscure options in DicomObjects are controlled via registry keys, all under the master key:

HKEY_LOCAL_MACHINE/Software/Medical Connections/DicomObjects
In fact, these values are cached when first used, and from then on, the cached value is used, and subsequent changes to the registry itself will be ignored until DicomObjects is reloaded (normally when it’s container program is restarted). However, these methods allow direct manipulation of the registry cache, allowing any of the values to be over-ridden. Also, programs may through reading these parameterised properties find the value currently being used, whether from the registry itself, a default value, or previous use of one of these properties.

All values used by DicomObjects are either Strings or DWORDs, and it is important that the correct type of value be used.
Some values are held under further registry keys, and these may be controlled by prepending any necessary sub-keys separated by backslashes.
e.g. to change the preferred transfer syntax used for verification to explicit VR, the following could be used:
DicomGlobal.RegString(“TransferSyntax\1.2.840.10008.1.1”)=”1.2.840.10008.1.2.1 1.2.840.10008.1.2”

To change the default value of a key use a trailing backslash e.g. to change the preferred transfer syntax to compressed JPEG for all abstract syntaxes, the following would be appropriate:

DicomGlobal.RegString(“TransferSyntax\”)=”1.2.840.10008.1.2.4.51 1.2.840.10008.1.2”

See Also

DicomGlobal Object | DicomGlobal Members


RegWord Property

RegWord Property
DicomObjects Reference > DicomGlobal Object : RegWord Property
The name of the registry key to over-ride
Description
Get DicomObjects currently registry value
Property type
Read-write property
Syntax
Visual Basic
Public Property RegWord( _
   ByVal Name As String _
) As Long
Parameters
Name
The name of the registry key to over-ride
Remarks

Many obscure options in DicomObjects are controlled via registry keys, all under the master key:

HKEY_LOCAL_MACHINE/Software/Medical Connections/DicomObjects
In fact, these values are cached when first used, and from then on, the cached value is used, and subsequent changes to the registry itself will be ignored until DicomObjects is reloaded (normally when it’s container program is restarted). However, these methods allow direct manipulation of the registry cache, allowing any of the values to be over-ridden. Also, programs may through reading these parameterised properties find the value currently being used, whether from the registry itself, a default value, or previous use of one of these properties.

All values used by DicomObjects are either Strings or DWORDs, and it is important that the correct type of value be used.
Some values are held under further registry keys, and these may be controlled by prepending any necessary sub-keys separated by backslashes.
e.g. to change the preferred transfer syntax used for verification to explicit VR, the following could be used:
DicomGlobal.RegString(“TransferSyntax\1.2.840.10008.1.1”)=”1.2.840.10008.1.2.1 1.2.840.10008.1.2”

To change the default value of a key use a trailing backslash e.g. to change the preferred transfer syntax to compressed JPEG for all abstract syntaxes, the following would be appropriate:

DicomGlobal.RegString(“TransferSyntax\”)=”1.2.840.10008.1.2.4.51 1.2.840.10008.1.2”

See Also

DicomGlobal Object | DicomGlobal Members


Version Property

Version Property
DicomObjects Reference > DicomGlobal Object : Version Property
Description
Current Version of DicomObjects
Property type
Read-write property
Syntax
Visual Basic
Public Property Version As String
Remarks
The same version may be seen in the AboutBox, and in the first message logged when a program using DicomObjects is started.
See Also

DicomGlobal Object | DicomGlobal Members


DicomImage Object

DicomImage Object
Members
DicomObjects Reference : DicomImage Object
Description
In general, a DicomImage is a superset of the DicomDataSet type, which also contains a collection of attributes, the distinction being that a DicomImage contains pixel data, and is therefore displayable within a DicomViewer control, whereas a DicomDataSet does not contain pixel data, and is not displayable. The different properties and methods reflect this difference.
Remarks

Each DicomImage object corresponds to one SOP instance, and for display, DicomImages are commonly held within a DicomImages collection.

A DicomImage object is directly creatable, either using Visual Basic’s “CreateObject” method (or equivalent) using the name “DicomObjects.DicomImage” or via the DicomViewer’s New method.

See Also

DicomImage Members


DicomImage Object Members

DicomImage Object Members
Overview
DicomObjects Reference : DicomImage Object
Public Methods
Public Method AllocatePixelSpace | Allocate space for pixel data
Public Method ArrayExport | Export an image to an array
Public Method ArrayImport | Import an image from an array
Public Method Blt | Copy pixel data from one image to another
Public Method BurnInLabels | Burn Annotations into pixel data
Public Method Capture | Returns a secondary capture version of the image, complete with labels etc.
Public Method Copy | Copies an image to the clipboard as a DIB
Public Method CopyPixelBuffer | Copy pixel data from an external buffer
Public Method CurrentToPresentationState | Takes all current display information and creates a corresponding DICOM presentation state
Public Method DecompressAll | Causes all frames of an image to be decompressed
Public Method DecompressFrame | Decompresses a frame
Public Method FileExport | Export an image to a file
Public Method FileImport | Import an image from a file
Public Method Histogram | Computes the histogram of pixel values
Public Method MakeVolume | Make 3D Volume
Public Method MemoryExport | Export an image to a global memory block
Public Method MemoryImport | Import an image from a global memory block
Public Method Paste | Paste an image from the clipboard
Public Method Picture | An IPicture representation of the image
Public Method PictureWithLUT | An IPicture representation of the image
Public Method PixelsModified | Notify DicomObjects that Pixel data has been modified
Public Method PresentationStateToCurrent | Modifies current display properties to match the DICOM presentation state
Public Method PrinterImage | Creates a copy of the image for printing images
Public Method ReferenceLine | Creates a reference line label
Public Method Refresh | Refresh an image, optionally invalidating the pixel cache
Public Method RenderToDC | Render to a Device Context
Public Method RenderToDCWithLUT | Render to a Device Context
Public Method Send | Sends an Image to a remote DICOM application
Public Method SetDefaultWindows | Resets Width and Level back to their initial values
Public Method SetPixelFile | Maps pixel data onto a file
Public Method SetPixelFileCompressed | Sets a Pixel file - with compressed data
Public Method SetPixelFileExt | Sets a Pixel file - allowing offset > 4 Gig
Public Method SetPixelFiles | Maps pixel data onto a file
Public Method SubImage | Creates a copy of part or all of the image with controlled size
Public Method WriteArray | Writes object into a byte array (analogous to WriteFile)
Public Method WriteField | Writes a DICOM image into a database field
Public Method WriteFile | Writes an image to an external DICOM file
Public Method WriteMemory | Writes data to a global memory block
Public Method WriteStream | Writes an image to an IStream
Public Properties
Public Property AccessionNumber | Accession Number
Public Property ActualScrollX | Actual image offset (X) used for display
Public Property ActualScrollY | Actual image offset (Y) used for display
Public Property ActualZoom | Actual Zoom used for display
Public Property Angle | Angle of rotation
Public Property Attributes | The Collection of Attributes comprising this image
Public Property BorderColour | Colour of the border around an image
Public Property BorderStyle | The style used to draw the image border
Public Property BorderWidth | Width of the border around an image
Public Property Bottom | Controls the display position of an image
Public Property CacheDecompressed | Controls caching of decompressed images
Public Property CacheDisplay | Controls whether displayed images are Cached
Public Property CineMode | Controls auto-run mode for multi-frame images
Public Property CineRate | Controls auto-run rate for of multi-frame images
Public Property ColourTable | Colour table for application of pseudo-colour to monochrome images
Public Property Command | The full request dataset received
Public Property CompressionInfo | Information about how an image was compressed when received or read.
Public Property CubicSplineAlpha | Controls images sharpness when magnifiaction mode is doCubicSpline
Public Property DateOfBirth | The patient's date of birth (as a Variant)
Public Property DateOfBirthAsDate | The patient's date of birth (as DATE)
Public Property DownScale | Downsample display for increased speed
Public Property FilterLength | Controls averaging length when minifcation mode is doFilterMovingAverage
Public Property FlipState | Controls horizontal & vertical flipping of the image
Public Property Frame | Controls which frame of a multi-frame image is displayed
Public Property FrameCount | The number of frames contained in a multi-frame image
Public Property IncludedInImageIndex | Indicates whether this Image should be included for DicomViewer.ImageIndex method
Public Property InstanceUID | Unique Image identifier
Public Property JPEG | Returns an array containing a JPEG byte stream corresponding to the image
Public Property Labels | The collection of DicomLabels to display over this image
Public Property Left | Controls the display position of an image
Public Property Level | Controls the grey-scale mapping of a displayed image
Public Property LevelShift | Provides a means to modify the usage of a Values of Interest Lookup Table (VOI LUT) or other display mapping
Public Property LongFrame | Controls which frame of a multi-frame image is displayed
Public Property LongFrameCount | The number of frames contained in a multi-frame image
Public Property LookupTable | Returns the lookup table used to convert pixel values to display or intermediate values
Public Property LosslessCompressionMode | Control of how to handle the old lossless compression bug
Public Property LosslessDecompressionMode | Control of how to handle the old lossless compression bug
Public Property MagnificationMode | Controls interpolation mode when zoom is >1
Public Property Mask | Controls mask subtraction - see MaskFrame for number
Public Property MaskFraction | Controls partial masking to show some original image landmarks
Public Property MaskFrame | Frame to use for masking if not defined in mask sequence or presentation state
Public Property MaximumPixelValue | Maximum Pixel Value in the Image
Public Property MinificationMode | Controls interpolation mode when zoom is <1
Public Property MinimumPixelValue | Minimum Pixel Value in the Image
Public Property ModalityLUT | Selects which Modality LUT to apply (0 for none)
Public Property Mode | Image display Mode
Public Property Name | The patient's Name
Public Property ObjectType | Describes the nature of an automation object
Public Property OriginX | Position of top-left corner within the control's coordinate system
Public Property OriginY | Position of top-left corner within the control's coordinate system
Public Property OverlayColour | Controls the colour of an overlay embedded in the image
Public Property OverlayVisible | Controls visibility of an overlay embedded in the image
Public Property PatientID | Patient identifier
Public Property PixelAddress | Long pointer to Pixel Buffer
Public Property PixelAddress64 | Pointer to Pixel Buffer as true pointer
Public Property Pixels | Accesses pixeldata as an array
Public Property PresentationLUT | Selects which Presentation LUT to apply (0 for none)
Public Property PresentationState | DataSet contining the DICOM grayscale Presentation State to apply
Public Property Projection | Projection for 3D
Public Property PropertiesFor3D | Properties For 3D
Public Property PropertiesForFusion | Properties For Fusion
Public Property ReceivedSyntax | Transfer Syntax with which SOP instance was received or read
Public Property Right | Controls the display position of an image
Public Property RotateState | Controls Rotation of the image
Public Property RotationBehaviour | Controls the rotation behaviour of the image with respect to the current StretchMode
Public Property ScrollX | Controls the positioning of an image display
Public Property ScrollY | Controls the positioning of an image display
Public Property SeriesDescription | Series Description
Public Property SeriesUID | Unique Series identifier
Public Property Sex | The patient's sex
Public Property ShowLabels | Whether DicomLabels are to be shown
Public Property ShowShutter | Controls whether or not to display Shutter if present
Public Property ShowUpdates | Controls whether updates are shown for this image
Public Property SizeX | The horizontal dimension of the image
Public Property SizeY | The vertical dimension of the image
Public Property SOPClass | The Image's SOP Class UID
Public Property StretchedAlignment | Controls the alignment of a stretched-to-fit Image
Public Property StretchMode | Controls the zoom of an image to fill the space available
Public Property StudyDescription | Study Description
Public Property StudyUID | Unique Study identifier
Public Property Tag | General Purpose Tag
Public Property Top | Controls the display position of an image
Public Property UnsharpEnhancement | Unsharp masking enhancement value
Public Property UnsharpLength | Unsharp Masking mask size
Public Property VOILUT | Selects which VOI LUT to apply (0 for none)
Public Property VoiLUTFunction | Controls which VOILUT function to use, default value is Linear.
Public Property Width | Controls the grey-scale mapping of a displayed image
Public Property WidthMultiplier | Provides a means to modify the usage of a Values of Interest Lookup Table (VOI LUT) or other display mapping
Public Property Zoom | Controls the zooming of an image
Public Property ZVector | Direction cosines for 'Z-direction'
See Also

DicomImage Object


AllocatePixelSpace Method

AllocatePixelSpace Method
DicomObjects Reference > DicomImage Object : AllocatePixelSpace Method
Length of data to allocate (in bytes)
Description
Allocate space for pixel data
Syntax
Visual Basic
Public Sub AllocatePixelSpace( _
   ByVal Length As Long _
)
Parameters
Length
Length of data to allocate (in bytes)
Remarks
It is the user’s responsibility to ensure that the data length is correct, normally being the product of the rows, columns, frames, samples per pixel, and bytes per sample(1 or 2).
See Also

DicomImage Object | DicomImage Members


ArrayExport Method

ArrayExport Method
DicomObjects Reference > DicomImage Object : ArrayExport Method
The type of export operation to perform.
Further information necessary for the export.
Description
Export an image to an array
Syntax
Visual Basic
Public Function ArrayExport( _
   ByVal Type As String, _
   Optional ByVal Information As Variant _
) As Variant
Parameters
Type
The type of export operation to perform.
Information
Further information necessary for the export.
Remarks

Only JPEG and BMP/DIB formats are supported directly, but other formats such as TIF may be supported via extension DLLs.

The following applies to JPEG file import:

  • The Type parameter must be JPEG or JPG
  • The Information parameter must contain an integer up to 100, which controls the quality of the resulting JPEG image.

The following applies to DIB/BMP file export:

  • Data will be uncompressed.
  • If type is BMP, then a BMP file header is included at the start of the data. If type is DIB, then no header is included.
  • The Type parameter must be DIB or BMP
  • The Information parameter is not used.

See Import/Export DLLs for details of how to write and configure your own extension DLLs

See Also

DicomImage Object | DicomImage Members


ArrayImport Method

ArrayImport Method
DicomObjects Reference > DicomImage Object : ArrayImport Method
Byte array containing the image data
The type of import operation to perform.
Further information necessary for the import.
Description
Import an image from an array
Syntax
Visual Basic
Public Sub ArrayImport( _
   ByVal Array As Variant, _
   ByVal Type As String, _
   Optional ByVal Information As Variant _
)
Parameters
Array
Byte array containing the image data
Type
The type of import operation to perform.
Information
Further information necessary for the import.
Remarks

Like the Paste method, this method modifies only the minimum number of attributes necessary to ensure consistency of the image. In order to produce a valid DICOM SOP instance, many other attributes (depending on the SOP class) must be added.
If Type is omitted or zero length, it is assumed to equal the extension of the filename for “FileImport”, but must be specified for the other forms.
Only JPEG, BMP/DIB, AVI and (experimentally) MPEG formats are supported directly, but other formats may be supported via extension DLLs.

The following applies to JPEG file import:

The JPEG data is imported directly, and may either be stored or transmitted unchanged as a JPEG encapsulated SOP instance (1.2.840.10008.1.2.4.50), or automatically decompressed if necessary.
The Type parameter must be JPEG or JPG
The Information parameter is not used.

The following applies to DIB/BMP file import:

Data must be uncompressed.
If a BMP file header is present, this is detected automatically.
The Type parameter must be DIB or BMP
The Information parameter is not used.

The following applies to AVI file import:

The Type parameter must be AVI
The Information parameter is not used.
A multi-frame DICOM image is generated.

The following applies to MPEG file import:

The Type parameter must be MPG
The Information parameter is not used.
An MPEG-2 encoded DICOM image is generated.
FFMpeg implementation supports other popular video formats as well.

See Import/Export DLLs for details of how to write and configure your own extension DLLs

See Also

DicomImage Object | DicomImage Members


Blt Method

Blt Method
DicomObjects Reference > DicomImage Object : Blt Method
The image to copy from
The X coordinate of the left edge of the area to copy from
The Y coordinate of the top edge of the area to copy from
The X coordinate of the left edge of the area to copy into
The Y coordinate of the top edge of the area to copy into
The width of the source area to copy
The height of the source area to copy
The frame to copy from (1-based)
The frame to copy to (1-based)
The magnification factor to apply
Whether to apply standard windowing to the image data during the transfer
Description
Copy pixel data from one image to another
Syntax
Visual Basic
Public Sub Blt( _
   ByVal Source As DicomImage, _
   ByVal SourceX As Long, _
   ByVal SourceY As Long, _
   ByVal DestinationX As Long, _
   ByVal DestinationY As Long, _
   ByVal SizeX As Long, _
   ByVal SizeY As Long, _
   ByVal SourceFrame As Long, _
   ByVal DestinationFrame As Long, _
   ByVal Zoom As Single, _
   ByVal Window As Boolean _
)
Parameters
Source
The image to copy from
SourceX
The X coordinate of the left edge of the area to copy from
SourceY
The Y coordinate of the top edge of the area to copy from
DestinationX
The X coordinate of the left edge of the area to copy into
DestinationY
The Y coordinate of the top edge of the area to copy into
SizeX
The width of the source area to copy
SizeY
The height of the source area to copy
SourceFrame
The frame to copy from (1-based)
DestinationFrame
The frame to copy to (1-based)
Zoom
The magnification factor to apply
Window
Whether to apply standard windowing to the image data during the transfer
Remarks

This method takes frame SourceFrame of Source, and magnifies by the factor Zoom. It extracts from that a rectangle with a top left corner at Source/Y and size SizeX/Y. It then overwrites this onto an area of DestinationFrame of the destination image (the image on which this method is called), putting the top left corner of the rectangle at DestinationX/Y.

If Window is true, the data is windowed before transfer, and scaled to match the full bit depth of the destination. If window is false, then data is copied "as is", but in this case, the photometric interpretation of the two images must be the same (RGB, MONOCHROME2 etc.) Note that Zoom is applied BEFORE selecting the rectangle.

Because this image over-writes existing pixels, it is necessary that the destination image must have allocated and writeable pixels. When making a montage from scratch, this is commonly done either by using AllocatePixelSpace, or when starting with an “base” image, PrinterImage is useful, as it produces images scaled to the full bit depth. Where the destination image has been read from disk, it may be necessary to call the DecompressAll method to ensure that a writeable copy of the pixel data is made, rather than the read-only copy mapped from the disk.

Any type of image may be used for the source, but when windowing, the destination image must have unsigned pixel values.

See Also

DicomImage Object | DicomImage Members


BurnInLabels Method

BurnInLabels Method
DicomObjects Reference > DicomImage Object : BurnInLabels Method
Description
Burn Annotations into pixel data
Syntax
Visual Basic
Public Sub BurnInLabels()
Remarks
Add all labels to the image at maximum pixel value for white and minimum for black, or the inverse if the image is MONOCHROME1
See Also

DicomImage Object | DicomImage Members


Capture Method

Capture Method
DicomObjects Reference > DicomImage Object : Capture Method
Whether to capture the whole image
Description
Returns a secondary capture version of the image, complete with labels etc.
Syntax
Visual Basic
Public Function Capture( _
   ByVal WholeImage As Boolean _
) As DicomImage
Parameters
WholeImage
Whether to capture the whole image
Remarks

The image is copied, at its present display resolution, zoom, orientation and scrolling, complete with annotations (if ShowLabels is true).

If WholeImage is false, then just the area of the image currently displayed is captured, but if WholeImage is true, then the entire image is captured. In whole image mode, the scroll properties are ignored, but other display properties, including Zoom are still used, so this method should be used with caution if Zoom is large, as very large images may result.

A new Instance UID is generated, and the type is set to secondary, but most image properties are copied unchanged. If the resulting image is entirely monochrome, then it is generated as a MONOCHROME2 image, but if any colour is present (even in annotations), then a full RGB image is produced, unless used with the screen set to an 8 bit display mode, in which case a PALETTE COLOR image results.

The SOP class and instance UID of the original image are correctly stored in the (0008,2112) sequence, and a new Instance UID is generated as described in the UIDs section.

If the image is not associated with a DicomViewer, then WholeImage is regarded as TRUE, irrespective of the value given, as the “displayed” size could not be calculated.

See Also

DicomImage Object | DicomImage Members


Copy Method

Copy Method
DicomObjects Reference > DicomImage Object : Copy Method
Description
Copies an image to the clipboard as a DIB
Syntax
Visual Basic
Public Sub Copy()
Remarks
The image is copied as a device independent bitmap (DIB), which can be imported into most graphical applications.
The image generated is partially based on that which would be displayed, as Width, Level and Frame are used to locate and pre-process the image, but Zoom, ScrollX and ScrollY are not.
See Also

DicomImage Object | DicomImage Members


CopyPixelBuffer Method

CopyPixelBuffer Method
DicomObjects Reference > DicomImage Object : CopyPixelBuffer Method
The address from which data is to be copied
The frame number to fill.
The distance (in bytes) between the start of one row of data and the next
The distance (in bytes) between the start of one pixel and the next
Description
Copy pixel data from an external buffer
Syntax
Visual Basic
Public Sub CopyPixelBuffer( _
   ByVal Address As Long, _
   ByVal Frame As Integer, _
   ByVal RowStep As Long, _
   ByVal ColumnStep As Long _
)
Parameters
Address
The address from which data is to be copied
Frame
The frame number to fill.
RowStep
The distance (in bytes) between the start of one row of data and the next
ColumnStep
The distance (in bytes) between the start of one pixel and the next
Remarks

This function is primarily used to load data from an external frame buffer such as that produced by a video-grabber, into the pixel buffer, which should be allocated using AllocatePixelSpace if not already allocated by other means.
An entire frame is loaded in one call, using values from the DicomImage’s Attributes to determine the following parameters:
The height and width of the image (0028,0011) & (0028 & 0010)
The bit depth - currently only 8 or 16 bits allocated are supported (0028,0100)

The number of samples per pixel (0028,0002)
When capturing from devices that use top to bottom row ordering, RowStep may be negative, in which case Address should be increased appropriately so that it still points to the first pixel of the lowest row.
If samples per pixel is 3, then bits allocated must be 8. In this case it is assumed that the data is being copied from a Windows compatible bitmap ordered as BGR, and the bytes are swapped appropriately to produce the RGB ordering needed for DICOM.

See Also

DicomImage Object | DicomImage Members


CurrentToPresentationState Method

CurrentToPresentationState Method
DicomObjects Reference > DicomImage Object : CurrentToPresentationState Method
Controls whether additional private elements are included
Description
Takes all current display information and creates a corresponding DICOM presentation state
Syntax
Visual Basic
Public Sub CurrentToPresentationState( _
   ByVal usePrivate As Boolean _
)
Parameters
usePrivate
Controls whether additional private elements are included
Remarks

The presentation state created is immediately used as the image’s PresentationState property, so after this call, the display should not be visibly altered, though small changes may be seen due to the reduced flexibility of colours etc. in DICOM presentation states compared with DicomObjects' DicomLabel objects.
The properties encapsulated into the presentation state include:

  • Window Width & Level
  • Zoom
  • FlipState& RotateState
  • ScrollX & ScrollY
  • ModalityLUT, VOILUT & PresentationLUT
  • OverlayVisible & OverlayColour
  • All DicomLabels except “special” and “ruler” types

There are several properties of DicomLabel objects which do not have official DICOM equivalents, such as font details, RotationMode and RotationCentre. If usePrivate is true, then private attribute in the range 6E15,7Axx are added to the presentation state to store them, but if usePrivate is false, then these properties must be discarded.

This method does have some limitations, and the following objects/properties are not currently converted:

  • Some label types – arrows, rulers, arcs and “special” labels
  • Mask subtraction information
  • ModalityLUT, VOILUT and PresentationLUT properties
  • ColourTable

These issues will be addressed in a future version of DicomObjects

See Also

DicomImage Object | DicomImage Members


DecompressAll Method

DecompressAll Method
DicomObjects Reference > DicomImage Object : DecompressAll Method
Description
Causes all frames of an image to be decompressed
Syntax
Visual Basic
Public Sub DecompressAll()
Remarks

he normal policy adopted by DicomObjects for the handling of compressed images is to decompress frames only when necessary, and to keep the decompressed versions only for as long as is necessary for display or translation, thereby minimising image load times, and memory use. This behaviour is not, however, always appropriate, especially when cine sequences are shown, or where modifications need to be made to the image. When this method is called, all frames are decompressed and held in RAM, replacing the original compressed version, thereby greatly speeding subsequent display, though needing much more memory.

Once this method has been executed, all reference to the compressed version is lost, and the ReceivedSyntax property is reset to little-endian default (1.2.840.10008.1.2).
See also CacheDecompressed & DecompressFrame, which cause a decompressed copy to be made, but do not remove the original compressed data.

See Also

DicomImage Object | DicomImage Members


DecompressFrame Method

DecompressFrame Method
DicomObjects Reference > DicomImage Object : DecompressFrame Method
The 1-based number of the frame to decompress
Description
Decompresses a frame
Syntax
Visual Basic
Public Sub DecompressFrame( _
   ByVal Frame As Long _
)
Parameters
Frame
The 1-based number of the frame to decompress
Remarks
This will not always give a performance improvement, but may depending on hardware and memory constraints – experiment!
See Also

DicomImage Object | DicomImage Members


FileExport Method

FileExport Method
DicomObjects Reference > DicomImage Object : FileExport Method
The name of the file to write.

The type of export operation to perform.

(If Type is omitted, it is assumed to equal the extension of the filename. It must be stated for the other operations)

Further information necessary for the export.
Description
Export an image to a file
Syntax
Visual Basic
Public Sub FileExport( _
   ByVal FileName As String, _
   ByVal Type As String, _
   Optional ByVal Information As Variant _
)
Parameters
FileName
The name of the file to write.
Type

The type of export operation to perform.

(If Type is omitted, it is assumed to equal the extension of the filename. It must be stated for the other operations)

Information
Further information necessary for the export.
Remarks

Only JPEG and BMP/DIB formats are supported directly, but other formats such as TIF may be supported via extension DLLs.

The following applies to JPEG file import:

  • The Type parameter must be JPEG or JPG
  • The Information parameter must contain an integer up to 100, which controls the quality of the resulting JPEG image.

The following applies to DIB/BMP file export:

  • Data will be uncompressed.
  • If type is BMP, then a BMP file header is included at the start of the data. If type is DIB, then no header is included.
  • The Type parameter must be DIB or BMP
  • The Information parameter is not used.

See Import/Export DLLs for details of how to write and configure your own extension DLLs

See Also

DicomImage Object | DicomImage Members


FileImport Method

FileImport Method
DicomObjects Reference > DicomImage Object : FileImport Method
The name of the file to read.
The type of import operation to perform.
Further information necessary for the import.
Description
Import an image from a file
Syntax
Visual Basic
Public Sub FileImport( _
   ByVal FileName As String, _
   ByVal Type As String, _
   Optional ByVal Information As Variant _
)
Parameters
FileName
The name of the file to read.
Type
The type of import operation to perform.
Information
Further information necessary for the import.
Remarks

Like the Paste method, this method modifies only the minimum number of attributes necessary to ensure consistency of the image. In order to produce a valid DICOM SOP instance, many other attributes (depending on the SOP class) must be added.
If Type is omitted or zero length, it is assumed to equal the extension of the filename for “FileImport”, but must be specified for the other forms.
Only JPEG, BMP/DIB, AVI and (experimentally) MPEG formats are supported directly, but other formats may be supported via extension DLLs.

The following applies to JPEG file import:

The JPEG data is imported directly, and may either be stored or transmitted unchanged as a JPEG encapsulated SOP instance (1.2.840.10008.1.2.4.50), or automatically decompressed if necessary.
The Type parameter must be JPEG or JPG
The Information parameter is not used.

The following applies to DIB/BMP file import:

Data must be uncompressed.
If a BMP file header is present, this is detected automatically.
The Type parameter must be DIB or BMP
The Information parameter is not used.

The following applies to AVI file import:

The Type parameter must be AVI
The Information parameter is not used.
A multi-frame DICOM image is generated.

The following applies to MPEG file import:

The Type parameter must be MPG
The Information parameter is not used.
An MPEG-2 encoded DICOM image is generated.
FFMpeg implementation supports other popular video formats as well.

See Import/Export DLLs for details of how to write and configure your own extension DLLs

See Also

DicomImage Object | DicomImage Members


Histogram Method

Histogram Method
DicomObjects Reference > DicomImage Object : Histogram Method
The lowest pixel value to be included
The highest pixel value to be included
The number of adjacent pixel values to be grouped into each bin
Description
Computes the histogram of pixel values
Syntax
Visual Basic
Public Function Histogram( _
   ByVal MinValue As Long, _
   ByVal MaxValue As Long, _
   ByVal BinWidth As Long _
) As Variant
Parameters
MinValue
The lowest pixel value to be included
MaxValue
The highest pixel value to be included
BinWidth
The number of adjacent pixel values to be grouped into each bin
Remarks

The format of the returned data is suitable for creating DICOM Image Histogram modules, though to use this a few other attributes must be added.
In keeping with the image histogram module, the values used are raw pixel values before application of a modality lookup table or rescaling – use LookupTable if such translation is required.
The array returned is, like most arrays in DicomObjects, “1-based”, so the bin corresponding to the minimum pixel value quoted is bin 1 (not 0).

For multi-frame images, only the first frame is used for this method.

See Also

DicomImage Object | DicomImage Members


MakeVolume Method

MakeVolume Method
DicomObjects Reference > DicomImage Object : MakeVolume Method
The factor by which the data should be downscaled to reduce memory usage
Description
Make 3D Volume
Syntax
Visual Basic
Public Function MakeVolume( _
   ByVal Decimate As Long _
) As DicomVolume
Parameters
Decimate
The factor by which the data should be downscaled to reduce memory usage
Remarks
The returned DicomVolume can be reused for different 3D rendering modes
See Also

DicomImage Object | DicomImage Members


MemoryExport Method

MemoryExport Method
DicomObjects Reference > DicomImage Object : MemoryExport Method
The type of export operation to perform.
Further information necessary for the export.
The length of the available memory block
Description
Export an image to a global memory block
Syntax
Visual Basic
Public Function MemoryExport( _
   ByVal Type As String, _
   ByVal Information As Variant, _
   ByRef Length As Long _
) As Integer
Parameters
Type
The type of export operation to perform.
Information
Further information necessary for the export.
Length
The length of the available memory block
Remarks

Only JPEG and BMP/DIB formats are supported directly, but other formats such as TIF may be supported via extension DLLs.

The following applies to JPEG file import:

  • The Type parameter must be JPEG or JPG
  • The Information parameter must contain an integer up to 100, which controls the quality of the resulting JPEG image.

The following applies to DIB/BMP file export:

  • Data will be uncompressed.
  • If type is BMP, then a BMP file header is included at the start of the data. If type is DIB, then no header is included.
  • The Type parameter must be DIB or BMP
  • The Information parameter is not used.

See Import/Export DLLs for details of how to write and configure your own extension DLLs

See Also

DicomImage Object | DicomImage Members


MemoryImport Method

MemoryImport Method
DicomObjects Reference > DicomImage Object : MemoryImport Method
Handle of a global memory block containing the image data
The type of import operation to perform.
Further information necessary for the import.
Description
Import an image from a global memory block
Syntax
Visual Basic
Public Sub MemoryImport( _
   ByVal Handle As Integer, _
   ByVal Type As String, _
   Optional ByVal Information As Variant _
)
Parameters
Handle
Handle of a global memory block containing the image data
Type
The type of import operation to perform.
Information
Further information necessary for the import.
Remarks

Like the Paste method, this method modifies only the minimum number of attributes necessary to ensure consistency of the image. In order to produce a valid DICOM SOP instance, many other attributes (depending on the SOP class) must be added.
If Type is omitted or zero length, it is assumed to equal the extension of the filename for “FileImport”, but must be specified for the other forms.
Only JPEG, BMP/DIB, AVI and (experimentally) MPEG formats are supported directly, but other formats may be supported via extension DLLs.

The following applies to JPEG file import:

The JPEG data is imported directly, and may either be stored or transmitted unchanged as a JPEG encapsulated SOP instance (1.2.840.10008.1.2.4.50), or automatically decompressed if necessary.
The Type parameter must be JPEG or JPG
The Information parameter is not used.

The following applies to DIB/BMP file import:

Data must be uncompressed.
If a BMP file header is present, this is detected automatically.
The Type parameter must be DIB or BMP
The Information parameter is not used.

The following applies to AVI file import:

The Type parameter must be AVI
The Information parameter is not used.
A multi-frame DICOM image is generated.

The following applies to MPEG file import:

The Type parameter must be MPG
The Information parameter is not used.
An MPEG-2 encoded DICOM image is generated.
FFMpeg implementation supports other popular video formats as well.

See Import/Export DLLs for details of how to write and configure your own extension DLLs

See Also

DicomImage Object | DicomImage Members


Paste Method

Paste Method
DicomObjects Reference > DicomImage Object : Paste Method
Description
Paste an image from the clipboard
Syntax
Visual Basic
Public Sub Paste()
Remarks

In order for this method to succeed, the clipboard must contain data which is, or can automatically be converted to, a device independent bitmap (DIB).
Like the Import methods, this method modifies only the minimum number of attributes necessary to ensure consistency of the image. In order to produce a valid DICOM SOP instance, many other attributes (depending on the SOP class) must be added.
Depending on the format of the data on the clipboard, the resulting image may be MONOCHROME2, PALETTE COLOR, or RGB.

Note that this method can only be applied to an existing DicomImage, so this should be created first as a new object.

See Also

DicomImage Object | DicomImage Members


Picture Method

Picture Method
DicomObjects Reference > DicomImage Object : Picture Method
Description
An IPicture representation of the image
Syntax
Visual Basic
Public Function Picture() As IPicture
Remarks

The object returned is a standard Windows representation of an image, and may for instance be assigned to the picture property of a Visual Basic PictureBox. It is also useful in many development environments for printing to standard (non-DICOM) printers.
e.g. in Visual Basic, an image may be printed simply by using
Printer.PaintPicture Image.Picture, 100, 100
Printer.NewPage
Like Copy, the Picture method returns a fully windowed version of the image “as seen”.

The image is always full size (1pixel:1 pixel), allowing full resolution.
PictureWithLUT likewise applies windowing to the image, but then applies an additional lookup table, as specified in the LookupTable parameter. This final lookup enables the programmer to correct for non-linearities in the printer response, and is equivalent to the CalibrationCurve property of a DicomViewer (which corrects for screen non-linearities). By use of an appropriate table, compliance with Part 14 of DICOM can be achieved.

For more details of how the final lookup table works, see CalibrationCurve.

See Also

DicomImage Object | DicomImage Members


PictureWithLUT Method

PictureWithLUT Method
DicomObjects Reference > DicomImage Object : PictureWithLUT Method
LookupTable as Variant Array of Long Integers
Description
An IPicture representation of the image
Syntax
Visual Basic
Public Function PictureWithLUT( _
   ByVal LUT As Variant _
) As IPicture
Parameters
LUT
LookupTable as Variant Array of Long Integers
Remarks

The object returned is a standard Windows representation of an image, and may for instance be assigned to the picture property of a Visual Basic PictureBox. It is also useful in many development environments for printing to standard (non-DICOM) printers.
e.g. in Visual Basic, an image may be printed simply by using
Printer.PaintPicture Image.Picture, 100, 100
Printer.NewPage
Like Copy, the Picture method returns a fully windowed version of the image “as seen”.

The image is always full size (1pixel:1 pixel), allowing full resolution.
PictureWithLUT likewise applies windowing to the image, but then applies an additional lookup table, as specified in the LookupTable parameter. This final lookup enables the programmer to correct for non-linearities in the printer response, and is equivalent to the CalibrationCurve property of a DicomViewer (which corrects for screen non-linearities). By use of an appropriate table, compliance with Part 14 of DICOM can be achieved.

For more details of how the final lookup table works, see CalibrationCurve.

See Also

DicomImage Object | DicomImage Members


PixelsModified Method

PixelsModified Method
DicomObjects Reference > DicomImage Object : PixelsModified Method
Description
Notify DicomObjects that Pixel data has been modified
Syntax
Visual Basic
Public Sub PixelsModified()
Remarks
This method enables DicomObjects to synchronise its display and invalidate any derivatives such as compressed forms of the image.
This method is not necessary if the “Pixels” property or CopyPixelBuffer is used to modify the pixel data, but is necessary if modifications are made based on the PixelAddress property.
See Also

DicomImage Object | DicomImage Members


PresentationStateToCurrent Method

PresentationStateToCurrent Method
DicomObjects Reference > DicomImage Object : PresentationStateToCurrent Method
Description
Modifies current display properties to match the DICOM presentation state
Syntax
Visual Basic
Public Sub PresentationStateToCurrent()
Remarks

This is essentially the reverse of CurrentToPresentationState. DicomObjects properties such as ScrollX, ScrollY,, Zoom and labels are set to reflect as accurately as possible the data in the current PresentationState property.
If private attributes have been added by CurrentToPresentationState, then they are utilized in this method.
This method does have some limitations, and the following objects/properties are not currently converted:

  • Mask subtraction information
  • ModalityLUT, VOILUT and PresentationLUT properties

These issues will be addressed in a future version of DicomObjects

See Also

DicomImage Object | DicomImage Members


PrinterImage Method

PrinterImage Method
DicomObjects Reference > DicomImage Object : PrinterImage Method
Bit depth of final image (must be 8-16, but always 8 when Planes=3)
1 for monochrome and 3 for colour
Controls whether annotations are “burnt-in” to the new image
Zoom to apply to new image
Edges of the original image to use.
Edges of the original image to use.
Edges of the original image to use.
Edges of the original image to use.
Description
Creates a copy of the image for printing images
Syntax
Visual Basic
Public Function PrinterImage( _
   ByVal Bits As Integer, _
   ByVal Planes As Integer, _
   ByVal ShowAnnotations As Boolean, _
   ByVal Zoom As Single, _
   ByVal Left As Integer, _
   ByVal Right As Integer, _
   ByVal Top As Integer, _
   ByVal Bottom As Integer _
) As DicomImage
Parameters
Bits
Bit depth of final image (must be 8-16, but always 8 when Planes=3)
Planes
1 for monochrome and 3 for colour
ShowAnnotations
Controls whether annotations are “burnt-in” to the new image
Zoom
Zoom to apply to new image
Left
Edges of the original image to use.
Right
Edges of the original image to use.
Top
Edges of the original image to use.
Bottom
Edges of the original image to use.
Remarks
The copy is fully rendered and scaled to the chosen bit depth, so no further windowing is required. Only 8 bits are allowed when Planes=3 (RGB). Left, Right, Top and Bottom refer to the original image – the size of the final image is the product of the cropped size and the chosen zoom. If the edges are given as 0, the full image is used.
See Also

DicomImage Object | DicomImage Members


ReferenceLine Method

ReferenceLine Method
DicomObjects Reference > DicomImage Object : ReferenceLine Method
The image whose position is to be shown
Whether to generate an intersection line (as opposed to a projection)
Description
Creates a reference line label
Syntax
Visual Basic
Public Function ReferenceLine( _
   ByVal Image As DicomImage, _
   ByVal Intersection As Boolean _
) As DicomLabel
Parameters
Image
The image whose position is to be shown
Intersection
Whether to generate an intersection line (as opposed to a projection)
Remarks

This method is used which you wish to show the relative positions of one image on another. It is typically used in CT and MRI to indicate the position of main imaging sections relative to a previously obtained localiser or “scout” image.

The method is called on the “localiser” image, and the first parameter is the main section who’s position is to be shown. The result is a new DicomLabel object which is designed to be added to the localiser image’s Labels collection. E.g. if “localiser” and “main_image” are defined as DicomObjects, then the following code will add an appropriate reference line to the localiser image:

Set NewLabel = localiser.ReferenceLine(main_image, false)
Localiser.Labels.Add NewLabel

  • If true, then the DicomLabel will still be of type doLabelLine, representing the intersection of the two image planes.
  • If false, then the DicomLabel returned will be of type doLabelPolygon with 4 vertices, each representing the projection of a corner of the main image onto the plane of the localiser.
See Also

DicomImage Object | DicomImage Members


Refresh Method

Refresh Method
DicomObjects Reference > DicomImage Object : Refresh Method
Set to true if the underlying pixel data has changed
Description
Refresh an image, optionally invalidating the pixel cache
Syntax
Visual Basic
Public Sub Refresh( _
   ByVal PixelsChanged As Boolean _
)
Parameters
PixelsChanged
Set to true if the underlying pixel data has changed
Remarks

This method is used mainly in the following circumstances:

  • After altering or adding DicomLabel items in either the control’s or any image’s Labels collection.
  • When a defined series of images must be drawn, such as when modifying the Frame property to generate a non-standard cine sequence
  • After changing an image’s PresentationState

These methods should not need to be called under other circumstances, as all other changes which would cause the display to alter should automatically cause a re-draw, but is available in case of problems.

See Also

DicomImage Object | DicomImage Members


RenderToDC Method

RenderToDC Method
DicomObjects Reference > DicomImage Object : RenderToDC Method
The Device Context to render to render the image to
The top left corner of the location in the DC to render to
The top left corner of the location in the DC to render to
The height and width of the area of the DC to render to.
The height and width of the area of the DC to render to.
Description
Render to a Device Context
Syntax
Visual Basic
Public Sub RenderToDC( _
   ByVal hDC As Integer, _
   ByVal x As Long, _
   ByVal y As Long, _
   ByVal cx As Long, _
   ByVal cy As Long _
)
Parameters
hDC
The Device Context to render to render the image to
x
The top left corner of the location in the DC to render to
y
The top left corner of the location in the DC to render to
cx
The height and width of the area of the DC to render to.
cy
The height and width of the area of the DC to render to.
Remarks
See PictureWithLut for more details of how the LUT is constructed and used.
See Also

DicomImage Object | DicomImage Members


RenderToDCWithLUT Method

RenderToDCWithLUT Method
DicomObjects Reference > DicomImage Object : RenderToDCWithLUT Method
The Device Context to render to render the image to
The top left corner of the location in the DC to render to
The top left corner of the location in the DC to render to
The height and width of the area of the DC to render to.
The height and width of the area of the DC to render to.
Lookup table to apply to the DICOM data before rendering.
Description
Render to a Device Context
Syntax
Visual Basic
Public Sub RenderToDCWithLUT( _
   ByVal hDC As Integer, _
   ByVal x As Long, _
   ByVal y As Long, _
   ByVal cx As Long, _
   ByVal cy As Long, _
   ByVal LUT As Variant _
)
Parameters
hDC
The Device Context to render to render the image to
x
The top left corner of the location in the DC to render to
y
The top left corner of the location in the DC to render to
cx
The height and width of the area of the DC to render to.
cy
The height and width of the area of the DC to render to.
LUT
Lookup table to apply to the DICOM data before rendering.
Remarks
See PictureWithLut for more details of how the LUT is constructed and used.
See Also

DicomImage Object | DicomImage Members


Send Method

Send Method
DicomObjects Reference > DicomImage Object : Send Method
Network address (as dotted notation or resolvable name) to which the image is to be sent.
Port on which remote application is listening.
Name of remote Application Entity.
Name to quote for this Application Entity.
Description
Sends an Image to a remote DICOM application
Syntax
Visual Basic
Public Function Send( _
   ByVal Node As String, _
   ByVal Port As Integer, _
   ByVal CallingAE As String, _
   ByVal CalledAE As String _
) As Long
Parameters
Node
Network address (as dotted notation or resolvable name) to which the image is to be sent.
Port
Port on which remote application is listening.
CallingAE
Name of remote Application Entity.
CalledAE
Name to quote for this Application Entity.
Return Type

Long

The status as returned by the remote application. Zero indicates success.

Remarks
This method negotiates an association, sends one image/dataset over it, and then closes it. DICOM does not allow SCPs to draw any conclusions about the relationships between images based on the opening and closing of associations, so this should never be a problem (apart from slight network inefficiency). However, there are several badly written applications in the world, which incorrectly assume that the end of an association indicates the end of a series or a study etc., and if interfacing to such a faulty implementation, it is possible to send multiple images on one association by using a DicomConnection object, and its SendImages method.
See Also

DicomImage Object | DicomImage Members


SetDefaultWindows Method

SetDefaultWindows Method
DicomObjects Reference > DicomImage Object : SetDefaultWindows Method
Description
Resets Width and Level back to their initial values
Syntax
Visual Basic
Public Sub SetDefaultWindows()
Remarks
Where possible, DicomObjects sets the initial values of Width and Level using attributes 0028,1050 & 0028,1051 in the file itself, but where these are not present, it calculates the values by measuring the range of pixel values. The values may of course be subsequently changed, and this method is therefore useful either to reset to initial values, or to calculate suitable “guess” values when new images are created, or when the pixel data itself is changed.
See Also

DicomImage Object | DicomImage Members


SetPixelFile Method

SetPixelFile Method
DicomObjects Reference > DicomImage Object : SetPixelFile Method
The file containing the uncompressed or compressed image data
The offset in the file of the start of the first frame in that file
The offset in the file between the start of one frame, and the start of the next
Description
Maps pixel data onto a file
Syntax
Visual Basic
Public Sub SetPixelFile( _
   ByVal FileName As String, _
   ByVal InitialOffset As Long, _
   ByVal FrameOffset As Long _
)
Parameters
FileName
The file containing the uncompressed or compressed image data
InitialOffset
The offset in the file of the start of the first frame in that file
FrameOffset
The offset in the file between the start of one frame, and the start of the next
Remarks

These methods do not, in themselves, cause the data to be read, but a mapping is set up, such that when the pixel data for a frame is required for display, compression, transmission etc., then it is read as needed. This is therefore useful for the conversion of long cine sequences to DICOM, as only one frame at a time is held in memory.
SetPixelFileExt uses a double instead of a long integer for the offset, allowing use of data segments within massive (>2 GByte) files. Although use of a floating point value is unusual for this type of application, double precision values can hold integers accurately to 48 bits (allowing files up to 256 TBytes!)

SetPixelFiles uses one file for each frame – all starting at the same offset (normally 0) within each file.
For all versions except SetPixelFileCompressed, the pixel data must be uncompressed in a format which matches the bits allocated specified in the DICOM data.
The number of frames is set, as usual, by element (0028,0008), which should be set before invoking these methods.

See Also

DicomImage Object | DicomImage Members


SetPixelFileCompressed Method

SetPixelFileCompressed Method
DicomObjects Reference > DicomImage Object : SetPixelFileCompressed Method
The file containing the uncompressed or compressed image data
The offset in the file of the start of the first frame in that file
UID of the transfer syntax for compressed data
Description
Sets a Pixel file - with compressed data
Syntax
Visual Basic
Public Sub SetPixelFileCompressed( _
   ByVal FileName As String, _
   ByVal InitialOffset As Double, _
   ByVal TransferSyntax As String _
)
Parameters
FileName
The file containing the uncompressed or compressed image data
InitialOffset
The offset in the file of the start of the first frame in that file
TransferSyntax
UID of the transfer syntax for compressed data
Remarks

These methods do not, in themselves, cause the data to be read, but a mapping is set up, such that when the pixel data for a frame is required for display, compression, transmission etc., then it is read as needed. This is therefore useful for the conversion of long cine sequences to DICOM, as only one frame at a time is held in memory.
SetPixelFileExt uses a double instead of a long integer for the offset, allowing use of data segments within massive (>2 GByte) files. Although use of a floating point value is unusual for this type of application, double precision values can hold integers accurately to 48 bits (allowing files up to 256 TBytes!)

SetPixelFiles uses one file for each frame – all starting at the same offset (normally 0) within each file.
For all versions except SetPixelFileCompressed, the pixel data must be uncompressed in a format which matches the bits allocated specified in the DICOM data.
The number of frames is set, as usual, by element (0028,0008), which should be set before invoking these methods.

See Also

DicomImage Object | DicomImage Members


SetPixelFileExt Method

SetPixelFileExt Method
DicomObjects Reference > DicomImage Object : SetPixelFileExt Method
The file containing the uncompressed or compressed image data
The offset in the file of the start of the first frame in that file
The offset in the file between the start of one frame, and the start of the next
Description
Sets a Pixel file - allowing offset > 4 Gig
Syntax
Visual Basic
Public Sub SetPixelFileExt( _
   ByVal FileName As String, _
   ByVal InitialOffset As Double, _
   ByVal FrameOffset As Long _
)
Parameters
FileName
The file containing the uncompressed or compressed image data
InitialOffset
The offset in the file of the start of the first frame in that file
FrameOffset
The offset in the file between the start of one frame, and the start of the next
Remarks

These methods do not, in themselves, cause the data to be read, but a mapping is set up, such that when the pixel data for a frame is required for display, compression, transmission etc., then it is read as needed. This is therefore useful for the conversion of long cine sequences to DICOM, as only one frame at a time is held in memory.
SetPixelFileExt uses a double instead of a long integer for the offset, allowing use of data segments within massive (>2 GByte) files. Although use of a floating point value is unusual for this type of application, double precision values can hold integers accurately to 48 bits (allowing files up to 256 TBytes!)

SetPixelFiles uses one file for each frame – all starting at the same offset (normally 0) within each file.
For all versions except SetPixelFileCompressed, the pixel data must be uncompressed in a format which matches the bits allocated specified in the DICOM data.
The number of frames is set, as usual, by element (0028,0008), which should be set before invoking these methods.

See Also

DicomImage Object | DicomImage Members


SetPixelFiles Method

SetPixelFiles Method
DicomObjects Reference > DicomImage Object : SetPixelFiles Method
The files containing the uncompressed image data
The offset in the file of the start of the first frame in that file
Description
Maps pixel data onto a file
Syntax
Visual Basic
Public Sub SetPixelFiles( _
   ByVal Filenames As Variant, _
   ByVal Offset As Long _
)
Parameters
Filenames
The files containing the uncompressed image data
Offset
The offset in the file of the start of the first frame in that file
Remarks

These methods do not, in themselves, cause the data to be read, but a mapping is set up, such that when the pixel data for a frame is required for display, compression, transmission etc., then it is read as needed. This is therefore useful for the conversion of long cine sequences to DICOM, as only one frame at a time is held in memory.
SetPixelFileExt uses a double instead of a long integer for the offset, allowing use of data segments within massive (>2 GByte) files. Although use of a floating point value is unusual for this type of application, double precision values can hold integers accurately to 48 bits (allowing files up to 256 TBytes!)

SetPixelFiles uses one file for each frame – all starting at the same offset (normally 0) within each file.
For all versions except SetPixelFileCompressed, the pixel data must be uncompressed in a format which matches the bits allocated specified in the DICOM data.
The number of frames is set, as usual, by element (0028,0008), which should be set before invoking these methods.

See Also

DicomImage Object | DicomImage Members


SubImage Method

SubImage Method
DicomObjects Reference > DicomImage Object : SubImage Method
Top left corner of original image to use
Top left corner of original image to use
Size of final image
Size of final image
Magnification to apply before cropping to size given by XSize and YSize
The Frame to copy
Description
Creates a copy of part or all of the image with controlled size
Syntax
Visual Basic
Public Function SubImage( _
   ByVal XOffset As Long, _
   ByVal YOffset As Long, _
   ByVal XSize As Long, _
   ByVal YSize As Long, _
   ByVal Magnification As Single, _
   ByVal Frame As Long _
) As DicomImage
Parameters
XOffset
Top left corner of original image to use
YOffset
Top left corner of original image to use
XSize
Size of final image
YSize
Size of final image
Magnification
Magnification to apply before cropping to size given by XSize and YSize
Frame
The Frame to copy
Remarks

Makes a derived image (of same basic DICOM type as the original) scaled and cropped as required. Unlike PrinterImage, the pixel data is not modified or scaled, and XSize and YSize refer to the final image size, not the input (useful for making fixed size thumbnails etc.)

If the original image is flipped and/or rotated, then the SubImage will be similarly modified, and the coordinates used for the offsets and sizes apply in the rotated/flipped coordinate space. This makes it simple to select sub-images using a GUI, as the coordinates used for SubImage are compatible with those used for an DicomLabel with ScaleMode set to Image.

See Also

DicomImage Object | DicomImage Members


WriteArray Method

WriteArray Method
DicomObjects Reference > DicomImage Object : WriteArray Method
If TRUE, a blank 128 byte header, DICM marker, and meta-header are written at the start of the file, and an appropriate transfer syntax is used, as below.
If FALSE, the file is written in the unofficial, but common format, with no header, and using the little-endian implicit VR transfer syntax.
Specifies the full UID of the transfer syntax with which the file is to be saved when Part 10 format is used. If omitted, the little-endian explicit VR transfer syntax is used. For details of the currently supported syntaxes, see the conformance entry.
The quality factor to be used.
Description
Writes object into a byte array (analogous to WriteFile)
Syntax
Visual Basic
Public Function WriteArray( _
   ByVal isPart10 As Boolean, _
   Optional ByVal TransferSyntax As Variant, _
   Optional ByVal Quality As Variant _
) As Variant
Parameters
isPart10
If TRUE, a blank 128 byte header, DICM marker, and meta-header are written at the start of the file, and an appropriate transfer syntax is used, as below.
If FALSE, the file is written in the unofficial, but common format, with no header, and using the little-endian implicit VR transfer syntax.
TransferSyntax
Specifies the full UID of the transfer syntax with which the file is to be saved when Part 10 format is used. If omitted, the little-endian explicit VR transfer syntax is used. For details of the currently supported syntaxes, see the conformance entry.
Quality
The quality factor to be used.
Remarks
Quality is specific to the compression method being used, and is ignored for non-compressed or lossless JPEG transfer syntaxes. For Lossy JPEG, it is an integer in the range 1-100, the higher the number, the better the quality (and the larger the file) , and for JPEG 2000 lossy, it is a compression ratio. Other compression methods may use this for other purposes in the future.
Data may be read back by the corresponding ReadArray method.
See Also

DicomImage Object | DicomImage Members


WriteField Method

WriteField Method
DicomObjects Reference > DicomImage Object : WriteField Method

The field into which the image or dataset is to be Written.
This must be from the list of supported interfaces below, and must be of a type capable of holding binary objects. In Microsoft Access, this would be either an OLE or Memo field. The supported object types are:

Object Category | Version | Object Type
ActiveX Data Objects ADO | >=1.5 | Field
Data Access Objects DAO | 3.0 or 3.5 | Field
Remote Data Objects RDO | 2.0 | Column

If TRUE, a blank 128 byte header, DICM marker, and meta-header are written at the start of the field.
If FALSE, the field is written in the unofficial, but common format, with no header, and using the little-endian implicit VR transfer syntax.
Specifies the full UID of the transfer syntax used when Part 10 format is specified. If omitted, the little-endian explicit VR transfer syntax is used. For details of the currently supported syntaxes, see the conformance entry.
The quality factor to be used.
Description
Writes a DICOM image into a database field
Syntax
Visual Basic
Public Sub WriteField( _
   ByVal Field As Object, _
   ByVal isPart10 As Boolean, _
   Optional ByVal TransferSyntax As Variant, _
   Optional ByVal Quality As Variant _
)
Parameters
Field

The field into which the image or dataset is to be Written.
This must be from the list of supported interfaces below, and must be of a type capable of holding binary objects. In Microsoft Access, this would be either an OLE or Memo field. The supported object types are:

Object Category | Version | Object Type
ActiveX Data Objects ADO | >=1.5 | Field
Data Access Objects DAO | 3.0 or 3.5 | Field
Remote Data Objects RDO | 2.0 | Column

isPart10
If TRUE, a blank 128 byte header, DICM marker, and meta-header are written at the start of the field.
If FALSE, the field is written in the unofficial, but common format, with no header, and using the little-endian implicit VR transfer syntax.
TransferSyntax
Specifies the full UID of the transfer syntax used when Part 10 format is specified. If omitted, the little-endian explicit VR transfer syntax is used. For details of the currently supported syntaxes, see the conformance entry.
Quality
The quality factor to be used.
Remarks

The field would normally be read by the ReadField method, but may be copied from the field to an external file.
Quality is specific to the compression method being used, and is ignored for non-compressed or lossless JPEG transfer syntaxes. For Lossy JPEG, it is an integer in the range 1-100, the higher the number, the better the quality (and the larger the file) , and for JPEG 2000 lossy, it is a compression ratio. Other compression methods may use this for other purposes in the future.

This method has been provided to allow development of a DICOM servers using Microsoft tools such as Access and SQL server, which have limited facilities for the handling of Binary Large Objects (BLOBs).
Note:
Whilst this method is useful for simple demonstrations and small projects, most database servers do not handle large BLOBs well when stored within the main database, and in a “production” environment, storage in simple files is strongly advised (with storage of just the filename within the database).

See Also

DicomImage Object | DicomImage Members


WriteFile Method

WriteFile Method
DicomObjects Reference > DicomImage Object : WriteFile Method
The name of the file to write.
This is passed unmodified to the operating system, and it is therefore the container’s responsibility to ensure either that the current directory is set correctly, or that a fully qualified filename is provided.
If TRUE, a blank 128 byte header, DICM marker, and meta-header are written at the start of the file, and an appropriate transfer syntax is used, as below.
If FALSE, the file is written in the unofficial, but common format, with no header, and using the little-endian implicit VR transfer syntax.
Specifies the full UID of the transfer syntax with which the file is to be saved when Part 10 format is used. If omitted, the little-endian explicit VR transfer syntax is used. For details of the currently supported syntaxes, see the conformance entry.
The quality factor to be used.
Description
Writes an image to an external DICOM file
Syntax
Visual Basic
Public Sub WriteFile( _
   ByVal FileName As String, _
   ByVal isPart10 As Boolean, _
   Optional ByVal TransferSyntax As Variant, _
   Optional ByVal Quality As Variant _
)
Parameters
FileName
The name of the file to write.
This is passed unmodified to the operating system, and it is therefore the container’s responsibility to ensure either that the current directory is set correctly, or that a fully qualified filename is provided.
isPart10
If TRUE, a blank 128 byte header, DICM marker, and meta-header are written at the start of the file, and an appropriate transfer syntax is used, as below.
If FALSE, the file is written in the unofficial, but common format, with no header, and using the little-endian implicit VR transfer syntax.
TransferSyntax
Specifies the full UID of the transfer syntax with which the file is to be saved when Part 10 format is used. If omitted, the little-endian explicit VR transfer syntax is used. For details of the currently supported syntaxes, see the conformance entry.
Quality
The quality factor to be used.
Remarks

The file may subsequently be read by the ReadFile method or by other DICOM software.
Quality is specific to the compression method being used, and is ignored for non-compressed or lossless JPEG transfer syntaxes. For Lossy JPEG, it is an integer in the range 1-100, the higher the number, the better the quality (and the larger the file), and for JPEG 2000 lossy, it is a compression ratio. Other compression methods may use this for other purposes in the future.
For writing the “DICOMDIR” directory file on exchangeable media, the WriteDirectory method should be used instead.

See the security page for details of restrictions on this method.

See Also

DicomImage Object | DicomImage Members


WriteMemory Method

WriteMemory Method
DicomObjects Reference > DicomImage Object : WriteMemory Method
This must be the handle to a global block of memory, or may be NULL to find the length required
The length of the memory block (i.e. available space for the data), or 0 to find the length required
If TRUE, a blank 128 byte header, DICM marker, and meta-header are written at the start of the data, and an appropriate transfer syntax is used, as below.
If FALSE, the data is written in the unofficial, but common format, with no header, and using the little-endian implicit VR transfer syntax.
Specifies the full UID of the transfer syntax with which the data is to be saved when Part 10 format is used. If omitted, the little-endian explicit VR transfer syntax is used. For details of the currently supported syntaxes, see the conformance entry.
The quality factor to be used.
Description
Writes data to a global memory block
Syntax
Visual Basic
Public Function WriteMemory( _
   ByVal Handle As Integer, _
   ByVal Length As Long, _
   ByVal isPart10 As Boolean, _
   Optional ByVal TransferSyntax As Variant, _
   Optional ByVal Quality As Variant _
) As Long
Parameters
Handle
This must be the handle to a global block of memory, or may be NULL to find the length required
Length
The length of the memory block (i.e. available space for the data), or 0 to find the length required
isPart10
If TRUE, a blank 128 byte header, DICM marker, and meta-header are written at the start of the data, and an appropriate transfer syntax is used, as below.
If FALSE, the data is written in the unofficial, but common format, with no header, and using the little-endian implicit VR transfer syntax.
TransferSyntax
Specifies the full UID of the transfer syntax with which the data is to be saved when Part 10 format is used. If omitted, the little-endian explicit VR transfer syntax is used. For details of the currently supported syntaxes, see the conformance entry.
Quality
The quality factor to be used.
Remarks
The data may subsequently be read by the ReadMemory method or by other DICOM software.
If either Handle is NULL, or Length is 0, then no data is written, but the length is still calculated (applying compression if necessary), so that a suitable memory block may be allocated.
If the length available is not enough for the data to be written, an error is thrown.
Quality is specific to the compression method being used, and is ignored for non-compressed or lossless JPEG transfer syntaxes. For Lossy JPEG, it is an integer in the range 1-100, the higher the number, the better the quality (and the larger the data). Other compression methods may use this for other purposes in the future.
See Also

DicomImage Object | DicomImage Members


WriteStream Method

WriteStream Method
DicomObjects Reference > DicomImage Object : WriteStream Method
The name of the stream object to write to.
Although this object must support an IStream interface, this is retrieved via a QueryInterface call, and any interface to the object may therefore be passed.
If TRUE, a blank 128 byte header, DICM marker, and meta-header are written at the start of the stream, and an appropriate transfer syntax is used, as below.
If FALSE, the stream is written in the unofficial, but common format, with no header, and using the little-endian implicit VR transfer syntax.
Specifies the full UID of the transfer syntax with which the data is to be saved when Part 10 format is used. If omitted, the little-endian explicit VR transfer syntax is used.
The quality factor to be used.
Description
Writes an image to an IStream
Syntax
Visual Basic
Public Sub WriteStream( _
   ByVal Stream As Unknown, _
   ByVal isPart10 As Boolean, _
   Optional ByVal TransferSyntax As Variant, _
   Optional ByVal Quality As Variant _
)
Parameters
Stream
The name of the stream object to write to.
Although this object must support an IStream interface, this is retrieved via a QueryInterface call, and any interface to the object may therefore be passed.
isPart10
If TRUE, a blank 128 byte header, DICM marker, and meta-header are written at the start of the stream, and an appropriate transfer syntax is used, as below.
If FALSE, the stream is written in the unofficial, but common format, with no header, and using the little-endian implicit VR transfer syntax.
TransferSyntax
Specifies the full UID of the transfer syntax with which the data is to be saved when Part 10 format is used. If omitted, the little-endian explicit VR transfer syntax is used.
Quality
The quality factor to be used.
Remarks

The file may subsequently be read by the ReadStream method or by other DICOM software.
Quality is specific to the compression method being used, and is ignored for non-compressed or lossless JPEG transfer syntaxes. For Lossy JPEG, it is an integer in the range 1-100, the higher the number, the better the quality (and the larger the file) , and for JPEG 2000 lossy, it is a compression ratio. Other compression methods may use this for other purposes in the future.

This method is particularly suitable for use with Delphi, which provides access to streams via classes such as TStreamAdapter.

See Also

DicomImage Object | DicomImage Members


AccessionNumber Property

AccessionNumber Property
DicomObjects Reference > DicomImage Object : AccessionNumber Property
Description
Accession Number
Property type
Read-write property
Syntax
Visual Basic
Public Property AccessionNumber As String
Remarks
This is a shortcut for the Accession Number (0008,0060)
See Also

DicomImage Object | DicomImage Members


ActualScrollX Property

ActualScrollX Property
DicomObjects Reference > DicomImage Object : ActualScrollX Property
Description
Actual image offset (X) used for display
Property type
Read-only property
Syntax
Visual Basic
Public Property ActualScrollX As Single
Remarks
If StretchedCentred is set, and PresentationState is not in use, then these properties are exactly equivalent to Zoom, ScrollX & ScrollY. If the values are over-ridden by StretchToFit or a presentation state, then these properties provide equivalent information, which may of use in locating points in an image. Normally however, ImageIndex, ImageXPosition & ImageYPosition are easier to use.
See Also

DicomImage Object | DicomImage Members


ActualScrollY Property

ActualScrollY Property
DicomObjects Reference > DicomImage Object : ActualScrollY Property
Description
Actual image offset (Y) used for display
Property type
Read-only property
Syntax
Visual Basic
Public Property ActualScrollY As Single
Remarks
If StretchedCentred is set, and PresentationState is not in use, then these properties are exactly equivalent to Zoom, ScrollX & ScrollY. If the values are over-ridden by StretchToFit or a presentation state, then these properties provide equivalent information, which may of use in locating points in an image. Normally however, ImageIndex, ImageXPosition & ImageYPosition are easier to use.
See Also

DicomImage Object | DicomImage Members


ActualZoom Property

ActualZoom Property
DicomObjects Reference > DicomImage Object : ActualZoom Property
Description
Actual Zoom used for display
Property type
Read-only property
Syntax
Visual Basic
Public Property ActualZoom As Single
Remarks
If StretchedCentred is set, and PresentationState is not in use, then these properties are exactly equivalent to Zoom, ScrollX & ScrollY. If the values are over-ridden by StretchToFit or a presentation state, then these properties provide equivalent information, which may of use in locating points in an image. Normally however, ImageIndex, ImageXPosition & ImageYPosition are easier to use.
See Also

DicomImage Object | DicomImage Members


Angle Property

Angle Property
DicomObjects Reference > DicomImage Object : Angle Property
Description
Angle of rotation
Property type
Read-write property
Syntax
Visual Basic
Public Property Angle As Single
Remarks

If set to anything other than 0, then MagnificationMode and MinificationMode are handled internally as if the FilterMode was set to doFilterGpu.

The angle is measured in degrees, and clockwise

As for all other display features, the Scroll values continue to work in screen units and relative to the screen axes, and hence are applied after rotation

See Also

DicomImage Object | DicomImage Members


Attributes Property

Attributes Property
DicomObjects Reference > DicomImage Object : Attributes Property
Description
The Collection of Attributes comprising this image
Property type
Read-only property
Syntax
Visual Basic
Public Property Attributes As DicomAttributes
Remarks
This property provides access to the collection of Attributes that comprise a DicomImage or DicomDataSet.
See Also

DicomImage Object | DicomImage Members


BorderColour Property

BorderColour Property
DicomObjects Reference > DicomImage Object : BorderColour Property
Description
Colour of the border around an image
Property type
Read-write property
Syntax
Visual Basic
Public Property BorderColour As ULong
Remarks

Together with BorderWidth, this determines the display of a border placed around an image.

As is standard for colour properties, the value may be represented as 00RRGGBB hex, and in most client languages, appropriate symbolic constants may be used, e.g. vbRed, vbWhite etc. in Visual Basic.

The initial value for the property is FFFFFFh, giving white.

See Also

DicomImage Object | DicomImage Members


BorderStyle Property

BorderStyle Property
DicomObjects Reference > DicomImage Object : BorderStyle Property
Description
The style used to draw the image border
Property type
Read-write property
Syntax
Visual Basic
Public Property BorderStyle As Integer
See Also

DicomImage Object | DicomImage Members


BorderWidth Property

BorderWidth Property
DicomObjects Reference > DicomImage Object : BorderWidth Property
Description
Width of the border around an image
Property type
Read-write property
Syntax
Visual Basic
Public Property BorderWidth As Integer
Remarks
Together with BorderColour, this determines the display of a border placed around an image.
The initial value of this property is always 0, causing no border to be drawn.
The border normally overlaps and obscures the outer edge of the image, but if the associated DicomViewer has a CellSpacing property >0, then as much as possible of the border will be displayed in this region.
See Also

DicomImage Object | DicomImage Members


Bottom Property

Bottom Property
DicomObjects Reference > DicomImage Object : Bottom Property
Description
Controls the display position of an image
Property type
Read-write property
Syntax
Visual Basic
Public Property Bottom As Integer
Remarks

Normally, if these 4 properties all have their default value of 0, the images within a DicomViewer’ Images collection are displayed in a fixed grid arrangement, controlled by the viewer’s MultiRows, MultiColumns and CurrentIndex properties. If however, any of these properties are set non-zero, then the default behaviour is over-ridden, and the image is displayed in a “cell” defined by these properties (coordinates are relative to the viewer’s top-left corner). All other properties such as StretchedCentred etc. operate exactly as normal, but within this different cell.

One common use for these properties is to create an efficient “magnifying glass”, as it is easy to add a second copy of an image to a viewer’s Images collection, then alter it’s zoom, and positioning properties as the mouse moves, to implement the magnifier. The re-display is optimised for this purpose, and when these properties are changed, then only the affected area is redrawn (quickly). Therefore use of the viewer’s Refresh method is not only unnecessary, but it actually slows the application.

See Also

DicomImage Object | DicomImage Members


CacheDecompressed Property

CacheDecompressed Property
DicomObjects Reference > DicomImage Object : CacheDecompressed Property
Description
Controls caching of decompressed images
Property type
Read-write property
Syntax
Visual Basic
Public Property CacheDecompressed As Boolean
Remarks
Means of enabling/disabling cache mode of decompressed images
See Also

DicomImage Object | DicomImage Members


CacheDisplay Property

CacheDisplay Property
DicomObjects Reference > DicomImage Object : CacheDisplay Property
Description
Controls whether displayed images are Cached
Property type
Read-write property
Syntax
Visual Basic
Public Property CacheDisplay As Boolean
Remarks
Default value is true
If true, then the final form of the image pixel data for each frame is cached after windowing sizing etc., in exactly the form needed for transfer to the screen.
This property may be useful when it is necessary to speed the display of multi-frame images such as cardiac angiography, but if runs are long, then the memory used can be large, and memory paging may have a paradoxical negative effect.
See Also

DicomImage Object | DicomImage Members


CineMode Property

CineMode Property
DicomObjects Reference > DicomImage Object : CineMode Property
Description
Controls auto-run mode for multi-frame images
Property type
Read-write property
Syntax
Visual Basic
Public Property CineMode As doCineMode
Remarks

There are 6 available modes.

The rate is determined by the true rate as given in the image itself, and the CineRate property.

Applications wishing to update items such as frame counters should use the OnFrameChanging event.

See Also

DicomImage Object | DicomImage Members


CineRate Property

CineRate Property
DicomObjects Reference > DicomImage Object : CineRate Property
Description
Controls auto-run rate for of multi-frame images
Property type
Read-write property
Syntax
Visual Basic
Public Property CineRate As Single
Remarks
The “true” rate as determined from the attributes of the image is multiplied by this value to give the rate at which frames are to be displayed. It is not used when CineMode has the default value of doCineStatic.
The default value is 1.0
See Also

DicomImage Object | DicomImage Members


ColourTable Property

ColourTable Property
DicomObjects Reference > DicomImage Object : ColourTable Property
Description
Colour table for application of pseudo-colour to monochrome images
Property type
Read-write property
Syntax
Visual Basic
Public Property ColourTable As Variant
Remarks

This array is used as a final lookup when the images is being rendered for any purpose. The 2nd dimension of the array may be any size, and may have any maximum value (up to 64k), as both input and output are scaled to fit the required ranges.

The data range (after windowing etc.) is divided into N ranges (N=number of elements defined by 2nd dimension), and each is assigned a colour dependent on the 3 corresponding elements in this array = 1=Red, 2=Green, 3=Blue.

As a result, this may be used to apply “false-colour” to an image.

To clear the lookup, this property may be set to a null variant.

If this property is not null, then when the image is displayed in a DicomViewer the viewer’s CalibrationCurve lookup table is not used.

See Also

DicomImage Object | DicomImage Members


Command Property

Command Property
DicomObjects Reference > DicomImage Object : Command Property
Description
The full request dataset received
Property type
Read-only property
Syntax
Visual Basic
Public Property Command As DicomDataSet
Remarks

For data received via network transfer, this property gives access to the command (group 0000) DataSet, and for those read from Part 10 format files, it gives access to the Meta-header (group 0002) DatsSet.

Note that writing to this group does not affect the data subsequently written to disk.

See Also

DicomImage Object | DicomImage Members


CompressionInfo Property

CompressionInfo Property
DicomObjects Reference > DicomImage Object : CompressionInfo Property
Description
Information about how an image was compressed when received or read.
Property type
Read-write property
Syntax
Visual Basic
Public Property CompressionInfo As String
See Also

DicomImage Object | DicomImage Members


CubicSplineAlpha Property

CubicSplineAlpha Property
DicomObjects Reference > DicomImage Object : CubicSplineAlpha Property
Description
Controls images sharpness when magnifiaction mode is doCubicSpline
Property type
Read-write property
Syntax
Visual Basic
Public Property CubicSplineAlpha As Single
Remarks

These properties control how DicomObjects handles magnification and minification of images, either for display or other uses such as PrinterImage. Separate properties are used depending on whether the ActualZoom
of the image is <1 (MinificationMode) or >1 (MagnificationMode), allowing developers to select both, without needing to change when the image size changes.

There are few doFilterMode enumerations (used for Magnification and MinificationMode)

See Also

DicomImage Object | DicomImage Members


DateOfBirth Property

DateOfBirth Property
DicomObjects Reference > DicomImage Object : DateOfBirth Property
Description
The patient's date of birth (as a Variant)
Property type
Read-write property
Syntax
Visual Basic
Public Property DateOfBirth As Variant
Return Type
Variant
Remarks

This really just a shortcut for attribute (0010,0030).

DateOfBirth is presented as a Variant rather than a Date, in order to accommodate null dates without error - for a Date form see DateOfBirthAsDate Property

See Also

DicomImage Object | DicomImage Members | DateOfBirthAsDate Property


DateOfBirthAsDate Property

DateOfBirthAsDate Property
DicomObjects Reference > DicomImage Object : DateOfBirthAsDate Property
Description
The patient's date of birth (as DATE)
Property type
Read-write property
Syntax
Visual Basic
Public Property DateOfBirthAsDate As Date
Return Type
Date
Remarks

This really just a shortcut for attribute (0010,0030), but converted from a variant to a Date, unlike DateOfBirth Property which returns a Variant.

See Also

DicomImage Object | DicomImage Members


DownScale Property

DownScale Property
DicomObjects Reference > DicomImage Object : DownScale Property
Description
Downsample display for increased speed
Property type
Read-write property
Syntax
Visual Basic
Public Property DownScale As Single
See Also

DicomImage Object | DicomImage Members


FilterLength Property

FilterLength Property
DicomObjects Reference > DicomImage Object : FilterLength Property
Description
Controls averaging length when minifcation mode is doFilterMovingAverage
Property type
Read-write property
Syntax
Visual Basic
Public Property FilterLength As Integer
Remarks

These properties control how DicomObjects handles magnification and minification of images, either for display or other uses such as PrinterImage. Separate properties are used depending on whether the ActualZoom
of the image is <1 (MinificationMode) or >1 (MagnificationMode), allowing developers to select both, without needing to change when the image size changes.

There are few doFilterMode enumerations (used for Magnification and MinificationMode)

See Also

DicomImage Object | DicomImage Members


FlipState Property

FlipState Property
DicomObjects Reference > DicomImage Object : FlipState Property
Description
Controls horizontal & vertical flipping of the image
Property type
Read-write property
Syntax
Visual Basic
Public Property FlipState As doFlipState
Remarks
See the DicomImageFlipState Enumeration for more details.
See Also

DicomImage Object | DicomImage Members


Frame Property

Frame Property
DicomObjects Reference > DicomImage Object : Frame Property
Description
Controls which frame of a multi-frame image is displayed
Property type
Read-write property
Syntax
Visual Basic
Public Property Frame As Integer
Remarks

Like all indices in DicomObjects, this is 1-based - i.e. the range is from 1 to FrameCount.
If set to a value higher than FrameCount, this property is reduced modulo FrameCount, to bring it within range. Cine sequences may therefore be run repeatedly simply by incrementing Frame continuously. Alternatively, to allow multi-frame images to “play” autonomously, the CineMode property may be used.

Frame only returns sensible values for images up to 32k frames – for larger images use LongFrame.

See Also

DicomImage Object | DicomImage Members


FrameCount Property

FrameCount Property
DicomObjects Reference > DicomImage Object : FrameCount Property
Description
The number of frames contained in a multi-frame image
Property type
Read-only property
Syntax
Visual Basic
Public Property FrameCount As Integer
Remarks
The actual frame displayed is controlled by the image’s Frame property.
If the image does not contain a frame count, a value of 1 is returned.
FrameCount only returns sensible values for images up to 32k frames – for larger images use LongFrameCount.
See Also

DicomImage Object | DicomImage Members


IncludedInImageIndex Property

IncludedInImageIndex Property
DicomObjects Reference > DicomImage Object : IncludedInImageIndex Property
Description
Indicates whether this Image should be included for DicomViewer.ImageIndex method
Property type
Read-write property
Syntax
Visual Basic
Public Property IncludedInImageIndex As Boolean
Remarks
The default value is true. If set to false, then this image will not be considered when the DicomViewer.ImageIndex value is calculated.
See Also

DicomImage Object | DicomImage Members


InstanceUID Property

InstanceUID Property
DicomObjects Reference > DicomImage Object : InstanceUID Property
Description
Unique Image identifier
Property type
Read-write property
Syntax
Visual Basic
Public Property InstanceUID As String
Remarks

This really just a shortcut for attribute (0010,0020).

See Also

DicomImage Object | DicomImage Members


JPEG Property

JPEG Property
DicomObjects Reference > DicomImage Object : JPEG Property
The quality factor to use, where 100 is best quality (but still with some loss of quality)
Description
Returns an array containing a JPEG byte stream corresponding to the image
Property type
Read-only property
Syntax
Visual Basic
Public Property JPEG( _
   ByVal Quality As Integer _
) As Variant
Parameters
Quality
The quality factor to use, where 100 is best quality (but still with some loss of quality)
See Also

DicomImage Object | DicomImage Members


Labels Property

Labels Property
DicomObjects Reference > DicomImage Object : Labels Property
Description
The collection of DicomLabels to display over this image
Property type
Read-only property
Syntax
Visual Basic
Public Property Labels As DicomLabels
Remarks
After changing the contents of this collection or any of the individual images, you must call Refresh Method to make the changes visible.
See Also

DicomImage Object | DicomImage Members


Left Property

Left Property
DicomObjects Reference > DicomImage Object : Left Property
Description
Controls the display position of an image
Property type
Read-write property
Syntax
Visual Basic
Public Property Left As Integer
Remarks

Normally, if these 4 properties all have their default value of 0, the images within a DicomViewer’ Images collection are displayed in a fixed grid arrangement, controlled by the viewer’s MultiRows, MultiColumns and CurrentIndex properties. If however, any of these properties are set non-zero, then the default behaviour is over-ridden, and the image is displayed in a “cell” defined by these properties (coordinates are relative to the viewer’s top-left corner). All other properties such as StretchedCentred etc. operate exactly as normal, but within this different cell.

One common use for these properties is to create an efficient “magnifying glass”, as it is easy to add a second copy of an image to a viewer’s Images collection, then alter it’s zoom, and positioning properties as the mouse moves, to implement the magnifier. The re-display is optimised for this purpose, and when these properties are changed, then only the affected area is redrawn (quickly). Therefore use of the viewer’s Refresh method is not only unnecessary, but it actually slows the application.

See Also

DicomImage Object | DicomImage Members


Level Property

Level Property
DicomObjects Reference > DicomImage Object : Level Property
Description
Controls the grey-scale mapping of a displayed image
Property type
Read-write property
Syntax
Visual Basic
Public Property Level As Single
Remarks

Width and Level control the grey-scale mapping from the original pixel data to the screen. Following the normal convention, the grey scale ranges from level-width/2 to level+width/2. Note that re-scale values present in some SOP classes are used for the purposes of this mapping, but the native data are not altered, and other operations such as obtaining the Pixels are unaffected.
Windowing using these values applies now also to colour (RGB, YBR & COLOR PALETTE images, which by default have Width=255 and Level=128)

These values are initialised from the suggested values in the DICOM data, if present, but if not present, then reasonable initial values are calculated from the pixel data itself.
These values are regarded as transitory, and therefore, when an image is written, they are not written back into the DICOM data. If this behaviour is required, then code similar to this should be included prior to the write:
Image.Attributes.Add(&h0028,&h1050),Image.Level
Image.Attributes.Add(&h0028,&h1051),Image.Width

Width and Level are ignored under the following circumstances:

  • When a PresentationState is applied to the image
  • When the image contains a “Values of Interest Lookup Table” (VOI LUT), as this takes the place of windowing

In the later case, the VOI LUT can be ignored (and width and level used), by setting the image’s VOILUT property to 0.

See Also

DicomImage Object | DicomImage Members


LevelShift Property

LevelShift Property
DicomObjects Reference > DicomImage Object : LevelShift Property
Description
Provides a means to modify the usage of a Values of Interest Lookup Table (VOI LUT) or other display mapping
Property type
Read-write property
Syntax
Visual Basic
Public Property LevelShift As Single
See Also

DicomImage Object | DicomImage Members


LongFrame Property

LongFrame Property
DicomObjects Reference > DicomImage Object : LongFrame Property
Description
Controls which frame of a multi-frame image is displayed
Property type
Read-write property
Syntax
Visual Basic
Public Property LongFrame As Long
Remarks

Like all indices in DicomObjects, this is 1-based - i.e. the range is from 1 to FrameCount.
If set to a value higher than LongFrameCount, this property is reduced modulo FrameCount, to bring it within range. Cine sequences may therefore be run repeatedly simply by incrementing Frame continuously. Alternatively, to allow multi-frame images to “play” autonomously, the CineMode property may be used.

This property is equivalent to the Frame Property, but allows much larger values.

See Also

DicomImage Object | DicomImage Members


LongFrameCount Property

LongFrameCount Property
DicomObjects Reference > DicomImage Object : LongFrameCount Property
Description
The number of frames contained in a multi-frame image
Property type
Read-only property
Syntax
Visual Basic
Public Property LongFrameCount As Long
Remarks
The actual frame displayed is controlled by the image’s Frame property.
If the image does not contain a frame count, a value of 1 is returned.
FrameCount only returns sensible values for images up to 32k frames – for larger images use LongFrameCount.
See Also

DicomImage Object | DicomImage Members


LookupTable Property

LookupTable Property
DicomObjects Reference > DicomImage Object : LookupTable Property
Minimum input value to use
Maximum input value to use
Whether to use the modality transform stage (rescale or LUT)
Whether to use the VOI transform stage (windowing or LUT)
Whether to use the presentation transform stage (inversion or LUT)
Whether you use any screen calibration as set by the viewer's CalibrationCurve Property
Description
Returns the lookup table used to convert pixel values to display or intermediate values
Property type
Read-only property
Syntax
Visual Basic
Public Property LookupTable( _
   ByVal Min As Long, _
   ByVal Max As Long, _
   ByVal Modality As Boolean, _
   ByVal VOI As Boolean, _
   ByVal presentation As Boolean, _
   ByVal Calibration As Boolean _
) As Variant
Parameters
Min
Minimum input value to use
Max
Maximum input value to use
Modality
Whether to use the modality transform stage (rescale or LUT)
VOI
Whether to use the VOI transform stage (windowing or LUT)
presentation
Whether to use the presentation transform stage (inversion or LUT)
Calibration
Whether you use any screen calibration as set by the viewer's CalibrationCurve Property
Remarks

This property enables developers to leverage the lookup tables used within DicomObjects when transforming pixel values into display values.

Use of each of the stages is conditional on that stage being enabled, and it is then used exactly as it would be internally by DicomObjects – e.g. a modality lookup table will not be used if ModalityLUT is false, even if it is present, and the first parameter to this method is true. Likewise, a false value for VOILUT can enable use of window width and level where they would otherwise be over-ridden by the LUT.

Although, in principle, the overall chain could be dissected into up to 4 discreet stages, this will not always produce exactly the same result as a single operation using all 4 stages due to:

  1. Rounding errors
  2. The fact that DICOM requires the output of one lookup table to be scaled implicitly to match the input to the next, so where there is a mis-match this cannot be catered for as separate stages.

It is much more efficient to access this once and use the resulting array repeatedly than to access it repeatedly with single value inputs.

See Also

DicomImage Object | DicomImage Members


LosslessCompressionMode Property

LosslessCompressionMode Property
DicomObjects Reference > DicomImage Object : LosslessCompressionMode Property
Description
Control of how to handle the old lossless compression bug
Property type
Read-write property
Syntax
Visual Basic
Public Property LosslessCompressionMode As Integer
See Also

DicomImage Object | DicomImage Members


LosslessDecompressionMode Property

LosslessDecompressionMode Property
DicomObjects Reference > DicomImage Object : LosslessDecompressionMode Property
Description
Control of how to handle the old lossless compression bug
Property type
Read-write property
Syntax
Visual Basic
Public Property LosslessDecompressionMode As Integer
See Also

DicomImage Object | DicomImage Members


MagnificationMode Property

MagnificationMode Property
DicomObjects Reference > DicomImage Object : MagnificationMode Property
Description
Controls interpolation mode when zoom is >1
Property type
Read-write property
Syntax
Visual Basic
Public Property MagnificationMode As doFilterMode
Remarks

These properties control how DicomObjects handles magnification and minification of images, either for display or other uses such as PrinterImage. Separate properties are used depending on whether the ActualZoom
of the image is <1 (MinificationMode) or >1 (MagnificationMode), allowing developers to select both, without needing to change when the image size changes.

There are few doFilterMode enumerations (used for Magnification and MinificationMode)

See Also

DicomImage Object | DicomImage Members


Mask Property

Mask Property
DicomObjects Reference > DicomImage Object : Mask Property
Description
Controls mask subtraction - see MaskFrame for number
Property type
Read-write property
Syntax
Visual Basic
Public Property Mask As Integer
Remarks

If non-zero, then mask subtraction may occur, as specified (in order of preference) by:

  • A Presentation State
  • The mask sequence (0028,6100) within the image
  • The MaskFrame property.

If 0, then no mask subtraction occurs, even if specified in one of these three ways.

The default value is 1 (allow subtraction if specified elsewhere)

Note: This property was previously incorrectly documented as specifying the frame to be subtracted (hence why it is an integer not a Boolean), but this was never implemented, and it has only ever functioned as a switch. To specify a frame directly, use the MaskFrame property.

See Also

DicomImage Object | DicomImage Members


MaskFraction Property

MaskFraction Property
DicomObjects Reference > DicomImage Object : MaskFraction Property
Description
Controls partial masking to show some original image landmarks
Property type
Read-write property
Syntax
Visual Basic
Public Property MaskFraction As Single
Remarks
The frame selected by MaskFrame is normally subtracted 100% from the chosen display frame (or all frames if a cine mode is in use) before display, leaving only the differences between the frames. By setting this value to slightly less than 1.0 it is possible to “leave” a little of the original image showing, which can make it easier to see bony landmarks etc.
See Also

DicomImage Object | DicomImage Members


MaskFrame Property

MaskFrame Property
DicomObjects Reference > DicomImage Object : MaskFrame Property
Description
Frame to use for masking if not defined in mask sequence or presentation state
Property type
Read-write property
Syntax
Visual Basic
Public Property MaskFrame As Long
Remarks

The selected frame is subtracted from the chosen display frame (or all frames if a cine mode is in use) before display, if no other method of subtraction is specified.
Normally, in DICOM subtraction is specified via the subtraction sequence (00028,6100) either within the image itself or it’s associated Presentation State. This method allows such features as frame averaging. If however, subtraction is activated using the Mask property, and no such sequence is present, then this property is used to specify a simple single-frame mask, which is subtracted from the chosen display frame (or all frames if a cine mode is in use) before display.

If 0, and the other methods are not used, then no subtraction occurs, irrespective of the Mask property.
The default value is 0.

Note This method of specifying the subtraction frame was previously, incorrectly, documented as the function of the Mask property, which is now used solely as a switch.

See Also

DicomImage Object | DicomImage Members


MaximumPixelValue Property

MaximumPixelValue Property
DicomObjects Reference > DicomImage Object : MaximumPixelValue Property
Whether to scale the values
Description
Maximum Pixel Value in the Image
Property type
Read-only property
Syntax
Visual Basic
Public Property MaximumPixelValue( _
   ByVal ScaleOrLUT As Boolean _
) As Long
Parameters
ScaleOrLUT
Whether to scale the values
Remarks

Many images have actual pixel values much smaller than the range suggested by their “bits stored” value, presenting difficulties for those needing to set suitable ranges for user controls related to the windowing parameters These properties indicate the highest and lowest values actually present, for this purpose. If ScaleOrLUT is false, then the native values in the pixel data are returned, but if ScaleOrLUT is true (and if rescale information or a modality LUT are present in the image), then the values are transformed through the modality lookup table or rescale operation, ensuring that the values are then compatible with windowing operations.

Pixels equal to the “Pixel Padding Value” (if specified in the image) are ignored for these calculations.

See Also

DicomImage Object | DicomImage Members


MinificationMode Property

MinificationMode Property
DicomObjects Reference > DicomImage Object : MinificationMode Property
Description
Controls interpolation mode when zoom is <1
Property type
Read-write property
Syntax
Visual Basic
Public Property MinificationMode As doFilterMode
Remarks

These properties control how DicomObjects handles magnification and minification of images, either for display or other uses such as PrinterImage. Separate properties are used depending on whether the ActualZoom
of the image is <1 (MinificationMode) or >1 (MagnificationMode), allowing developers to select both, without needing to change when the image size changes.

There are few doFilterMode enumerations (used for Magnification and MinificationMode)

See Also

DicomImage Object | DicomImage Members


MinimumPixelValue Property

MinimumPixelValue Property
DicomObjects Reference > DicomImage Object : MinimumPixelValue Property
Whether to scale the values
Description
Minimum Pixel Value in the Image
Property type
Read-only property
Syntax
Visual Basic
Public Property MinimumPixelValue( _
   ByVal ScaleOrLUT As Boolean _
) As Long
Parameters
ScaleOrLUT
Whether to scale the values
Remarks

Many images have actual pixel values much smaller than the range suggested by their “bits stored” value, presenting difficulties for those needing to set suitable ranges for user controls related to the windowing parameters These properties indicate the highest and lowest values actually present, for this purpose. If ScaleOrLUT is false, then the native values in the pixel data are returned, but if ScaleOrLUT is true (and if rescale information or a modality LUT are present in the image), then the values are transformed through the modality lookup table or rescale operation, ensuring that the values are then compatible with windowing operations.

Pixels equal to the “Pixel Padding Value” (if specified in the image) are ignored for these calculations.

See Also

DicomImage Object | DicomImage Members


ModalityLUT Property

ModalityLUT Property
DicomObjects Reference > DicomImage Object : ModalityLUT Property
Description
Selects which Modality LUT to apply (0 for none)
Property type
Read-write property
Syntax
Visual Basic
Public Property ModalityLUT As Integer
Remarks
DICOM allows multiple VOI and presentation Lookup Tables (LUTs) in images, and the user may select whichever they require. These properties provide that choice, and the value 0 may be used to disable a particular type of LUT. Only one Modality LUT is allowed, so the only meaningful values for ModalityLUT are 0 and 1, but the other two may range from 0 to the number of such LUTs in the image. Value beyond the available range are treated as 0.
The default values are all 1, indicating that the first table of each type, if present, should be used.
See Also

DicomImage Object | DicomImage Members


Mode Property

Mode Property
DicomObjects Reference > DicomImage Object : Mode Property
Description
Image display Mode
Property type
Read-write property
Syntax
Visual Basic
Public Property Mode As Integer
Remarks
This indicates whether an image is MPR, MIP, VR or 2D
See Also

DicomImage Object | DicomImage Members


Name Property

Name Property
DicomObjects Reference > DicomImage Object : Name Property
Description
The patient's Name
Property type
Read-write property
Syntax
Visual Basic
Public Property Name As String
Remarks

This really just a shortcut for attribute (0010,0010).

See Also

DicomImage Object | DicomImage Members


ObjectType Property

ObjectType Property
DicomObjects Reference > DicomImage Object : ObjectType Property
Description
Describes the nature of an automation object
Property type
Read-only property
Syntax
Visual Basic
Public Property ObjectType As String
Remarks

The possible values are as follows:

“DicomViewer”
“DicomQuery”
“DicomImage”
“DicomImages”
“DicomDataSet”
“DicomDataSets”
“DicomAttribute”
“DicomConnection”
“DicomConnections”
“DicomContext”
“DicomContexts”
“DicomLabel”
“DicomLabels”
“DicomGlobal”
“DicomLog”
“DicomPrint”

See Also

DicomImage Object | DicomImage Members


OriginX Property

OriginX Property
DicomObjects Reference > DicomImage Object : OriginX Property
Description
Position of top-left corner within the control's coordinate system
Property type
Read-only property
Syntax
Visual Basic
Public Property OriginX As Single
Remarks

When relating mouse events to images, it is necessary to know the position of an image within the control displaying it, and these properties provide that information. They represent the location of the top left of the “cell” displaying the image.

In order to locate the image occupying a given location, use the ImageIndex method of the control.

The top left of the image “cell” may not correspond with the top left point of the image displayed if the image has been scrolled - see ActualScrollX and ActualScrollY for more information. Also, in many cases the ImageXPosition and ImageYPosition methods provide a simple method of calculating image pixel positions.

See Also

DicomImage Object | DicomImage Members


OriginY Property

OriginY Property
DicomObjects Reference > DicomImage Object : OriginY Property
Description
Position of top-left corner within the control's coordinate system
Property type
Read-only property
Syntax
Visual Basic
Public Property OriginY As Single
Remarks

When relating mouse events to images, it is necessary to know the position of an image within the control displaying it, and these properties provide that information. They represent the location of the top left of the “cell” displaying the image.

In order to locate the image occupying a given location, use the ImageIndex method of the control.

The top left of the image “cell” may not correspond with the top left point of the image displayed if the image has been scrolled - see ActualScrollX and ActualScrollY for more information. Also, in many cases the ImageXPosition and ImageYPosition methods provide a simple method of calculating image pixel positions.

See Also

DicomImage Object | DicomImage Members


OverlayColour Property

OverlayColour Property
DicomObjects Reference > DicomImage Object : OverlayColour Property
Which overlay to control
Description
Controls the colour of an overlay embedded in the image
Property type
Read-write property
Syntax
Visual Basic
Public Property OverlayColour( _
   ByVal Overlay As Integer _
) As ULong
Parameters
Overlay
Which overlay to control
Remarks

DICOM defines up to 16 overlay planes embedded in an image, using group number 6000, 6002, 6004…601E, and these properties allow the developer to choose which to display. Each is a simple single bit mask, and is displayed if the appropriate OverlayVisible property is true, using the associated OverlayColour.

The source of the data for such overlays can be either unused bits in the pixel data, or separate elements, but this is handled internally by DicomObjects, and all such overlays are handled identically.

The OverlayIDs are numbered from 1 to 15, and so are related to the group numbers as follows:

OverlayID=(group number – 0x6000) / 2

Or put another way

Group number=OverlayID * 2 + 0x6000

See Also

DicomImage Object | DicomImage Members


OverlayVisible Property

OverlayVisible Property
DicomObjects Reference > DicomImage Object : OverlayVisible Property
Which overlay to control
Description
Controls visibility of an overlay embedded in the image
Property type
Read-write property
Syntax
Visual Basic
Public Property OverlayVisible( _
   ByVal Overlay As Integer _
) As Boolean
Parameters
Overlay
Which overlay to control
Remarks

DICOM defines up to 16 overlay planes embedded in an image, using group number 6000, 6002, 6004…601E, and these properties allow the developer to choose which to display. Each is a simple single bit mask, and is displayed if the appropriate OverlayVisible property is true, using the associated OverlayColour.

The source of the data for such overlays can be either unused bits in the pixel data, or separate elements, but this is handled internally by DicomObjects, and all such overlays are handled identically.

The OverlayIDs are numbered from 1 to 15, and so are related to the group numbers as follows:

OverlayID=(group number – 0x6000) / 2

Or put another way

Group number=OverlayID * 2 + 0x6000

See Also

DicomImage Object | DicomImage Members


PatientID Property

PatientID Property
DicomObjects Reference > DicomImage Object : PatientID Property
Description
Patient identifier
Property type
Read-write property
Syntax
Visual Basic
Public Property PatientID As String
Remarks

This really just a shortcut for attribute (0010,0020).

See Also

DicomImage Object | DicomImage Members


PixelAddress Property

PixelAddress Property
DicomObjects Reference > DicomImage Object : PixelAddress Property
Description
Long pointer to Pixel Buffer
Property type
Read-only property
Syntax
Visual Basic
Public Property PixelAddress As Long
Return Type
Returns a 32 bit pointer
Remarks

This property provides a method of accessing the pixel data directly for languages that support native pointers. The value returned is, however, a long integer, to prevent the automatic dereferencing that would otherwise occur in some languages such as Visual Basic, were an official OLE pointer type to be used.
If the client program manipulates the pixel data in any way, then PixelsModified must be called after the modification to enable DicomObjects to synchronise its display and invalidate any derivatives such as compressed forms of the image.

This is an advanced property, and it is the responsibility of the client program to implement its own bounds checking etc when using the value received, as failure to do so may cause unpredictable results.
Where the pixel data is held on disk rather than in RAM, then the memory area given by this property is read-only.
If the data is compressed, then this method will return an error. To circumvent this, call DecompressAll first.
See also the following methods:

AllocatePixelSpace
CopyPixelBuffer

See Also

DicomImage Object | DicomImage Members


PixelAddress64 Property

PixelAddress64 Property
DicomObjects Reference > DicomImage Object : PixelAddress64 Property
Description
Pointer to Pixel Buffer as true pointer
Property type
Read-only property
Syntax
Visual Basic
Public Property PixelAddress64 As Unknown
Return Type
Returns a 64 bit pointer
Remarks
Same as PixelAddress but designed to work with 64 bit systems
See Also

DicomImage Object | DicomImage Members


Pixels Property

Pixels Property
DicomObjects Reference > DicomImage Object : Pixels Property
Description
Accesses pixeldata as an array
Property type
Read-write property
Syntax
Visual Basic
Public Property Pixels As Variant
Remarks

This returns an array of either bytes or short integers, depending on the size of the native data. The data returned is unaffected by the display parameters.
The first two dimensions of the array returned are those of the image itself, the third being the number of frames (as returned by FrameCount).
If the data has more than one sample per pixel (e.g. RGB images), then the format of the array returned depends on the planar configuration (0028,0006). If this is 0 (colour-by-pixel), then the 1st (horizontal) dimension of the array is multiplied by the number of samples, whereas if the planar configuration is 1 (colour-by-plane), then it is the 2nd (vertical) dimension that is increased. This ensures that each “row” of pixels remains intact.

When writing to this property, either a 1, 2 or 3 dimensional array will be accepted, and will be interpreted as a byte or word stream, varying the first dimension fastest, then the others in order.
Note that Visual Basic can have a problem distinguishing between function parameters and array indices if an attempt is made to create the pixel array and access a specific pixel value in the same statement. e.g.
x=image.pixels(1,1,1)
will generate an error, stating that the numbers of parameters is incorrect, and this should therefore be changed to:

pix=image.pixels
x=pix(1,1,1)
Similar problems may occur in other languages, and the same solution is recommended.

See Also

DicomImage Object | DicomImage Members


PresentationLUT Property

PresentationLUT Property
DicomObjects Reference > DicomImage Object : PresentationLUT Property
Description
Selects which Presentation LUT to apply (0 for none)
Property type
Read-write property
Syntax
Visual Basic
Public Property PresentationLUT As Integer
Remarks
DICOM allows multiple VOI and presentation Lookup Tables (LUTs) in images, and the user may select whichever they require. These properties provide that choice, and the value 0 may be used to disable a particular type of LUT. Only one Modality LUT is allowed, so the only meaningful values for ModalityLUT are 0 and 1, but the other two may range from 0 to the number of such LUTs in the image. Value beyond the available range are treated as 0.
The default values are all 1, indicating that the first table of each type, if present, should be used.
See Also

DicomImage Object | DicomImage Members


PresentationState Property

PresentationState Property
DicomObjects Reference > DicomImage Object : PresentationState Property
Description
DataSet contining the DICOM grayscale Presentation State to apply
Property type
Read-write property
Syntax
Visual Basic
Public Property PresentationState As DicomDataSet
Remarks
When this property is set to an existing DicomDataSet containing a valid DICOM greyscale presentation state, all the normal display parameters (Zoom, ScrollX/Y, Width & Level etc.) are over-ridden, and the display is determines solely by the presentation state as defined in DICOM supplement 33.
See Also

DicomImage Object | DicomImage Members


Projection Property

Projection Property
DicomObjects Reference > DicomImage Object : Projection Property
Description
Projection for 3D
Property type
Read-only property
Syntax
Visual Basic
Public Property Projection As DicomProjection
See Also

DicomImage Object | DicomImage Members


PropertiesFor3D Property

PropertiesFor3D Property
DicomObjects Reference > DicomImage Object : PropertiesFor3D Property
Description
Properties For 3D
Property type
Read-only property
Syntax
Visual Basic
Public Property PropertiesFor3D As PropertiesFor3D
See Also

DicomImage Object | DicomImage Members


PropertiesForFusion Property

PropertiesForFusion Property
DicomObjects Reference > DicomImage Object : PropertiesForFusion Property
Description
Properties For Fusion
Property type
Read-only property
Syntax
Visual Basic
Public Property PropertiesForFusion As PropertiesForFusion
See Also

DicomImage Object | DicomImage Members


ReceivedSyntax Property

ReceivedSyntax Property
DicomObjects Reference > DicomImage Object : ReceivedSyntax Property
Description
Transfer Syntax with which SOP instance was received or read
Property type
Read-only property
Syntax
Visual Basic
Public Property ReceivedSyntax As String
Remarks
The value returned is the UID, in dotted numerical form, or the transfer syntax used.
This property may be useful to programs that handle compressed images, that wish to avoid re-compression of images, e.g. when using the WriteFile method.
If an image has been created locally, then a zero-length string is returned
See Also

DicomImage Object | DicomImage Members


Right Property

Right Property
DicomObjects Reference > DicomImage Object : Right Property
Description
Controls the display position of an image
Property type
Read-write property
Syntax
Visual Basic
Public Property Right As Integer
Remarks

Normally, if these 4 properties all have their default value of 0, the images within a DicomViewer’ Images collection are displayed in a fixed grid arrangement, controlled by the viewer’s MultiRows, MultiColumns and CurrentIndex properties. If however, any of these properties are set non-zero, then the default behaviour is over-ridden, and the image is displayed in a “cell” defined by these properties (coordinates are relative to the viewer’s top-left corner). All other properties such as StretchedCentred etc. operate exactly as normal, but within this different cell.

One common use for these properties is to create an efficient “magnifying glass”, as it is easy to add a second copy of an image to a viewer’s Images collection, then alter it’s zoom, and positioning properties as the mouse moves, to implement the magnifier. The re-display is optimised for this purpose, and when these properties are changed, then only the affected area is redrawn (quickly). Therefore use of the viewer’s Refresh method is not only unnecessary, but it actually slows the application.

See Also

DicomImage Object | DicomImage Members


RotateState Property

RotateState Property
DicomObjects Reference > DicomImage Object : RotateState Property
Description
Controls Rotation of the image
Property type
Read-write property
Syntax
Visual Basic
Public Property RotateState As doRotateState
Remarks
For normal display, only rotation in increments of 90 degrees is supported - see the DicomImageRotateState Enumeration for more details.
See Also

DicomImage Object | DicomImage Members


RotationBehaviour Property

RotationBehaviour Property
DicomObjects Reference > DicomImage Object : RotationBehaviour Property
Description
Controls the rotation behaviour of the image with respect to the current StretchMode
Property type
Read-write property
Syntax
Visual Basic
Public Property RotationBehaviour As doRotationBehaviour
See Also

DicomImage Object | DicomImage Members


ScrollX Property

ScrollX Property
DicomObjects Reference > DicomImage Object : ScrollX Property
Description
Controls the positioning of an image display
Property type
Read-write property
Syntax
Visual Basic
Public Property ScrollX As Single
Remarks

Together with Zoom, this determines the display of an image, which is magnified by ‘Zoom’ and then displaced ScrollX pixels to the left and ScrollY pixels up. These properties are ignored if the containing control is set to StretchedCentred.
In order to find the values used at any given time, even if StretchToFit is true, use the ActualScrollX and ActualScrollY properties
These properties are over-ridden if a Presentation State is applied.

If the viewer in which the image is held has UseScrollBars is true, then the values of ScrollX and ScrollY are silently constrained to values which keep the corners of the image cell within the image.

See Also

DicomImage Object | DicomImage Members


ScrollY Property

ScrollY Property
DicomObjects Reference > DicomImage Object : ScrollY Property
Description
Controls the positioning of an image display
Property type
Read-write property
Syntax
Visual Basic
Public Property ScrollY As Single
Remarks

Together with Zoom, this determines the display of an image, which is magnified by ‘Zoom’ and then displaced ScrollX pixels to the left and ScrollY pixels up. These properties are ignored if the containing control is set to StretchedCentred.
In order to find the values used at any given time, even if StretchToFit is true, use the ActualScrollX and ActualScrollY properties
These properties are over-ridden if a Presentation State is applied.

If the viewer in which the image is held has UseScrollBars is true, then the values of ScrollX and ScrollY are silently constrained to values which keep the corners of the image cell within the image.

See Also

DicomImage Object | DicomImage Members


SeriesDescription Property

SeriesDescription Property
DicomObjects Reference > DicomImage Object : SeriesDescription Property
Description
Series Description
Property type
Read-write property
Syntax
Visual Basic
Public Property SeriesDescription As String
Remarks
This property provides a human readable description of the Series, being a shortcut to correspond to attribute (0x0008, 0x103e)
See Also

DicomImage Object | DicomImage Members


SeriesUID Property

SeriesUID Property
DicomObjects Reference > DicomImage Object : SeriesUID Property
Description
Unique Series identifier
Property type
Read-write property
Syntax
Visual Basic
Public Property SeriesUID As String
Remarks
This is a shortcut to attribute (0008,000E) - the Series Instance UID
See Also

DicomImage Object | DicomImage Members


Sex Property

Sex Property
DicomObjects Reference > DicomImage Object : Sex Property
Description
The patient's sex
Property type
Read-write property
Syntax
Visual Basic
Public Property Sex As String
Return Type

This really just a shortcut for attribute (0010,0040).

See Also

DicomImage Object | DicomImage Members


ShowLabels Property

ShowLabels Property
DicomObjects Reference > DicomImage Object : ShowLabels Property
Description
Whether DicomLabels are to be shown
Property type
Read-write property
Syntax
Visual Basic
Public Property ShowLabels As Boolean
See Also

DicomImage Object | DicomImage Members


ShowShutter Property

ShowShutter Property
DicomObjects Reference > DicomImage Object : ShowShutter Property
Description
Controls whether or not to display Shutter if present
Property type
Read-write property
Syntax
Visual Basic
Public Property ShowShutter As Boolean
See Also

DicomImage Object | DicomImage Members


ShowUpdates Property

ShowUpdates Property
DicomObjects Reference > DicomImage Object : ShowUpdates Property
Description
Controls whether updates are shown for this image
Property type
Read-write property
Syntax
Visual Basic
Public Property ShowUpdates As Boolean
See Also

DicomImage Object | DicomImage Members


SizeX Property

SizeX Property
DicomObjects Reference > DicomImage Object : SizeX Property
Description
The horizontal dimension of the image
Property type
Read-only property
Syntax
Visual Basic
Public Property SizeX As Integer
Remarks
These is really just a shortcuts for attribute (0028,0011) - the width of the image in pixels
See Also

DicomImage Object | DicomImage Members


SizeY Property

SizeY Property
DicomObjects Reference > DicomImage Object : SizeY Property
Description
The vertical dimension of the image
Property type
Read-only property
Syntax
Visual Basic
Public Property SizeY As Integer
Remarks
These is really just a shortcuts for attribute (0028,001o) - the height of the image in pixels
See Also

DicomImage Object | DicomImage Members


SOPClass Property

SOPClass Property
DicomObjects Reference > DicomImage Object : SOPClass Property
Description
The Image's SOP Class UID
Property type
Read-write property
Syntax
Visual Basic
Public Property SOPClass As String
Remarks
This is a shortcut to attribute (0008,0016) - the SOP class of the object as a UID
See Also

DicomImage Object | DicomImage Members


StretchedAlignment Property

StretchedAlignment Property
DicomObjects Reference > DicomImage Object : StretchedAlignment Property
Description
Controls the alignment of a stretched-to-fit Image
Property type
Read-write property
Syntax
Visual Basic
Public Property StretchedAlignment As Integer
Remarks

When StretchedCentred is set then the image is maximised in either the vertical or horizontal directions, according to which one would give the smaller size, then it has to be aligned in the other direction. By default (when the value of this property is 5) the image is centred, whichever direction applies, but this property allows that default behaviour to be changed. Note though that only the horizontal or the vertical aspect will be used, since the other direction will be maximised.

 | Align Left | Align Centre | Align Right
Align Top | 0 | 1 | 2
Align Centre | 4 | 5 | 6
Align Bottom | 8 | 9 | 10

See Also

DicomImage Object | DicomImage Members


StretchMode Property

StretchMode Property
DicomObjects Reference > DicomImage Object : StretchMode Property
Description
Controls the zoom of an image to fill the space available
Property type
Read-write property
Syntax
Visual Basic
Public Property StretchMode As doStretchModes
See Also

DicomImage Object | DicomImage Members


StudyDescription Property

StudyDescription Property
DicomObjects Reference > DicomImage Object : StudyDescription Property
Description
Study Description
Property type
Read-write property
Syntax
Visual Basic
Public Property StudyDescription As String
Remarks
These property provides a human readable description of the Study, being a shortcut to correspond to attribute (0x0008, 0x1030)
See Also

DicomImage Object | DicomImage Members


StudyUID Property

StudyUID Property
DicomObjects Reference > DicomImage Object : StudyUID Property
Description
Unique Study identifier
Property type
Read-write property
Syntax
Visual Basic
Public Property StudyUID As String
Remarks
This is a shortcut to attribute (0008,000D) - the Study Instance UID
See Also

DicomImage Object | DicomImage Members


Tag Property

Tag Property
DicomObjects Reference > DicomImage Object : Tag Property
Description
General Purpose Tag
Property type
Read-write property
Syntax
Visual Basic
Public Property Tag As Variant
Remarks

Tag properties are attached to most objects in DicomObjects. The values are not used by the associated object, and are available for user use. A special case is the DicomConnection object, where Tag is included in the ActionComplete event procedure, assisting identification of necessary features of the connection, such as pending database operations etc. In this use, the value of Tag is stored at the time an operation is initiated, and it is this stored value which is passed to ActionComplete, simplifying the task of tracking which operations have happened.

The TagObject property holds another object, typically a DicomLabels collection, and this can be useful when arranging DicomLabel objects into groups.

See Also

DicomImage Object | DicomImage Members


Top Property

Top Property
DicomObjects Reference > DicomImage Object : Top Property
Description
Controls the display position of an image
Property type
Read-write property
Syntax
Visual Basic
Public Property Top As Integer
Remarks

Normally, if these 4 properties all have their default value of 0, the images within a DicomViewer’ Images collection are displayed in a fixed grid arrangement, controlled by the viewer’s MultiRows, MultiColumns and CurrentIndex properties. If however, any of these properties are set non-zero, then the default behaviour is over-ridden, and the image is displayed in a “cell” defined by these properties (coordinates are relative to the viewer’s top-left corner). All other properties such as StretchedCentred etc. operate exactly as normal, but within this different cell.

One common use for these properties is to create an efficient “magnifying glass”, as it is easy to add a second copy of an image to a viewer’s Images collection, then alter it’s zoom, and positioning properties as the mouse moves, to implement the magnifier. The re-display is optimised for this purpose, and when these properties are changed, then only the affected area is redrawn (quickly). Therefore use of the viewer’s Refresh method is not only unnecessary, but it actually slows the application.

See Also

DicomImage Object | DicomImage Members


UnsharpEnhancement Property

UnsharpEnhancement Property
DicomObjects Reference > DicomImage Object : UnsharpEnhancement Property
Description
Unsharp masking enhancement value
Property type
Read-write property
Syntax
Visual Basic
Public Property UnsharpEnhancement As Single
Remarks

These properties control how DicomObjects handles magnification and minification of images, either for display or other uses such as PrinterImage. Separate properties are used depending on whether the ActualZoom
of the image is <1 (MinificationMode) or >1 (MagnificationMode), allowing developers to select both, without needing to change when the image size changes.

There are few doFilterMode enumerations (used for Magnification and MinificationMode)

See Also

DicomImage Object | DicomImage Members


UnsharpLength Property

UnsharpLength Property
DicomObjects Reference > DicomImage Object : UnsharpLength Property
Description
Unsharp Masking mask size
Property type
Read-write property
Syntax
Visual Basic
Public Property UnsharpLength As Integer
Remarks

These properties control how DicomObjects handles magnification and minification of images, either for display or other uses such as PrinterImage. Separate properties are used depending on whether the ActualZoom
of the image is <1 (MinificationMode) or >1 (MagnificationMode), allowing developers to select both, without needing to change when the image size changes.

There are few doFilterMode enumerations (used for Magnification and MinificationMode)

See Also

DicomImage Object | DicomImage Members


VOILUT Property

VOILUT Property
DicomObjects Reference > DicomImage Object : VOILUT Property
Description
Selects which VOI LUT to apply (0 for none)
Property type
Read-write property
Syntax
Visual Basic
Public Property VOILUT As Integer
Remarks
DICOM allows multiple VOI and presentation Lookup Tables (LUTs) in images, and the user may select whichever they require. These properties provide that choice, and the value 0 may be used to disable a particular type of LUT. Only one Modality LUT is allowed, so the only meaningful values for ModalityLUT are 0 and 1, but the other two may range from 0 to the number of such LUTs in the image. Value beyond the available range are treated as 0.
The default values are all 1, indicating that the first table of each type, if present, should be used.
See Also

DicomImage Object | DicomImage Members


VoiLUTFunction Property

VoiLUTFunction Property
DicomObjects Reference > DicomImage Object : VoiLUTFunction Property
Description
Controls which VOILUT function to use, default value is Linear.
Property type
Read-write property
Syntax
Visual Basic
Public Property VoiLUTFunction As doVoiLUTFunction
Remarks

Like Width & Level, this property is initially set from the original DICOM data, but may subsequently be altered.

See Also

DicomImage Object | DicomImage Members


Width Property

Width Property
DicomObjects Reference > DicomImage Object : Width Property
Description
Controls the grey-scale mapping of a displayed image
Property type
Read-write property
Syntax
Visual Basic
Public Property Width As Single
Remarks

Width and Level control the grey-scale mapping from the original pixel data to the screen. Following the normal convention, the grey scale ranges from level-width/2 to level+width/2. Note that re-scale values present in some SOP classes are used for the purposes of this mapping, but the native data are not altered, and other operations such as obtaining the Pixels are unaffected.
Windowing using these values applies now also to colour (RGB, YBR & COLOR PALETTE images, which by default have Width=255 and Level=128)

These values are initialised from the suggested values in the DICOM data, if present, but if not present, then reasonable initial values are calculated from the pixel data itself.
These values are regarded as transitory, and therefore, when an image is written, they are not written back into the DICOM data. If this behaviour is required, then code similar to this should be included prior to the write:
Image.Attributes.Add(&h0028,&h1050),Image.Level
Image.Attributes.Add(&h0028,&h1051),Image.Width

Width and Level are ignored under the following circumstances:

  • When a PresentationState is applied to the image
  • When the image contains a “Values of Interest Lookup Table” (VOI LUT), as this takes the place of windowing

In the later case, the VOI LUT can be ignored (and width and level used), by setting the image’s VOILUT property to 0.

See Also

DicomImage Object | DicomImage Members


WidthMultiplier Property

WidthMultiplier Property
DicomObjects Reference > DicomImage Object : WidthMultiplier Property
Description
Provides a means to modify the usage of a Values of Interest Lookup Table (VOI LUT) or other display mapping
Property type
Read-write property
Syntax
Visual Basic
Public Property WidthMultiplier As Single
See Also

DicomImage Object | DicomImage Members


Zoom Property

Zoom Property
DicomObjects Reference > DicomImage Object : Zoom Property
Description
Controls the zooming of an image
Property type
Read-write property
Syntax
Visual Basic
Public Property Zoom As Single
Remarks
Together with ScrollX & ScrollY, this property determines the display of an image, which is magnified by ‘Zoom’ relative to an original size which is defined as 1 pixel = 1 screen pixel. This property is ignored if the image’s StretchToFit property is true.
In order to find the value used at any given time, even if StretchToFit is true, use the ActualZoom property.
These properties are over-ridden if a Presentation State is applied..
See Also

DicomImage Object | DicomImage Members


ZVector Property

ZVector Property
DicomObjects Reference > DicomImage Object : ZVector Property
Description
Direction cosines for 'Z-direction'
Property type
Read-write property
Syntax
Visual Basic
Public Property ZVector As Variant
See Also

DicomImage Object | DicomImage Members


DicomImages Collection

DicomImages Collection
Members
DicomObjects Reference : DicomImages Collection
Description
This is a true OLE collection, comprising DicomImage objects, including that represented by the DICOM viewer control’s Images Property.
Remarks

In addition to the above public properties, the DicomImages collection also supports the "NewEnumVariant" restricted method. This allows suitable clients such as Visual Basic to iterate through the images it contains using the following syntax:

Enumeration
Copy Code
Dim image as DicomImage
Dim control as DicomViewer
For each image in control.Images
  MsgBox image.name
Next

It is directly creatable, either using Visual Basic’s “CreateObject” method (or equivalent) using the name “DicomObjects.DicomImages” or via the DicomViewer’s New method.

See Also

DicomImages Members


DicomImages Collection Members

DicomImages Collection Members
Overview
DicomObjects Reference : DicomImages Collection
Public Methods
Public Method Add | Adds a DicomImage to a DicomImages Collection
Public Method Clear | Clears the Collection
Public Method IndexOf | Identifies position of an item in a collection
Public Method MakeFusion | Make Fusion Image
Public Method MakeMultiFrame | Constructs a multi-frame image
Public Method MakeVolume | Make 3D Volume
Public Method Move | Moves a DicomImage within a DicomImages Collection
Public Method ReadArray | Reads a DICOM 'file' from an array.
Public Method ReadField | Reads a DICOM image from a database field
Public Method ReadFile | Reads an external DICOM file
Public Method ReadMemory | Reads a DICOM image from a global memory handle
Public Method ReadStream | Reads an image from an IStream
Public Method ReadURL | Reads a dataset from a network location
Public Method Remove | Removes a DicomImage from a DicomImages Collection
Public Properties
Public Property Count | Indicates the number of items in a collection
Public Property Count32 | Indicates the number of items in a collection
Public Property Item | Provides access to the individual DicomImage items of a DicomImages collection
Public Property ObjectType | Describes the nature of an automation object
Public Property Tag | General Purpose Tag
See Also

DicomImages Collection


Add Method

Add Method
DicomObjects Reference > DicomImages Collection : Add Method
The Image to add
Description
Adds a DicomImage to a DicomImages Collection
Syntax
Visual Basic
Public Sub Add( _
   ByVal Image As Object _
)
Parameters
Image
The Image to add
Remarks

The new member is added at the end of the collection (it may subsequently be moved using Move if necessary). If the DicomImages collection to which an image is added belongs to a DicomViewer control, the control’s CurrentIndex property may be adjusted if AutoDisplay is True.
As it is often useful to create multiple displayed versions of a single image, the display parameters are created as a new object, but they still reference the same underlying DICOM dataset, thereby conserving memory. Using this feature it is possible to show two versions of an image, showing different frames or with different magnification or windowing, without doubling the memory requirements.

The parameter to this method is actually declared as a generic IDispatch object, allowing both DicomImage and DicomDataSet objects to be added to either type of collection. This is particularly useful when manipulating images embedded within sequences such as thumbnails within a DICOMDIR, as the object added acquires the type of the collection to which it is added, whilst retaining the same underlying DICOM dataset.

See Also

DicomImages Collection | DicomImages Members


Clear Method

Clear Method
DicomObjects Reference > DicomImages Collection : Clear Method
Description
Clears the Collection
Syntax
Visual Basic
Public Sub Clear()
Remarks
Immediately clears a collection. The collection object persists, but after the call is empty. The contained objects are only destroyed if there are no other outstanding references to them.
See Also

DicomImages Collection | DicomImages Members


IndexOf Method

IndexOf Method
DicomObjects Reference > DicomImages Collection : IndexOf Method
The object to be located.
Description
Identifies position of an item in a collection
Syntax
Visual Basic
Public Function IndexOf( _
   ByVal Object As DicomImage _
) As Long
Parameters
Object
The object to be located.
Remarks
The value returned locates the first occurrence of the specified object within the collection. In the case of DicomImages, DicomDataSets or DicomLabels collections, the reference may be to an object derived from the same source, as such objects may be cloned when added to collections.
See Also

DicomImages Collection | DicomImages Members


MakeFusion Method

MakeFusion Method
DicomObjects Reference > DicomImages Collection : MakeFusion Method
Description
Make Fusion Image
Syntax
Visual Basic
Public Function MakeFusion() As DicomImage
Remarks
Fusion properties are accessible through PropertiesForFusion
See Also

DicomImages Collection | DicomImages Members


MakeMultiFrame Method

MakeMultiFrame Method
DicomObjects Reference > DicomImages Collection : MakeMultiFrame Method
Controls whether the collection is emptied during use
Description
Constructs a multi-frame image
Syntax
Visual Basic
Public Function MakeMultiFrame( _
   ByVal Remove As Boolean _
) As DicomImage
Parameters
Remove
Controls whether the collection is emptied during use
Remarks
Constructs a single multi-frame image from a series of identically-sized single frame images, which have been collected into a DicomImages collection. If the argument is true, the images are removed from the collection as they are added to the new object. Apart from the pixel data, all information is copied from the first image only.
Note that the newly created multi-frame image may need some modifications, as DicomObjects has no knowledge of the relationship between frames. By default, attributes 0028,0009 & 0018,1063 are set to give a constant 10 frames per second. These may need to be removed/changed.
See Also

DicomImages Collection | DicomImages Members


MakeVolume Method

MakeVolume Method
DicomObjects Reference > DicomImages Collection : MakeVolume Method
The factor by which the data should be downscaled to reduce memory usage
Description
Make 3D Volume
Syntax
Visual Basic
Public Function MakeVolume( _
   ByVal Decimate As Long _
) As DicomVolume
Parameters
Decimate
The factor by which the data should be downscaled to reduce memory usage
Remarks
The returned DicomVolume can be reused for different 3D rendering modes
See Also

DicomImages Collection | DicomImages Members


Move Method

Move Method
DicomObjects Reference > DicomImages Collection : Move Method

A reference to the image or dataset to be moved, either:
a) An integer referencing the object by its current position in the collection, starting at 1.

or

b) A String referencing the Instance UID of the Image.

The new index for the object within the collection
Description
Moves a DicomImage within a DicomImages Collection
Syntax
Visual Basic
Public Sub Move( _
   ByVal Index As Variant, _
   ByVal Destination As Integer _
)
Parameters
Index

A reference to the image or dataset to be moved, either:
a) An integer referencing the object by its current position in the collection, starting at 1.

or

b) A String referencing the Instance UID of the Image.

Destination
The new index for the object within the collection
Remarks
By using Move, objects may be re-ordered within the collection. The object referred to by the index is placed at the position given by "destination", other objects being kept in sequence but moved as necessary to accommodate the moved item.
The index is a variant as images may be referred to either by numerical sequence (as used for CurrentIndex), but also by their unique instance UID. An exception is generated if either a numerical argument is out of bounds, or if reference is made to a non-existent instance UID.
See Also

DicomImages Collection | DicomImages Members


ReadArray Method

ReadArray Method
DicomObjects Reference > DicomImages Collection : ReadArray Method
The array to read data from
Description
Reads a DICOM 'file' from an array.
Syntax
Visual Basic
Public Function ReadArray( _
   ByVal Data As Variant _
) As DicomDataSet
Parameters
Data
The array to read data from
See Also

DicomImages Collection | DicomImages Members


ReadField Method

ReadField Method
DicomObjects Reference > DicomImages Collection : ReadField Method

The field from which the image is to be read.
This must be from the list of supported interfaces below, and must be of a type capable of holding binary objects. In Microsoft Access, this would be either an OLE or Memo field. The supported object types are:

Object Category | Version | Object Type
ActiveX Data Objects ADO | >=1.5 | Field
Data Access Objects DAO | 3.0 or 3.5 | Field
Remote Data Objects RDO | 2.0 | Column

Description
Reads a DICOM image from a database field
Syntax
Visual Basic
Public Function ReadField( _
   ByVal Field As Object _
) As DicomImage
Parameters
Field

The field from which the image is to be read.
This must be from the list of supported interfaces below, and must be of a type capable of holding binary objects. In Microsoft Access, this would be either an OLE or Memo field. The supported object types are:

Object Category | Version | Object Type
ActiveX Data Objects ADO | >=1.5 | Field
Data Access Objects DAO | 3.0 or 3.5 | Field
Remote Data Objects RDO | 2.0 | Column

Remarks

This method can read fields in either the official “Part10” format with the 128 byte header, or the unofficial “Part3” format without a header, and detection of the type is automatic.

The field would normally have been written by the WriteField method, but may have been imported into the field from an external file.

This method has been provided to allow development of a simple DICOM server using Microsoft Access, which has limited facilities for the handling of Binary Large Objects (BLOBs).

Whilst this method is useful for simple demonstrations and small projects, most database servers do not handle large BLOBs well when stored within the main database, and in a “production” environment, storage in simple files is strongly advised (with storage of just the filename within the database).

See Also

DicomImages Collection | DicomImages Members


ReadFile Method

ReadFile Method
DicomObjects Reference > DicomImages Collection : ReadFile Method

The name of the file to read.

This is passed unmodified to the operating system, and it is therefore the container’s responsibility to ensure either that the file exists within the current directory, or that a fully qualified filename is provided.

Description
Reads an external DICOM file
Syntax
Visual Basic
Public Function ReadFile( _
   ByVal FileName As String _
) As DicomImage
Parameters
FileName

The name of the file to read.

This is passed unmodified to the operating system, and it is therefore the container’s responsibility to ensure either that the file exists within the current directory, or that a fully qualified filename is provided.

Remarks

This method can read either official “Part10” format files with the 128 byte header, or unofficial “Part3” format files without a header, and detection of the type is automatic.
The file may have been written by the WriteFile method or by other DICOM software.
See ReadDirectory for an alternative method suitable for reading “DICOMDIR” directory files.

By default, pixel data is read only when it is required, greatly speeding the display of multi-frame images, and reducing memory requirements. However, a side effect of this is that any elements after the pixel data (7FE0,0010) will not be read. This should not affect most applications, but if necessary, this behaviour made be over-ridden using the DisableFileMapping or DisableQuickRead registry entries. See the registry entries page for more details.

Another effect of file mapping is that files read using this method cannot be deleted until the image object is released. This method creates two references to the newly created DicomImage object (one in the collection, and one as the return value), and both must be released before the file can be deleted.

See Also

DicomImages Collection | DicomImages Members


ReadMemory Method

ReadMemory Method
DicomObjects Reference > DicomImages Collection : ReadMemory Method
This must be the handle to a global block of memory
The length of the DICOM data within the memory block
Description
Reads a DICOM image from a global memory handle
Syntax
Visual Basic
Public Function ReadMemory( _
   ByVal Handle As Integer, _
   ByVal Length As Long _
) As DicomImage
Parameters
Handle
This must be the handle to a global block of memory
Length
The length of the DICOM data within the memory block
Remarks
This method can read data from either official “Part10” format files with the 128 byte header, or unofficial “Part3” format data without a header, and detection of the type is automatic.
The data may have been written by the WriteMemory method or by other DICOM software.
The memory block will be locked before use, then unlocked after. It is the containing application’s responsibility to free the block when no longer needed.
As DICOM has no mechanism to determine the length of the image/dataset from the data alone, the Length parameter must be accurate.
See Also

DicomImages Collection | DicomImages Members


ReadStream Method

ReadStream Method
DicomObjects Reference > DicomImages Collection : ReadStream Method

The name of the stream from which to read.

Although this object must support an IStream interface, this is retrieved via a QueryInterface call, and any interface to the object may therefore be passed.

Description
Reads an image from an IStream
Syntax
Visual Basic
Public Function ReadStream( _
   ByVal Stream As Unknown _
) As DicomImage
Parameters
Stream

The name of the stream from which to read.

Although this object must support an IStream interface, this is retrieved via a QueryInterface call, and any interface to the object may therefore be passed.

See Also

DicomImages Collection | DicomImages Members


ReadURL Method

ReadURL Method
DicomObjects Reference > DicomImages Collection : ReadURL Method
The fully qualified URL of the object to be read.
This is passed unmodified to the operating system, and it is therefore the container’s responsibility to ensure that a fully qualified, accessible URL is provided.
Description
Reads a dataset from a network location
Syntax
Visual Basic
Public Function ReadURL( _
   ByVal URL As String _
) As DicomImage
Parameters
URL
The fully qualified URL of the object to be read.
This is passed unmodified to the operating system, and it is therefore the container’s responsibility to ensure that a fully qualified, accessible URL is provided.
Remarks

The URL may begin http://, https://, ftp://, gopher:// or file://, and the appropriate access method will be used. Note that for local files, security restrictions apply.
Where authentication is required, the standard format may be used:

ReadURL(“http://username:password@servername/path”)

This method can read either official “Part10” format files with the 128 byte header, or unofficial “Part3” format files without a header, and detection of the type is automatic.
The file may have been written by the WriteFile method or by other DICOM software.

See Also

DicomImages Collection | DicomImages Members


Remove Method

Remove Method
DicomObjects Reference > DicomImages Collection : Remove Method

Either:
a) An integer referencing the image by its position in the collection, starting at 1.
or
b) A String referencing the Instance UID of the Image/DataSet.

Description
Removes a DicomImage from a DicomImages Collection
Syntax
Visual Basic
Public Sub Remove( _
   ByVal Index As Variant _
)
Parameters
Index

Either:
a) An integer referencing the image by its position in the collection, starting at 1.
or
b) A String referencing the Instance UID of the Image/DataSet.

Remarks
The index is a variant as images or datasets may be referred to either by numerical sequence (as used for CurrentIndex), but also by their unique instance UID. An exception is generated if either a numerical argument is out of bounds, or if reference is made to a non-existent instance UID.
See Also

DicomImages Collection | DicomImages Members


Count Property

Count Property
DicomObjects Reference > DicomImages Collection : Count Property
Description
Indicates the number of items in a collection
Property type
Read-only property
Syntax
Visual Basic
Public Property Count As Integer
Remarks
This is useful both for checking the value of indexes into the collection, and for iterating thought the images numerically, though as all collections in this product provide true iterators (allowing for instance the For Each construct in Visual Basic), this should rarely be necessary in such languages.
Where it is necessary to iterate through collections by integer index this can be done using ItemByIndex for DicomAttributes collections, and the Item property for the others.
See Also

DicomImages Collection | DicomImages Members


Count32 Property

Count32 Property
DicomObjects Reference > DicomImages Collection : Count32 Property
Description
Indicates the number of items in a collection
Property type
Read-only property
Syntax
Visual Basic
Public Property Count32 As Integer
Remarks
This is useful both for checking the value of indexes into the collection, and for iterating thought the images numerically, though as all collections in this product provide true iterators (allowing for instance the For Each construct in Visual Basic), this should rarely be necessary in such languages.
Where it is necessary to iterate through collections by integer index this can be done using ItemByIndex for DicomAttributes collections, and the Item property for the others.
See Also

DicomImages Collection | DicomImages Members


Item Property

Item Property
DicomObjects Reference > DicomImages Collection : Item Property
Either:
a) An integer referencing the image by its position in the collection, starting at 1.
or
b) A String referencing the Instance UID of the Image.
Description
Provides access to the individual DicomImage items of a DicomImages collection
Property type
Read-only property
Syntax
Visual Basic
Public Property Item( _
   ByVal Index As Variant _
) As DicomImage
Parameters
Index
Either:
a) An integer referencing the image by its position in the collection, starting at 1.
or
b) A String referencing the Instance UID of the Image.
Remarks
The index is a variant as images may be referenced either by numerical sequence (as used for CurrentIndex), or by their unique instance UID. An exception is generated if either a numerical argument is out of bounds, or if reference is made to a non-existent instance UID.
As this is the default property, the term "Item" is rarely used, as Control.Images.Item(3)
may rather more concisely be written as
Control.Images(3)
See Also

DicomImages Collection | DicomImages Members


ObjectType Property

ObjectType Property
DicomObjects Reference > DicomImages Collection : ObjectType Property
Description
Describes the nature of an automation object
Property type
Read-only property
Syntax
Visual Basic
Public Property ObjectType As String
Remarks

The possible values are as follows:

“DicomViewer”
“DicomQuery”
“DicomImage”
“DicomImages”
“DicomDataSet”
“DicomDataSets”
“DicomAttribute”
“DicomConnection”
“DicomConnections”
“DicomContext”
“DicomContexts”
“DicomLabel”
“DicomLabels”
“DicomGlobal”
“DicomLog”
“DicomPrint”

See Also

DicomImages Collection | DicomImages Members


Tag Property

Tag Property
DicomObjects Reference > DicomImages Collection : Tag Property
Description
General Purpose Tag
Property type
Read-write property
Syntax
Visual Basic
Public Property Tag As Variant
Remarks

Tag properties are attached to most objects in DicomObjects. The values are not used by the associated object, and are available for user use. A special case is the DicomConnection object, where Tag is included in the ActionComplete event procedure, assisting identification of necessary features of the connection, such as pending database operations etc. In this use, the value of Tag is stored at the time an operation is initiated, and it is this stored value which is passed to ActionComplete, simplifying the task of tracking which operations have happened.

The TagObject property holds another object, typically a DicomLabels collection, and this can be useful when arranging DicomLabel objects into groups.

See Also

DicomImages Collection | DicomImages Members


DicomLabel Object

DicomLabel Object
Members
DicomObjects Reference : DicomLabel Object
Description

A DicomLabel item represents a label, or annotation, to be displayed over an image in a DicomViewer control, or in derived copies of the image.
Labels may be ellipses (or circles), rectangles (or squares), lines, text or bitmaps, or other shapes (see LabelType for a full list), and the properties control not only the type and size of the object, but many other properties such as colour and line thickness.

Labels may be tied to the viewer control, to the display area in which an image is displayed, or to the image itself, this latter distinction being controlled by the RotateModeWithImage property.
All properties have default values, which are suitable for many uses, and each is documented with the appropriate property. The same label may be added into several DicomLabels collections if necessary, but where this is done, subsequent labels will be “cloned” when added, so that they may later be manipulated independently. Also, unambiguous association of each DicomLabel with one image is necessary for the ROI functions.

Remarks

Many new methods and properties have been added in version 4.1, to support both the needs of developers, and also to provide full compatibility with DICOM annotations as used in the presentation state definition. The main additions are:

  • Arc type labels
  • Interpolated Polygons
  • “Special” labels to handle automatic anatomic side markers

An arc is defined as if it were an ellipse using top, left, height and width, but the first two items of the Points collection are used to define the start and end (working anti-clockwise)

There is a separate help topic for Special Labels.

See Also

DicomLabel Members


DicomLabel Object Members

DicomLabel Object Members
Overview
DicomObjects Reference : DicomLabel Object
Public Methods
Public Method AddPoint | Adds a point for polygon and polyline types
Public Method BoundingPolygon | Makes a polyline label enclosing a bitmap label
Public Method Rescale | Rescales a label to a new frame of reference
Public Method Threshold | Makes a bitmap label by threesholding an existing label
Public Properties
Public Property Alignment | Annotation text alignment
Public Property AnchorX | Anchor point location (X)
Public Property AnchorY | Anchor point location (Y)
Public Property Angle | Rotation angle for label
Public Property AutoHeight | Height of AutoSize Text label
Public Property AutoSizeMode | Controls the size of a text label
Public Property AutoWidth | Width of AutoSize Text label
Public Property BackColour | Annotation background/fill colour
Public Property BackColourAsLong | Annotation background/fill colour
Public Property BackStyle | Style used to fill non-transparentlabels
Public Property Font | Font for text
Public Property FontName | Annotation Font
Public Property FontSize | Annotation Font Size
Public Property ForeColour | Annotation colour
Public Property ForeColourAsLong | Annotation colour
Public Property Height | Defines size of an annotation
Public Property LabelType | Type of annotation
Public Property Left | Defines position of an annotation
Public Property LineStyle | Style of line drawn (as Windows)
Public Property LineWidth | Annotation line width
Public Property Margin | Margin between bounding box and text
Public Property ObjectType | Describes the nature of an automation object
Public Property Points | The Points of a polyline or polygon
Public Property ReferenceImage | Image used for ref line
Public Property ROIArea | ROI's Area
Public Property ROIDistanceUnits | Units used for length and area
Public Property ROILength | Length of a line or polyline
Public Property ROIMax | ROI's max value
Public Property ROIMean | ROI's mean value
Public Property ROIMin | ROI's min value
Public Property ROIStandardDeviation | ROI's standard deviation
Public Property ROIValues | The values in an ROI
Public Property RotationCentre | Controls the centre of rotation of a text label
Public Property RotationMode | Controls the rotation behaviour of a label
Public Property RotationPointX | Defines the X axis centre point used for label rotation
Public Property RotationPointY | Defines the Y axis centre point used for label rotation
Public Property ScaleAnchorWithCell | Determines whether the label's anchor scales with the cell dimensions
Public Property ScaleFontSize | Control whether font size scales with image
Public Property ScaleMode | Controls units used for the label's size
Public Property SelectColour | Colour used for handles etc. when SelectMode causes them to be shown
Public Property SelectMode | Controls whether 'handles' and bounding box are shown
Public Property Shadow | Controls whether a label is displayed with a contrasting shadow
Public Property ShowAnchor | Control whether anchor point is shown
Public Property ShowTextBox | Whether to display a box around text
Public Property Tag | General Purpose Tag
Public Property TagObject | Tag Facility for object (e.g. a DicomLabels group
Public Property Text | Annotation text
Public Property TickSpacing | The spacing between ticks of a doLabelRuler type label
Public Property Top | Defines position of an annotation
Public Property Transparent | Controls whether an annotation has a transparent background
Public Property Visible | Controls whether to display an annotation
Public Property Width | Defines size of an annotation
See Also

DicomLabel Object


AddPoint Method

AddPoint Method
DicomObjects Reference > DicomLabel Object : AddPoint Method
The co-ordinates of the point to add.
The co-ordinates of the point to add.
Description
Adds a point for polygon and polyline types
Syntax
Visual Basic
Public Sub AddPoint( _
   ByVal x As Single, _
   ByVal y As Single _
)
Parameters
x
The co-ordinates of the point to add.
y
The co-ordinates of the point to add.
Remarks

This method only affects Label objects where the LabelType is doLabelPolygon or doLabelPolyLine.
The points are scaled and moved exactly as are Top, Left, Width & Height, i.e. if used a part of a DicomViewer’s Labels collection or if RotateModeWithImage is not set, then they are display pixels, but if RotateModeWithImage is set, and used as part of a DicomImage’s Labels collection, then they are scaled and scrolled with the image pixels, ensuring that the shape produced maintains an exact relationship to the underlying image.

After points have been added, they may be accessed through the Points property, which may also be used to set the whole array in a single operation.

See Also

DicomLabel Object | DicomLabel Members


BoundingPolygon Method

BoundingPolygon Method
DicomObjects Reference > DicomLabel Object : BoundingPolygon Method
Description
Makes a polyline label enclosing a bitmap label
Syntax
Visual Basic
Public Function BoundingPolygon() As DicomLabel
Remarks
The DicomLabel to which this method is applied must be of type doLabelBitmap.
The result is a new label (unattached to any collection) of type doLabelPolygon, which just encloses all the points of the original bitmap. The resulting polygon is entirely convex, and no inner boundaries or “holes” are created.
See Also

DicomLabel Object | DicomLabel Members


Rescale Method

Rescale Method
DicomObjects Reference > DicomLabel Object : Rescale Method
The image displayed within a DicomViewer to use as the basis of the new dimensions
Description
Rescales a label to a new frame of reference
Syntax
Visual Basic
Public Sub Rescale( _
   ByVal Image As DicomImage, _
   ByVal NewScaleMode As doScaleMode _
)
Parameters
Image
The image displayed within a DicomViewer to use as the basis of the new dimensions
NewScaleMode
Value | Description
doLabelScale3D | Used to specify points in 3D space using images' frame of reference
doLabelScaleCell | Dimensions are in the coordinate system used by DICOM in presentation states, where (0.0,0.0) represents the top left corner of the display area, and (1.0,1.0) represents the bottom right
doLabelScaleCell1000 | Like Cell, but the corners are (0,0) and (1000,1000)
doLabelScaleImage | Dimensions are in image pixels
doLabelScaleOutput | Dimensions are in screen or other output device pixels and are unaffected by the zooming of the image
Remarks
The purpose of the this method is to scale images which have been drawn freehand in a DicomViewer’s frame of reference to the images or image “cells” contained within it.
This method is used to allow freehand additions to be added to an image, with or without the RotateModeWithImage property being set. If ImageTied is true, then the zoom, scrolling and orientation of the label are all adjusted so that it may be added to the given image’s Labels property, and will display as drawn, but will subsequently move correctly with the image.
See Also

DicomLabel Object | DicomLabel Members


Threshold Method

Threshold Method
DicomObjects Reference > DicomLabel Object : Threshold Method
Define the range of values to include in the new DicomLabel
Define the range of values to include in the new DicomLabel
Description
Makes a bitmap label by threesholding an existing label
Syntax
Visual Basic
Public Function Threshold( _
   ByVal Min As Single, _
   ByVal Max As Single _
) As DicomLabel
Parameters
Min
Define the range of values to include in the new DicomLabel
Max
Define the range of values to include in the new DicomLabel
Remarks
The DicomLabel to which this method is applied must be of a type which defines an area, i.e. doLabelRectangle, doLabelEllipse, doLabelPolygon, or doLabelBitmap.
The result is a new label (unattached to any collection) of type doLabelBitmap, which consists of all those points in the original label whose values (after applying scaling if necessary) fall with the range Min to Max inclusive.
See Also

DicomLabel Object | DicomLabel Members


Alignment Property

Alignment Property
DicomObjects Reference > DicomLabel Object : Alignment Property
Description
Annotation text alignment
Property type
Read-write property
Syntax
Visual Basic
Public Property Alignment As doLabelAlignment
See Also

DicomLabel Object | DicomLabel Members


AnchorX Property

AnchorX Property
DicomObjects Reference > DicomLabel Object : AnchorX Property
Description
Anchor point location (X)
Property type
Read-write property
Syntax
Visual Basic
Public Property AnchorX As Single
Remarks
Only applies to text labels.
If ShowAnchor is true, then a line is drawn from the border of the text label to a point in the image indicated by these co-ordinates.
See Also

DicomLabel Object | DicomLabel Members


AnchorY Property

AnchorY Property
DicomObjects Reference > DicomLabel Object : AnchorY Property
Description
Anchor point location (Y)
Property type
Read-write property
Syntax
Visual Basic
Public Property AnchorY As Single
Remarks
Only applies to text labels.
If ShowAnchor is true, then a line is drawn from the border of the text label to a point in the image indicated by these co-ordinates.
See Also

DicomLabel Object | DicomLabel Members


Angle Property

Angle Property
DicomObjects Reference > DicomLabel Object : Angle Property
Description
Rotation angle for label
Property type
Read-write property
Syntax
Visual Basic
Public Property Angle As Single
Remarks

The label is rotated around its centre after any transformations due to RotateModeWithImage have been applied.
This property only applies to labels of type rectangle, ellipse and text
If RotateTextWithImage is true, and the label is of type text, then:

For display, this angle is added to the rotation of the image.
This angle is modified when Rescale is called, so as to preserve the relationship between the text and the image

See Also

DicomLabel Object | DicomLabel Members


AutoHeight Property

AutoHeight Property
DicomObjects Reference > DicomLabel Object : AutoHeight Property
Description
Height of AutoSize Text label
Property type
Read-write property
Syntax
Visual Basic
Public Property AutoHeight As Single
Remarks
These only return the last values used – they may change subsequently if the associated DicomImage’s display properties are altered, and will not be updated until after the image has actually been redisplayed.
Result is in screen pixels.
See Also

DicomLabel Object | DicomLabel Members


AutoSizeMode Property

AutoSizeMode Property
DicomObjects Reference > DicomLabel Object : AutoSizeMode Property
Description
Controls the size of a text label
Property type
Read-write property
Syntax
Visual Basic
Public Property AutoSizeMode As doAutoSizeMode
See Also

DicomLabel Object | DicomLabel Members


AutoWidth Property

AutoWidth Property
DicomObjects Reference > DicomLabel Object : AutoWidth Property
Description
Width of AutoSize Text label
Property type
Read-write property
Syntax
Visual Basic
Public Property AutoWidth As Single
Remarks
These only return the last values used – they may change subsequently if the associated DicomImage’s display properties are altered, and will not be updated until after the image has actually been redisplayed.
Result is in screen pixels.
See Also

DicomLabel Object | DicomLabel Members


BackColour Property

BackColour Property
DicomObjects Reference > DicomLabel Object : BackColour Property
Description
Annotation background/fill colour
Property type
Read-write property
Syntax
Visual Basic
Public Property BackColour As ULong
Remarks

The ForeColour is used for all drawing all DicomLabel items.

BackColour is only used is Transparent is false, and it is not used for Line and PolyLine objects.

For text, only the area immediately behind the characters is filled.

Ellipses, rectangles and polygons are filled with the BackColour.

SelectColour is used for the bounding box and construction lines, when SelectMode causes them to be shown.

See Also

DicomLabel Object | DicomLabel Members


BackColourAsLong Property

BackColourAsLong Property
DicomObjects Reference > DicomLabel Object : BackColourAsLong Property
Description
Annotation background/fill colour
Property type
Read-write property
Syntax
Visual Basic
Public Property BackColourAsLong As Long
See Also

DicomLabel Object | DicomLabel Members


BackStyle Property

BackStyle Property
DicomObjects Reference > DicomLabel Object : BackStyle Property
Description
Style used to fill non-transparentlabels
Property type
Read-write property
Syntax
Visual Basic
Public Property BackStyle As Integer
Remarks

These properties are not relevant where LabelType=doLabelLine(3).

If transparent is false, then ellipses, rectangles, polygons, and the area behind text are filled with the BackColour Colour.

If BackStyle is not –1, then a pattern is used to fill the area, the lines being drawn in the BackColour. If transparent is false, then these are drawn on a white background.

The styles are:

0 | Horizontal | -----
1 | Vertical | |||||
2 | Fdiagonal | \\\\
3 | Bdiagonal | /////
4 | H_Cross | +++++
5 | Diagcross | xxxxx

See Also

DicomLabel Object | DicomLabel Members


Font Property

Font Property
DicomObjects Reference > DicomLabel Object : Font Property
Description
Font for text
Property type
Read-only property
Syntax
Visual Basic
Public Property Font As IFont
Remarks
This property is only relevant where LabelType is doLabelText or doLabelSpecial.
As of version 4.1, this is the primary method to set the font for text labels.
FontName and FontSize remain for backwards compatibility, but are now just shortcuts to the Font.Name and Font.Size sub-properties.
See Also

DicomLabel Object | DicomLabel Members


FontName Property

FontName Property
DicomObjects Reference > DicomLabel Object : FontName Property
Description
Annotation Font
Property type
Read-write property
Syntax
Visual Basic
Public Property FontName As String
Remarks

These properties are only relevant where LabelType=doLabelText(0), and as of version 4.1, they are merely alternative means of changing properties of the Font property’s own properties.

FontSize is measured in nominal (screen) points.

If FontName is blank (default), then the system default font is used.

If FontSize is 0 (default), then the system default font size is used.

If FontSize is non-zero, and RotateModeWithImage is set, then the font size scales with the image, i.e. it is multiplied by the Zoom factor.

If Bold or Italics is required, this should be specified as part of the full font name, e.g. “Arial Bold”

See Also

DicomLabel Object | DicomLabel Members


FontSize Property

FontSize Property
DicomObjects Reference > DicomLabel Object : FontSize Property
Description
Annotation Font Size
Property type
Read-write property
Syntax
Visual Basic
Public Property FontSize As Integer
Remarks

These properties are only relevant where LabelType=doLabelText(0), and as of version 4.1, they are merely alternative means of changing properties of the Font property’s own properties.

FontSize is measured in nominal (screen) points.

If FontName is blank (default), then the system default font is used.

If FontSize is 0 (default), then the system default font size is used.

If FontSize is non-zero, and RotateModeWithImage is set, then the font size scales with the image, i.e. it is multiplied by the Zoom factor.

If Bold or Italics is required, this should be specified as part of the full font name, e.g. “Arial Bold”

See Also

DicomLabel Object | DicomLabel Members


ForeColour Property

ForeColour Property
DicomObjects Reference > DicomLabel Object : ForeColour Property
Description
Annotation colour
Property type
Read-write property
Syntax
Visual Basic
Public Property ForeColour As ULong
Remarks

The ForeColour is used for all drawing all DicomLabel items.

BackColour is only used is Transparent is false, and it is not used for Line and PolyLine objects.

For text, only the area immediately behind the characters is filled.

Ellipses, rectangles and polygons are filled with the BackColour.

SelectColour is used for the bounding box and construction lines, when SelectMode causes them to be shown.

See Also

DicomLabel Object | DicomLabel Members


ForeColourAsLong Property

ForeColourAsLong Property
DicomObjects Reference > DicomLabel Object : ForeColourAsLong Property
Description
Annotation colour
Property type
Read-write property
Syntax
Visual Basic
Public Property ForeColourAsLong As Long
See Also

DicomLabel Object | DicomLabel Members


Height Property

Height Property
DicomObjects Reference > DicomLabel Object : Height Property
Description
Defines size of an annotation
Property type
Read-write property
Syntax
Visual Basic
Public Property Height As Single
Remarks

Each label object is drawn within a rectangle, of size Width x Height, with its top-left corner defined by Top and Left.
Measurement units are pixels, but there are several variations:

  • If displayed as part of a DicomViewer’s Labels collection, then the origin is the top-left corner of the viewer control, and no scaling occurs.
  • If ScaleWithCell is true, and if displayed as part of a DicomImage’s Labels collection, then the coordinates are scaled such that 0 represents the left/top edges of the cell within which the images is displayed, and 1000 represents the bottom/right edges. This setting is particularly appropriate for demographic text labels.
  • If RotateModeWithImage is not set, and if displayed as part of a DicomImage’s Labels collection, then the pixels are display pixels, and the origin is the top-left corner of the part of the control within which the image is displayed. i.e. if an image is zoomed or scrolled, then the object stays fixed on the screen.
  • If ImageTied is true, and if displayed as part of a DicomImage’s Labels collection, then the pixels are image pixels, and the origin is the top-left corner of the image. i.e. if an image is zoomed or scrolled, then the object moves with the image.

If Height or Width are zero for text labels, then the lower-right is set to the lower-right corner of the display area or image as appropriate.

Lines are drawn from the top left to the “bottom-right” as defined above, but as Weight and Width may be negative or zero, any line is possible.

These properties are not used for PolyLine and Polygon types.

See Also

DicomLabel Object | DicomLabel Members


LabelType Property

LabelType Property
DicomObjects Reference > DicomLabel Object : LabelType Property
Description
Type of annotation
Property type
Read-write property
Syntax
Visual Basic
Public Property LabelType As doLabelType
Remarks
Here is the list of LabelTypes.
See Also

DicomLabel Object | DicomLabel Members


Left Property

Left Property
DicomObjects Reference > DicomLabel Object : Left Property
Description
Defines position of an annotation
Property type
Read-write property
Syntax
Visual Basic
Public Property Left As Single
Remarks

Each label object is drawn within a rectangle, of size Width x Height, with its top-left corner defined by Top and Left.
Measurement units are pixels, but there are several variations:

  • If displayed as part of a DicomViewer’s Labels collection, then the origin is the top-left corner of the viewer control, and no scaling occurs.
  • If ScaleWithCell is true, and if displayed as part of a DicomImage’s Labels collection, then the coordinates are scaled such that 0 represents the left/top edges of the cell within which the images is displayed, and 1000 represents the bottom/right edges. This setting is particularly appropriate for demographic text labels.
  • If RotateModeWithImage is not set, and if displayed as part of a DicomImage’s Labels collection, then the pixels are display pixels, and the origin is the top-left corner of the part of the control within which the image is displayed. i.e. if an image is zoomed or scrolled, then the object stays fixed on the screen.
  • If ImageTied is true, and if displayed as part of a DicomImage’s Labels collection, then the pixels are image pixels, and the origin is the top-left corner of the image. i.e. if an image is zoomed or scrolled, then the object moves with the image.

If Height or Width are zero for text labels, then the lower-right is set to the lower-right corner of the display area or image as appropriate.

Lines are drawn from the top left to the “bottom-right” as defined above, but as Weight and Width may be negative or zero, any line is possible.

These properties are not used for PolyLine and Polygon types.

See Also

DicomLabel Object | DicomLabel Members


LineStyle Property

LineStyle Property
DicomObjects Reference > DicomLabel Object : LineStyle Property
Description
Style of line drawn (as Windows)
Property type
Read-write property
Syntax
Visual Basic
Public Property LineStyle As Integer
Remarks

These properties apply to lines, arrows, polylines, rectangles, arcs and ellipses only.
Width is measured in pixels.
If LineWidth is 0, then a single pixel line is drawn.
The LineStyle values are used only where the LineWidth is 0, and are the standard windows constants:

0 | Solid Line |
1 | Dashed | -------
2 | Dotted | .......
3 | Dash-Dot | _._._._
4 | Dash-Dot-Dot | _.._.._
See Also

DicomLabel Object | DicomLabel Members


LineWidth Property

LineWidth Property
DicomObjects Reference > DicomLabel Object : LineWidth Property
Description
Annotation line width
Property type
Read-write property
Syntax
Visual Basic
Public Property LineWidth As Single
Remarks

These properties apply to lines, arrows, polylines, rectangles, arcs and ellipses only.
Width is measured in pixels.
If LineWidth is 0, then a single pixel line is drawn.
The LineStyle values are used only where the LineWidth is 0, and are the standard windows constants:

0 | Solid Line |
1 | Dashed | -------
2 | Dotted | .......
3 | Dash-Dot | _._._._
4 | Dash-Dot-Dot | _.._.._
See Also

DicomLabel Object | DicomLabel Members


Margin Property

Margin Property
DicomObjects Reference > DicomLabel Object : Margin Property
Description
Margin between bounding box and text
Property type
Read-write property
Syntax
Visual Basic
Public Property Margin As Integer
Remarks
The bounding rectangle defined by Height and Width is reduced by this size on all four sides before text is drawn, leaving a clear margin around the text. If AutoSizeMode is set to Auto, then the calculated box is automatically expanded to accommodate this margin.
See Also

DicomLabel Object | DicomLabel Members


ObjectType Property

ObjectType Property
DicomObjects Reference > DicomLabel Object : ObjectType Property
Description
Describes the nature of an automation object
Property type
Read-only property
Syntax
Visual Basic
Public Property ObjectType As String
Remarks

The possible values are as follows:

“DicomViewer”
“DicomQuery”
“DicomImage”
“DicomImages”
“DicomDataSet”
“DicomDataSets”
“DicomAttribute”
“DicomConnection”
“DicomConnections”
“DicomContext”
“DicomContexts”
“DicomLabel”
“DicomLabels”
“DicomGlobal”
“DicomLog”
“DicomPrint”

See Also

DicomLabel Object | DicomLabel Members


Points Property

Points Property
DicomObjects Reference > DicomLabel Object : Points Property
Description
The Points of a polyline or polygon
Property type
Read-write property
Syntax
Visual Basic
Public Property Points As Variant
Remarks
This is a single-dimension array, but interpreted as pairs of values (x and y).
The values may be updated either by direct assignment to this property, or as in earlier versions of DicomObjects, the AddPoint method may be used to add a point to the end of the array.
See Also

DicomLabel Object | DicomLabel Members


ReferenceImage Property

ReferenceImage Property
DicomObjects Reference > DicomLabel Object : ReferenceImage Property
Description
Image used for ref line
Property type
Read-write property
Syntax
Visual Basic
Public Property ReferenceImage As DicomImage
See Also

DicomLabel Object | DicomLabel Members


ROIArea Property

ROIArea Property
DicomObjects Reference > DicomLabel Object : ROIArea Property
Description
ROI's Area
Property type
Read-write property
Syntax
Visual Basic
Public Property ROIArea As Single
Remarks

ROIMean returns the mean value of the pixels in the ROI
ROIStandardDeviation returns the standard deviation of the values of the pixels in the ROI
ROIMin & ROIMax return the minimum and maximum values of the pixels in the ROI

For the above properties, where rescale parameters are used (e.g. for CT) they are applied to the pixel values automatically before the statistical values are calculated.

ROIArea returns the area of the ROI.

Where pixel dimensions for the whole image are present within the image data, these are used to scale the area appropriately, but at present multiple region calibration areas (e.g. in U/S images) are not currently supported. The units used (which for un calibrated data may simply be pixels) is returned by ROIDistanceUnits (for this property, they should be interpreted as square units of course)

All these properties may only be used for DicomLabels of type Rectangle, Ellipse, Polygon or Bitmap.

See Also

DicomLabel Object | DicomLabel Members


ROIDistanceUnits Property

ROIDistanceUnits Property
DicomObjects Reference > DicomLabel Object : ROIDistanceUnits Property
Description
Units used for length and area
Property type
Read-write property
Syntax
Visual Basic
Public Property ROIDistanceUnits As String
Remarks

Distance units for the values returned by ROILength and ROIArea of a None-Image-Tied label

The value returned depends on whether distance calibration is present in the image data. The possible values are:

  • "mm"
  • "mm at Imager"
  • "mm at Imaging Plane"
  • "Pixels"
See Also

DicomLabel Object | DicomLabel Members


ROILength Property

ROILength Property
DicomObjects Reference > DicomLabel Object : ROILength Property
Description
Length of a line or polyline
Property type
Read-write property
Syntax
Visual Basic
Public Property ROILength As Single
Remarks
This property may not be used for DicomLabels of type Bitmap.
The length is the length of the entire circumference of the label.
Where pixel dimensions for the whole image are present within the image data, these are used to scale the length appropriately, but at present multiple region calibration areas (e.g. in U/S images) are not currently supported. The units used (which for un calibrated data may simply be pixels) is returned by ROIDistanceUnits.
See Also

DicomLabel Object | DicomLabel Members


ROIMax Property

ROIMax Property
DicomObjects Reference > DicomLabel Object : ROIMax Property
Description
ROI's max value
Property type
Read-write property
Syntax
Visual Basic
Public Property ROIMax As Single
Remarks

ROIMean returns the mean value of the pixels in the ROI
ROIStandardDeviation returns the standard deviation of the values of the pixels in the ROI
ROIMin & ROIMax return the minimum and maximum values of the pixels in the ROI

For the above properties, where rescale parameters are used (e.g. for CT) they are applied to the pixel values automatically before the statistical values are calculated.

ROIArea returns the area of the ROI.

Where pixel dimensions for the whole image are present within the image data, these are used to scale the area appropriately, but at present multiple region calibration areas (e.g. in U/S images) are not currently supported. The units used (which for un calibrated data may simply be pixels) is returned by ROIDistanceUnits (for this property, they should be interpreted as square units of course)

All these properties may only be used for DicomLabels of type Rectangle, Ellipse, Polygon or Bitmap.

See Also

DicomLabel Object | DicomLabel Members


ROIMean Property

ROIMean Property
DicomObjects Reference > DicomLabel Object : ROIMean Property
Description
ROI's mean value
Property type
Read-write property
Syntax
Visual Basic
Public Property ROIMean As Single
Remarks

ROIMean returns the mean value of the pixels in the ROI
ROIStandardDeviation returns the standard deviation of the values of the pixels in the ROI
ROIMin & ROIMax return the minimum and maximum values of the pixels in the ROI

For the above properties, where rescale parameters are used (e.g. for CT) they are applied to the pixel values automatically before the statistical values are calculated.

ROIArea returns the area of the ROI.

Where pixel dimensions for the whole image are present within the image data, these are used to scale the area appropriately, but at present multiple region calibration areas (e.g. in U/S images) are not currently supported. The units used (which for un calibrated data may simply be pixels) is returned by ROIDistanceUnits (for this property, they should be interpreted as square units of course)

All these properties may only be used for DicomLabels of type Rectangle, Ellipse, Polygon or Bitmap.

See Also

DicomLabel Object | DicomLabel Members


ROIMin Property

ROIMin Property
DicomObjects Reference > DicomLabel Object : ROIMin Property
Description
ROI's min value
Property type
Read-write property
Syntax
Visual Basic
Public Property ROIMin As Single
Remarks

ROIMean returns the mean value of the pixels in the ROI
ROIStandardDeviation returns the standard deviation of the values of the pixels in the ROI
ROIMin & ROIMax return the minimum and maximum values of the pixels in the ROI

For the above properties, where rescale parameters are used (e.g. for CT) they are applied to the pixel values automatically before the statistical values are calculated.

ROIArea returns the area of the ROI.

Where pixel dimensions for the whole image are present within the image data, these are used to scale the area appropriately, but at present multiple region calibration areas (e.g. in U/S images) are not currently supported. The units used (which for un calibrated data may simply be pixels) is returned by ROIDistanceUnits (for this property, they should be interpreted as square units of course)

All these properties may only be used for DicomLabels of type Rectangle, Ellipse, Polygon or Bitmap.

See Also

DicomLabel Object | DicomLabel Members


ROIStandardDeviation Property

ROIStandardDeviation Property
DicomObjects Reference > DicomLabel Object : ROIStandardDeviation Property
Description
ROI's standard deviation
Property type
Read-write property
Syntax
Visual Basic
Public Property ROIStandardDeviation As Single
Remarks

ROIMean returns the mean value of the pixels in the ROI
ROIStandardDeviation returns the standard deviation of the values of the pixels in the ROI
ROIMin & ROIMax return the minimum and maximum values of the pixels in the ROI

For the above properties, where rescale parameters are used (e.g. for CT) they are applied to the pixel values automatically before the statistical values are calculated.

ROIArea returns the area of the ROI.

Where pixel dimensions for the whole image are present within the image data, these are used to scale the area appropriately, but at present multiple region calibration areas (e.g. in U/S images) are not currently supported. The units used (which for un calibrated data may simply be pixels) is returned by ROIDistanceUnits (for this property, they should be interpreted as square units of course)

All these properties may only be used for DicomLabels of type Rectangle, Ellipse, Polygon or Bitmap.

See Also

DicomLabel Object | DicomLabel Members


ROIValues Property

ROIValues Property
DicomObjects Reference > DicomLabel Object : ROIValues Property
Description
The values in an ROI
Property type
Read-write property
Syntax
Visual Basic
Public Property ROIValues As Variant
Remarks
This property may only be used for DicomLabels of type Rectangle, Ellipse, Polygon or Bitmap.
Where rescale parameters are used (e.g. for CT) they are applied to the pixel values automatically before returning these values.
See Also

DicomLabel Object | DicomLabel Members


RotationCentre Property

RotationCentre Property
DicomObjects Reference > DicomLabel Object : RotationCentre Property
Description
Controls the centre of rotation of a text label
Property type
Read-write property
Syntax
Visual Basic
Public Property RotationCentre As doRotationCentre
See Also

DicomLabel Object | DicomLabel Members


RotationMode Property

RotationMode Property
DicomObjects Reference > DicomLabel Object : RotationMode Property
Description
Controls the rotation behaviour of a label
Property type
Read-write property
Syntax
Visual Basic
Public Property RotationMode As doRotationMode
See Also

DicomLabel Object | DicomLabel Members


RotationPointX Property

RotationPointX Property
DicomObjects Reference > DicomLabel Object : RotationPointX Property
Description
Defines the X axis centre point used for label rotation
Property type
Read-write property
Syntax
Visual Basic
Public Property RotationPointX As Single
See Also

DicomLabel Object | DicomLabel Members


RotationPointY Property

RotationPointY Property
DicomObjects Reference > DicomLabel Object : RotationPointY Property
Description
Defines the Y axis centre point used for label rotation
Property type
Read-write property
Syntax
Visual Basic
Public Property RotationPointY As Single
See Also

DicomLabel Object | DicomLabel Members


ScaleAnchorWithCell Property

ScaleAnchorWithCell Property
DicomObjects Reference > DicomLabel Object : ScaleAnchorWithCell Property
Description
Determines whether the label's anchor scales with the cell dimensions
Property type
Read-write property
Syntax
Visual Basic
Public Property ScaleAnchorWithCell As Boolean
See Also

DicomLabel Object | DicomLabel Members


ScaleFontSize Property

ScaleFontSize Property
DicomObjects Reference > DicomLabel Object : ScaleFontSize Property
Description
Control whether font size scales with image
Property type
Read-write property
Syntax
Visual Basic
Public Property ScaleFontSize As Boolean
Remarks
When this property is true (the default case, as used in previous versions of DicomObjects), then when RotateModeWithImage is set, the font size of a text label scales with the zoom of the image, but when false, the font size remains constant.
See Also

DicomLabel Object | DicomLabel Members


ScaleMode Property

ScaleMode Property
DicomObjects Reference > DicomLabel Object : ScaleMode Property
Description
Controls units used for the label's size
Property type
Read-write property
Syntax
Visual Basic
Public Property ScaleMode As doScaleMode
Remarks

Check the Enums.ScaleMode for the possible values

See Also

DicomLabel Object | DicomLabel Members


SelectColour Property

SelectColour Property
DicomObjects Reference > DicomLabel Object : SelectColour Property
Description
Colour used for handles etc. when SelectMode causes them to be shown
Property type
Read-write property
Syntax
Visual Basic
Public Property SelectColour As ULong
Remarks

The ForeColour is used for all drawing all DicomLabel items.

BackColour is only used is Transparent is false, and it is not used for Line and PolyLine objects.

For text, only the area immediately behind the characters is filled.

Ellipses, rectangles and polygons are filled with the BackColour.

SelectColour is used for the bounding box and construction lines, when SelectMode causes them to be shown.

See Also

DicomLabel Object | DicomLabel Members


SelectMode Property

SelectMode Property
DicomObjects Reference > DicomLabel Object : SelectMode Property
Description
Controls whether 'handles' and bounding box are shown
Property type
Read-write property
Syntax
Visual Basic
Public Property SelectMode As doSelectMode
Remarks

There is a list of allowable values for SelectMode.

Although defined as enumerated types, the values above can be (and normally are) used as bit fields, so the value doSelectBox + doSelectBoxHandles gives a bounding box with visible corners.

See Also

DicomLabel Object | DicomLabel Members


Shadow Property

Shadow Property
DicomObjects Reference > DicomLabel Object : Shadow Property
Description
Controls whether a label is displayed with a contrasting shadow
Property type
Read-write property
Syntax
Visual Basic
Public Property Shadow As doShadowType
Remarks

There is a list of Shadow Types.

Although defined as enumerated types, the values above can be (and normally are) combined and used as bit fields

The shadow is drawn in the direction(s) indicated above displaced by one pixel from the main label, and it is drawn using the label’s BackColour colour.

Some development versions of DicomObjects had a temporary property called Outline (Boolean), which is now deprecated in favour of Shadow. If Outline is set to true, then the value of Shadow will be set to doShadowAll (255).

See Also

DicomLabel Object | DicomLabel Members


ShowAnchor Property

ShowAnchor Property
DicomObjects Reference > DicomLabel Object : ShowAnchor Property
Description
Control whether anchor point is shown
Property type
Read-write property
Syntax
Visual Basic
Public Property ShowAnchor As Boolean
Remarks
If the label is a text label, and this property is true, then a line is drawn from the border of the text label to a point in the image indicated by the AnchorX and AnchorY co-ordinates.
See Also

DicomLabel Object | DicomLabel Members


ShowTextBox Property

ShowTextBox Property
DicomObjects Reference > DicomLabel Object : ShowTextBox Property
Description
Whether to display a box around text
Property type
Read-write property
Syntax
Visual Basic
Public Property ShowTextBox As Boolean
Remarks
If true, then the area occupied by a text label is outlined (in the label’s ForeColour)
See Also

DicomLabel Object | DicomLabel Members


Tag Property

Tag Property
DicomObjects Reference > DicomLabel Object : Tag Property
Description
General Purpose Tag
Property type
Read-write property
Syntax
Visual Basic
Public Property Tag As Variant
Remarks

Tag properties are attached to most objects in DicomObjects. The values are not used by the associated object, and are available for user use. A special case is the DicomConnection object, where Tag is included in the ActionComplete event procedure, assisting identification of necessary features of the connection, such as pending database operations etc. In this use, the value of Tag is stored at the time an operation is initiated, and it is this stored value which is passed to ActionComplete, simplifying the task of tracking which operations have happened.

The TagObject property holds another object, typically a DicomLabels collection, and this can be useful when arranging DicomLabel objects into groups.

See Also

DicomLabel Object | DicomLabel Members


TagObject Property

TagObject Property
DicomObjects Reference > DicomLabel Object : TagObject Property
Description
Tag Facility for object (e.g. a DicomLabels group
Property type
Read-write property
Syntax
Visual Basic
Public Property TagObject As Object
Remarks

Tag properties are attached to most objects in DicomObjects. The values are not used by the associated object, and are available for user use. A special case is the DicomConnection object, where Tag is included in the ActionComplete event procedure, assisting identification of necessary features of the connection, such as pending database operations etc. In this use, the value of Tag is stored at the time an operation is initiated, and it is this stored value which is passed to ActionComplete, simplifying the task of tracking which operations have happened.

The TagObject property holds another object, typically a DicomLabels collection, and this can be useful when arranging DicomLabel objects into groups.

See Also

DicomLabel Object | DicomLabel Members


Text Property

Text Property
DicomObjects Reference > DicomLabel Object : Text Property
Description
Annotation text
Property type
Read-write property
Syntax
Visual Basic
Public Property Text As String
Remarks
This property is only relevant where LabelType is doLabelText or (indirectly) doLabelSpecial.
The Alignment, Font , ScaleFontSize, ShowAnchor and AnchorX/Y properties are important also for this case.
If ShowTextBox is true, then the text is surrounded by a rectangular box, drawn in the foreground colour.
As of version 4, Unicode characters may be used, and the UnicodeValue property of an attribute may be very useful for extracting and displaying properties such the patient’s name.
See Also

DicomLabel Object | DicomLabel Members


TickSpacing Property

TickSpacing Property
DicomObjects Reference > DicomLabel Object : TickSpacing Property
True if the major tick size is being requested
Description
The spacing between ticks of a doLabelRuler type label
Property type
Read-only property
Syntax
Visual Basic
Public Property TickSpacing( _
   ByVal MajorTicks As Boolean _
) As Double
Parameters
MajorTicks
True if the major tick size is being requested
Remarks

The value returned is the spacing in nominal mm between tick marks on the ruler displayed. Note that depending on the type of image, these may not be true patient measurements, and the ROIDistanceUnits property should be checked to see whether these are “mm at imager” etc.

If MajorTicks is true, then the value is the spacing between large marks, and if false, it will be the small mark spacing. The large mark spacing is always exactly 2, 5 or 10 time the small mark spacing.

The values returned by this property are highly labile, and will change if the Zoom, StretchMode or any other display parameters of the associated image are altered, so if used for display purposes, it may be advisable to update in the DrawStart event.

See Also

DicomLabel Object | DicomLabel Members


Top Property

Top Property
DicomObjects Reference > DicomLabel Object : Top Property
Description
Defines position of an annotation
Property type
Read-write property
Syntax
Visual Basic
Public Property Top As Single
Remarks

Each label object is drawn within a rectangle, of size Width x Height, with its top-left corner defined by Top and Left.
Measurement units are pixels, but there are several variations:

  • If displayed as part of a DicomViewer’s Labels collection, then the origin is the top-left corner of the viewer control, and no scaling occurs.
  • If ScaleWithCell is true, and if displayed as part of a DicomImage’s Labels collection, then the coordinates are scaled such that 0 represents the left/top edges of the cell within which the images is displayed, and 1000 represents the bottom/right edges. This setting is particularly appropriate for demographic text labels.
  • If RotateModeWithImage is not set, and if displayed as part of a DicomImage’s Labels collection, then the pixels are display pixels, and the origin is the top-left corner of the part of the control within which the image is displayed. i.e. if an image is zoomed or scrolled, then the object stays fixed on the screen.
  • If ImageTied is true, and if displayed as part of a DicomImage’s Labels collection, then the pixels are image pixels, and the origin is the top-left corner of the image. i.e. if an image is zoomed or scrolled, then the object moves with the image.

If Height or Width are zero for text labels, then the lower-right is set to the lower-right corner of the display area or image as appropriate.

Lines are drawn from the top left to the “bottom-right” as defined above, but as Weight and Width may be negative or zero, any line is possible.

These properties are not used for PolyLine and Polygon types.

See Also

DicomLabel Object | DicomLabel Members


Transparent Property

Transparent Property
DicomObjects Reference > DicomLabel Object : Transparent Property
Description
Controls whether an annotation has a transparent background
Property type
Read-write property
Syntax
Visual Basic
Public Property Transparent As Boolean
Remarks

These properties are not relevant where LabelType=doLabelLine(3).

If transparent is false, then ellipses, rectangles, polygons, and the area behind text are filled with the BackColour Colour.

If BackStyle is not –1, then a pattern is used to fill the area, the lines being drawn in the BackColour. If transparent is false, then these are drawn on a white background.

The styles are:

0 | Horizontal | -----
1 | Vertical | |||||
2 | Fdiagonal | \\\\
3 | Bdiagonal | /////
4 | H_Cross | +++++
5 | Diagcross | xxxxx

See Also

DicomLabel Object | DicomLabel Members


Visible Property

Visible Property
DicomObjects Reference > DicomLabel Object : Visible Property
Description
Controls whether to display an annotation
Property type
Read-write property
Syntax
Visual Basic
Public Property Visible As Boolean
Remarks
A label is only displayed if this property is true, and if the ShowLabels property of the associated image is also true.
See Also

DicomLabel Object | DicomLabel Members


Width Property

Width Property
DicomObjects Reference > DicomLabel Object : Width Property
Description
Defines size of an annotation
Property type
Read-write property
Syntax
Visual Basic
Public Property Width As Single
Remarks

Each label object is drawn within a rectangle, of size Width x Height, with its top-left corner defined by Top and Left.
Measurement units are pixels, but there are several variations:

  • If displayed as part of a DicomViewer’s Labels collection, then the origin is the top-left corner of the viewer control, and no scaling occurs.
  • If ScaleWithCell is true, and if displayed as part of a DicomImage’s Labels collection, then the coordinates are scaled such that 0 represents the left/top edges of the cell within which the images is displayed, and 1000 represents the bottom/right edges. This setting is particularly appropriate for demographic text labels.
  • If RotateModeWithImage is not set, and if displayed as part of a DicomImage’s Labels collection, then the pixels are display pixels, and the origin is the top-left corner of the part of the control within which the image is displayed. i.e. if an image is zoomed or scrolled, then the object stays fixed on the screen.
  • If ImageTied is true, and if displayed as part of a DicomImage’s Labels collection, then the pixels are image pixels, and the origin is the top-left corner of the image. i.e. if an image is zoomed or scrolled, then the object moves with the image.

If Height or Width are zero for text labels, then the lower-right is set to the lower-right corner of the display area or image as appropriate.

Lines are drawn from the top left to the “bottom-right” as defined above, but as Weight and Width may be negative or zero, any line is possible.

These properties are not used for PolyLine and Polygon types.

See Also

DicomLabel Object | DicomLabel Members


DicomLabels Collection

DicomLabels Collection
Members
DicomObjects Reference : DicomLabels Collection
Description

This is a true OLE collection, a consisting of DicomLabel objects.

Although it may be instantiated independently, the most common examples of such collections are the Labels properties of DicomViewer and DicomImage objects, representing the labels to be drawn over that viewer or image respectively.

Remarks

The order of the objects in a collection may be significant if they overlap, as Labels are drawn in ascending numerical order, possibly partially or completely over-writing those below them in the numbering sequence. The order of the objects in a collection may be significant if they overlap, as Labels are drawn in ascending numerical order, possibly partially or completely over-writing those below them in the numbering sequence.

See Also

DicomLabels Members


DicomLabels Collection Members

DicomLabels Collection Members
Overview
DicomObjects Reference : DicomLabels Collection
Public Methods
Public Method Add | Adds an item
Public Method Clear | Clears the Collection
Public Method IndexOf | Identifes position of an item in a collection
Public Method Move | Moves a Label item
Public Method Remove | Removes an item from the collection
Public Properties
Public Property Count | The number of items in the collection
Public Property Item | Accesses a Label item
Public Property ObjectType | Describes the nature of an automation object
Public Property Tag | General Purpose Tag
See Also

DicomLabels Collection


Add Method

Add Method
DicomObjects Reference > DicomLabels Collection : Add Method
The Label to add
Description
Adds an item
Syntax
Visual Basic
Public Sub Add( _
   ByVal Label As DicomLabel _
)
Parameters
Label
The Label to add
Remarks

The new addition is added at the end of the collection. It may subsequently be moved using Move if necessary.

Individual labels may only be attached to a single DicomImage objects, to prevent ambiguities when the ROI functions are used. Accordingly if this method is used on a label which is already a member of a DicomLabels collection, then a cloned copy of the label will be created, and the clone will be added. This should be noted when manipulating the properties of such a label after using this method.

See Also

DicomLabels Collection | DicomLabels Members


Clear Method

Clear Method
DicomObjects Reference > DicomLabels Collection : Clear Method
Description
Clears the Collection
Syntax
Visual Basic
Public Sub Clear()
Remarks
Immediately clears a collection. The collection object persists, but after the call is empty. The contained objects are only destroyed if there are no other outstanding references to them.
See Also

DicomLabels Collection | DicomLabels Members


IndexOf Method

IndexOf Method
DicomObjects Reference > DicomLabels Collection : IndexOf Method
The object to be located.
Description
Identifes position of an item in a collection
Syntax
Visual Basic
Public Function IndexOf( _
   ByVal Object As DicomLabel _
) As Long
Parameters
Object
The object to be located.
Remarks
The value returned locates the first occurrence of the specified object within the collection. In the case of DicomImages, DicomDataSets or DicomLabels collections, the reference may be to an object derived from the same source, as such objects may be cloned when added to collections.
See Also

DicomLabels Collection | DicomLabels Members


Move Method

Move Method
DicomObjects Reference > DicomLabels Collection : Move Method
The current index in the collection
The new index for the Label within the collection
Description
Moves a Label item
Syntax
Visual Basic
Public Sub Move( _
   ByVal Index As Long, _
   ByVal Destination As Long _
)
Parameters
Index
The current index in the collection
Destination
The new index for the Label within the collection
Remarks
By using Move, Labels may be re-ordered within the collection. The Label referred to by the index is placed at the position given by "destination", other Labels being kept in sequence but moved as necessary to accommodate the moved item.
The main need for this method is when labels overlap, as those later in the collection are drawn last, possible over-writing parts of earlier labels.
See Also

DicomLabels Collection | DicomLabels Members


Remove Method

Remove Method
DicomObjects Reference > DicomLabels Collection : Remove Method
The 1-based index of the label to remove
Description
Removes an item from the collection
Syntax
Visual Basic
Public Sub Remove( _
   ByVal Index As Long _
)
Parameters
Index
The 1-based index of the label to remove
Remarks
Removes specified DicomLabel from the collection.
See Also

DicomLabels Collection | DicomLabels Members


Count Property

Count Property
DicomObjects Reference > DicomLabels Collection : Count Property
Description
The number of items in the collection
Property type
Read-only property
Syntax
Visual Basic
Public Property Count As Long
Remarks
This is useful both for checking the value of indexes into the collection, and for iterating thought the images numerically, though as all collections in this product provide true iterators (allowing for instance the For Each construct in Visual Basic), this should rarely be necessary in such languages.
Where it is necessary to iterate through collections by integer index this can be done using ItemByIndex for DicomAttributes collections, and the Item property for the others.
See Also

DicomLabels Collection | DicomLabels Members


Item Property

Item Property
DicomObjects Reference > DicomLabels Collection : Item Property
An integer referencing the DicomLabel by its position in the collection, starting at 1.
Description
Accesses a Label item
Property type
Read-only property
Syntax
Visual Basic
Public Property Item( _
   ByVal Index As Long _
) As DicomLabel
Parameters
Index
An integer referencing the DicomLabel by its position in the collection, starting at 1.
Remarks
As this is the default property, the term "Item" is rarely used, as Labels.Item(3)
may rather more concisely be written as
Labels(3)
See Also

DicomLabels Collection | DicomLabels Members


ObjectType Property

ObjectType Property
DicomObjects Reference > DicomLabels Collection : ObjectType Property
Description
Describes the nature of an automation object
Property type
Read-only property
Syntax
Visual Basic
Public Property ObjectType As String
Remarks

The possible values are as follows:

“DicomViewer”
“DicomQuery”
“DicomImage”
“DicomImages”
“DicomDataSet”
“DicomDataSets”
“DicomAttribute”
“DicomConnection”
“DicomConnections”
“DicomContext”
“DicomContexts”
“DicomLabel”
“DicomLabels”
“DicomGlobal”
“DicomLog”
“DicomPrint”

See Also

DicomLabels Collection | DicomLabels Members


Tag Property

Tag Property
DicomObjects Reference > DicomLabels Collection : Tag Property
Description
General Purpose Tag
Property type
Read-write property
Syntax
Visual Basic
Public Property Tag As Variant
Remarks

Tag properties are attached to most objects in DicomObjects. The values are not used by the associated object, and are available for user use. A special case is the DicomConnection object, where Tag is included in the ActionComplete event procedure, assisting identification of necessary features of the connection, such as pending database operations etc. In this use, the value of Tag is stored at the time an operation is initiated, and it is this stored value which is passed to ActionComplete, simplifying the task of tracking which operations have happened.

The TagObject property holds another object, typically a DicomLabels collection, and this can be useful when arranging DicomLabel objects into groups.

See Also

DicomLabels Collection | DicomLabels Members


DicomLicense Object

DicomLicense Object
Members
DicomObjects Reference : DicomLicense Object
Description
An object which represents a single license allowing specific use of DicomObjects on this machine.
See Also

DicomLicense Members


DicomLicense Object Members

DicomLicense Object Members
Overview
DicomObjects Reference : DicomLicense Object
Public Methods
Public Method DeleteLicense Delete license
Public Properties
Public Property AllowedFunctions | Functions Allowed by this license
Public Property Expiry | Expiry Date of this license
Public Property LicenseType | The Type of this License
Public Property MachineID | The Identifier for the machine associated with this license
See Also

DicomLicense Object


DeleteLicense Method

DeleteLicense Method
DicomObjects Reference > DicomLicense Object : DeleteLicense Method
Description
Delete license
Syntax
Visual Basic
Public Sub DeleteLicense()
See Also

DicomLicense Object | DicomLicense Members


AllowedFunctions Property

AllowedFunctions Property
DicomObjects Reference > DicomLicense Object : AllowedFunctions Property
Description
Functions Allowed by this license
Property type
Read-write property
Syntax
Visual Basic
Public Property AllowedFunctions As Integer
Remarks
0 | None | No functions allowed
1 | Viewer | Allows use of the DicomViewer control
2 | Read | Allows reading and importing of images
4 | Write | Allows writing and exporting of images
8 | Initiator | Allows associations to be intiated
16 | Acceptor | Allows listening for and accepting new associations
32 | QuerySCP | Allows use as a Query/Retrieve SCP
64 | NormalisedSCP | Allows use as an SCP for normalised services
128 | Allow 3D | Allow use of 3D features
Example
If returned value is 255 it includes all the functions as it is the total of all the bit flags shown above
See Also

DicomLicense Object | DicomLicense Members


Expiry Property

Expiry Property
DicomObjects Reference > DicomLicense Object : Expiry Property
Description
Expiry Date of this license
Property type
Read-write property
Syntax
Visual Basic
Public Property Expiry As Date
Remarks
Full licenses would have the expiry date set to a distant year in the future
See Also

DicomLicense Object | DicomLicense Members


LicenseType Property

LicenseType Property
DicomObjects Reference > DicomLicense Object : LicenseType Property
Description
The Type of this License
Property type
Read-write property
Syntax
Visual Basic
Public Property LicenseType As Integer
Remarks
0 | Full | Full commercial license for production use
1 | Developer | Use for development and testing only
2 | Trial | Allows use for evaluation only
3 | Demo | Allows use for demonstrations
See Also

DicomLicense Object | DicomLicense Members


MachineID Property

MachineID Property
DicomObjects Reference > DicomLicense Object : MachineID Property
Description
The Identifier for the machine associated with this license
Property type
Read-write property
Syntax
Visual Basic
Public Property MachineID As String
Remarks
This string is needed to generate a license and must be entered into the web activation system when ActivateOffLine is to be used.
See Also

DicomLicense Object | DicomLicense Members


DicomLicenseGlobal Object

DicomLicenseGlobal Object
Members
DicomObjects Reference : DicomLicenseGlobal Object
Description
This object supports various operations related to the licensing of DicomObjects.
Remarks
An instance of this object must be created before its members may be used - this is needed as the COM model does not support simple static members.
See Also

DicomLicenseGlobal Members


DicomLicenseGlobal Object Members

DicomLicenseGlobal Object Members
Overview
DicomObjects Reference : DicomLicenseGlobal Object
Public Methods
Public Method ActivateOffLine | Activate a copy of DicomObjects using the off-line method.
Public Method ActivateOnLine | Activate a license on-line
Public Method DeleteAllLicenses | Delete All Licenses on this machine
Public Method ReActivateOnLine | ReActivate a license on-line
Public Method ShowActivationDialog | Displays license activation dialog
Public Properties
Public Property CurrentLicense | The license currently in use
Public Property InstalledLicenses | Obtains all installed licenses
Public Property MachineID | This machine's unique ID
See Also

DicomLicenseGlobal Object


ActivateOffLine Method

ActivateOffLine Method
DicomObjects Reference > DicomLicenseGlobal Object : ActivateOffLine Method
The authorisation string, normally of the forms xxxx-yyyy-zzzz which has been provided by Medical Connections
The license token, always of the form uuuu-wwww-xxxx-yyyy-zzzz which has been obtained from the activation web page
Description
Activate a copy of DicomObjects using the off-line method.
Syntax
Visual Basic
Public Function ActivateOffLine( _
   ByVal AuthorizationString As String, _
   ByVal LicenseToken As String _
) As DicomLicense
Parameters
AuthorizationString
The authorisation string, normally of the forms xxxx-yyyy-zzzz which has been provided by Medical Connections
LicenseToken
The license token, always of the form uuuu-wwww-xxxx-yyyy-zzzz which has been obtained from the activation web page
Remarks

This method (unlike ActivateOnLine) does not need an active Internet connection for the machine being licensed.

The page to perform off-line activation is:
http://activation.medicalconnections.co.uk

See Also

DicomLicenseGlobal Object | DicomLicenseGlobal Members


ActivateOnLine Method

ActivateOnLine Method
DicomObjects Reference > DicomLicenseGlobal Object : ActivateOnLine Method
The authorisation string, normally of the forms xxxx-yyyy-zzzz which has been provided by Medical Connections
Information to help identify the customer - this is available via e-mail to both the developer and Medical Connections
Further similar information
Description
Activate a license on-line
Syntax
Visual Basic
Public Function ActivateOnLine( _
   ByVal AuthorisationString As String, _
   ByVal CustomerInfo1 As String, _
   ByVal CustomerInfo2 As String _
) As DicomLicense
Parameters
AuthorisationString
The authorisation string, normally of the forms xxxx-yyyy-zzzz which has been provided by Medical Connections
CustomerInfo1
Information to help identify the customer - this is available via e-mail to both the developer and Medical Connections
CustomerInfo2
Further similar information
Remarks
This method (unlike ActivateOffLine) does need an active Internet connection for the machine being licensed.
See Also

DicomLicenseGlobal Object | DicomLicenseGlobal Members


DeleteAllLicenses Method

DeleteAllLicenses Method
DicomObjects Reference > DicomLicenseGlobal Object : DeleteAllLicenses Method
Description
Delete All Licenses on this machine
Syntax
Visual Basic
Public Sub DeleteAllLicenses()
Remarks

Following this, no DicomObjects functionality will be available until a new license has been installed.

No notification is sent to Medical Connections Ltd when this is used.

See Also

DicomLicenseGlobal Object | DicomLicenseGlobal Members


ReActivateOnLine Method

ReActivateOnLine Method
DicomObjects Reference > DicomLicenseGlobal Object : ReActivateOnLine Method
The string provided by Medical Connections, allowing you to activate DicomObjects
Provide as much information as possible for the Original License, including original MachineID and license token
A string identifying the PC and or institution at which this copy is being activated
A second string with the same function
Description
ReActivate a license on-line
Syntax
Visual Basic
Public Function ReActivateOnLine( _
   ByVal AuthorisationString As String, _
   ByVal OriginalLicense As String, _
   ByVal CustomerInfo1 As String, _
   ByVal CustomerInfo2 As String _
) As DicomLicense
Parameters
AuthorisationString
The string provided by Medical Connections, allowing you to activate DicomObjects
OriginalLicense
Provide as much information as possible for the Original License, including original MachineID and license token
CustomerInfo1
A string identifying the PC and or institution at which this copy is being activated
CustomerInfo2
A second string with the same function
Return Type

A valid DicomLicense object if the activation succeeded or if already activated using this Authorisation string or null if the activation failed

See Also

DicomLicenseGlobal Object | DicomLicenseGlobal Members


ShowActivationDialog Method

ShowActivationDialog Method
DicomObjects Reference > DicomLicenseGlobal Object : ShowActivationDialog Method
Description
Displays license activation dialog
Syntax
Visual Basic
Public Sub ShowActivationDialog()
See Also

DicomLicenseGlobal Object | DicomLicenseGlobal Members


CurrentLicense Property

CurrentLicense Property
DicomObjects Reference > DicomLicenseGlobal Object : CurrentLicense Property
Description
The license currently in use
Property type
Read-only property
Syntax
Visual Basic
Public Property CurrentLicense As DicomLicense
Remarks
The license is set automatically from those that have been installed on the machine.
See Also

DicomLicenseGlobal Object | DicomLicenseGlobal Members


InstalledLicenses Property

InstalledLicenses Property
DicomObjects Reference > DicomLicenseGlobal Object : InstalledLicenses Property
Description
Obtains all installed licenses
Property type
Read-only property
Syntax
Visual Basic
Public Property InstalledLicenses As Variant
Return Type
Licenses are added to this list automatically by use of ActivateOnLine or ActivateOffLine, and removed by using DeleteAllLicenses.
See Also

DicomLicenseGlobal Object | DicomLicenseGlobal Members


MachineID Property

MachineID Property
DicomObjects Reference > DicomLicenseGlobal Object : MachineID Property
Description
This machine's unique ID
Property type
Read-only property
Syntax
Visual Basic
Public Property MachineID As String
Remarks
This is an 8 digit hexadecimal number, which identifies the machine for licensing purposes.
See Also

DicomLicenseGlobal Object | DicomLicenseGlobal Members


DicomPrint Object

DicomPrint Object
Members
DicomObjects Reference : DicomPrint Object
Description
Object to simplify printing to DICOM printers
Remarks

An object which supports simplified DICOM printing.

By using this object it is possible to print to most DICOM printers without detailed knowledge of the underlying messages used. At its simplest, it is used (in VB) as follows:

Set Print=new DicomPrint

Print.Node=address

Print.Port=104

Print.CallingAE=”MY AET”

Print.CalledAE=”PRINTER AET”

Print.Open

Print.FilmSize=”STANDARD\3,4”

For each image in images
Print.PrintImage image
Next
Print.PrintFilm
Print.Close

The above is a very simple example, and much more flexibility is possible. In particular, you can:

  • Alter how images are laid out using NextPosition and PrintFilm
  • Access printer properties (after Open) using the Printer object
  • Change the Orientation, FilmSize, Copies or BitDepth
  • Use the Colour property to select Colour or monochrome printing (where supported by the printer!)
  • Even more properties of the session, filmbox or image box can be over-ridden using the Session, FilmBox and ImageBox properties.
See Also

DicomPrint Members


DicomPrint Object Members

DicomPrint Object Members
Overview
DicomObjects Reference : DicomPrint Object
Public Methods
Public Method AddAnnotation | Adds a DICOM annotation to a film box
Public Method Close | Close connection to a printer
Public Method Open | Open connection to a printer
Public Method PrintFilm | Print a film now
Public Method PrintImage | Send an image to the printer
Public Properties
Public Property AnnotationFormat | Requested annotation format
Public Property Annotations | Annotations to add to film
Public Property BitDepth | The Bit depth to render images to for printing
Public Property CalledAE | The application entity title of the Printer
Public Property CallingAE | The application entity title by which the DicomPrint object is to be known
Public Property Colour | Controls whether to use colour printing
Public Property Connection | The DicomConnection used by a DicomPrint Object
Public Property Copies | Copies requested
Public Property FilmBox | Attributes to use when creating a film box
Public Property FilmSize | Film size to request
Public Property Format | Film size to request
Public Property ImageBox | Attributes to set in an image box
Public Property NextPosition | Get/Set position on film for next image
Public Property Node | The IP address at which the Printer may be found
Public Property ObjectType | Describes the nature of an automation object
Public Property Orientation | Film orientation to request
Public Property Port | The TCP port at which the Printer is listening
Public Property Printer | The well-known printer object (valid after Open)
Public Property Session | Attributes to use when creating a film session
Public Property Tag | General Purpose Tag
See Also

DicomPrint Object


AddAnnotation Method

AddAnnotation Method
DicomObjects Reference > DicomPrint Object : AddAnnotation Method
The ID of the annotation being added
The String value to add
Description
Adds a DICOM annotation to a film box
Syntax
Visual Basic
Public Sub AddAnnotation( _
   ByVal AnnotationID As Integer, _
   ByVal AnnotationString As String _
)
Parameters
AnnotationID
The ID of the annotation being added
AnnotationString
The String value to add
Remarks
This is simply a shortcut way of adding items to the Annotations collection. See that property for more details of how annotations work in DicomObjects printing.
See Also

DicomPrint Object | DicomPrint Members


Close Method

Close Method
DicomObjects Reference > DicomPrint Object : Close Method
Description
Close connection to a printer
Syntax
Visual Basic
Public Sub Close()
Remarks
It is often not necessary to call this method explicitly, as it is called automatically when the DicomPrint object goes out of scope.
Any pending film boxes are printed (using an implicit PrintFilm method) before the association is closed.
See Also

DicomPrint Object | DicomPrint Members


Open Method

Open Method
DicomObjects Reference > DicomPrint Object : Open Method
Description
Open connection to a printer
Syntax
Visual Basic
Public Sub Open()
Example
The destination should already have been set before this method is called using the Node, Port, CallingAE and CalledAE properties.
Although no result is returned, success at subsequent statements can always be assumed, as failure will produce a (trappable) error.
As part of this method the well-known printer object is retrieved, so after this call, the Printer property becomes valid.
See Also

DicomPrint Object | DicomPrint Members


PrintFilm Method

PrintFilm Method
DicomObjects Reference > DicomPrint Object : PrintFilm Method
Description
Print a film now
Syntax
Visual Basic
Public Sub PrintFilm()
Remarks
This method is implicitly called once a film becomes “full” as a result of PrintImage calls, or when Close is (explicitly or implicitly) called but this method is provided for those wishing to flush a film to start subsequent images on a new sheet.
See Also

DicomPrint Object | DicomPrint Members


PrintImage Method

PrintImage Method
DicomObjects Reference > DicomPrint Object : PrintImage Method
The image to print
If true, the image is presumed to be pre-formatted (e.g. from a PrinterImage method), and is sent without modification, but if false (the norm), then an internal PrinterImage method is called first, thereby “fixing” the windowing, and (if UseLabels is true) adding any annotations.
If Raw is false, and this parameter is true, then any DicomLabels or DICOM annotations are “burnt-in” to the pixel data before the image is sent to the printer.
Description
Send an image to the printer
Syntax
Visual Basic
Public Sub PrintImage( _
   ByVal Image As DicomImage, _
   ByVal Raw As Boolean, _
   ByVal UseLabels As Boolean _
)
Parameters
Image
The image to print
Raw
If true, the image is presumed to be pre-formatted (e.g. from a PrinterImage method), and is sent without modification, but if false (the norm), then an internal PrinterImage method is called first, thereby “fixing” the windowing, and (if UseLabels is true) adding any annotations.
UseLabels
If Raw is false, and this parameter is true, then any DicomLabels or DICOM annotations are “burnt-in” to the pixel data before the image is sent to the printer.
Remarks
Unless the order is altered explicitly using NextPosition or PrintFilm, images are put into each of the image boxes on the film in the default order, and each film is printed once full.
See Also

DicomPrint Object | DicomPrint Members


AnnotationFormat Property

AnnotationFormat Property
DicomObjects Reference > DicomPrint Object : AnnotationFormat Property
Description
Requested annotation format
Property type
Read-write property
Syntax
Visual Basic
Public Property AnnotationFormat As String
Remarks

These are the most commonly used variables when printing so they are given names, so that users do not need to remember the attribute tags for each, and which of the Datasets they apply to. These properties are simply shortcuts to values in Session or FilmBox. The equivalences and default values are as below:

Property | DataSet | Tags | Default
FilmSize | FilmBox | 2010,0050 | blank (printer default)
Orientation | FilmBox | 2010,0040 | PORTRAIT
Format | FilmBox | 2010,0010 | STANDARD\1,1
AnnotationFormat | FilmBox | 2010,0030 | blank
Copies | Session | 2000,0010 | 1

See Also

DicomPrint Object | DicomPrint Members


Annotations Property

Annotations Property
DicomObjects Reference > DicomPrint Object : Annotations Property
Description
Annotations to add to film
Property type
Read-only property
Syntax
Visual Basic
Public Property Annotations As DicomDataSets
Remarks

Annotations allow one or more items of text to be added to each film printed (not each image). They are very printer-dependent, and many printers do not support them at all. The number and placement depend on the annotation format ID, which in DicomObjects should be placed, before the filmbox is created in the AnnotationFormat property. Each DicomDataSet in this collection corresponds to one annotation, and they must be added with appropriate tags (20300,0010 for the ID and 2030,0020 for the text). Alternatively, the AddAnnotation method may be used.

This type of “annotation” has limited usefulness as it is very printer-dependent, and DICOM annotations of this type should not be confused with the common annotations in the form of graphics or text overlaid onto an image, achieved using DicomLabel objects.

See Also

DicomPrint Object | DicomPrint Members


BitDepth Property

BitDepth Property
DicomObjects Reference > DicomPrint Object : BitDepth Property
Description
The Bit depth to render images to for printing
Property type
Read-write property
Syntax
Visual Basic
Public Property BitDepth As Integer
Remarks
Not all printers support the same bit depths, and PrintImage uses this property to ensure that images are rendered to the appropriate number of bits before being sent to the printer (though if the Raw parameter is true, this becomes the user’s responsibility)
See Also

DicomPrint Object | DicomPrint Members


CalledAE Property

CalledAE Property
DicomObjects Reference > DicomPrint Object : CalledAE Property
Description
The application entity title of the Printer
Property type
Read-write property
Syntax
Visual Basic
Public Property CalledAE As String
Remarks
Some servers allow access from any application entity, whilst others must be configured to include a list of “allowable” clients. Whilst this software allows an arbitrary choice of AE name, it would be prudent to keep to a limited, unique list for each machine.
See Also

DicomPrint Object | DicomPrint Members


CallingAE Property

CallingAE Property
DicomObjects Reference > DicomPrint Object : CallingAE Property
Description
The application entity title by which the DicomPrint object is to be known
Property type
Read-write property
Syntax
Visual Basic
Public Property CallingAE As String
Remarks
For most servers this value must be looked up in the server’s documentation, and must be exactly correct for an association to be accepted.
See Also

DicomPrint Object | DicomPrint Members


Colour Property

Colour Property
DicomObjects Reference > DicomPrint Object : Colour Property
Description
Controls whether to use colour printing
Property type
Read-write property
Syntax
Visual Basic
Public Property Colour As Boolean
Remarks
If true, then the DicomPrint objects attempts to use the Basic Colour Print Meta SOP class, but if false, then the Basic Greyscale Print Meta SOP class is used. The film box classes are also changed to suit, and PrintImage uses this property to ensure that images are rendered appropriately (though if the Raw parameter is true, this becomes the user’s responsibility)
See Also

DicomPrint Object | DicomPrint Members


Connection Property

Connection Property
DicomObjects Reference > DicomPrint Object : Connection Property
Description
The DicomConnection used by a DicomPrint Object
Property type
Read-write property
Syntax
Visual Basic
Public Property Connection As DicomConnection
Remarks
This property is useful when extra operations are required over a print association, and enables you to use the simplified interface provided by DicomPrint, yet still have flexibility to make arbitrary requests. In particular, it can be used to N-GET the well-known printer instance during an association to check for the printer’s status.
The Mode property will always be doSync, and cannot be changed.
See Also

DicomPrint Object | DicomPrint Members


Copies Property

Copies Property
DicomObjects Reference > DicomPrint Object : Copies Property
Description
Copies requested
Property type
Read-write property
Syntax
Visual Basic
Public Property Copies As Integer
Remarks

These are the most commonly used variables when printing so they are given names, so that users do not need to remember the attribute tags for each, and which of the Datasets they apply to. These properties are simply shortcuts to values in Session or FilmBox. The equivalences and default values are as below:

Property | DataSet | Tags | Default
FilmSize | FilmBox | 2010,0050 | blank (printer default)
Orientation | FilmBox | 2010,0040 | PORTRAIT
Format | FilmBox | 2010,0010 | STANDARD\1,1
AnnotationFormat | FilmBox | 2010,0030 | blank
Copies | Session | 2000,0010 | 1

See Also

DicomPrint Object | DicomPrint Members


FilmBox Property

FilmBox Property
DicomObjects Reference > DicomPrint Object : FilmBox Property
Description
Attributes to use when creating a film box
Property type
Read-only property
Syntax
Visual Basic
Public Property FilmBox As DicomDataSet
Remarks
When any of these three type of objects are created during printing, values can be passed in the N-CREATE message, and the resulting dataset is retrieved. These properties allow the initial values to be set to any non-default values needed
Some of the more commonly used properties of these items have been given their own properties of the DicomPrint objects. These are FilmSize, Orientation, Format, AnnotationFormat & Copies. Values placed in any of these immediately update the corresponding values elements in the Session, Filmbox or ImageBox properties.
See Also

DicomPrint Object | DicomPrint Members


FilmSize Property

FilmSize Property
DicomObjects Reference > DicomPrint Object : FilmSize Property
Description
Film size to request
Property type
Read-write property
Syntax
Visual Basic
Public Property FilmSize As String
Remarks

These are the most commonly used variables when printing so they are given names, so that users do not need to remember the attribute tags for each, and which of the Datasets they apply to. These properties are simply shortcuts to values in Session or FilmBox. The equivalences and default values are as below:

Property | DataSet | Tags | Default
FilmSize | FilmBox | 2010,0050 | blank (printer default)
Orientation | FilmBox | 2010,0040 | PORTRAIT
Format | FilmBox | 2010,0010 | STANDARD\1,1
AnnotationFormat | FilmBox | 2010,0030 | blank
Copies | Session | 2000,0010 | 1

See Also

DicomPrint Object | DicomPrint Members


Format Property

Format Property
DicomObjects Reference > DicomPrint Object : Format Property
Description
Film size to request
Property type
Read-write property
Syntax
Visual Basic
Public Property Format As String
Remarks

These are the most commonly used variables when printing so they are given names, so that users do not need to remember the attribute tags for each, and which of the Datasets they apply to. These properties are simply shortcuts to values in Session or FilmBox. The equivalences and default values are as below:

Property | DataSet | Tags | Default
FilmSize | FilmBox | 2010,0050 | blank (printer default)
Orientation | FilmBox | 2010,0040 | PORTRAIT
Format | FilmBox | 2010,0010 | STANDARD\1,1
AnnotationFormat | FilmBox | 2010,0030 | blank
Copies | Session | 2000,0010 | 1

See Also

DicomPrint Object | DicomPrint Members


ImageBox Property

ImageBox Property
DicomObjects Reference > DicomPrint Object : ImageBox Property
Description
Attributes to set in an image box
Property type
Read-only property
Syntax
Visual Basic
Public Property ImageBox As DicomDataSet
Remarks
When any of these three type of objects are created during printing, values can be passed in the N-CREATE message, and the resulting dataset is retrieved. These properties allow the initial values to be set to any non-default values needed
Some of the more commonly used properties of these items have been given their own properties of the DicomPrint objects. These are FilmSize, Orientation, Format, AnnotationFormat & Copies. Values placed in any of these immediately update the corresponding values elements in the Session, Filmbox or ImageBox properties.
See Also

DicomPrint Object | DicomPrint Members


NextPosition Property

NextPosition Property
DicomObjects Reference > DicomPrint Object : NextPosition Property
Description
Get/Set position on film for next image
Property type
Read-write property
Syntax
Visual Basic
Public Property NextPosition As Long
Remarks
The value ranges from 1 to n where n is the number of images boxes in the current film box, which in turn depends on the value of Format. If this property is not altered, then images are printed sequentially.
See Also

DicomPrint Object | DicomPrint Members


Node Property

Node Property
DicomObjects Reference > DicomPrint Object : Node Property
Description
The IP address at which the Printer may be found
Property type
Read-write property
Syntax
Visual Basic
Public Property Node As String
Remarks
This may be any form of IP address, either dotted numerical or text name, understandable by the machines IP implementation.
See Also

DicomPrint Object | DicomPrint Members


ObjectType Property

ObjectType Property
DicomObjects Reference > DicomPrint Object : ObjectType Property
Description
Describes the nature of an automation object
Property type
Read-only property
Syntax
Visual Basic
Public Property ObjectType As String
Remarks

The possible values are as follows:

“DicomViewer”
“DicomQuery”
“DicomImage”
“DicomImages”
“DicomDataSet”
“DicomDataSets”
“DicomAttribute”
“DicomConnection”
“DicomConnections”
“DicomContext”
“DicomContexts”
“DicomLabel”
“DicomLabels”
“DicomGlobal”
“DicomLog”
“DicomPrint”

See Also

DicomPrint Object | DicomPrint Members


Orientation Property

Orientation Property
DicomObjects Reference > DicomPrint Object : Orientation Property
Description
Film orientation to request
Property type
Read-write property
Syntax
Visual Basic
Public Property Orientation As String
Remarks

These are the most commonly used variables when printing so they are given names, so that users do not need to remember the attribute tags for each, and which of the Datasets they apply to. These properties are simply shortcuts to values in Session or FilmBox. The equivalences and default values are as below:

Property | DataSet | Tags | Default
FilmSize | FilmBox | 2010,0050 | blank (printer default)
Orientation | FilmBox | 2010,0040 | PORTRAIT
Format | FilmBox | 2010,0010 | STANDARD\1,1
AnnotationFormat | FilmBox | 2010,0030 | blank
Copies | Session | 2000,0010 | 1

See Also

DicomPrint Object | DicomPrint Members


Port Property

Port Property
DicomObjects Reference > DicomPrint Object : Port Property
Description
The TCP port at which the Printer is listening
Property type
Read-write property
Syntax
Visual Basic
Public Property Port As Integer
Remarks
The “official” value for DICOM should be 104, but many manufacturers use other values such as 4006. Please check with the documentation of the service provider.
See Also

DicomPrint Object | DicomPrint Members


Printer Property

Printer Property
DicomObjects Reference > DicomPrint Object : Printer Property
Description
The well-known printer object (valid after Open)
Property type
Read-only property
Syntax
Visual Basic
Public Property Printer As DicomDataSet
Remarks
When the DicomPrint Open method is called, the well-known SOP instance representing the printer is retrieved, and placed into this property, which may allow some useful information about the printer and it’s current state to be determined before attempting to print any images.
Please check the printer’s conformance statement for more details of what information may be available.
To get updated information after the initial connection, use an NGet operation on the Connection object.
See Also

DicomPrint Object | DicomPrint Members


Session Property

Session Property
DicomObjects Reference > DicomPrint Object : Session Property
Description
Attributes to use when creating a film session
Property type
Read-only property
Syntax
Visual Basic
Public Property Session As DicomDataSet
Remarks
When any of these three type of objects are created during printing, values can be passed in the N-CREATE message, and the resulting dataset is retrieved. These properties allow the initial values to be set to any non-default values needed
Some of the more commonly used properties of these items have been given their own properties of the DicomPrint objects. These are FilmSize, Orientation, Format, AnnotationFormat & Copies. Values placed in any of these immediately update the corresponding values elements in the Session, Filmbox or ImageBox properties.
See Also

DicomPrint Object | DicomPrint Members


Tag Property

Tag Property
DicomObjects Reference > DicomPrint Object : Tag Property
Description
General Purpose Tag
Property type
Read-write property
Syntax
Visual Basic
Public Property Tag As Variant
Remarks

Tag properties are attached to most objects in DicomObjects. The values are not used by the associated object, and are available for user use. A special case is the DicomConnection object, where Tag is included in the ActionComplete event procedure, assisting identification of necessary features of the connection, such as pending database operations etc. In this use, the value of Tag is stored at the time an operation is initiated, and it is this stored value which is passed to ActionComplete, simplifying the task of tracking which operations have happened.

The TagObject property holds another object, typically a DicomLabels collection, and this can be useful when arranging DicomLabel objects into groups.

See Also

DicomPrint Object | DicomPrint Members


DicomProjection Object

DicomProjection Object
Members
DicomObjects Reference : DicomProjection Object
Description
This class provides a "view" of an image, including both 3D images and Fusion image.
See Also

DicomProjection Members


DicomProjection Object Members

DicomProjection Object Members
Overview
DicomObjects Reference : DicomProjection Object
Public Methods
Public Method Cut | Cut Display
Public Method RemoveLastCut | Remove the latest remaining cut line
Public Method RestoreView | Restore the current view
Public Method Rotate | Rotate
Public Method SaveView | Save the current view
Public Method SetViewPlane | Reset Display
Public Method TranslateMm | Translate by X,Y,Z Mm in real world space
Public Method TranslateNormal | Translate Z Mm normal to display
Public Method TranslatePixels | TranslatePixels
Public Method Zoom | Zoom
See Also

DicomProjection Object


Cut Method

Cut Method
DicomObjects Reference > DicomProjection Object : Cut Method
Description
Cut Display
Syntax
Visual Basic
Public Sub Cut( _
   ByVal Label As DicomLabel _
)
Parameters
Label
See Also

DicomProjection Object | DicomProjection Members


RemoveLastCut Method

RemoveLastCut Method
DicomObjects Reference > DicomProjection Object : RemoveLastCut Method
Description
Remove the latest remaining cut line
Syntax
Visual Basic
Public Sub RemoveLastCut()
See Also

DicomProjection Object | DicomProjection Members


RestoreView Method

RestoreView Method
DicomObjects Reference > DicomProjection Object : RestoreView Method
Description
Restore the current view
Syntax
Visual Basic
Public Sub RestoreView( _
   ByVal State As Variant _
)
Parameters
State
See Also

DicomProjection Object | DicomProjection Members


Rotate Method

Rotate Method
DicomObjects Reference > DicomProjection Object : Rotate Method
Description
Rotate
Syntax
Visual Basic
Public Sub Rotate( _
   ByVal Theta As Single, _
   ByVal x As Single, _
   ByVal y As Single, _
   ByVal Z As Single _
)
Parameters
Theta
x
y
Z
See Also

DicomProjection Object | DicomProjection Members


SaveView Method

SaveView Method
DicomObjects Reference > DicomProjection Object : SaveView Method
Description
Save the current view
Syntax
Visual Basic
Public Function SaveView() As Variant
See Also

DicomProjection Object | DicomProjection Members


SetViewPlane Method

SetViewPlane Method
DicomObjects Reference > DicomProjection Object : SetViewPlane Method
Description
Reset Display
Syntax
Visual Basic
Public Sub SetViewPlane( _
   ByVal plane As doPlane, _
   ByVal Recentre As Boolean, _
   ByVal Zoom As Single _
)
Parameters
plane
Value | Description
doPlaneAxial | Typical a cross-section of a patient
doPlaneCoronal | A slice as if viewed from the front/back
doPlaneSagittal | A slice as if viewed from the side
doPlaneUnchanged | As a special Plane, which when used in SetViewPlane indicates the view plane should be left unaltered.
Recentre
Zoom
See Also

DicomProjection Object | DicomProjection Members


TranslateMm Method

TranslateMm Method
DicomObjects Reference > DicomProjection Object : TranslateMm Method
Description
Translate by X,Y,Z Mm in real world space
Syntax
Visual Basic
Public Sub TranslateMm( _
   ByVal x As Single, _
   ByVal y As Single, _
   ByVal Z As Single _
)
Parameters
x
y
Z
See Also

DicomProjection Object | DicomProjection Members


TranslateNormal Method

TranslateNormal Method
DicomObjects Reference > DicomProjection Object : TranslateNormal Method
Description
Translate Z Mm normal to display
Syntax
Visual Basic
Public Sub TranslateNormal( _
   ByVal Z As Single _
)
Parameters
Z
See Also

DicomProjection Object | DicomProjection Members


TranslatePixels Method

TranslatePixels Method
DicomObjects Reference > DicomProjection Object : TranslatePixels Method
Description
TranslatePixels
Syntax
Visual Basic
Public Sub TranslatePixels( _
   ByVal x As Single, _
   ByVal y As Single _
)
Parameters
x
y
See Also

DicomProjection Object | DicomProjection Members


Zoom Method

Zoom Method
DicomObjects Reference > DicomProjection Object : Zoom Method
Description
Zoom
Syntax
Visual Basic
Public Sub Zoom( _
   ByVal Zoom As Single _
)
Parameters
Zoom
See Also

DicomProjection Object | DicomProjection Members


DicomQuery Object

DicomQuery Object
Members
DicomObjects Reference : DicomQuery Object
Description

A DicomQuery Object is an externally creatable OLE automation object that facilitates the querying of information and retrieval of images from DICOM servers that support the Query/Retrieve protocols as a Service Class Provider (SCP)

A useful feature of this object is that is re-usable, so as the user descends though a hierarchical search, new constraints may be added, and the search repeated, with having to re-set those already used.

Remarks

The query object can be used either to retrieve images to itself for data extraction, conversion to JPEG etc., or it may initiate DICOM C-MOVE requests to send the images to another entity, commonly a DicomViewer control.

An instance of this object may be created using the title “DicomObjects.DicomQuery”, and in Visual Basic the code would be:

Creat a DicomQuery
Copy Code
Dim q As DicomQuery
Set q=CreateObject(“DicomObjects.DicomQuery”)

Alternatively, the DicomViewer’s New method may be used.

See Also

DicomQuery Members


DicomQuery Object Members

DicomQuery Object Members
Overview
DicomObjects Reference : DicomQuery Object
Public Methods
Public Method DoQuery | Send a C_FIND query request to a DICOM server, and return the results
Public Method DoRawQuery | Send a flexible C_FIND query request to a DICOM server, and return the results
Public Method GetImages | Send a C_GET retrieve request to a DICOM server, and returns the resulting images
Public Method GetUsingMove | Synchronous retrieval of images using C-MOVE
Public Method MoveImages | Send a C_MOVE request to a DICOM server
Public Method MoveSync | Synchronous C-MOVE request with returned status
Public Method QueryDataSet | Returns a 'basic' dataset as would be used in DoQuery for modification and use in DoRawQuery
Public Properties
Public Property AccessionNumber | The Accession Number to Query
Public Property CalculatedFrameList | Calculated set of Frames for Frame level retrieve
Public Property CalledAE | The application entity title of the server providing the Query/Retrieve service
Public Property CallingAE | The application entity title by which the DicomQuery object is to be known
Public Property DateOfBirth | The patient's date of birth
Public Property Destination | The Application Entity Name to which a MoveImages request should be sent
Public Property FrameTimes | Time Range for Frame level retrieve
Public Property InstanceUID | Unique Image identifier
Public Property Level | Defines the type of query requested within the DICOM search hierarchies
Public Property LocalCertificate | X509 (CAPICOM) certificate to be used in negotiation
Public Property Name | The patient's Name
Public Property NoBulkData | Specify if bulk data is required in the FrameLevelRetrieve C-GET response (e.g. pixel data, etc)
Public Property Node | The IP address at which the Query/Retrieve service may be found
Public Property ObjectType | Describes the nature of an automation object
Public Property PatientID | Patient identifier
Public Property Port | The TCP port at which the Query/Retrieve service is listening
Public Property ReceivePort | Port to receive images on for GetUsingMove
Public Property RemoteCertificate | X509 (CAPICOM) certificate provided by remote entity
Public Property Root | Defines the type of query requested within the DICOM search hierarchies
Public Property SeriesUID | Unique Series identifier
Public Property Sex | The patient's sex
Public Property SimpleFrameList | Simple List of Frames for Frame level retrieve
Public Property StudyDate | Date of the study as a date or DICOM formatted date range
Public Property StudyUID | Unique Study identifier
Public Property Tag | General Purpose Tag
Public Property TransferSyntaxes | Over-ride of transfer syntaxes to use
Public Property UseTLS | Controls whether to negotiate a secure association using TLS
See Also

DicomQuery Object


DoQuery Method

DoQuery Method
DicomObjects Reference > DicomQuery Object : DoQuery Method
Description
Send a C_FIND query request to a DICOM server, and return the results
Syntax
Visual Basic
Public Function DoQuery() As DicomDataSets
Remarks
This method takes no parameters, as all values are set as properties of the DicomQuery Object.
The returned value is an object of type DicomDataSets, containing one DicomDataSet for each successful match. An unsuccessful search produces no error, but the Count property of the returned DicomDataSets objects will be zero.
See Also

DicomQuery Object | DicomQuery Members


DoRawQuery Method

DoRawQuery Method
DicomObjects Reference > DicomQuery Object : DoRawQuery Method
A DataSet containing ALL the data elements necessary for a C-FIND request, including both those to be matched, and those required to be returned.
Description
Send a flexible C_FIND query request to a DICOM server, and return the results
Syntax
Visual Basic
Public Function DoRawQuery( _
   ByVal QueryDataSet As DicomDataSet _
) As DicomDataSets
Parameters
QueryDataSet
A DataSet containing ALL the data elements necessary for a C-FIND request, including both those to be matched, and those required to be returned.
Remarks

This method is intended for advanced users, requiring more control over the query than can be achieved using the query object’s standard properties, and methods. Note that even the QueryLevel value, must be included in the data set.
The returned value is an object of type DicomDataSets, containing one DicomDataSet for each successful match. An unsuccessful search produces no error, but the Count property of the returned DicomDataSets objects will be zero.

This method MUST be used (rather than DoQuery) if QueryRoot is set to “WORKLIST” or “GP-WORKLIST”.
In many cases, where only a small variation from a “standard” query is required, the QueryDataSet method may be used to generate a standard dataset suitable for modification and then use by this method.

See Also

DicomQuery Object | DicomQuery Members


GetImages Method

GetImages Method
DicomObjects Reference > DicomQuery Object : GetImages Method
Description
Send a C_GET retrieve request to a DICOM server, and returns the resulting images
Syntax
Visual Basic
Public Function GetImages() As DicomImages
Remarks
This method takes no parameters, as all values are set as properties of the DicomQuery Object.
The returned value is an object of type DicomImages, containing one DicomImage for each successful match. An unsuccessful retrieval produces no error, but the Count property of the returned DicomImages objects will be zero.
Note that many servers do not support the C-GET protocol required for this method, requiring instead C-MOVE. In this case, the GetUsingMove method is advised as an alternative.
See Also

DicomQuery Object | DicomQuery Members


GetUsingMove Method

GetUsingMove Method
DicomObjects Reference > DicomQuery Object : GetUsingMove Method
Description
Synchronous retrieval of images using C-MOVE
Syntax
Visual Basic
Public Function GetUsingMove() As DicomImages
Remarks

This is a major new facility in DicomObjects, allowing C-MOVE to be used as easily as C-GET (GetImages). This is important, as many commonly available servers refuse to support the C-GET protocol, forcing use of C-MOVE. While MoveImages has been available in DicomObjects for some time, it is difficult to use, requiring close co-ordination between a listening object (DicomViewer or DicomServer) and a DicomQuery object. GetUsingMove handles all the necessary co-ordination internally, opening a port, receiving the images, and presenting them, just like GetImages. Before using this method, the DicomQuery object’s Destination and ReceivePort properties must have been set to appropriate values, such that the destination name is known to the server, and maps to the ReceivePort and IP address from which the query is being sent.

Notes:

  • C-MOVE is more complicated to set up than C-GET, and there it cannot work unless the application entity name, port and IP address have been set up on the server. This is a fundamental limitation of the protocol as only the destination AE title can be specified in a C-MOVE request, not a port or IP address.
  • The port used to receive the images may be shared between several simultaneous GetUsingMove requests (which will generally allocate the images appropriately), but it must not be in use by other listening objects such as a DicomViewer.
  • When receiving from eFilm, a special registry value “IgnoreMessageID” type DWORD, value 1 must be set alongside the other DicomObjects values, as eFilm does not send the correct information to allow images received to be matched to the request.
See Also

DicomQuery Object | DicomQuery Members


MoveImages Method

MoveImages Method
DicomObjects Reference > DicomQuery Object : MoveImages Method
Description
Send a C_MOVE request to a DICOM server
Syntax
Visual Basic
Public Sub MoveImages()
Remarks

This method takes no parameters, as all values are set as properties of the DicomQuery Object.
Images are requested to be transferred to the application entity specified by the DicomQuery object’s Destination property.
The reason that no result is returned is that this method is commonly used to transfer images to a DicomViewer control running within the same container as the DicomQuery object. Were the viewer control and DicomQuery object to run in the same thread, a deadlock could occur due to the need to call the AssociationRequest event of the control, before the MoveImages status could be reported. MoveImages is therefore implemented on an independent thread, the main thread returning immediately.

This method has been retained for backwards compatibility, but three alternatives now exist, each suitable for different scenarios:

GetUsingMove: For moving to the same application making the call (synchronously)
MoveSync: For moving images to different application (synchronously)
Move (DicomConnection): For moving anywhere asynchronously

See Also

DicomQuery Object | DicomQuery Members


MoveSync Method

MoveSync Method
DicomObjects Reference > DicomQuery Object : MoveSync Method
Description
Synchronous C-MOVE request with returned status
Syntax
Visual Basic
Public Function MoveSync() As Long
Remarks

This method is essentially the same as MoveImages, except that it does not return until the C-MOVE request completes, and can therefore check the final status received from the C-MOVE SCP.
This method must not be used to transfer images to a listener within the same program (or at least not one created on the same thread), as the AssociationRequest and ImageReceived will not be able to fire, and a deadlock will occur. It should only therefore be used for genuine third-party C-MOVE requests.

For applications where it may be necessary to move to the requesting SCU, or where more complete status and feedback information is required, then the DicomConnection.Move method should be considered instead.
Note: Any status code except 0 (success) will result in a trappable error (1415). The return values is therefore the number of images transferred.

See Also

DicomQuery Object | DicomQuery Members


QueryDataSet Method

QueryDataSet Method
DicomObjects Reference > DicomQuery Object : QueryDataSet Method
Description
Returns a 'basic' dataset as would be used in DoQuery for modification and use in DoRawQuery
Syntax
Visual Basic
Public Function QueryDataSet() As DicomDataSet
Remarks
This method returns exactly the same dataset that would have been used for a DoQuery method, which depends on most of the other DicomQuery parameters such as QueryRoot, QueryLevel etc. The result is suitable for passing to DoRawQuery, normally after some modification/addition and this method is particularly useful where a slight variation on the “standard” queries generated by DoQuery is required, but the user does not wish to generate a whole new dataset from scratch.
See Also

DicomQuery Object | DicomQuery Members


AccessionNumber Property

AccessionNumber Property
DicomObjects Reference > DicomQuery Object : AccessionNumber Property
Description
The Accession Number to Query
Property type
Read-write property
Syntax
Visual Basic
Public Property AccessionNumber As String
See Also

DicomQuery Object | DicomQuery Members


CalculatedFrameList Property

CalculatedFrameList Property
DicomObjects Reference > DicomQuery Object : CalculatedFrameList Property
Description
Calculated set of Frames for Frame level retrieve
Property type
Read-write property
Syntax
Visual Basic
Public Property CalculatedFrameList As Variant
Remarks
Specify the list of frames (by triplets with the starting frame, ending frame and frame step) for Frame Level Retrieval
See Also

DicomQuery Object | DicomQuery Members


CalledAE Property

CalledAE Property
DicomObjects Reference > DicomQuery Object : CalledAE Property
Description
The application entity title of the server providing the Query/Retrieve service
Property type
Read-write property
Syntax
Visual Basic
Public Property CalledAE As String
Remarks
Some servers allow access from any application entity, whilst others must be configured to include a list of “allowable” clients. Whilst this software allows an arbitrary choice of AE name, it would be prudent to keep to a limited, unique list for each machine.
See Also

DicomQuery Object | DicomQuery Members


CallingAE Property

CallingAE Property
DicomObjects Reference > DicomQuery Object : CallingAE Property
Description
The application entity title by which the DicomQuery object is to be known
Property type
Read-write property
Syntax
Visual Basic
Public Property CallingAE As String
Remarks
For most servers this value must be looked up in the server’s documentation, and must be exactly correct for an association to be accepted.
See Also

DicomQuery Object | DicomQuery Members


DateOfBirth Property

DateOfBirth Property
DicomObjects Reference > DicomQuery Object : DateOfBirth Property
Description
The patient's date of birth
Property type
Read-write property
Syntax
Visual Basic
Public Property DateOfBirth As String
Remarks

This really just a shortcut for attribute (0010,0010).

See Also

DicomQuery Object | DicomQuery Members


Destination Property

Destination Property
DicomObjects Reference > DicomQuery Object : Destination Property
Description
The Application Entity Name to which a MoveImages request should be sent
Property type
Read-write property
Syntax
Visual Basic
Public Property Destination As String
Remarks
This property is used in conjunction with the MoveImages , MoveSync and GetUsingMove methods of a DicomQuery object. The Application entity name must be known to the DICOM server to which the request is being sent, as the standard allows no other means of specifying the destination. In particular, it is not possible to direct images to an arbitrary IP address and port using MoveImages.
A Query/Retrieve SCP must use this property of the DicomConnection object to find the values of the IP address, port, and possibly calling AET to use before calling SetDestination.
See Also

DicomQuery Object | DicomQuery Members


FrameTimes Property

FrameTimes Property
DicomObjects Reference > DicomQuery Object : FrameTimes Property
Description
Time Range for Frame level retrieve
Property type
Read-write property
Syntax
Visual Basic
Public Property FrameTimes As Variant
See Also

DicomQuery Object | DicomQuery Members


InstanceUID Property

InstanceUID Property
DicomObjects Reference > DicomQuery Object : InstanceUID Property
Description
Unique Image identifier
Property type
Read-write property
Syntax
Visual Basic
Public Property InstanceUID As String
Remarks

This really just a shortcut for attribute (0010,0020).

See Also

DicomQuery Object | DicomQuery Members


Level Property

Level Property
DicomObjects Reference > DicomQuery Object : Level Property
Description
Defines the type of query requested within the DICOM search hierarchies
Property type
Read-write property
Syntax
Visual Basic
Public Property Level As String
Remarks

DICOM defines three different hierarchies for image-related Query/Retrieve operations, each of which has different semantics and allowable search levels. The allowable combinations of QueryRoot and QueryLevel are:

QueryRoot | PATIENT | STUDY | PATIENTSTUDY
QueryLevel | PATIENT | STUDY | PATIENT
 | STUDY | SERIES | STUDY
 | SERIES | IMAGE |
 | IMAGE |  |

In addition, to the above values, QueryRoot may be set to “WORKLIST” to indicate a Modality Worklist query, or “GP-WORKLIST” to indicate a general purpose worklist query, but if this is done, then a DoRawQuery must be performed, as the parameters for the query DataSet are very different to those used for the other queries.

See Also

DicomQuery Object | DicomQuery Members


LocalCertificate Property

LocalCertificate Property
DicomObjects Reference > DicomQuery Object : LocalCertificate Property
Description
X509 (CAPICOM) certificate to be used in negotiation
Property type
Read-write property
Syntax
Visual Basic
Public Property LocalCertificate As Object
Remarks

The LocalCertificate specifies the certificate to present to the remote entity when initiating an association (when acting as a receiver, use ListenSecure, which includes a certificate in it’s parameters). If UseTLS is true, but this property is null, then an anonymous association attempt will be made, which may or may not be accepted by the remote entity.

RemoteCertificate allows an application to verify the certificate presented by the remote entity, which may be done in 3 ways:

When receiving an incoming association in AssociationRequest2, the remote certificate is available as a property of the new incoming association, allowing an accept/reject decision to be made based on it’s contents (it may be NULL if an anonymous association has been attempted).
After making an outgoing association using SetDestination, the remote certificate is available once this operation has completed (during ActionComplete or one isReady is true). This is the correct place for a client to validate the server before performing sensitive transactions, as it protects against a “man-in-the-middle” attack.

After an outgoing DicomQuery based operation has completed, this property indicates the certificate which has been provided. Note of course, that this is useful only for auditing, not control, as it is available only after data has been exchanged, so in a proper secure application, the DicomQuery based methods should be replaced by their DicomConnection based equivalents, which allow prior validation.

For more information on using X509 certificates in DicomObjects, see Certificates

See Also

DicomQuery Object | DicomQuery Members


Name Property

Name Property
DicomObjects Reference > DicomQuery Object : Name Property
Description
The patient's Name
Property type
Read-write property
Syntax
Visual Basic
Public Property Name As String
Remarks

This really just a shortcut for attribute (0010,0010).

See Also

DicomQuery Object | DicomQuery Members


NoBulkData Property

NoBulkData Property
DicomObjects Reference > DicomQuery Object : NoBulkData Property
Description
Specify if bulk data is required in the FrameLevelRetrieve C-GET response (e.g. pixel data, etc)
Property type
Read-write property
Syntax
Visual Basic
Public Property NoBulkData As Boolean
See Also

DicomQuery Object | DicomQuery Members


Node Property

Node Property
DicomObjects Reference > DicomQuery Object : Node Property
Description
The IP address at which the Query/Retrieve service may be found
Property type
Read-write property
Syntax
Visual Basic
Public Property Node As String
Remarks
This may be any form of IP address, either dotted numerical or text name, understandable by the machines IP implementation.
See Also

DicomQuery Object | DicomQuery Members


ObjectType Property

ObjectType Property
DicomObjects Reference > DicomQuery Object : ObjectType Property
Description
Describes the nature of an automation object
Property type
Read-only property
Syntax
Visual Basic
Public Property ObjectType As String
Remarks

The possible values are as follows:

“DicomViewer”
“DicomQuery”
“DicomImage”
“DicomImages”
“DicomDataSet”
“DicomDataSets”
“DicomAttribute”
“DicomConnection”
“DicomConnections”
“DicomContext”
“DicomContexts”
“DicomLabel”
“DicomLabels”
“DicomGlobal”
“DicomLog”
“DicomPrint”

See Also

DicomQuery Object | DicomQuery Members


PatientID Property

PatientID Property
DicomObjects Reference > DicomQuery Object : PatientID Property
Description
Patient identifier
Property type
Read-write property
Syntax
Visual Basic
Public Property PatientID As String
Remarks

This really just a shortcut for attribute (0010,0020).

See Also

DicomQuery Object | DicomQuery Members


Port Property

Port Property
DicomObjects Reference > DicomQuery Object : Port Property
Description
The TCP port at which the Query/Retrieve service is listening
Property type
Read-write property
Syntax
Visual Basic
Public Property Port As Integer
Remarks
The “official” value for DICOM should be 104, but many manufacturers use other values such as 4006. Please check with the documentation of the service provider.
See Also

DicomQuery Object | DicomQuery Members


ReceivePort Property

ReceivePort Property
DicomObjects Reference > DicomQuery Object : ReceivePort Property
Description
Port to receive images on for GetUsingMove
Property type
Read-write property
Syntax
Visual Basic
Public Property ReceivePort As Long
Remarks
See GetUsingMove for further details.
See Also

DicomQuery Object | DicomQuery Members


RemoteCertificate Property

RemoteCertificate Property
DicomObjects Reference > DicomQuery Object : RemoteCertificate Property
Description
X509 (CAPICOM) certificate provided by remote entity
Property type
Read-write property
Syntax
Visual Basic
Public Property RemoteCertificate As Object
Remarks

The LocalCertificate specifies the certificate to present to the remote entity when initiating an association (when acting as a receiver, use ListenSecure, which includes a certificate in it’s parameters). If UseTLS is true, but this property is null, then an anonymous association attempt will be made, which may or may not be accepted by the remote entity.

RemoteCertificate allows an application to verify the certificate presented by the remote entity, which may be done in 3 ways:

When receiving an incoming association in AssociationRequest2, the remote certificate is available as a property of the new incoming association, allowing an accept/reject decision to be made based on it’s contents (it may be NULL if an anonymous association has been attempted).
After making an outgoing association using SetDestination, the remote certificate is available once this operation has completed (during ActionComplete or one isReady is true). This is the correct place for a client to validate the server before performing sensitive transactions, as it protects against a “man-in-the-middle” attack.

After an outgoing DicomQuery based operation has completed, this property indicates the certificate which has been provided. Note of course, that this is useful only for auditing, not control, as it is available only after data has been exchanged, so in a proper secure application, the DicomQuery based methods should be replaced by their DicomConnection based equivalents, which allow prior validation.

For more information on using X509 certificates in DicomObjects, see Certificates

See Also

DicomQuery Object | DicomQuery Members


Root Property

Root Property
DicomObjects Reference > DicomQuery Object : Root Property
Description
Defines the type of query requested within the DICOM search hierarchies
Property type
Read-write property
Syntax
Visual Basic
Public Property Root As String
Remarks

DICOM defines three different hierarchies for image-related Query/Retrieve operations, each of which has different semantics and allowable search levels. The allowable combinations of QueryRoot and QueryLevel are:

QueryRoot | PATIENT | STUDY | PATIENTSTUDY
QueryLevel | PATIENT | STUDY | PATIENT
 | STUDY | SERIES | STUDY
 | SERIES | IMAGE |
 | IMAGE |  |

In addition, to the above values, QueryRoot may be set to “WORKLIST” to indicate a Modality Worklist query, or “GP-WORKLIST” to indicate a general purpose worklist query, but if this is done, then a DoRawQuery must be performed, as the parameters for the query DataSet are very different to those used for the other queries.

See Also

DicomQuery Object | DicomQuery Members


SeriesUID Property

SeriesUID Property
DicomObjects Reference > DicomQuery Object : SeriesUID Property
Description
Unique Series identifier
Property type
Read-write property
Syntax
Visual Basic
Public Property SeriesUID As String
Remarks

This really just a shortcut for attribute (0010,0020).

See Also

DicomQuery Object | DicomQuery Members


Sex Property

Sex Property
DicomObjects Reference > DicomQuery Object : Sex Property
Description
The patient's sex
Property type
Read-write property
Syntax
Visual Basic
Public Property Sex As String
Remarks

This really just a shortcut for attribute (0010,0010).

See Also

DicomQuery Object | DicomQuery Members


SimpleFrameList Property

SimpleFrameList Property
DicomObjects Reference > DicomQuery Object : SimpleFrameList Property
Description
Simple List of Frames for Frame level retrieve
Property type
Read-write property
Syntax
Visual Basic
Public Property SimpleFrameList As Variant
See Also

DicomQuery Object | DicomQuery Members


StudyDate Property

StudyDate Property
DicomObjects Reference > DicomQuery Object : StudyDate Property
Description
Date of the study as a date or DICOM formatted date range
Property type
Read-write property
Syntax
Visual Basic
Public Property StudyDate As String
Remarks
Like DateOfBirth, this property may either contain a single value, in any form intelligible as a date, or if a range is required, then it must comply exactly with the DICOM format for date ranges, namely YYYYMMDD-YYYYMMDD
See Also

DicomQuery Object | DicomQuery Members


StudyUID Property

StudyUID Property
DicomObjects Reference > DicomQuery Object : StudyUID Property
Description
Unique Study identifier
Property type
Read-write property
Syntax
Visual Basic
Public Property StudyUID As String
Remarks

This really just a shortcut for attribute (0010,0020).

See Also

DicomQuery Object | DicomQuery Members


Tag Property

Tag Property
DicomObjects Reference > DicomQuery Object : Tag Property
Description
General Purpose Tag
Property type
Read-write property
Syntax
Visual Basic
Public Property Tag As Variant
Remarks

Tag properties are attached to most objects in DicomObjects. The values are not used by the associated object, and are available for user use. A special case is the DicomConnection object, where Tag is included in the ActionComplete event procedure, assisting identification of necessary features of the connection, such as pending database operations etc. In this use, the value of Tag is stored at the time an operation is initiated, and it is this stored value which is passed to ActionComplete, simplifying the task of tracking which operations have happened.

The TagObject property holds another object, typically a DicomLabels collection, and this can be useful when arranging DicomLabel objects into groups.

See Also

DicomQuery Object | DicomQuery Members


TransferSyntaxes Property

TransferSyntaxes Property
DicomObjects Reference > DicomQuery Object : TransferSyntaxes Property
Description
Over-ride of transfer syntaxes to use
Property type
Read-write property
Syntax
Visual Basic
Public Property TransferSyntaxes As String
Remarks
If blank (the default) the default transfer syntax list specified by the registry keys (default or transfer syntax-specific) is used, but if , this value is non-blank then it over-rides the registry setting.
The list is space separated – e.g. “1.2.840.10008.1.2 1.2.40.10008.1.2.1”
Any syntaxes immediately preceded by an asterisk are sent in their own separate presentation context.
See Also

DicomQuery Object | DicomQuery Members


UseTLS Property

UseTLS Property
DicomObjects Reference > DicomQuery Object : UseTLS Property
Description
Controls whether to negotiate a secure association using TLS
Property type
Read-write property
Syntax
Visual Basic
Public Property UseTLS As Boolean
Remarks
If true, then new outgoing associations made using this object (using SetDestination for DicomConnection objects, or any of the Q/R methods such as DoQuery, GetImages etc. for DicomQuery) will use a secured connection.
Secure associations can be made with or without a client certificate, and this is controlled by the LocalCertificate property.
See Also

DicomQuery Object | DicomQuery Members


DicomServer Object

DicomServer Object
Members
DicomObjects Reference : DicomServer Object
Description
Automation object providing SCP functionality
Remarks
DicomServer objects are created directly by a user application, and provide a subset of the DicomViewer’s interfaces, such that all the Service Class Provider functionality is provided, without a user interface.
Since events are used to notify the container application of incoming requests, this object is only suitable for more recent containers (such as Visual Basic 5 or 6), that have the ability to attach event procedures to automation objects other than visible controls.
See Also

DicomServer Members


DicomServer Object Members

DicomServer Object Members
Overview
DicomObjects Reference : DicomServer Object
Public Methods
Public Method Listen | Opens a 'listening' TCP port for incoming DICOM Connections
Public Method ListenSecure | Listen for secure (TLS) incoming assocations
Public Method ListenSpecific | Listen on a specific IP address
Public Method New | Creates a new DicomConnection automation object
Public Method Unlisten | Closes a 'listening' TCP port
Public Method UnlistenSpecific | Stop listening on a specific IP address
Public Properties
Public Property DefaultStatus | Default status to be returned if event not captured
Public Property ObjectType | Describes the nature of an automation object
Public Property Tag | General Purpose Tag
Events
Public Event ActionComplete | fired when transmission of requests on a DicomConnection object is complete
Public Event ActionUpdate | fired when intermediate responses are received from the remote application
Public Event AssociationClosed | fired when an incoming association is closed
Public Event AssociationRequest | fired when the server receives a DICOM association request
Public Event EventReport | fired when an incoming N-EVENT-REPORT notification is received
Public Event InfoMessage | Passes information back to the container for error messages and notifications originating from the DICOM interface
Public Event InstanceReceived | fired whene an incoming C-STORE operation is received
Public Event NormalisedReceived | fired when an incoming request for a normalised operation is received
Public Event PixelsReceived | fired when Pixel data is received, allowing direct to disk receiving to be triggered
Public Event QueryRequest | fired when an incoming Query request is received
Public Event VerifyReceived | fired when an incoming C-ECHO request is received
See Also

DicomServer Object


Listen Method

Listen Method
DicomObjects Reference > DicomServer Object : Listen Method
The TCP port on which to receive connections
Description
Opens a 'listening' TCP port for incoming DICOM Connections
Syntax
Visual Basic
Public Function Listen( _
   ByVal Port As Long _
) As Boolean
Parameters
Port
The TCP port on which to receive connections
Remarks
More than one port may be active simultaneously. The listening sockets are all closed when the control is de-activated.
Closing a “listening” socket has no effect on currently active associations that connected via that socket.
Port is specified as a long integer, to avoid ambiguities in the range 8000-FFFF.
If the specific option is used, then address must be either in dotted form, or a resolvable name.
See Also

DicomServer Object | DicomServer Members


ListenSecure Method

ListenSecure Method
DicomObjects Reference > DicomServer Object : ListenSecure Method
The port number to listen on
The certificate (a CAPICOM certificate) to use to authenticate with the client
Whether to request the client to send its own certificate
Description
Listen for secure (TLS) incoming assocations
Syntax
Visual Basic
Public Function ListenSecure( _
   ByVal Port As Long, _
   ByVal Certificate As Object, _
   ByVal NeedClientCertificate As Boolean _
) As Boolean
Parameters
Port
The port number to listen on
Certificate
The certificate (a CAPICOM certificate) to use to authenticate with the client
NeedClientCertificate
Whether to request the client to send its own certificate
Remarks

This is the secure equivalent of the Listen method.

Different ports must be used for secure and non-secure associations, as the security negotiation occurs before DICOM negotiation. The remote entity’s certificate is available for checking (as the RemoteCertificate property of the DicomConnection) during Associationrequest2

More than one port may be active simultaneously. The listening sockets are all closed when the control is de-activated.

Closing a “listening” socket has no effect on currently active associations that connected via that socket.

Port is specified as a long integer, to avoid ambiguities in the range 8000-FFFF.
If the specific option is used, then address must be either in dotted form, or a resolvable name.

Note that requesting a client certificate does not guarantee that one will be sent.

See Also

DicomServer Object | DicomServer Members


ListenSpecific Method

ListenSpecific Method
DicomObjects Reference > DicomServer Object : ListenSpecific Method
The TCP port on which to receive connections
IP address to listen on
Description
Listen on a specific IP address
Syntax
Visual Basic
Public Function ListenSpecific( _
   ByVal Port As Long, _
   ByVal Address As String _
) As Boolean
Parameters
Port
The TCP port on which to receive connections
Address
IP address to listen on
Remarks
More than one port may be active simultaneously. The listening sockets are all closed when the control is de-activated.
Closing a “listening” socket has no effect on currently active associations that connected via that socket.
Port is specified as a long integer, to avoid ambiguities in the range 8000-FFFF.
If the specific option is used, then address must be either in dotted form, or a resolvable name.
See Also

DicomServer Object | DicomServer Members


New Method

New Method
DicomObjects Reference > DicomServer Object : New Method
The type of object to create - must be "DicomConnection"
Description
Creates a new DicomConnection automation object
Syntax
Visual Basic
Public Function New( _
   ByVal Type As String _
) As Object
Parameters
Type
The type of object to create - must be "DicomConnection"
Remarks

Only the value “DicomConnection” is valid for base objects of type DicomServer. The purpose of using this call, rather than allowing direct creation of DicomConnection objects, is to route ActionComplete events though a limited number of static objects, to which event handlers may easily be attached.

Unlike most other methods and properties in DicomObjects, this method returns a generic “IDispatch” pointer, which in most languages except Visual Basic must be cast to the appropriate known object type.

See Also

DicomServer Object | DicomServer Members


Unlisten Method

Unlisten Method
DicomObjects Reference > DicomServer Object : Unlisten Method
The TCP port on which to receive connections
Description
Closes a 'listening' TCP port
Syntax
Visual Basic
Public Sub Unlisten( _
   ByVal Port As Long _
)
Parameters
Port
The TCP port on which to receive connections
Remarks
More than one port may be active simultaneously. The listening sockets are all closed when the control is de-activated.
Closing a “listening” socket has no effect on currently active associations that connected via that socket.
Port is specified as a long integer, to avoid ambiguities in the range 8000-FFFF.
If the specific option is used, then address must be either in dotted form, or a resolvable name.
See Also

DicomServer Object | DicomServer Members


UnlistenSpecific Method

UnlistenSpecific Method
DicomObjects Reference > DicomServer Object : UnlistenSpecific Method
The TCP port on which to receive connections
IP address to listen on
Description
Stop listening on a specific IP address
Syntax
Visual Basic
Public Sub UnlistenSpecific( _
   ByVal Port As Long, _
   ByVal Address As String _
)
Parameters
Port
The TCP port on which to receive connections
Address
IP address to listen on
Remarks
More than one port may be active simultaneously. The listening sockets are all closed when the control is de-activated.
Closing a “listening” socket has no effect on currently active associations that connected via that socket.
Port is specified as a long integer, to avoid ambiguities in the range 8000-FFFF.
If the specific option is used, then address must be either in dotted form, or a resolvable name.
See Also

DicomServer Object | DicomServer Members


DefaultStatus Property

DefaultStatus Property
DicomObjects Reference > DicomServer Object : DefaultStatus Property
Description
Default status to be returned if event not captured
Property type
Read-write property
Syntax
Visual Basic
Public Property DefaultStatus As Long
Remarks

When incoming requests such as C-STORE, C-ECHO or normalised operations are received, a status code must be returned to the sender. Normally, this is supplied either by the final value of the “Status” parameter to the VerifyReceived or InstanceReceived event, or for C-STORE operation by a SendStatus call. Under some circumstances, however (such as when a message box is displayed in Visual Basic), events may not be fired, so this property provides a default value. It is used in the following circumstances:

  • It provides the initial value for the Status parameter for an InstanceReceived or VerifyReceved event
  • It provides the definitive value if the appropriate event is not fired or not captured
  • It is sent as the status if no call to SendStatus is made before the DicomConnection object is released.

Servers should normally set this value to a suitable error code, so that sending applications are alerted when an image cannot be handled due to server errors etc.

See Also

DicomServer Object | DicomServer Members


ObjectType Property

ObjectType Property
DicomObjects Reference > DicomServer Object : ObjectType Property
Description
Describes the nature of an automation object
Property type
Read-only property
Syntax
Visual Basic
Public Property ObjectType As String
Remarks

The possible values are as follows:

“DicomViewer”
“DicomQuery”
“DicomImage”
“DicomImages”
“DicomDataSet”
“DicomDataSets”
“DicomAttribute”
“DicomConnection”
“DicomConnections”
“DicomContext”
“DicomContexts”
“DicomLabel”
“DicomLabels”
“DicomGlobal”
“DicomLog”
“DicomPrint”

See Also

DicomServer Object | DicomServer Members


Tag Property

Tag Property
DicomObjects Reference > DicomServer Object : Tag Property
Description
General Purpose Tag
Property type
Read-write property
Syntax
Visual Basic
Public Property Tag As Variant
Remarks

Tag properties are attached to most objects in DicomObjects. The values are not used by the associated object, and are available for user use. A special case is the DicomConnection object, where Tag is included in the ActionComplete event procedure, assisting identification of necessary features of the connection, such as pending database operations etc. In this use, the value of Tag is stored at the time an operation is initiated, and it is this stored value which is passed to ActionComplete, simplifying the task of tracking which operations have happened.

The TagObject property holds another object, typically a DicomLabels collection, and this can be useful when arranging DicomLabel objects into groups.

See Also

DicomServer Object | DicomServer Members


ActionComplete Event

ActionComplete Event
DicomObjects Reference > DicomServer Object : ActionComplete Event
Identifies the connection that has completed its operation
The name of the action which has just completed
The value of the Tag property of the DicomConnection object at the time the action was initiated
Indicates whether the action completed without errors

If Success if false, then this contains the related error message

Description
fired when transmission of requests on a DicomConnection object is complete
Syntax
Visual Basic
Public Event ActionComplete( _
   ByVal Connection As DicomConnection, _
   ByVal Action As String, _
   ByVal Tag As Variant, _
   ByVal Success As Boolean, _
   ByVal ErrorMessage As String _
)
Parameters
Connection
Identifies the connection that has completed its operation
Action
The name of the action which has just completed
Tag
The value of the Tag property of the DicomConnection object at the time the action was initiated
Success
Indicates whether the action completed without errors
ErrorMessage

If Success if false, then this contains the related error message

Remarks

This Event will be generated after any asynchronous operation has either completed successfully or failed.
The possible values for action are:

None | SendImages (includes SendModifiedImages) | NGet | Close | Find
SetDestination | SendData SendStatus | NCreate NAction | Shutdown AutoDisconnect | Get Move
SaveImage | SendVerify | NSet NDelete NEventReport |  |

See Also

DicomServer Object | DicomServer Members


ActionUpdate Event

ActionUpdate Event
DicomObjects Reference > DicomServer Object : ActionUpdate Event
Identifies the connection that has completed its operation
The name of the action which has just completed
The value of the Tag property of the DicomConnection object at the time the action was initiated
One of the values “Response”, “DataSet” or “Image” indicating the nature of the intermediate result.
The index of the just added entry to the ReturnedResponses collection
The index of the just added entry to the ReturnedDataSets collection
The index of the just added entry to the ReturnedImages collection
Description
fired when intermediate responses are received from the remote application
Syntax
Visual Basic
Public Event ActionUpdate( _
   ByVal Connection As DicomConnection, _
   ByVal Action As String, _
   ByVal Tag As Variant, _
   ByVal ResponseType As String, _
   ByVal LastResponse As Long, _
   ByVal LastDataSet As Long, _
   ByVal LastImage As Long _
)
Parameters
Connection
Identifies the connection that has completed its operation
Action
The name of the action which has just completed
Tag
The value of the Tag property of the DicomConnection object at the time the action was initiated
ResponseType
One of the values “Response”, “DataSet” or “Image” indicating the nature of the intermediate result.
LastResponse
The index of the just added entry to the ReturnedResponses collection
LastDataSet
The index of the just added entry to the ReturnedDataSets collection
LastImage
The index of the just added entry to the ReturnedImages collection
Remarks

This Event will be generated when responses are received from the remote application. The situations where this occurs are:

  • In almost all operations, simple status returns can occur, and these are placed in the ReturnedResponses collection, and ActionUpdate fires with ResponseType of “Response”. Examples include status updates on the primary association during C-MOVE (the Move method) or responses to individual image storage during SendImages or SendModifiedImages.
  • During C-GET operations (the Get method), a response of type “Image” is generated as each image is received.
  • During C-FIND operations (the Find method) a response of type “DataSet” is generated as each result is received.

This event occurs asynchronously to prevent deadlocks, so by the time it fires, further data may have been added to the collection. That is why the LastXXX parameters are included, as by using them it is possible to ensure that each response is processed once and only once – you cannot assume that the last item in a collection is the one to be processed on any firing of this event.

See Also

DicomServer Object | DicomServer Members


AssociationClosed Event

AssociationClosed Event
DicomObjects Reference > DicomServer Object : AssociationClosed Event
The connection which has been closed
Description
fired when an incoming association is closed
Syntax
Visual Basic
Public Event AssociationClosed( _
   ByVal Connection As DicomConnection _
)
Parameters
Connection
The connection which has been closed
Remarks

At the time this event fires, the association has closed, but the associated DicomConnection object still exists, so it’s properties are all still available.
When acting as a print SCP, this event is useful, as the DICOM standard allows all associated objects created during the association to be deleted once the association closes

With the sole exception of applications acting as a print service SCP, DICOM specifically bars any application from making any assumptions about the organisation of incoming data based on the association on which it arrives – to quote part 4 (section B.4):

“…an SCP of the Storage SOP Classes may not attach any significance to the particular association or associations over which C-STORE operations are requested, nor the order in which C-STORE operations occur within an association. No constraints are placed on the operations an SCU may perform during any particular association, other than those defined during association negotiation. An SCP may not expect an SCU to perform C-STORE operations in a particular order.
Similarly, no semantics are attached to the closing of an Association, such as the end of Study or Performed Procedure.”

Therefore, if this event is used for any purpose other than a print SCP, any actions taken within it are most likely to be violations of the DICOM standard.

See Also

DicomServer Object | DicomServer Members


AssociationRequest Event

AssociationRequest Event
DicomObjects Reference > DicomServer Object : AssociationRequest Event
The connection which has been requested
This parameter is passed by reference, and is initially true. If set to false by the container, it causes the association to be rejected.
Description
fired when the server receives a DICOM association request
Syntax
Visual Basic
Public Event AssociationRequest( _
   ByVal Connection As DicomConnection, _
   ByRef isOK As Boolean _
)
Parameters
Connection
The connection which has been requested
isOK
This parameter is passed by reference, and is initially true. If set to false by the container, it causes the association to be rejected.
Remarks

This event has now been superseded by the more flexible AssociationRequest2 which should be used for new applications.
This event is fired whenever an association request is received, giving the container the opportunity to accept or reject the association. isOK is true by default, so if the event is not captured, all associations will be accepted.
To choose which abstract and transfer syntaxes are accepted, the items in the Contexts collection should be checked and acted upon for production environments, and details are given in the tutorial guide – see Getting Started for more information.

Trailing spaces are trimmed from Application Entity Titles.

See Also

DicomServer Object | DicomServer Members


EventReport Event

EventReport Event
DicomObjects Reference > DicomServer Object : EventReport Event
The connection on which the notification is received.
The ID of the notification
The identifier received with the notification

This parameter is passed by reference, and should be set to the error code to be returned to the application generating the notification. Please see notes below however, as this event is called asynchronously, and this result is ignored unless the connection’s Mode is doNoSync.

Description
fired when an incoming N-EVENT-REPORT notification is received
Syntax
Visual Basic
Public Event EventReport( _
   ByVal Connection As DicomConnection, _
   ByVal EventID As Integer, _
   ByVal dataset As DicomDataSet, _
   ByRef Status As Long _
)
Parameters
Connection
The connection on which the notification is received.
EventID
The ID of the notification
dataset
The identifier received with the notification
Status

This parameter is passed by reference, and should be set to the error code to be returned to the application generating the notification. Please see notes below however, as this event is called asynchronously, and this result is ignored unless the connection’s Mode is doNoSync.

Remarks

In order for events to be generated the client application must establish a connection to an appropriate SCP, offering a Meta SOP class that supports the N-EVENT-REPORT operation. This is achieved by creating a DicomConnection object (using the New method, to enable the link between the DicomConnection and the event-enabled DicomViewer or DicomServer), and issuing a SetDestination call.

The handling of N-EVENT-REPORT notifications is complicated by their asynchronous arrival on associations which are for other purposes outgoing only (i.e. DicomObjects is SCU). This means that it is not always possible to fire this event synchronously, as an attempt to do so could produce a deadlock if called during an outgoing association. Consequently, the result is only used when the connection’s Mode property is doNoSync, as the rules imposed by this mode prevent a deadlock from occurring.

See Also

DicomServer Object | DicomServer Members


InfoMessage Event

InfoMessage Event
DicomObjects Reference > DicomServer Object : InfoMessage Event
An enumeration indicating the importance of the message as follows:
0: Fatal Error
1: Protocol Error
2: Warning
3: Information
4: Debugging trace
Human readable error message or notification.
Description
Passes information back to the container for error messages and notifications originating from the DICOM interface
Syntax
Visual Basic
Public Event InfoMessage( _
   ByVal InfoType As Integer, _
   ByVal Text As String _
)
Parameters
InfoType
An enumeration indicating the importance of the message as follows:
0: Fatal Error
1: Protocol Error
2: Warning
3: Information
4: Debugging trace
Text
Human readable error message or notification.
Remarks

Where possible, objects pass error information back to the container via OLE exceptions, but this is not possible for errors originating from the DICOM interface, as there is no call from the container to the object in progress. This event is therefore used for that purpose.

Debugging information may include all or part of the byte stream exchanged between DicomObjects and other entities, and is useful when communication failures occur.

See Also

DicomServer Object | DicomServer Members


InstanceReceived Event

InstanceReceived Event
DicomObjects Reference > DicomServer Object : InstanceReceived Event
Identifies the connection that has received the instance
The received instance as DicomDataSet
Description
fired whene an incoming C-STORE operation is received
Syntax
Visual Basic
Public Event InstanceReceived( _
   ByVal Connection As DicomConnection, _
   ByVal dataset As DicomDataSet _
)
Parameters
Connection
Identifies the connection that has received the instance
dataset
The received instance as DicomDataSet
Remarks
This event is triggered when an open connection receives an instance
See Also

DicomServer Object | DicomServer Members


NormalisedReceived Event

NormalisedReceived Event
DicomObjects Reference > DicomServer Object : NormalisedReceived Event
Contains details of the request, including its type, Q/R model, and the request identifier.
Description
fired when an incoming request for a normalised operation is received
Syntax
Visual Basic
Public Event NormalisedReceived( _
   ByVal Connection As DicomConnection _
)
Parameters
Connection
Contains details of the request, including its type, Q/R model, and the request identifier.
Remarks
The information required to process the request is available via the properties of the connection.
See Also

DicomServer Object | DicomServer Members


PixelsReceived Event

PixelsReceived Event
DicomObjects Reference > DicomServer Object : PixelsReceived Event
Identifies the connection that has received the instance
Received pixel data in a DicomDataSet
Description
fired when Pixel data is received, allowing direct to disk receiving to be triggered
Syntax
Visual Basic
Public Event PixelsReceived( _
   ByVal Connection As DicomConnection, _
   ByVal dataset As DicomDataSet _
)
Parameters
Connection
Identifies the connection that has received the instance
dataset
Received pixel data in a DicomDataSet
See Also

DicomServer Object | DicomServer Members


QueryRequest Event

QueryRequest Event
DicomObjects Reference > DicomServer Object : QueryRequest Event
Contains details of the request, including its type, Q/R model, and the request identifier.
Description
fired when an incoming Query request is received
Syntax
Visual Basic
Public Event QueryRequest( _
   ByVal Connection As DicomConnection _
)
Parameters
Connection
Contains details of the request, including its type, Q/R model, and the request identifier.
Remarks
The handling of Query/Retrieve requests as an SCP is an advanced technique, and the rules to be obeyed are beyond the scope of this help file. See the Access SCP example for a demonstration of a possible implementation, or consult the tutorial guide – see Useful Links for help.
See Also

DicomServer Object | DicomServer Members


VerifyReceived Event

VerifyReceived Event
DicomObjects Reference > DicomServer Object : VerifyReceived Event
The status to return (as this is a "by reference" parameter)
Description
fired when an incoming C-ECHO request is received
Syntax
Visual Basic
Public Event VerifyReceived( _
   ByRef Status As Long _
)
Parameters
Status
The status to return (as this is a "by reference" parameter)
Remarks

In previous versions of DicomObjects, C-ECHO requests always generated a status of 0 (success).
The initial value of status is the originating object’s DefaultStatus value, and applications should replace this by zero in this event.

In all release applications, DefaultStatus should be non-zero, so that if the main thread stalls or fails to respond to events (e.g. when a message box is active in Visual Basic), then probing applications will receive a non-zero responses to their C-ECHO (verify) requests.

See Also

DicomServer Object | DicomServer Members


DicomViewer Object

DicomViewer Object
Members
DicomObjects Reference : DicomViewer Object
Description

The primary purpose of this control is the display of DICOM images, and extensive facilities are available to allow images to be obtained from a variety of sources, including files and network operations. There is extensive control over how the images are displayed, including not only the normal width/level controls, but also use of DICOM greyscale presentation states, a wide range of annotations, flipping, zooming etc.

Remarks
The control can also act as an SCP, and can be instructed to "listen" on one or more TCP ports, and can accept and respond to, storage, query/retrieve, normalised and verification requests directed to it, from either remote machines, or from other processes on the same machine.

Images received via C-STORE operations are, by default, stored in memory and displayed. Any number of images can be received (subject to memory limitations), and may be displayed either singly or in combination. Images may be "windowed", and their various attributes, (including the pixel data), are available to the container application. Images may be selectively deleted, duplicated or re-ordered. They may also be stored and retrieved to/from files or database fields.

A major design feature is that this control has no intrinsic user interface other than the display itself, all functionality being exposed and implemented via OLE automation interfaces. In general, as much functionality as possible is devolved to the container. For instance, the control does not have its own application entity name, and acceptance or rejection of associations is controlled via an event. This event is given the remote IP address and the calling and called application entity titles, allowing the container to make its own accept/reject decision.

Similarly, other SCP functionality is expressed entirely through events, allowing the control to respond as required by the container.

See Also

DicomViewer Members


DicomViewer Object Members

DicomViewer Object Members
Overview
DicomObjects Reference : DicomViewer Object
Public Methods
Public Method AboutBox | Display the Control's AboutBox, containing Copyright Information etc.
Public Method ImageXPosition | Translates display area corrdinates to image pixel (X) position
Public Method ImageYPosition | Translates display area corrdinates to image pixel (Y) position
Public Method LabelHits | Finds labels covering an area of the viewer
Public Method Location3D | Translate from screen coordinates to image coordinates
Public Method New | Returns a new subsidiary automation object
Public Method Refresh | Refreshes the Controlâ€™s display area
Public Properties
Public Property AutoDisplay | Determines whether current image number is modified automatically
Public Property BackColour | Control's Background Colour
Public Property BackColourAsLong | Control's Background Colour
Public Property BorderStyle | The border to apply to the viewer as a whole
Public Property CalibrationCurve | Controls a final display Calibration Curve for grayscale presentation state use
Public Property CellSpacing | Spacing (in pixels) between adjacent image cells
Public Property CurrentImage | Reference to first image currently displayed
Public Property CurrentIndex | Index of first image currently displayed
Public Property DelphiSizeFix | Controls whether a fix for a Delphi viewer position is applied
Public Property hWnd | The hWnd property of the viewer
Public Property ImageIndex | Translates a cursor position to an image number
Public Property Images | Provides access to the collection of images stored in the control at any time
Public Property Labels | The collection of DicomLabels to display over this viewer
Public Property MonitorMode | Controls the Monitor Mode of the Screen the image is being displayed
Public Property MultiColumns | Controls the layout of images within the control
Public Property MultiRows | Controls the layout of images within the control
Public Property ObjectType | Describes the nature of an automation object
Public Property Part14Max | Controls the Maximum value
Public Property Part14Min | Controls the Minimum value
Public Property PixelSizeX | Physical size of Screen Pixels (X)
Public Property PixelSizeY | Physical size of Screen Pixels (Y)
Public Property PreferredViewerMode | Controls the mode used to display images
Public Property UseMouseWheel | Controls whether the mouse wheel generates MouseWheel events, or scrolls the viewer
Public Property UseScrollBars | Determines whether scroll bars are used for over-size single images
Events
Public Event Click | Fired on a mouse click
Public Event DblClick | Fired on a mouse double click
Public Event DrawEnd | fired when drawing ends
Public Event DrawEnd2 | fired when drawing ends and provides an hDC for flicker-free drawing
Public Event DrawException | fired when an error occurs during drawing
Public Event DrawStart | fired when drawing starts
Public Event InfoMessage | Passes information back to the container for error messages and notifications originating from the DICOM interface
Public Event KeyDown | Fired on key down
Public Event KeyPress | Fired on a key press
Public Event KeyUp | Fired on key up
Public Event MouseDown | Fired on mouse down
Public Event MouseMove | Fired on mouse move
Public Event MouseUp | Fired on mouse up
Public Event MouseWheel | fired when the Mouse Wheel is turned (only if UseMouseWheel is true)
Public Event OnDataChanged | fired whenever the underlying data in the controlâ€™s Images collection changes
Public Event OnDisplayChanged | fired whenever the display properties of any of the images in the controlâ€™s Images collection change
Public Event OnFrameChanging | fired when the frame on any displayed image changes
See Also

DicomViewer Object


AboutBox Method

AboutBox Method
DicomObjects Reference > DicomViewer Object : AboutBox Method
Description
Display the Control's AboutBox, containing Copyright Information etc.
Syntax
Visual Basic
Public Sub AboutBox()
See Also

DicomViewer Object | DicomViewer Members


ImageXPosition Method

ImageXPosition Method
DicomObjects Reference > DicomViewer Object : ImageXPosition Method
The location of interest in the control.
The location of interest in the control.
Description
Translates display area corrdinates to image pixel (X) position
Syntax
Visual Basic
Public Function ImageXPosition( _
   ByVal x As Single, _
   ByVal y As Single _
) As Single
Parameters
x
The location of interest in the control.
y
The location of interest in the control.
Return Type
The units used for x and y are the same as are sent to the MouseDown and MouseMove events, enabling easy identification of the location clicked by the user.
Note that an image cell is identified, rather than an image, so the ImageIndex returns an appropriate image even if a point is given within the cell, but outside the image actually displayed.
See Also

DicomViewer Object | DicomViewer Members


ImageYPosition Method

ImageYPosition Method
DicomObjects Reference > DicomViewer Object : ImageYPosition Method
The location of interest in the control.
The location of interest in the control.
Description
Translates display area corrdinates to image pixel (Y) position
Syntax
Visual Basic
Public Function ImageYPosition( _
   ByVal x As Single, _
   ByVal y As Single _
) As Single
Parameters
x
The location of interest in the control.
y
The location of interest in the control.
Return Type
The units used for x and y are the same as are sent to the MouseDown and MouseMove events, enabling easy identification of the location clicked by the user.
Note that an image cell is identified, rather than an image, so the ImageIndex returns an appropriate image even if a point is given within the cell, but outside the image actually displayed.
See Also

DicomViewer Object | DicomViewer Members


LabelHits Method

LabelHits Method
DicomObjects Reference > DicomViewer Object : LabelHits Method
The point to be investigated
The point to be investigated
Labels in the DicomViewer’s Labels collection
Labels in a DicomImage’s Labels collection, where RotateModeWithImage is set.
Labels in a DicomImage’s Labels collection, where RotateModeWithImage is set.
Description
Finds labels covering an area of the viewer
Syntax
Visual Basic
Public Function LabelHits( _
   ByVal x As Single, _
   ByVal y As Single, _
   ByVal ViewerLabels As Boolean, _
   ByVal ImageCellLabels As Boolean, _
   ByVal ImageTiedLabels As Boolean _
) As DicomLabels
Parameters
x
The point to be investigated
y
The point to be investigated
ViewerLabels
Labels in the DicomViewer’s Labels collection
ImageCellLabels
Labels in a DicomImage’s Labels collection, where RotateModeWithImage is set.
ImageTiedLabels
Labels in a DicomImage’s Labels collection, where RotateModeWithImage is set.
Remarks
This method is intended to help those needing to identify which, if any label(s) have been selected by a user. The x and y parameters, are normally fed directly from the parameters of a MouseDown event.
The area allowed for a “hit” to register is quite generous – any label within the Label’s bounding rectangle is considered to have been “hit”, and will be included in the returned collection.
When writing user interface facilities with this method, it is often useful to be able to highlight some labels – the SelectMode property is suitable for this purpose.
See Also

DicomViewer Object | DicomViewer Members


Location3D Method

Location3D Method
DicomObjects Reference > DicomViewer Object : Location3D Method
The screen X position
The screen Y position
Description
Translate from screen coordinates to image coordinates
Syntax
Visual Basic
Public Function Location3D( _
   ByVal x As Single, _
   ByVal y As Single _
) As Variant
Parameters
x
The screen X position
y
The screen Y position
Remarks
This returns a 3 element array, containing the X,Y & Z coordinates in real world space corresponding to the screen location identified by the X & Y input parameters.
See Also

DicomViewer Object | DicomViewer Members


New Method

New Method
DicomObjects Reference > DicomViewer Object : New Method
The type of object to create - this must be the name of the object to create - e.g. "DicomImage".
Description
Returns a new subsidiary automation object
Syntax
Visual Basic
Public Function New( _
   ByVal ObjectType As String _
) As Object
Parameters
ObjectType
The type of object to create - this must be the name of the object to create - e.g. "DicomImage".
Remarks

Only the value “DicomConnection” is valid for base objects of type DicomServer. The purpose of using this call, rather than allowing direct creation of DicomConnection objects, is to route ActionComplete events though a limited number of static objects, to which event handlers may easily be attached.

Unlike most other methods and properties in DicomObjects, this method returns a generic “IDispatch” pointer, which in most languages except Visual Basic must be cast to the appropriate known object type.

See Also

DicomViewer Object | DicomViewer Members


Refresh Method

Refresh Method
DicomObjects Reference > DicomViewer Object : Refresh Method
Description
Refreshes the Controlâ€™s display area
Syntax
Visual Basic
Public Sub Refresh()
Remarks

This method is used mainly in the following circumstances:

  • After altering or adding DicomLabel items in either the control’s or any image’s Labels collection.
  • When a defined series of images must be drawn, such as when modifying the Frame property to generate a non-standard cine sequence
  • After changing an image’s PresentationState

These methods should not need to be called under other circumstances, as all other changes which would cause the display to alter should automatically cause a re-draw, but is available in case of problems.

See Also

DicomViewer Object | DicomViewer Members


AutoDisplay Property

AutoDisplay Property
DicomObjects Reference > DicomViewer Object : AutoDisplay Property
Description
Determines whether current image number is modified automatically
Property type
Read-write property
Syntax
Visual Basic
Public Property AutoDisplay As Boolean
Remarks

If the number of the latest image to be added to the control is new then the formula used is:

CurrentIndex = max(1, new +1 - MultiRows * MultiColumns)

See Also

DicomViewer Object | DicomViewer Members


BackColour Property

BackColour Property
DicomObjects Reference > DicomViewer Object : BackColour Property
Description
Control's Background Colour
Property type
Read-write property
Syntax
Visual Basic
Public Property BackColour As ULong
Remarks
The colour specified by this property is used to fill any areas of the control not filled by images, whether due to absent images, or due to images being smaller than their display cells.
See Also

DicomViewer Object | DicomViewer Members


BackColourAsLong Property

BackColourAsLong Property
DicomObjects Reference > DicomViewer Object : BackColourAsLong Property
Description
Control's Background Colour
Property type
Read-write property
Syntax
Visual Basic
Public Property BackColourAsLong As Long
Remarks
This is the same as the BackColour Property, but is presented as a "long" as this is needed by some environments which cannot cope with OLE_COLOR.
See Also

DicomViewer Object | DicomViewer Members


BorderStyle Property

BorderStyle Property
DicomObjects Reference > DicomViewer Object : BorderStyle Property
Description
The border to apply to the viewer as a whole
Property type
Read-write property
Syntax
Visual Basic
Public Property BorderStyle As Integer
Remarks

The possible values are as follows:

  • 0: No Border
  • 1: Single Border
See Also

DicomViewer Object | DicomViewer Members


CalibrationCurve Property

CalibrationCurve Property
DicomObjects Reference > DicomViewer Object : CalibrationCurve Property
Description
Controls a final display Calibration Curve for grayscale presentation state use
Property type
Read-write property
Syntax
Visual Basic
Public Property CalibrationCurve As Variant
Remarks
This array is used as a final lookup when images are being rendered to the screen (but not for any other purposes such as Copy etc.), and assists developers who wish to write applications which conform to the DICOM greyscale display standard. The array may contain any number of elements, and may have any maximum value (subject to fitting within the range of short integers), as both input and output are scaled to fit the required ranges. As a result, it is possible to conform to the DICOM standard greyscale display function, even on otherwise un calibrated display cards and monitors.
See Also

DicomViewer Object | DicomViewer Members


CellSpacing Property

CellSpacing Property
DicomObjects Reference > DicomViewer Object : CellSpacing Property
Description
Spacing (in pixels) between adjacent image cells
Property type
Read-write property
Syntax
Visual Basic
Public Property CellSpacing As Integer
Remarks

The area available for display in a DicomViewer is divided into a number of image “cells” according to the values of MultiRows and MultiColumns and in previous versions of DicomObjects, the images were displayed in the whole of this cell, but as of version 4.1, the number of pixel specified by this property is effectively “removed” from the display area before rendering the image, giving a gap between images. This is useful if the image’s BorderWidth property is used, as it can prevent the visible highlight overlying the image itself.

The default value is 0.

See Also

DicomViewer Object | DicomViewer Members


CurrentImage Property

CurrentImage Property
DicomObjects Reference > DicomViewer Object : CurrentImage Property
Description
Reference to first image currently displayed
Property type
Read-only property
Syntax
Visual Basic
Public Property CurrentImage As DicomImage
See Also

DicomViewer Object | DicomViewer Members


CurrentIndex Property

CurrentIndex Property
DicomObjects Reference > DicomViewer Object : CurrentIndex Property
Description
Index of first image currently displayed
Property type
Read-write property
Syntax
Visual Basic
Public Property CurrentIndex As Long
Remarks
This defines the index (1-based) of the image displayed in the top left corner of the display matrix (or the only image if MultiRows and MultiColumns are 1). If MultiRows or MultiColumns are greater than 1, then other images are displayed sequentially along and then down.
See Also

DicomViewer Object | DicomViewer Members


DelphiSizeFix Property

DelphiSizeFix Property
DicomObjects Reference > DicomViewer Object : DelphiSizeFix Property
Description
Controls whether a fix for a Delphi viewer position is applied
Property type
Read-write property
Syntax
Visual Basic
Public Property DelphiSizeFix As Boolean
See Also

DicomViewer Object | DicomViewer Members


hWnd Property

hWnd Property
DicomObjects Reference > DicomViewer Object : hWnd Property
Description
The hWnd property of the viewer
Property type
Read-only property
Syntax
Visual Basic
Public Property hWnd As Integer
Remarks
This may be useful for some system calls, such as changing the cursor.
See Also

DicomViewer Object | DicomViewer Members


ImageIndex Property

ImageIndex Property
DicomObjects Reference > DicomViewer Object : ImageIndex Property
The location of interest in the control.
The location of interest in the control.
Description
Translates a cursor position to an image number
Property type
Read-only property
Syntax
Visual Basic
Public Property ImageIndex( _
   ByVal x As Single, _
   ByVal y As Single _
) As Integer
Parameters
x
The location of interest in the control.
y
The location of interest in the control.
Return Type
The units used for x and y are the same as are sent to the MouseDown and MouseMove events, enabling easy identification of the location clicked by the user.
Note that an image cell is identified, rather than an image, so the ImageIndex returns an appropriate image even if a point is given within the cell, but outside the image actually displayed.
See Also

DicomViewer Object | DicomViewer Members


Images Property

Images Property
DicomObjects Reference > DicomViewer Object : Images Property
Description
Provides access to the collection of images stored in the control at any time
Property type
Read-only property
Syntax
Visual Basic
Public Property Images As DicomImages
Remarks
This property provides access to the collection of images stored in the control at any time.
See Also

DicomViewer Object | DicomViewer Members


Labels Property

Labels Property
DicomObjects Reference > DicomViewer Object : Labels Property
Description
The collection of DicomLabels to display over this viewer
Property type
Read-only property
Syntax
Visual Basic
Public Property Labels As DicomLabels
See Also

DicomViewer Object | DicomViewer Members


MonitorMode Property

MonitorMode Property
DicomObjects Reference > DicomViewer Object : MonitorMode Property
Description
Controls the Monitor Mode of the Screen the image is being displayed
Property type
Read-write property
Syntax
Visual Basic
Public Property MonitorMode As doMonitorMode
Remarks

Controls special modes for use with unusual monitors

The only modes currently defined are:

0: Normal
1: Totoku 15 MP Portrait mode

The Totoku mode is for a 15 MegaPixel monitor which uses the “colour” pixel to increase the spatial resolution in one dimension.
If set to Totoku mode, then the Part14Max and Part14Min values should be set to ensure proper calibration.

See Also

DicomViewer Object | DicomViewer Members


MultiColumns Property

MultiColumns Property
DicomObjects Reference > DicomViewer Object : MultiColumns Property
Description
Controls the layout of images within the control
Property type
Read-write property
Syntax
Visual Basic
Public Property MultiColumns As Integer
Remarks
If either MultiRows or MultiColumns is greater than 1, then the display area is sub-divided into a matrix of equally sized cells, each displaying an image.
If only a single image cell is displayed, then it may be scrollable, if necessary, using standard scroll bars, but if either MultiRows or MultiColumns is greater than 1, then the scroll bars are not displayed. Positioning of the individual images then becomes the responsibility of the container, by use of the image’s ScrollX and ScrollY properties. If UseScrollBars is false, then scroll bars are not displayed, regardless of any other criteria.
See Also

DicomViewer Object | DicomViewer Members


MultiRows Property

MultiRows Property
DicomObjects Reference > DicomViewer Object : MultiRows Property
Description
Controls the layout of images within the control
Property type
Read-write property
Syntax
Visual Basic
Public Property MultiRows As Integer
Remarks
If either MultiRows or MultiColumns is greater than 1, then the display area is sub-divided into a matrix of equally sized cells, each displaying an image.
If only a single image cell is displayed, then it may be scrollable, if necessary, using standard scroll bars, but if either MultiRows or MultiColumns is greater than 1, then the scroll bars are not displayed. Positioning of the individual images then becomes the responsibility of the container, by use of the image’s ScrollX and ScrollY properties. If UseScrollBars is false, then scroll bars are not displayed, regardless of any other criteria.
See Also

DicomViewer Object | DicomViewer Members


ObjectType Property

ObjectType Property
DicomObjects Reference > DicomViewer Object : ObjectType Property
Description
Describes the nature of an automation object
Property type
Read-only property
Syntax
Visual Basic
Public Property ObjectType As String
Remarks

The possible values are as follows:

“DicomViewer”
“DicomQuery”
“DicomImage”
“DicomImages”
“DicomDataSet”
“DicomDataSets”
“DicomAttribute”
“DicomConnection”
“DicomConnections”
“DicomContext”
“DicomContexts”
“DicomLabel”
“DicomLabels”
“DicomGlobal”
“DicomLog”
“DicomPrint”

See Also

DicomViewer Object | DicomViewer Members


Part14Max Property

Part14Max Property
DicomObjects Reference > DicomViewer Object : Part14Max Property
Description
Controls the Maximum value
Property type
Read-write property
Syntax
Visual Basic
Public Property Part14Max As Single
Remarks
Since DICOM Part 14 display is non-linear, smoothing operations need to take this into account to “linearise” the split of pixel intensity between adjacent pixels. For this to work properly, DicomObjects needs to know the range of the display, which is set by these properties, which are measured in Lumens – so typical value would be Part14Min = 0.2 and Part14Max = 700.
See Also

DicomViewer Object | DicomViewer Members


Part14Min Property

Part14Min Property
DicomObjects Reference > DicomViewer Object : Part14Min Property
Description
Controls the Minimum value
Property type
Read-write property
Syntax
Visual Basic
Public Property Part14Min As Single
Remarks
Since DICOM Part 14 display is non-linear, smoothing operations need to take this into account to “linearise” the split of pixel intensity between adjacent pixels. For this to work properly, DicomObjects needs to know the range of the display, which is set by these properties, which are measured in Lumens – so typical value would be Part14Min = 0.2 and Part14Max = 700.
See Also

DicomViewer Object | DicomViewer Members


PixelSizeX Property

PixelSizeX Property
DicomObjects Reference > DicomViewer Object : PixelSizeX Property
Description
Physical size of Screen Pixels (X)
Property type
Read-write property
Syntax
Visual Basic
Public Property PixelSizeX As Single
Remarks
The absolute values of these properties are only used when the image has an attached DICOM greyscale presentation state, which specifies “ACTUAL SIZE” for the scaling mode, but their ratio is used in all display modes to allow anisotropic pixels to be corrected.
The default values are both 0.3mm.
See Also

DicomViewer Object | DicomViewer Members


PixelSizeY Property

PixelSizeY Property
DicomObjects Reference > DicomViewer Object : PixelSizeY Property
Description
Physical size of Screen Pixels (Y)
Property type
Read-write property
Syntax
Visual Basic
Public Property PixelSizeY As Single
Remarks
The absolute values of these properties are only used when the image has an attached DICOM greyscale presentation state, which specifies “ACTUAL SIZE” for the scaling mode, but their ratio is used in all display modes to allow anisotropic pixels to be corrected.
The default values are both 0.3mm.
See Also

DicomViewer Object | DicomViewer Members


PreferredViewerMode Property

PreferredViewerMode Property
DicomObjects Reference > DicomViewer Object : PreferredViewerMode Property
Description
Controls the mode used to display images
Property type
Read-write property
Syntax
Visual Basic
Public Property PreferredViewerMode As doViewerMode
Remarks
Default is set to doViewerModeDirectX
See Also

DicomViewer Object | DicomViewer Members


UseMouseWheel Property

UseMouseWheel Property
DicomObjects Reference > DicomViewer Object : UseMouseWheel Property
Description
Controls whether the mouse wheel generates MouseWheel events, or scrolls the viewer
Property type
Read-write property
Syntax
Visual Basic
Public Property UseMouseWheel As Boolean
Remarks
In previous versions of DicomObjects, MouseWheel events were converted internally to scroll events, and to maintain backwards compatibility, this remains the default behaviour. Therefore, to enable the MouseWheel event, this property of the viewer must be set explicitly to true. If left as false, then the events will be re-interpreted as scroll instructions.
See Also

DicomViewer Object | DicomViewer Members


UseScrollBars Property

UseScrollBars Property
DicomObjects Reference > DicomViewer Object : UseScrollBars Property
Description
Determines whether scroll bars are used for over-size single images
Property type
Read-write property
Syntax
Visual Basic
Public Property UseScrollBars As Boolean
Remarks
If true (the default value), scroll bars are displayed when MultiRows and MultiColumns are both 1, and the image displayed (after zooming) is larger than the available area of the DicomViewer (in either dimension. By setting this value to false, these scroll bars may be inhibited.
See Also

DicomViewer Object | DicomViewer Members


Click Event

Click Event
DicomObjects Reference > DicomViewer Object : Click Event
Description
Fired on a mouse click
Syntax
Visual Basic
Public Event Click()
Remarks
These events are essentially Microsoft standard mouse events, except that the x and y positions are specified as long integers representing display pixels rather than OLE_PIXELS. This avoids the transformations applied by some clients such as Visual Basic, guaranteeing that the values are compatible with DicomObject’s scrolling and drawing functions.
Due to a bug in Visual Basic, DicomViewer controls placed on a VB form do not receive events related to pressing arrow keys.
See Also

DicomViewer Object | DicomViewer Members


DblClick Event

DblClick Event
DicomObjects Reference > DicomViewer Object : DblClick Event
Description
Fired on a mouse double click
Syntax
Visual Basic
Public Event DblClick()
Remarks
These events are essentially Microsoft standard mouse events, except that the x and y positions are specified as long integers representing display pixels rather than OLE_PIXELS. This avoids the transformations applied by some clients such as Visual Basic, guaranteeing that the values are compatible with DicomObject’s scrolling and drawing functions.
Due to a bug in Visual Basic, DicomViewer controls placed on a VB form do not receive events related to pressing arrow keys.
See Also

DicomViewer Object | DicomViewer Members


DrawEnd Event

DrawEnd Event
DicomObjects Reference > DicomViewer Object : DrawEnd Event
Description
fired when drawing ends
Syntax
Visual Basic
Public Event DrawEnd()
Remarks
These events are always called as a pair, and surround any drawing of pixel data to the DicomViewer’s display.
See Also

DicomViewer Object | DicomViewer Members


DrawEnd2 Event

DrawEnd2 Event
DicomObjects Reference > DicomViewer Object : DrawEnd2 Event
Handle of the drawing context onto which the viewer's content has been drawn.
Description
fired when drawing ends and provides an hDC for flicker-free drawing
Syntax
Visual Basic
Public Event DrawEnd2( _
   ByVal hDC As Integer _
)
Parameters
hDC
Handle of the drawing context onto which the viewer's content has been drawn.
See Also

DicomViewer Object | DicomViewer Members


DrawException Event

DrawException Event
DicomObjects Reference > DicomViewer Object : DrawException Event
The index of the image in the Images collection which generated the error
The error message
Set to true if your code handles the error in a way which allows DicomObjects to re-attempt the drawing.
Description
fired when an error occurs during drawing
Syntax
Visual Basic
Public Event DrawException( _
   ByVal Index As Long, _
   ByVal Message As String, _
   ByRef Handled As Boolean _
)
Parameters
Index
The index of the image in the Images collection which generated the error
Message
The error message
Handled
Set to true if your code handles the error in a way which allows DicomObjects to re-attempt the drawing.
Remarks

This may be used to trap and handle errors which occur during drawing on the surface of the DicomViewer.

If you have "handled" this error and wish DicomObjects to try again, set the Handled parameter (by ref) to true, but beware infinite loops.

See Also

DicomViewer Object | DicomViewer Members


DrawStart Event

DrawStart Event
DicomObjects Reference > DicomViewer Object : DrawStart Event
Description
fired when drawing starts
Syntax
Visual Basic
Public Event DrawStart()
Remarks
These events are always called as a pair, and surround any drawing of pixel data to the DicomViewer’s display.
See Also

DicomViewer Object | DicomViewer Members


InfoMessage Event

InfoMessage Event
DicomObjects Reference > DicomViewer Object : InfoMessage Event
An enumeration indicating the importance of the message as follows:
0: Fatal Error
1: Protocol Error
2: Warning
3: Information
4: Debugging trace

Human readable error message or notification.

Description
Passes information back to the container for error messages and notifications originating from the DICOM interface
Syntax
Visual Basic
Public Event InfoMessage( _
   ByVal InfoType As Integer, _
   ByVal Text As String _
)
Parameters
InfoType
An enumeration indicating the importance of the message as follows:
0: Fatal Error
1: Protocol Error
2: Warning
3: Information
4: Debugging trace
Text

Human readable error message or notification.

Remarks

Where possible, objects pass error information back to the container via OLE exceptions, but this is not possible for errors originating from the DICOM interface, as there is no call from the container to the object in progress. This event is therefore used for that purpose.

Debugging information may include all or part of the byte stream exchanged between DicomObjects and other entities, and is useful when communication failures occur.

See Also

DicomViewer Object | DicomViewer Members


KeyDown Event

KeyDown Event
DicomObjects Reference > DicomViewer Object : KeyDown Event
Scan code of key pressed
State of the Ctrl, Shift and Alt keys
Description
Fired on key down
Syntax
Visual Basic
Public Event KeyDown( _
   ByRef KeyCode As Integer, _
   ByVal Shift As Integer _
)
Parameters
KeyCode
Scan code of key pressed
Shift
State of the Ctrl, Shift and Alt keys
Remarks
These events are essentially Microsoft standard mouse events, except that the x and y positions are specified as long integers representing display pixels rather than OLE_PIXELS. This avoids the transformations applied by some clients such as Visual Basic, guaranteeing that the values are compatible with DicomObject’s scrolling and drawing functions.
Due to a bug in Visual Basic, DicomViewer controls placed on a VB form do not receive events related to pressing arrow keys.
See Also

DicomViewer Object | DicomViewer Members


KeyPress Event

KeyPress Event
DicomObjects Reference > DicomViewer Object : KeyPress Event
ASCII code of key generated
Description
Fired on a key press
Syntax
Visual Basic
Public Event KeyPress( _
   ByRef KeyAscii As Integer _
)
Parameters
KeyAscii
ASCII code of key generated
Remarks
These events are essentially Microsoft standard mouse events, except that the x and y positions are specified as long integers representing display pixels rather than OLE_PIXELS. This avoids the transformations applied by some clients such as Visual Basic, guaranteeing that the values are compatible with DicomObject’s scrolling and drawing functions.
Due to a bug in Visual Basic, DicomViewer controls placed on a VB form do not receive events related to pressing arrow keys.
See Also

DicomViewer Object | DicomViewer Members


KeyUp Event

KeyUp Event
DicomObjects Reference > DicomViewer Object : KeyUp Event
Scan code of key pressed
State of the Ctrl, Shift and Alt keys
Description
Fired on key up
Syntax
Visual Basic
Public Event KeyUp( _
   ByRef KeyCode As Integer, _
   ByVal Shift As Integer _
)
Parameters
KeyCode
Scan code of key pressed
Shift
State of the Ctrl, Shift and Alt keys
Remarks
These events are essentially Microsoft standard mouse events, except that the x and y positions are specified as long integers representing display pixels rather than OLE_PIXELS. This avoids the transformations applied by some clients such as Visual Basic, guaranteeing that the values are compatible with DicomObject’s scrolling and drawing functions.
Due to a bug in Visual Basic, DicomViewer controls placed on a VB form do not receive events related to pressing arrow keys.
See Also

DicomViewer Object | DicomViewer Members


MouseDown Event

MouseDown Event
DicomObjects Reference > DicomViewer Object : MouseDown Event
Represents the mouse button pressed or released
State of the Ctrl, Shift and Alt keys
The mouse position, relative to the DicomViewer control.
The mouse position, relative to the DicomViewer control.
Description
Fired on mouse down
Syntax
Visual Basic
Public Event MouseDown( _
   ByVal Button As Integer, _
   ByVal Shift As Integer, _
   ByVal x As Long, _
   ByVal y As Long _
)
Parameters
Button
Represents the mouse button pressed or released
Shift
State of the Ctrl, Shift and Alt keys
x
The mouse position, relative to the DicomViewer control.
y
The mouse position, relative to the DicomViewer control.
Remarks
These events are essentially Microsoft standard mouse events, except that the x and y positions are specified as long integers representing display pixels rather than OLE_PIXELS. This avoids the transformations applied by some clients such as Visual Basic, guaranteeing that the values are compatible with DicomObject’s scrolling and drawing functions.
Due to a bug in Visual Basic, DicomViewer controls placed on a VB form do not receive events related to pressing arrow keys.
See Also

DicomViewer Object | DicomViewer Members


MouseMove Event

MouseMove Event
DicomObjects Reference > DicomViewer Object : MouseMove Event
Represents the mouse button pressed or released
State of the Ctrl, Shift and Alt keys
The mouse position, relative to the DicomViewer control.
The mouse position, relative to the DicomViewer control.
Description
Fired on mouse move
Syntax
Visual Basic
Public Event MouseMove( _
   ByVal Button As Integer, _
   ByVal Shift As Integer, _
   ByVal x As Long, _
   ByVal y As Long _
)
Parameters
Button
Represents the mouse button pressed or released
Shift
State of the Ctrl, Shift and Alt keys
x
The mouse position, relative to the DicomViewer control.
y
The mouse position, relative to the DicomViewer control.
Remarks
These events are essentially Microsoft standard mouse events, except that the x and y positions are specified as long integers representing display pixels rather than OLE_PIXELS. This avoids the transformations applied by some clients such as Visual Basic, guaranteeing that the values are compatible with DicomObject’s scrolling and drawing functions.
Due to a bug in Visual Basic, DicomViewer controls placed on a VB form do not receive events related to pressing arrow keys.
See Also

DicomViewer Object | DicomViewer Members


MouseUp Event

MouseUp Event
DicomObjects Reference > DicomViewer Object : MouseUp Event
Represents the mouse button pressed or released
State of the Ctrl, Shift and Alt keys
The mouse position, relative to the DicomViewer control.
The mouse position, relative to the DicomViewer control.
Description
Fired on mouse up
Syntax
Visual Basic
Public Event MouseUp( _
   ByVal Button As Integer, _
   ByVal Shift As Integer, _
   ByVal x As Long, _
   ByVal y As Long _
)
Parameters
Button
Represents the mouse button pressed or released
Shift
State of the Ctrl, Shift and Alt keys
x
The mouse position, relative to the DicomViewer control.
y
The mouse position, relative to the DicomViewer control.
Remarks
These events are essentially Microsoft standard mouse events, except that the x and y positions are specified as long integers representing display pixels rather than OLE_PIXELS. This avoids the transformations applied by some clients such as Visual Basic, guaranteeing that the values are compatible with DicomObject’s scrolling and drawing functions.
Due to a bug in Visual Basic, DicomViewer controls placed on a VB form do not receive events related to pressing arrow keys.
See Also

DicomViewer Object | DicomViewer Members


MouseWheel Event

MouseWheel Event
DicomObjects Reference > DicomViewer Object : MouseWheel Event
State of the Ctrl, Shift and Alt keys
The direction and distance scrolled
The mouse position, relative to the DicomViewer control.
The mouse position, relative to the DicomViewer control.
Description
fired when the Mouse Wheel is turned (only if UseMouseWheel is true)
Syntax
Visual Basic
Public Event MouseWheel( _
   ByVal Shift As Long, _
   ByVal Delta As Integer, _
   ByVal x As Long, _
   ByVal y As Long _
)
Parameters
Shift
State of the Ctrl, Shift and Alt keys
Delta
The direction and distance scrolled
x
The mouse position, relative to the DicomViewer control.
y
The mouse position, relative to the DicomViewer control.
Remarks

This is essentially a Microsoft standard wheel event, except that the x and y positions are specified as long integers representing display pixels rather than OLE_PIXELS. The value of delta is normally a positive or negative multiple of 120, (120 for each click), but might be less in future Windows implementations with a smooth scrolling mouse wheel.

Important: In previous versions of DicomObjects, MouseWheel events were converted internally to scroll events, and to maintain backwards compatibility, this remains the default behaviour. Therefore, to enable this event, the UseMouseWheel property of the viewer must be set explicitly to true.

See Also

DicomViewer Object | DicomViewer Members


OnDataChanged Event

OnDataChanged Event
DicomObjects Reference > DicomViewer Object : OnDataChanged Event
Description
fired whenever the underlying data in the controlâ€™s Images collection changes
Syntax
Visual Basic
Public Event OnDataChanged()
Remarks
This event is useful for updating any display elements which relate to the images displayed, such as the patient’s name etc.
See Also

DicomViewer Object | DicomViewer Members


OnDisplayChanged Event

OnDisplayChanged Event
DicomObjects Reference > DicomViewer Object : OnDisplayChanged Event
Description
fired whenever the display properties of any of the images in the controlâ€™s Images collection change
Syntax
Visual Basic
Public Event OnDisplayChanged()
Remarks
This event is useful for updating appropriate display elements relating to the images displayed, such as Width and Level sliders etc.
Note that OnDataChanged is always followed by OnDisplayChanged, so there is no need to duplicate functionality in the OnDataChanged routine.
See Also

DicomViewer Object | DicomViewer Members


OnFrameChanging Event

OnFrameChanging Event
DicomObjects Reference > DicomViewer Object : OnFrameChanging Event
The index of the image who’s Frame property is about to change.
The image involved may be found as: DicomViewer.Images.Item(ImageIndex)
The new Frame value
Description
fired when the frame on any displayed image changes
Syntax
Visual Basic
Public Event OnFrameChanging( _
   ByVal ImageIndex As Long, _
   ByVal Frame As Long _
)
Parameters
ImageIndex
The index of the image who’s Frame property is about to change.
The image involved may be found as: DicomViewer.Images.Item(ImageIndex)
Frame
The new Frame value
Remarks
This event is only called when an Image’s CineMode is not doCineStatic.
The main use is to display on-viewer or other frame counters, progress-bars etc.
See Also

DicomViewer Object | DicomViewer Members


DicomVolume Object

DicomVolume Object
Members
DicomObjects Reference : DicomVolume Object
Description
An object holding a set of slices which can be used as the basis for 3D reconstructions.
Remarks

This object may hold data from either:

  1. A single multi-frame DicomImage Object - via the DicomImage's MakeVolume method
    OR
  2. A set of related single frame images in a DicomImages Collection via the DicomImage collections' MakeVolume method

For more information on how this object fits into the overall mechanism for 3D viewing, see 3D Functionality

See Also

DicomVolume Members


DicomVolume Object Members

DicomVolume Object Members
Overview
DicomObjects Reference : DicomVolume Object
Public Methods
Public Method Make3D | Create a 3D image from a DicomVolume and with a defined rendering mode
Public Method PreLoad | PreLoad
See Also

DicomVolume Object


Make3D Method

Make3D Method
DicomObjects Reference > DicomVolume Object : Make3D Method
Description
Create a 3D image from a DicomVolume and with a defined rendering mode
Syntax
Visual Basic
Public Function Make3D( _
   ByVal Mode As do3DMode _
) As DicomImage
Parameters
Mode
Value | Description
do2D | Normal 2D display
doAverage | Average - this is like MPR, but with a finite thickness
doFusion | Fusion image
doMaximum | Maximum Intensity Projection
doMinimum | Minimum Intensity Projection
doMPR | Multi-Planar Reformatting
doVR | Volume Rendering
Remarks

Unlike in earlier versions of DicomObjects, MPR, MIP, VR & Slab/Average are all handled by the same class, allowing the view to be changed at will simply by changing the do3DMode property.

The members of the Projection property allow the projection to be rotated, zoomed etc., and these transformations are retained when changing views.

Multiple DicomImage objects may share the same Volume, greatly reducing memory requirements.

See Also

DicomVolume Object | DicomVolume Members


PreLoad Method

PreLoad Method
DicomObjects Reference > DicomVolume Object : PreLoad Method
Description
PreLoad
Syntax
Visual Basic
Public Sub PreLoad()
See Also

DicomVolume Object | DicomVolume Members


do3DMode Enumeration

do3DMode Enumeration
DicomObjects Reference : do3DMode Enumeration
Description
Modes used by the DicomImage Mode Property
Members
Member | Value | Description
do2D | 0 | Normal 2D display
doAverage | 3 | Average - this is like MPR, but with a finite thickness
doFusion | 7 | Fusion image
doMaximum | 4 | Maximum Intensity Projection
doMinimum | 5 | Minimum Intensity Projection
doMPR | 1 | Multi-Planar Reformatting
doVR | 6 | Volume Rendering


doAutoSizeMode Enumeration

doAutoSizeMode Enumeration
DicomObjects Reference : doAutoSizeMode Enumeration
Description

Mode available for DicomLabel.AutoSizeMode

Members
Member | Value | Description
doSizeModeAuto | 3 | Both the height and width are reduced to fit the size of the text displayed. The original width is still used to control the wrapping of the text
doSizeModeAutoSizeHeight | 2 | The original width, as defined by the label's Area is used, but the height is reduced to fit the size of the actual text displayed
doSizeModeAutoSizeWidth | 1 | The original height, as defined by the label's Area is used, but the width is reduced to fit the size of the actual text displayed
doSizeModeNoAutoSize | 0 | The original size, as defined by the label's Area is used


doCineMode Enumeration

doCineMode Enumeration
DicomObjects Reference : doCineMode Enumeration
Description
The mode used by the DicomImage.CineMode Property
Members
Member | Value | Description
doCineForward | 1 | A single run is made through the frames, and at the end, the value of this property reverts to doCineStatic
doCineOscillate | 4 | The sequence runs from the first frame to the last, and then back through the frames to the first, and the process then restarts.
doCineRepeat | 3 | The sequence of frames is run continuously from the first, to the last, and the sequence then restarts.
doCineRepeatReverse | 5 | The sequence of frames is run continuously from the last, to the first, and the sequence then restarts.
doCineReverse | 2 | A single run is made through the frames in reverse, and at the end (frame 1), the value of this property reverts to doCineStatic
doCineStatic | 0 | The default mode. The displayed frame is selected by the Frame property, and does not change.


doConnectionMode Enumeration

doConnectionMode Enumeration
DicomObjects Reference : doConnectionMode Enumeration
Description
Modes available for the DicomConnection's Mode Property
Members
Member Value Description
doAsync 1

In this mode, all operations occur on a background thread simultaneously with other operations, but .only one operation at a time may be outstanding on the DicomConnection. If another is attempted before it has completed, this causes the container to wait until the first completes, but if care is taken to avoid multiple outstanding operations true asynchronous operation is possible. The best way to achieve this is by firing all events except the first from the attached DicomViewer or DicomServer’s ActionComplete event. However, alternatives to ensure synchronization include the Wait method and isReady property.

Incoming N-EVENT-REPORTs are checked only when an outgoing operation is in progress or when CheckForEvents is called, and in either case, a success code is returned immediately. The EventReport is called at the next opportunity, but the status code is disregarded.

doNoSync 0

In this mode, it is the container’s responsibility to ensure that DicomObjects is never left waiting for an operation to complete. This can be achieved by ensuring that all operations on a DicomConnection other than the first (normally SetDestination) are fired only from ActionComplete events. The advantage of this mode is that as the container is never waiting, EventReport events can always fire synchronously, allowing a meaningful result to be returned. This is a very specialised mode of operation, intended primarily for use with reverse SCU/SCP role negotiation (e.g. for Storage Commitment use).

The default value depends on the method of creation of the DicomConnection object. If created stand-alone (which was not permitted in versions prior to 4), then mode is always doSync, and this cannot be changed, as an associated object would be required to fire ActionComplete events. For DicomConnections created through the DicomViewer’s or DicomServer’s New method, the initial value (as in prior versions) is doAsync, but this may be altered prior to the first actual operation. For incoming connections, the mode is always doAsync.

doSync 2

In this mode, every operation is performed synchronously – i.e. the method does not return control to the container until it is complete. This mode is useful for short operations, where it does not matter if the container has to wait for a network operation or for initial testing and debugging. This last feature is useful, as errors are guaranteed to be reported at the relevant method, rather than at the next, as will normally happen with the asynchronous modes.

ActionComplete events are not generated.
Incoming N-EVENT-REPORTs are checked only when an outgoing operation is in progress every 200ms, and in either case, a success code is returned immediately. The EventReport is called at the next opportunity, but the status code is disregarded.


doFilterMode Enumeration

doFilterMode Enumeration
DicomObjects Reference : doFilterMode Enumeration
Description
The list of spacing filtering modes available for use in the DicomImage MagnificationMode and MinificationMode properties.
Members
Member | Value | Description
doFilterBSpline | 2 | This smoothing procedure interpolates using a Cubic B-Spline, which has the advantage of guaranteeing continuity in both the first and second differentials of the image, in both directions. No other parameters are used in this smoothing method, which produces good visual results, though some users find them a little too “smoothed”
doFilterCubicSpline | 3 | This is similar to the B-Spline described above, but uses an additional parameter (CubicSplineAlpha) to control the degree of smoothing or edge enhancement. The default value is –0.75, and normal values range fro –0.5 to – 1.25, though higher negative values may be used to produce deliberate edge enhancement, though generally, UnsharpLength and UnsharpEnhancement should be used for this purpose, as they are independent of the smoothing method.
doFilterDefault | 0 | For MagnificationMode, this acts identically to doFilterReplicate and for MinificationMode it acts as doFilterMovingAverage. This behaviour is the default, and is deigned to minimise regulatory issues by doing the minimum necessary to display all pixel data, without adding extra “image processing”.
doFilterGpu | 8 | This mode uses interpolation in the GPU to apply magnification or minification. It does not give as much flexibility as the other modes, but may be significant faster, whilst still avoiding a "blocky" effect for magnification and avoiding aliasing on grid-lines for minification.
doFilterMovingAverage | 4 | This mode is most applicable when zoom is <1, and calculates pixels values as a weighted average of the surrounding values. The number of values used for this calculation depends on the value of FilterLength. If this is 0 (the default), then a suitable values is determined internally, based on the zoom (approximately 2/ActualZoom), but if FilterLength is non-zero then 2*FilterLength values are used.
doFilterReplicate | 1 | This would be more completely termed doFilterReplicateOrDecimate, and reproduces the behaviour used in versions of DicomObjects prior to 4.2. If zooming up is necessary, then pixels are simply replicated, giving a possibly “blocky” but honest representation of the pixel data. For minification, rows and columns are simply omitted as necessary.
Remarks
Other values may be seen in the type library but are not yet implemented.


doFlipState Enumeration

doFlipState Enumeration
DicomObjects Reference : doFlipState Enumeration
Description

Modes available for DicomImage.FlipState

Members
Member | Value | Description
doFlipBoth | 3 | Flip both horizontally and vertically
doFlipHorizontal | 1 | Flip horizontally
doFlipNormal | 0 | No flip
doFlipVertical | 2 | Flip vertically


doLabelAlignment Enumeration

doLabelAlignment Enumeration
DicomObjects Reference : doLabelAlignment Enumeration
Description
Where to align text in labels, as used in the DicomLabel's Alignment Property
Members
Member | Value | Description
doAlignBottomCentre | 9 | Bottom Centre
doAlignBottomLeft | 8 | Bottom Left
doAlignBottomRight | 10 | Bottom right
doAlignCentre | 1 | Centre
doAlignLeft | 0 | Left
doAlignMiddleCentre | 5 | MiddleCentre
doAlignMiddleLeft | 4 | MiddleLeft
doAlignMiddleRight | 6 | MiddleRight
doAlignRight | 2 | Right
Remarks
This property is only relevant where LabelType=doLabelText(0)
Alignment is relative to the area available for the text, defined by the Top, Left, Height, and Width values.


doLabelType Enumeration

doLabelType Enumeration
DicomObjects Reference : doLabelType Enumeration
Description
Types of DicomLabel, as specified by the LabelType Property
Members
Member | Value | Description
doLabelArc | 8 | Arc
doLabelArrow | 10 | Arrow
doLabelBitmap | 6 | Bitmap
doLabelEllipse | 1 | Ellipse or Circle
doLabelInterpolated | 9 | Interpolated Polygon
doLabelLine | 3 | Line
doLabelPolygon | 5 | Polygon
doLabelPolyLine | 4 | PolyLine
doLabelRectangle | 2 | Rectangle or Square
doLabelReferenceLine | 17 | ReferenceLine
doLabelRuler | 11 | Ruler (scale)
doLabelSpecial | 7 | Anatomic Side Markers
doLabelText | 0 | Text
Remarks

The meanings of all other attributes depend upon this property, and some are only relevant to some label types. See the other properties for details.
The Ruler type label produces either a vertical or horizontal scale marker, the orientation depending on which of the Width or Height properties is the larger, and tick marks may be reversed by setting the smaller property negative. The label is not displayed at all if the image does not contain scaling information, and the size of the marks may, if required, be obtained using the TickSpacing property.


doMonitorMode Enumeration

doMonitorMode Enumeration
DicomObjects Reference : doMonitorMode Enumeration
Description
Special monitor modes
Members
Member | Value | Description
doMonitorDefault | 0 | Normal - used for most cases
doMonitorTotokuPortraitMode | 1 | Special mode used for Totoku monitors which has highly anisometropic pixels, as they use the RGB components of a single pixel as if there were independent pixels.
Remarks
These are used in the viewer's MonitorMode Property


doPlane Enumeration

doPlane Enumeration
DicomObjects Reference : doPlane Enumeration
Description
Common planes used to display 3D images
Members
Member | Value | Description
doPlaneAxial | 1 | Typical a cross-section of a patient
doPlaneCoronal | 2 | A slice as if viewed from the front/back
doPlaneSagittal | 3 | A slice as if viewed from the side
doPlaneUnchanged | 0 | As a special Plane, which when used in SetViewPlane indicates the view plane should be left unaltered.


doPresentationStateFeatures Enumeration

doPresentationStateFeatures Enumeration
DicomObjects Reference : doPresentationStateFeatures Enumeration
Description
Flags to control which features of presentation states are used and/or converted
Members
Member | Value | Description
All | 65535 | All features
DisplayArea | 32 | Selection of part of image for display
GraphicAnnotations | 16 | Graphical Annotations
Masking | 512 | Masking / Subtraction
ModalityTransform | 1 | Modality Transform - i.e. rescale slope and intercept or Modality LUT
PresentationTransform | 4 | Presentation Transform - i.e. inversion or Presentation LUT
PSOverlays | 256 | Overlays activated or help by the presentation state
Shutters | 128 | Shutters defined
SpatialTransform | 64 | Rotate, flip, etc.
TextAnnotations | 8 | Text annotations
VoiTransform | 2 | VOI Transform - i.e. windowing or VOI LUT


doRotateState Enumeration

doRotateState Enumeration
DicomObjects Reference : doRotateState Enumeration
Description
Modes available for DicomImage.RotateState
Members
Member | Value | Description
doRotate180 | 2 | Rotate 180º
doRotateLeft | 1 | Rotate in 90º anti-clockwise
doRotateNormal | 0 | No rotation
doRotateRight | 3 | Rotate in 90º clockwise


doRotationBehaviour Enumeration

doRotationBehaviour Enumeration
DicomObjects Reference : doRotationBehaviour Enumeration
Description
Rotation behaviour of the Image
Members
Member | Value | Description
doRotationBehaviourBoundingBox | 1 | The top left position is defined as the top left corner of the bounding box which surrounds the rotated image
doRotationBehaviourFixedCentrePoint | 0 | The top left position is defined as being where the top left corner of the image would be if it were not rotated. If the image is rotated, it will rotated around the centre point of that non rotated position


doRotationCentre Enumeration

doRotationCentre Enumeration
DicomObjects Reference : doRotationCentre Enumeration
Description
Possible values for controlling the centre of rotation of a text label
Members
Member | Value | Description
doRotationAutoSizeCentre | 2 | The rotation point is the centre of the chosen text area, as defined by the AutoSizeMode
doRotationLabelCentre | 0 | The rotation point is the centre of the originally defined label, as defined by it's Area
doRotationSpecifiedPoint | 3 | The rotation point is the point specified by the RotationPointX and RotationPointY
doRotationTextCentre | 1 | The rotation point is the centre of the calculated text area - irrespective of the value of AutoSizeMode


doRotationMode Enumeration

doRotationMode Enumeration
DicomObjects Reference : doRotationMode Enumeration
Description
Possible values for controlling the rotation behaviour of a label
Members
Member | Value | Description
doRotationModeDefault | 2 | Non-text labels rotate, but text labels do not
doRotationModeNoRotate | 1 | The label does not rotate if the image is rotated
doRotationModeWithImage | 0 | The label rotates with the image (provided that the label's ScaleMode property is LabelScaleImage)


doScaleMode Enumeration

doScaleMode Enumeration
DicomObjects Reference : doScaleMode Enumeration
Description
How Label's dimensions should be interpreted and scaled
Members
Member | Value | Description
doLabelScale3D | 4 | Used to specify points in 3D space using images' frame of reference
doLabelScaleCell | 2 | Dimensions are in the coordinate system used by DICOM in presentation states, where (0.0,0.0) represents the top left corner of the display area, and (1.0,1.0) represents the bottom right
doLabelScaleCell1000 | 3 | Like Cell, but the corners are (0,0) and (1000,1000)
doLabelScaleImage | 1 | Dimensions are in image pixels
doLabelScaleOutput | 0 | Dimensions are in screen or other output device pixels and are unaffected by the zooming of the image


doSelectMode Enumeration

doSelectMode Enumeration
DicomObjects Reference : doSelectMode Enumeration
Description
Controls how "selection" handles are drawn on DicomLabels
Members
Member | Value | Description
doSelectAllHandles | 4 | Handles are drawn at all relevant “points”
doSelectBox | 1 | A bounding box is drawn around the label
doSelectBoxHandles | 2 | Handles are drawn at the corners of the above box
doSelectLimitedEllipseHandles | 8 | Handles are drawn only at the top, bottom and right and left hand extremes of an ellipse
doSelectNone | 0 | No highlighting
Remarks
This is used in the label's SelectMode Property


doShadowType Enumeration

doShadowType Enumeration
DicomObjects Reference : doShadowType Enumeration
Description
Control the shadowing of DicomLabel Objects
Members
Member | Value | Description
doShadowAll | 255 | All 8 directions - a wide shadow
doShadowBottom | 32 | Draw the shadow one pixel below the main label
doShadowBottomLeft | 64 | Draw the shadow one pixel to the left and one pixel down from the main label
doShadowBottomRight | 16 | Draw the shadow one pixel to the right and one pixel down from the main label
doShadowLeft | 128 | Draw the shadow one pixel to the left of the main label
doShadowNone | 0 | No shadowing (default)
doShadowRight | 8 | Draw the shadow one pixel to the right of the main label
doShadowTop | 2 | Draw the shadow one pixel above the main label
doShadowTopLeft | 1 | Draw the shadow one pixel to the left and one pixel up from the main label
doShadowTopRight | 4 | Draw the shadow one pixel to the right and one pixel up from the main label
Remarks

This is used in the label's Shadow Property

Each of the 8 main values represents one direction of shadowing, and they may be combined (by addition) as required.


doStretchModes Enumeration

doStretchModes Enumeration
DicomObjects Reference : doStretchModes Enumeration
Description
Controls how an image is displayed
Members
Member | Value | Description
NoStretch | 0 | Not stretched at all - display depends on Zoom and ScrollX & ScrollY properties. If rotated, image position will be calculated as if non-rotated, the moved by Scroll and then finally rotated around its centre point
NoStretchBoundingBox | 33 |
StretchCentred | 21 | Fitted to the available size, and centered within that
StretchTopLeft | 16 | Fitted to the available size, but placed in the top left corner
TrueSize | 32 | Similar to NoStretch, but image will be zoomed and rotated and the top-left of its bounding box calculated to provide a reference position before the Scroll is applied.


doViewerMode Enumeration

doViewerMode Enumeration
DicomObjects Reference : doViewerMode Enumeration
Description
The modes which can be used for displaying DICOM images in a DicomViewer
Members
Member | Value | Description
doViewerModeDirectX | 1 | DirectX (currently DirectX 11)
doViewerModeGdi | 0 | Graphics Display Interface (GDI+)


doVoiLUTFunction Enumeration

doVoiLUTFunction Enumeration
DicomObjects Reference : doVoiLUTFunction Enumeration
Description
Enumeration used to control whether simple width level has sharp corners (linear) or rounded ends (sigmoid)
Members
Member | Value | Description
doLinear | 0 | Use the linear mode
doSigmoid | 1 | Use the sigmoid mode
Remarks

Used to control whether simple width level has sharp corners (linear) or rounded ends (sigmoid)

This graph shows the difference between linear and sigmoid forms.

This enumeration is used by the VoiLUTFunction Property


3D Functionality

DicomObjects.COM.v8
3D Functionality
Reference Material > 3D Functionality

This is a major new feature in DicomObjects version 8, and this page provides notes on how to use it.

Concepts and Objects

The main things you need to know are:

  1. 3D reconstructions are still generated by DicomImage objects. This enables them to be viewed in DicomViewer controls via insertion to DicomImages collections.
  2. These 3D images are created by using the Make3D method of a DicomVolume Object.
  3. A DicomVolume Object is created from either:
    1. A single multi-frame DicomImage Object
      OR
    2. A set of related single frame images in a DicomImages Collection
  4. You then control the viewing of the reconstruction by using the methods and properties of the image's Projection Property.
  5. 3D specific operations are accessible with Image's PropertiesFor3D property.


New UID Allocations

DicomObjects.COM.v8
New UID Allocations
Reference Material > New UID Allocations

In order to ensure the integrity of the DICOM UID system, DicomObjects incorporates a mechanism for the automatic allocation of unique identifiers. This is used in the following circumstances:

  • When a new DicomImage is created from scratch.
    This can be due to any type of OLE object creation such as Visual Basic’s “CreateObject” method, or via the DicomViewer’
    s New method. New UIDs are automatically allocated for the Instance UID, StudyUID and SeriesUID. Commonly, of course, the Study and Series UIDs for images other than the 1st of a series will be replaced by those from the first image.
  • When a lossy image is generated. This can be due either to saving to a file, field, etc., or to network transmission. In these circumstances, the original instance UID is stored in item (0028,2112), as required by the DICOM standard, and the lossy flag, and lossy image type items are also set.
  • When the Capture or SubImage methods are used.
    As above, the details of the original image are stored in item (0028,2112).
  • When the DicomGlobal.NewUID method is used.

In order to guarantee that UIDs generated are unique, it is important that the machine is given a unique UID root under the registry entry:
HKEY_LOCAL_MACHINE/SOFTWARE/Medical Connections/DicomObjects/UIDRoot
As a service to its customers, Medical Connections will provide a guaranteed unique UID root to anyone needing one for use with DICOM, and if you do not have one, you are strongly advice to obtain one by visiting:

http://www.medicalconnections.co.uk/html/free_uid.html

Of course, you must then devise a system for allocating machine roots below this, but addition of simple sequential number to your root from Medical Connections is simple and effective. E.g. if you are given UID 1.2.826.0.1.3680043.2.50, then machines could be allocated

1.2.826.0.1.3680043.2.50.1

1.2.826.0.1.3680043.2.50.2 etc.

under the above registry key.

The UIDs generated use the date, time and an incrementing counter appended to these vales to ensure that each UID is unique. These may use up to 20 characters, so please make sure that each machine’s UID root is less than 43 characters to ensure that the resulting UIDs comply with DICOM’s 64 character limit (all lengths include the dots).


API changes for DicomLabel

DicomObjects.COM.v8
API changes for DicomLabel
Reference Material > API changes for DicomLabel

Introduction

Since labels on images were introduced in the very early days of DicomObjects, the facilities and flexibility for their display have been extended considerably, both for "specific" display and also to ensure full support for DICOM presentation states, as well as providing some rather specific requirements at some users' requests. The complexity is now rather excessive, and this has been compounded in V7 by the addition of the ability to rotate images by angles other than multiples of 90° leading to some anomalous effects when the image is rotated but the text is not.

We have therefore stepped right back and considered what is needed, bearing in mind the possible angular rotation, but always subject to the requirements for legibility. These requirements mean that text annotations cannot simply be treated the same as other graphics - to take an extreme example, flipping an image horizontally with a fully "image tied" label should fully flip an arrow etc., but clearly "mirror-image" text would be useless and possibly dangerous. Therefore the following options are planned for the new versions (.NET & COM). Whilst the primary design was based on text labels only, some users have expressed a wish to allow the same behaviour for non-text labels such as rectangles or ellipses and this has been incorporated, but the default for the 2 classes is different, being non-rotation for image tied text labels, but image tied rotation for non-text labels.

General

Text may be rotated and resized, but never mirrored

There is a (controllable) minimum font size

The specified size of the label will be used for wrapping and alignment, but will NOT cause text to be "clipped" - it will extend "downwards" (relative to its rendering angle) to ensure that whole string is rendered (but this might not all still be visible if obscured by other labels, images, or by the edge of the image area)

Auto-Sizing and Alignment

Auto-sizing is most useful when combined with showing a box around the text, or adding a line from the text to an "anchor point", as well as when adding "child labels" to the corners (.NET only). Previous versions have supported autosize as a simple Boolean, but with an obscure (user requested) means to specify that only the height should be shrunk, with the width remaining unchanged. These are being combined, with the addition (for consistency if nothing else) of a new option to preserve height but not width. As in all cases below, the dotted line indicates the defined "Area" of the label, and red indicates what is actually displayed:

This behaviour is controlled by a new AutoSizeMode property, which replaces the previous AutoSize (Boolean) property – the possibilities are:

NoAutoSize
AutoSizeWidth
AutoSizeHeight
Auto

This behaviour is of course modified by the chosen alignment, so for instance if the text is right & bottom aligned, then the appearance would be:

Similarly, if rotated, then the height/width remain relative to the rotated image's "text" frame of reference, giving for a 90° rotation (see below for when this would occur) this would be:

Explicit Rotation

This type of rotation is controlled by the Angle property of the label, and can be used on images of all scale modes (see following section for interaction with image pixel scale mode and rotated images). Whilst the DicomObjects API allows any degree of rotation, it should be noted that the DICOM Presentation State specification only allows exact multiples of 90° (via designation of one of the 4 corners as being "top left"). Whilst the angle is easy to specify as a single floating point value, there is an additional level of complexity due to the need to define the "centre of rotation", as not all users would necessarily wish this to be the centre of the label (especially if the area is defined as having a very large/unlimited right margin to avoid wrapping, as is often the case). Furthermore, if the centre were used by default, would that be the centre of the "whole" Area, or the centre of the reduced effective area actually occupied by the text (as used in AutoSized labels). A new enumeration and property have therefore been defined to control this behaviour:

RotationCentre:

RotateAtLabelCentre - default - centre of whole Area
RotateAtTextCentre - centre of actual text area (whether or not AutoSize is actually used)
RotateAtAutoSizeCentre - centre of whatever AutoSize is chosen
RotateAtPoint - defined by RotationPoint(.NET) or RotationPointX/Y (COM)

Transformation with the image

a) Rotation and Flipping

This is where the major complications arise, compounded by the different wishes of different developers. Before looking at the new model, I review the issues with the existing one. In the existing model, all works well if the text is allowed to rotate with the image (RotateTextWithImage = true), as all aspects of the label rotate in unison - e.g.

In the above scenarios, there is no need for any other adjustments to the text position, alignment nor angulation, and indeed it is important to prevent such accidental changes which were possible in the previous API - hence the decision as detailed below to move the top level control to a single enumeration, of which "RotatationMode.WithImage" is a complete definition. The only situation in which the overall effect is not the same as a simple transformation of the combined image & label is when the image is "flipped", either horizontally or vertically. In this case, the text is not mirrored, and the top left of the above set when flipped vertically would look like this:

or

With RotateAtLabelCentre With RotateAtLabelCentre
However, if the rectangle defining the area is allowed to rotate without rotation of the text, then the text and its container are mis-matched shapes, and some ambiguity arises. In these images, the green rectangle is the largest "straight" rectangle fitting within the rotated rectangle:

The above is the default behaviour of versions until now, inherited from V6, and whilst it makes some sense for the multiples of 90°, it makes no sense for other angles, and will therefore be dropped from now on. In its place will be a new "NoRotation" mode, which acts in an analogous but reversed manner to the simple rotation of an image without being image tied - i.e. the text will retain the same size and shape as if the image were NOT rotated. Like the simple rotation, this requires definition and use of a "rotation point", and the same RotationPoint and RotationCentre(X/Y) properties but in this case the definition will be in image pixel coordinates.

Equivalents to the above (moved slightly to separate centres of image and label) with NoRotate mode would now be:

With RotateAtLabelCentre

With RotateAtTextCentre

Similarly, the rotation point (the dot in the above) could be positioned elsewhere for RotateAtPoint mode.

2) Alignment

Previous versions have included a Boolean to specify whether the "Alignment" of a non-rotated text label within its overall Area should or should not be modified to match the rotation and flipping of the underlying image. This allowed text to stay at the "same corner" of the box as the box rotated

e.g.

Non-rotated

RotateAlignment = false

RotateAlignment = true

This however is not well defined when the angle can be a non multiple of 90°, and is superfluous when there is instead the ability to define the "rotation point" as being the centre of the actual text, thereby maintaining the equivalent effect of keeping the text in approximately the same place, irrespective of the "far" edges of the Area. This property is therefore being removed.

Combination of Image and Explicit Text Rotation angles

There can be independent angles for the image and the label. Logically, the point of rotation is selected, and an angle is calculated as the sum of the image rotation (if RotateWithImage mode, else 0) and the explicit rotation of the label itself. The text is then rotated about that combined angle.

Summary

The new API uses 5 properties to define the positioning and angle of the image relative to its Area and the image.

The following are new properties:

AutoSizeMode: enum

  1. AutoSize
  2. AutoSizeHeight
  3. AutoSizeWidth
  4. NoAutoSize

RotationMode: enum

  1. RotateWithImage
  2. NoRotate
  3. Default (RotateWithImage for non-text and NoRotate for text labels)

RotationCentre: enum

  1. RotateAtLabelCentre
  2. RotateAtTextCentre
  3. RotateAtAutoSizeCentre

RotateAtPoint

RotationPoint (PointF X&Y floats in COM)

These completely replace the following properties and registry values:

RotateTextWithImage : bool
RotateAlignmentWithImage: bool
AutoSize: bool
RegistryWord "FixedAutoWidth"


Third party license compliance

DicomObjects.COM.v8
Third party license compliance
Reference Material > Third party license compliance

Below is a list of third party tools included in this product and their usage policy as defined. This is to make you (our users) aware of the usage of third party tools, their policies and adherence to the legal aspects of using them in your product. Here is the complete list of external code included in our product and how you are entitled to use them, if you wish to.

  1. FFmpeg is a Codec to support variety of video formats and their usage policy can be viewed on their website which also has a compliance checklist for using FFmpeg in your project https://www.ffmpeg.org/legal.html. You can also find their reference in our website license http://www.medicalconnections.co.uk/kb/Video_support_with_FFmpeg
  2. JasPer Software License for handling JPEG 2000 file formats. Licence for using this Codec can be found int he Software License section in Appendix A https://www.ece.uvic.ca/~frodo/jasper/jasper.pdf
  3. We have supported other JPEG formats with the help of Independent JPEG Group's software's Codec http://www.ijg.org
  4. Microsoft's DirectX is used for GPU efficient processing and is available as a Viewer mode.
  5. Microsoft's Capicom is used for encryption to establish a secured connection.


Useful Links

DicomObjects.COM.v8
Useful Links
Reference Material > Useful Links

For FAQ please check our website articles, where you can find discussions and solutions for most common errors and questions regarding DICOM and our toolkit KB articles.

Latest DICOM standard can be found here DICOM standard.

For the latest list of DICOM attributes please follow this link DICOM standard Part 6.

Some values that relate to DicomObjects as a whole are controlled through registry values, which can be set using the RegWord and RegString properties of the DicomGlobal object. For latest list please click Here.


Contact Information

DicomObjects.COM.v8
Contact Information
Reference Material > Contact Information

Contact Information for Medical Connections Ltd:

E-mail: | support@medicalconnections.co.uk
Web: | www.medicalconnections.co.uk
Address: | Suite 10, Henley House Queensway Fforestfach Swansea SA5 4DJ United Kingdom
Telephone: | +44 1792 390209 US toll free: (during UK business hours!): 888 342 6634
Fax: | +44 1792 390495


Certificates

DicomObjects.COM.v8
Certificates

There are various places in DicomObjects where it is necessary either to use or to receive and verify X509 certificates. Fortunately, there is already a well-established method of doing this within Windows using “CAPICOM” objects, which are supplied by Microsoft.
Full reference is available on the Microsoft web site
Recent systems and those which have had other software might already have CAPICOM installed,. but it might needed to be added. It is freely redistributable, and available from Microsoft, but only as part of a complete platform SDK, which is a little large just to get one component, so if necessary, it is also available from the Medical Connections web site.

The CAPICOM API provides multiple ways of storing and accessing certificates in this form, but simple visual basic code to retrieve the first user certificate with a suitable private key from the local certificate store might be:

Load Certificate
Copy Code
Dim myStore As New Store
Dim cert As Certificate
myStore.Open CAPICOM_CURRENT_USER_STORE,
  CAPICOM_MY_STORE,CAPICOM_STORE_OPEN_READ_ONLY
For Each cert In myStore.Certificates
    If cert.HasPrivateKey Then Exit For
Next
cert.Display

This could then be used for any purpose where a certificate is needed in DicomObjects. e.g.:

MsgBox Viewer.ListenSecure(1000, cert, True)

Other methods are available, including importantly those for validation and extraction of data from certificates received from remote entities.


Compression and Decompression DLLs

DicomObjects.COM.v8
Compression and Decompression DLLs

DicomObjects includes the facility to write your own DLLs to implement private transfer syntaxes, and this topic explains how.
Separate routines are normally used for packing and unpacking of data. Routines are searched as below before checking the internal tables, so it would be possible to replace the DicomObjects default (de)compression routines for the various JPEG formats or RLE if required. It is also possible to write routines specifically to convert from one syntax to another, and if a specific transcoding routine is specified, this is used in place of the compression and decompression routines (whether external or intrinsic).

In order for the DLL to be found, the transfer syntax UID(s) to be handled should be created as a key under the DicomObjects appropriate registry path. For transcoding routines, the <Conversion> is simply the names of the source and destination syntaxes, with “TO” in between, e.g. “1.2.840.1234.1TO1.2.840.4321.4”. For (de)compression routines, this must contain the 2 values DllName and Entry, and for transcoding routines, it may contain also contain the Prepare entry:

DllName: The Name of the DLL This must either exist on the system PATH, or be fully qualified
Entry: The name of the entry point for this function
Prepare: An optional function called once before any frames are converted
The appropriate registry paths are:
Compression:
HKEY_LOCAL_MACHINE/Software/Medical Connections/DicomObjects/Compress/<UID>
Decompression:
HKEY_LOCAL_MACHINE/Software/Medical Connections/DicomObjects/Decompress/<UID>
Transcoding:
HKEY_LOCAL_MACHINE/Software/Medical Connections/DicomObjects/Transcode/<Conversion>

The functions to perform the export or export must be callable as standard DLL routines, and in C++, the declarations are:

Pack Function
Copy Code
extern "C"
_declspec(dllexport) int __cdecl PackFunction(
byte * source,
byte * destination,
unsigned int length,
unsigned int nx,
unsigned  int ny,
unsigned  int planes,
unsigned int planarconfig,
unsigned int bitsperpixel,
const char* TransferSyntax,
const char* PhotometricInterpretation,
bool issigned,
IDispatch* attributes,
  VARIANT quality)

Return value is total number of output bytes for the given frame.

Unpack Function
Copy Code
extern "C"
_declspec(dllexport) boolean __cdecl UnPackFunction(
byte * source,
byte * destination,
unsigned int length,
unsigned int nx,
unsigned  int ny,
unsigned  int planes,
unsigned int planarconfig,
unsigned int bitsperpixel,
const char* TransferSyntax,
const char* PhotometricInterpretation,
bool issigned,
IDispatch* attributes,
const char* ImplementationUID)

Return value is true for success or false for failure

Transcode Function
Copy Code
extern "C"
_declspec(dllexport) unsigned int __stdcall TranscodeFunction(
byte * source,
byte * dest,
unsigned int length,
unsigned int nx,
unsigned  int ny,
unsigned  int planes,
unsigned int planarconfig,
unsigned int bpp,
const char* InputTransferSyntax,
const char* OutputTransferSyntax,
const char* ColourSpace,
bool issigned, IDispatch* attributes,
VARIANT quality)

Return value is the number of bytes written for this frame.
The pack, unpack and transcode functions work on one frame at a time on request, and are called after the non-pixel data has been written, but for transcoding it may also be necessary to modify other data elements, so the prepare function allows this to happen, being called once before any data is written.

Prepare Function
Copy Code
extern "C"
_declspec(dllexport) unsigned int __stdcall PrepareFunction(
const char* InputTransferSyntax,
const char* OutputTransferSyntax,
const char* ColourSpace,
IDispatch* attributes,
VARIANT quality,
char OutputColourSpace[20],
char LossyDescription[128],
float & offset,
float & scale,
bool isCompressed,
byte * FirstFrame)

If errors occur in any of these functions, they may throw standard C++ exceptions.
In all cases, the destination buffer is allocated (and freed when necessary) by DicomObjects. For decompression, the buffer will be of exactly the required size, as calculated from the image dimensions and bit depth. For compression, the buffer is 1.5x the uncompressed size – enough to cope with even the worst compression scheme on random data!
Use of these facilities is an advanced technique and advice is available from Medical Connections if required.


Date and Time Formats

DicomObjects.COM.v8
Date and Time Formats

In general dates and times are handled correctly by the objects in this collection, all necessary conversions being performed. This means that:

  • DICOM dates are received in both the old (YYYY/MM/DD) and new (YYYYMMDD) format, the same applying to time and date/time values also.
  • The value of an correctly formatted DicomAttribute of DICOM value representation DA, TM or DT is a Variant of type Date.
  • When creating an element of a date related type using DicomAttributes.Add, either a date variant, or any type that Windows can coerce into a date is acceptable, and will be correctly converted.

There is, however, an anomaly in the DICOM standard, allowing dates and times to contain ‘range’ values in the forms ‘value-value’ ‘-value’ or ‘value-‘. Such constructs are not easily handled by the mechanisms above, and therefore, in order to allow such values to be used in queries (both outgoing and incoming), any date or time value which cannot be recognised will normally be stored and passed on as a simple string.

Applications creating such ranges will need to create them directly in a form such as ‘19810101-19811231’, and they may also be interpreted this way if required, but as of version 4.1, DicomObjects provides the DateTimeFrom and DateTimeTo properties, which simplify this process for programmers writing SCPs.


References

References


Error Codes

DicomObjects.COM.v8
Error Codes
1001 | Bad Element type
1002 | Invalid Colour space for JPEG
1003 | Failed to open file for reading
1004 | Error reading from file
1005 | Illegal combination of root and query level
1006 | Invalid New type requested
1007 | CurrentIndex Out of Range
1008 | Invalid Query root
1009 | Bad Initial PDU type
1010 | Failed to Create Socket
1011 | Failed to connect at TCP level
1012 | P-DATA PDU expected - type %i received
1013 | Remote Socket Disconnected
1014 | Missing Meta length
1015 | Attempt to use Abstract syntax not in negotiated list
1016 | 'Raw' queries must be used for Worklist management
1017 | %i bit Image not supported in Transfer Syntax %s
1018 | Array assigned to single-valued element
1019 | Invalid Variant passed - Conversion failed
1020 | String or Variant Array required
1021 | Subscript out of range
1022 | Invalid Array type passed
1023 | SOP Instance UID not found
1024 | Non object used as sequences item
1025 | Invalid DataSets passed as sequence
1026 | Pixel data must be 1, 2 or 3 dimensional array of bytes or short integers
1027 | Invalid Variant passed as date - Conversion failed
1028 | Invalid Variant type as index
1029 | Attempt to write a file in safe scripting mode
1030 | Attempt to read a file in safe scripting mode
1031 | Attempt to perform an outgoing network operation in safe scripting mode
1032 | URL open failed
1033 | Accepted Transfer Context or rejection code cannot be changed unless accepting an association
1034 | Offered Transfer Contexts can only be changed when initiating an association
1035 | Import/Export filter error
1036 | Pixel Data Length mismatch
1037 | SendStatus is only valid for Q/R requests
1038 | SendData is only valid for C-FIND
1039 | Not a DataSets or DataSet object
1040 | SetDestination is not valid for C-FIND and C-GET operations
1041 | SendImages is not valid for C-FIND operations
1042 | Not an Images or Image object
1043 | Close is not allowed for Q/R requests - use SendStatus instead
1044 | C-FIND pending must be returned via 'ReturnData'
1045 | Unknown status code
1046 | Internal return type error
1047 | No bitmap data on clipboard
1048 | Invalid association number
1049 | Association Request Rejected
1050 | Remote application appears to have disconnected
1051 | http connect failure
1052 | Not a DicomDir
1053 | Bad offset in DicomDir
1054 | Unsupported bits per pixel in imported bitmap
1055 | Internal offset lookup error
1056 | Internal offset lookup error - MRDR
1057 | Attempt to use undefined MRDR property
1058 | End of File reached
1059 | Unknown Import/Export Format
1060 | Invalid value in incoming data at about byte %u (0x%x)
1061 | Number of Planes does not match number of RLE segments
1062 | Unsupported transfer Syntax
1063 | NOT USED
1064 | Absent Pixel Data
1065 | Empty JPEG file
1066 | Unsupported Compression Method
1067 | Transfer syntax 1.2.840.10008.1.2.4.50 supports 8 bit images only
1068 | Only DicomDataSet Objects may be added to a DicomDataSets collection
1069 | Bitmap conversion for capture failed
1070 | Unknown VR
1071 | Too many components for interleaved scan
1072 | Invalid Combination: Bit(s) per Pixel=%i, but Photometric Interpretation=%s
1073 | Error reading from stream
1074 | Error reading from URL
1075 | Field object appears to be neither ADO (>=1.5) DAO 3.0, DAO 3.5 or RDO 2.0
1076 | Object appears not to support IStream
1077 | Bad Pixel Data
1078 | Bad Subsequent PDU Type
1079 | Corrupt JPEG Data: bad Huffman code
1080 | Date/Time arrays not supported
1081 | File Open error
1082 | Frame number out of range
1083 | Invalid Object Type
1084 | No data to find
1085 | No Pixel Data Defined
1086 | Photometric interpretation Not supported for JPEGs
1087 | Pixel Data is Compressed
1088 | SCP returned more Abstract Syntaxes than offered
1089 | Too many presentation contexts defined (limit is 127)
1090 | Unsupported conversion type
1091 | DicomConnection object is no longer open
1092 | Failed to open window into memory mapped file
1093 | No Association is currently open
1094 | Abort Received - source = x, reason=y
1095 | Unsupported JPEG colour space
1096 | Unknown Photometric Interpretation
1097 | System error
1099 | Unspecified error
1100 | Internal error: image number not found
1101 | Internal error: Unable to create DICOM notify window!
1102 | Internal error: bad command
1103 | Internal Error: Incompatible Storage syntaxes!
1104 | Internal Error: incorrect bookmark
1105 | Internal Error: incorrect seek
1106 | Internal error - bad date/time VR
1107 | Internal offset lookup error - MRDR
1201 | Huffman code size table overflow
1202 | Bogus DHT counts
1203 | Bogus DHT index
1204 | Can't malloc HuffmanTable
1205 | Not a JPEG file.
1206 | Bogus length in DRI
1207 | Empty JPEG image (DNL not supported)
1208 | Unsupported JPEG Data Precision
1209 | Bogus SOF length
1210 | Bogus SOS length
1211 | Invalid component number in SOS
1212 | Premature end of JPEG Data
1213 | Downsampling is not supported.
1214 | Too many components for interleaved scan
1215 | Use of undefined Huffman table (known problem with some GE files)
1216 | Corrupt JPEG Data.
1217 | Huffman table not defined
1218 | Restart interval is too big.
1219 | Maximum image dimension for JFIF is 65535 pixels
1400 | End of field
1401 | Bits must be in range 8-16
1402 | Must have at least one image for MakeMultiFrame
1403 | Unable to listen on port
1404 | Invalid command returned from remote entity
1405 | DicomConnection mode may not be changed if created 'stand-alone' or once association opened
1406 | Timed-out while waiting to receive network data
1407 | Timed-out while waiting to send network data
1408 | Element is absent
1409 | The remote node does not appear to accept %n requests with Root=%s, at least with currently defined transfer syntaxes
1410 | New VR must be a 2 character string
1411 | Points must be set to a 1 dimensional array of short integers
1412 | Value ROIs are only applicable to monochrome images
1414 | Label is not tied to an image
1415 | C-MOVE SCP returned error status
1416 | Error occured but could not be formatted
1417 | Cannot threshold a label without an area
1418 | At least 2 points are required for a BoundingPolygon
1419 | No image boxes created
1420 | NextPosition must be within range of current film
1421 | Printer error
1422 | BoundingPolygon only applies to bitmaps, polygons and polylines
1423 | Attempt to use (for display or masking) a frame beyond the available range
1424 | Memory access error while using pixel data - image is probably truncated
1425 | Failed to open port specifically for GetUsing Move - is it already open by a DicomViewer or DicomServer?
1426 | Methods must not overlap when Mode==doNOSYNC
1427 | Long integer values required
1428 | Only MONOCHROMEn & RGB are allowed as translated syntaxes
1429 | Failed to create thread
1430 | This function is not supported in DicomObjects Light
1431 | Memory limit exceeded
1432 | Failed to intialise sockets
1433 | Cannot 'Window' into an image with signed data
1434 | Must use windowing where source and destination images are of different types
1435 | This transfer syntax would require scaling to 12 bits unsigned, but images with Modality LUTs cannot safely be scaled
1436 | Cannot Render non-palette data into a COLOR PALETTE image
1437 | DirectDraw surface creation failed
1438 | Open method must be used before PrintImage
1439 | In order to use ReadURL, you ust either install Internet Explorer 3 or greater, or otherwise install WININET.DLL
1440 | This function is not supported in this version of DicomObjects
1442 | This operation is not supported on this type of DicomLabel under Windows CE
1443 | Association Aborted
1444 | Data received is too short
1445 | Accepted context not in offered list
1446 | Couldn't decrypt
1447 | Short Pixel Data
1448 | TLS Negotiation Failed
1449 | Reference lines can only be contructed where the images have the same frame of reference UID
1450 | Either the base or reference image is mising one of the following: orientation cosines, image position, or pixel sizing
1451 | String Value is not compatible with the rules for VR
1452 | Element is too long to be written in Explicit VR format
1453 | Display of images with bits per pixel not a multiple of 8 is not supported
1454 | JPEG 2000 decoding failed - probably corrupt data, or not JPEG 2000
1455 | Illegal 1D Texture length, maximum allowed length is 8192


Extended Character Sets

DicomObjects.COM.v8
Extended Character Sets

DICOM itself has always allowed use of a variety of extended character sets using ISO 2022 standardised encoding, and has recently incorporated also native Unicode (UTF-8) and Chinese GB18030 encodings. DicomObjects allows you to access data in these formats in two ways:

1) By using “standard” access methods (e.g. DicomAttribute Value property), the “raw” data, complete with escape strings, and double byte characters (where used) may be retrieved, and interpreted yourself, in conjunction with the 0008,0005 character set code.

2) By Using the UnicodeValue or UnicodeValue2 method, the strings are interpreted internally into Unicode, for subsequent display etc.

Notes:

DicomObjects relies on the operating system to do the necessary conversions, and support varies between different versions of Windows, but this is not generally an issue on recent versions of Windows.

The Unicode strings may be used directly for constructing DicomLabel objects – e.g. to display a patient’s name over the image. Provided that a suitable font is chosen (one which supports both Unicode and the local character set), then this should work with no further manipulation necessary

Standard GUI objects in VB (and possibly some other languages) do not support Unicode, so names using extended characters will not display correctly in standard text boxes, list boxes, tree controls etc. There are however a number of easy to use replacements in which Unicode has been properly implemented (e.g. UniToolBox ) which solve this problem.

At present, DicomObjects does not support translation of Unicode to DICOM escaped sequences, as there are so many possible ambiguities when converting in this direction. Support for conversion to UTF-8 may be added if requested.

DicomObjects supports all the character sets listed in DICOM as of July 2003, including those in CP252 (March 2003): They are:

  • Latin 1
  • Latin 2
  • Latin 3
  • Latin 4
  • Latin 5
  • Cyrillic
  • Arabic
  • Greek
  • Hebrew
  • Japanese ( Kanji, Supplemental Kanji, Romanji & Katakana )
  • Thai
  • Korean
  • Unicode in UTF-8
  • Chinese GB 18030


Import/Export DLLs

DicomObjects.COM.v8
Import/Export DLLs

DicomObjects includes the facility to write your own DLLs for import and export of external image formats, and this topic explains how.
There are two types of filter, those for memory formats, and those for files. When importing from or exporting to a file, DicomObjects first check for an appropriate file specific DLL entry, but if this is not present, then an appropriate memory based entry will be used if available. This process is applied before checking for intrinsic functions, so the internal JPEG and DIB/BMP routines may be over-ridden if necessary.

In order for the appropriate DLL to be found, the <Type> to be handled should be created as a key under the correct DicomObjects registry path, and this must contain 2 values:

  • DllName: The Name of the DLL This must either exist on the system PATH, or be fully qualified
  • Entry: The name of the entry point for this function

The appropriate registry paths are:

  • Memory Import:
    HKEY_LOCAL_MACHINE/Software/Medical Connections/DicomObjects/MemoryImport/<Type>
  • Memory Export:
    HKEY_LOCAL_MACHINE/Software/Medical Connections/DicomObjects/MemoryExport/<Type>
  • File Import:
    HKEY_LOCAL_MACHINE/Software/Medical Connections/DicomObjects/FileImport/<Type>
  • File Export:
    HKEY_LOCAL_MACHINE/Software/Medical Connections/DicomObjects/FileExport/<Type>

The functions to perform the export or export must be callable as standard DLL routines, and in C++, the declarations are:

extern "C"
_declspec(dllexport) void __cdecl FileImportExportFunction

(IDispatch * Image,
const char * Filename,
const char * Type,
const VARIANT FAR& Info,
char ** error)

extern "C"
_declspec(dllexport) OLE_HANDLE __cdecl ExportMemoryFunc(

IDispatch * Image,
const char * Type,
const VARIANT FAR& Info,
char ** error,
long * len)

extern "C"
_declspec(dllexport) void __cdecl ImportMemoryFunc(

IDispatch * Image,
OLE_HANDLE Handle,
const char * Type,
const VARIANT FAR& Info,
char ** error)

Image is the DicomImage being imported, and needs to be accessed through its standard properties and methods. In practice, the DicomObjects type library would normally be #import’ed, and this parameter may become “struct IDicomImage * Image”.
ExportMemoryFunc must return a global memory handle (cast to an OLE_HANDLE). This will be deallocated either by the calling process (if called from MemoryExport) or by DicomObjects (if called from ArrayExport or FileExport). The length of the actual data with this memory block should be returned in len)

ImportMemoryFunc is passed it’s data via the Handle parameter. This memory block should be unaltered on return, i.e. if locked it should be unlocked again, and it should not be freed.
Filename, Type and Info are passed directly from the corresponding Import or Export methods.
Error initially points to a NULL pointer, but if an error occurs, then it should be set to point to a simple character string, containing an explanatory message, (which should be allocated on the heap, and will be cleared by DicomObjects)


Log Level

DicomObjects.COM.v8
Log Level

This value controls the level of detail logged either to the display, or to a file. The same values are used when registry controlled logging is used ("LogLevel" registry key).
The value of this property is a bit field, being the sum of the following bit values:

Decimal | Hex |
1 | 1 | Errors
2 | 2 | Warnings
4 | 4 | Informational Messages
8 | 8 | Detailed Logging
16 | 10 | All DICOM attributes received or read
32 | 20 | All DICOM attributes send or written
64 | 40 | Byte-level data received, except contents of data PDUs
128 | 80 | Byte-level data sent, except contents of data PDUs
256 | 100 | ALL bytes received
512 | 200 | ALL bytes sent

The last two levels should NOT be used when images are being sent or received, as the quality of log data becomes unmanageable, and the system will probably run so slowly that connecting equipment will time-out.
Other bits in the lower word are reserved for Medical Connections’ use or future expansion.
The bits in the high word (65536 upwards) are available for user use – see the DicomGlobal.Log method for more details.


Security

DicomObjects.COM.v8
Security

The DicomObjects collection implements the IObjectSafety interface, which enables all objects to be placed into a “Safe for Scripting” mode. For security reasons the user’s explicit permission is required before outgoing network operations are allowed or files are read or written to whilst in this mode, which is activated automatically when a viewer is included on a web page as an ActiveX object. The methods affected by this restriction are:

ReadFile
WriteFile
ReadDirectory
WriteDirectory
ReadURL(if the URL refers to a local file)
Send
FileImport
FileExport

Creation of a DicomQuery or outgoing DicomConnection object

The DicomViewer is registered as “Safe for Initialising” at all times.


Special Labels

DicomObjects.COM.v8
Special Labels

DicomLabels of type doLabelSpecial are used where the text content is determined by DicomObjects rather than by the programmer. The first use is for anatomic side markers, but the more general name has been used, as other types may be used in the future.
Anatomic side markers are created by setting the Text property of the DicomLabel to one of the following 4 values:

  • “LEFT”
  • “RIGHT”
  • “TOP”
  • “BOTTOM”

If an unrecognised value is used, or if the image lacks the necessary DICOM attributes then the label will simply not be displayed.

If the label can be displayed, then DicomObjects calculates, using the orientation information within the image which anatomic direction(s) correspond with the selected edge of the image as displayed and (unless changed as below) will display one or more of the following characters R,L,A,P,I or S, corresponding to right, left, anterior, posterior, inferior and superior respectively. Where the image orientation is oblique, 2 or more characters will be displayed, in decreasing order of importance,

If writing an application for users who’s language is not English, you may wish to localise the characters used, and this can be done by setting the DirectionStrings property of a DicomGlobal object.

When interpreting this property, DicomObjects uses only the value of the text property to calculate the string displayed, not the position of the label, so it is the programmer’s responsibility to ensure that the position and content correspond by placing the label close to the appropriate edge. It is particularly important to ensure that width and height have non-zero but relatively small values, so that the label stays in the correct place when the image is flipped or rotated.

If the RotateModeWithImage property is set, then rotation or flipping of the image cause the label to move, but the text remains constant. If ImageTied is false, then label remains fixed in position, but the text alters to reflect the position of the image. In either case, the information should remain anatomically correct.

If you use this feature, you are strongly advised to use at least two markers, to prevent confusion between orientation and side markers. To make this distinction clear, consider an image of the right leg. If only a single side label is used, at the side of the image corresponding with the midline of the patient, this will be labelled “L” for left, which is correct as far as orientation is concerned, but could confuse users, who might think that they were being shown the left leg. However, if both R and L markers are present, then they could only be orientation markers, and the potential confusion is removed.