/// <summary>
        /// Deserializes the key object selection SOP instance into a list of constituent images and associated presentation states.
        /// </summary>
        public IList <IKeyObjectContentItem> Deserialize()
        {
            List <IKeyObjectContentItem> contentItems = new List <IKeyObjectContentItem>();

            SrDocumentContentModuleIod srDocument = _document.SrDocumentContent;

            if (srDocument.ContentSequence != null)
            {
                foreach (IContentSequence contentItem in srDocument.ContentSequence.Where(contentItem => contentItem.RelationshipType == RelationshipType.Contains))
                {
                    if (contentItem.ValueType == ValueType.Image)
                    {
                        IImageReferenceMacro imageReference = contentItem;
                        if (imageReference.ReferencedSopSequence == null)
                        {
                            Platform.Log(LogLevel.Warn, "Invalid Key Object Selection document has no Referenced SOP Sequence.");
                            continue;
                        }

                        string referencedSopInstanceUid        = imageReference.ReferencedSopSequence.ReferencedSopInstanceUid;
                        string presentationStateSopInstanceUid = null;

                        if (imageReference.ReferencedSopSequence.ReferencedSopSequence != null)
                        {
                            presentationStateSopInstanceUid = imageReference.ReferencedSopSequence.ReferencedSopSequence.ReferencedSopInstanceUid;
                        }

                        string referencedFrameNumbers = imageReference.ReferencedSopSequence.ReferencedFrameNumber;
                        int[]  frameNumbers;
                        if (!string.IsNullOrEmpty(referencedFrameNumbers) &&
                            DicomStringHelper.TryGetIntArray(referencedFrameNumbers, out frameNumbers) && frameNumbers.Length > 0)
                        {
                            foreach (int frameNumber in frameNumbers)
                            {
                                KeyImageContentItem item = new KeyImageContentItem(referencedSopInstanceUid, frameNumber, presentationStateSopInstanceUid, _document);
                                contentItems.Add(item);
                            }
                        }
                        else
                        {
                            KeyImageContentItem item = new KeyImageContentItem(referencedSopInstanceUid, presentationStateSopInstanceUid, _document);
                            contentItems.Add(item);
                        }
                    }
                }
            }
            else
            {
                Platform.Log(LogLevel.Warn, "Invalid Key Object Selection document has no Content Sequence.");
            }

            return(contentItems.AsReadOnly());
        }
		protected virtual List<IPresentationImage> CreateImages(KeyImageContentItem item)
		{
			List<IPresentationImage> images = new List<IPresentationImage>();

			ImageSop imageSop = FindReferencedImageSop(item.ReferencedImageSopInstanceUid, item.Source.GeneralStudy.StudyInstanceUid);
			if (imageSop != null)
			{

				int frameNumber = item.FrameNumber.GetValueOrDefault(-1);
				if (item.FrameNumber.HasValue)
				{
					// FramesCollection is a 1-based index!!!
					if (frameNumber > 0 && frameNumber <= imageSop.Frames.Count)
					{
						images.Add(Create(imageSop.Frames[frameNumber]));
					}
					else
					{
						Platform.Log(LogLevel.Error, "The referenced key image {0} does not have a frame {1} (referenced in Key Object Selection {2})", item.ReferencedImageSopInstanceUid, frameNumber, item.Source.SopCommon.SopInstanceUid);
						images.Add(new KeyObjectPlaceholderImage(SR.MessageReferencedKeyImageFrameNotFound));
					}
				}
				else
				{
					foreach (Frame frame in imageSop.Frames)
					{
						images.Add(Create(frame));
					}
				}

				Sop presentationStateSop = FindReferencedSop(item.PresentationStateSopInstanceUid, item.Source.GeneralStudy.StudyInstanceUid);
				if (presentationStateSop != null)
				{
					foreach (IPresentationImage image in images)
					{
						if (image is IPresentationStateProvider)
						{
							try
							{
								IPresentationStateProvider presentationStateProvider = (IPresentationStateProvider)image;
								presentationStateProvider.PresentationState = DicomSoftcopyPresentationState.Load(presentationStateSop.DataSource);
							}
							catch (Exception ex)
							{
								Platform.Log(LogLevel.Warn, ex, SR.MessagePresentationStateReadFailure);
							}
						}
					}
				}
			}
			else
			{
				Platform.Log(LogLevel.Warn, "The referenced key image {0} is not loaded as part of the current study (referenced in Key Object Selection {1})", item.ReferencedImageSopInstanceUid, item.Source.SopCommon.SopInstanceUid);
				images.Add(new KeyObjectPlaceholderImage(SR.MessageReferencedKeyImageFromOtherStudy));
			}

			return images;
		}
		/// <summary>
		/// Deserializes the key object selection SOP instance into a list of constituent images and associated presentation states.
		/// </summary>
		public IList<IKeyObjectContentItem> Deserialize()
		{
			List<IKeyObjectContentItem> contentItems = new List<IKeyObjectContentItem>();

			SrDocumentContentModuleIod srDocument = _document.SrDocumentContent;
			if (srDocument.ContentSequence != null)
			{
				foreach (IContentSequence contentItem in srDocument.ContentSequence.Where(contentItem => contentItem.RelationshipType == RelationshipType.Contains))
				{
					if (contentItem.ValueType == ValueType.Image)
					{
						IImageReferenceMacro imageReference = contentItem;
						if (imageReference.ReferencedSopSequence == null)
						{
							Platform.Log(LogLevel.Warn, "Invalid Key Object Selection document has no Referenced SOP Sequence.");
							continue;
						}

						string referencedSopInstanceUid = imageReference.ReferencedSopSequence.ReferencedSopInstanceUid;
						string presentationStateSopInstanceUid = null;

						if (imageReference.ReferencedSopSequence.ReferencedSopSequence != null)
						{
							presentationStateSopInstanceUid = imageReference.ReferencedSopSequence.ReferencedSopSequence.ReferencedSopInstanceUid;
						}

						string referencedFrameNumbers = imageReference.ReferencedSopSequence.ReferencedFrameNumber;
						int[] frameNumbers;
						if (!string.IsNullOrEmpty(referencedFrameNumbers)
						    && DicomStringHelper.TryGetIntArray(referencedFrameNumbers, out frameNumbers) && frameNumbers.Length > 0)
						{
							foreach (int frameNumber in frameNumbers)
							{
								KeyImageContentItem item = new KeyImageContentItem(referencedSopInstanceUid, frameNumber, presentationStateSopInstanceUid, _document);
								contentItems.Add(item);
							}
						}
						else
						{
							KeyImageContentItem item = new KeyImageContentItem(referencedSopInstanceUid, presentationStateSopInstanceUid, _document);
							contentItems.Add(item);
						}
					}
				}
			}
			else
			{
				Platform.Log(LogLevel.Warn, "Invalid Key Object Selection document has no Content Sequence.");
			}

			return contentItems.AsReadOnly();
		}