BeginReadSequence(DicomElement,bool,long) Method

Summary

Used to read values from an existing DICOM sequence.

Syntax

C++/CLI

public DicomDataSet BeginReadSequence( 
   DicomElement element, 
   bool tree, 
   long tag 
)

public: 
DicomDataSet^ BeginReadSequence(  
   DicomElement^ element, 
   bool tree, 
   int64 tag 
)

Parameters

element
an item in the data set

tree
true to evaluate the Data Set as a tree; false to evaluate the Data Set as a list.

tag
tag number of the DICOM element sequence

Return Value

a reference to the DicomDataSet

Remarks

This method is used to begin reading values from an existing DICOM sequence. It is part of a group of four methods that are to be used together. The four methods are listed below:

BeginReadSequence
EndReadSequence
BeginReadItem
EndReadItem

These methods are part of a fluent interface that are used to easily work with DICOM sequences. The methods can be chained together to create easily human readable code to create a sequence.

Passing null for the parameter element, and true for the parameter tree will attempt to read a sequence from the root of the DICOM data set. To read a sequence that is not at the root, pass the sequence item element for the parameter element, and false for the parameter tree. For more information on the element and tree paramters, see FindFirstElement.

The format of the code for reading a sequence is as follows:

ds.BeginReadSequence 
  .BeginReadItem() 
     .GetValue 
     .GetValue 
  .EndReadItem() 
  .BeginReadItem() 
     .GetValue 
     .GetValue 
  .EndReadItem() 
.EndReadSequence();

Example

using Leadtools; 
using Leadtools.Dicom; 
 
 
///  
private void DicomDataSet_BeginEditSequenceExample() 
{ 
   // The methods below all return a 'this' pointer so that they can be chained together (a 'fluent' interface) 
   // BeginEditItem has an index item to allow you to specify which item to edit (defaults to 0). 
   // BeginReadItem should also have this overload. 
   // 
 
   // Create a DicomDataSet  
   DicomDataSet ds = new DicomDataSet(); 
 
   // *************************************************** 
   // *** Example 1  
   // *************************************************** 
 
   // Create a sequence with two items 
   ds.BeginEditSequence(DicomTag.RequestAttributesSequence) 
        .BeginEditItem() 
           .InsertElementAndSetValue(DicomTag.RequestedProcedureID, "RequestedProcedureID -- first item") 
           .InsertElementAndSetValue(DicomTag.ScheduledProcedureStepID, "ScheduledProcedureStepID -- first item") 
        .EndEditItem() 
        .BeginEditItem() 
           .InsertElementAndSetValue(DicomTag.RequestedProcedureID, "RequestedProcedureID -- second item") 
           .InsertElementAndSetValue(DicomTag.ScheduledProcedureStepID, "ScheduledProcedureStepID -- second item") 
        .EndEditItem() 
     .EndEditSequence(); 
 
   // Now add a third item to the sequence 
   ds.BeginEditSequence(DicomTag.RequestAttributesSequence) 
        .BeginEditItem(2) 
           .InsertElementAndSetValue(DicomTag.RequestedProcedureID, "RequestedProcedureID -- third item") 
           .InsertElementAndSetValue(DicomTag.ScheduledProcedureStepID, "ScheduledProcedureStepID -- third item") 
        .EndEditItem() 
     .EndEditSequence(); 
 
   // Now update the second item in the sequence 
   ds.BeginEditSequence(DicomTag.RequestAttributesSequence) 
        .BeginEditItem(1) 
           .InsertElementAndSetValue(DicomTag.RequestedProcedureID, "RequestedProcedureID -- second item updated") 
           .InsertElementAndSetValue(DicomTag.ScheduledProcedureStepID, "ScheduledProcedureStepID -- second item updated") 
        .EndEditItem() 
     .EndEditSequence(); 
 
   // Read the first item in the sequence 
   string sRequestedProcedureID; 
   string sScheduledProcedureStepID; 
   ds.BeginReadSequence(DicomTag.RequestAttributesSequence) 
      .BeginReadItem() 
         .GetValue<string>(DicomTag.RequestedProcedureID, null, out sRequestedProcedureID) 
         .GetValue<string>(DicomTag.ScheduledProcedureStepID, null, out sScheduledProcedureStepID) 
      .EndReadItem() 
     .EndReadSequence(); 
 
   // Read the third item in the sequence 
   sRequestedProcedureID = string.Empty; 
   sScheduledProcedureStepID = string.Empty; 
   ds.BeginReadSequence(DicomTag.RequestAttributesSequence) 
      .BeginReadItem(2) 
         .GetValue<string>(DicomTag.RequestedProcedureID, null, out sRequestedProcedureID) 
         .GetValue<string>(DicomTag.ScheduledProcedureStepID, null, out sScheduledProcedureStepID) 
      .EndReadItem() 
     .EndReadSequence(); 
 
   // *************************************************** 
   // *** Example 2  
   // *************************************************** 
 
   // This example creates a sequence inside another sequence 
   // Add a per-frame functional gropus sequence with two items 
   ds.BeginEditSequence(DicomTag.PerFrameFunctionalGroupsSequence) 
        .BeginEditItem() 
               .BeginEditSequence(DicomTag.FrameVOILUTSequence) 
                     .BeginEditItem() 
                        .InsertElementAndSetValue(DicomTag.WindowCenter, 32000) 
                        .InsertElementAndSetValue(DicomTag.WindowWidth, 64000) 
                     .EndEditItem() 
                     .BeginEditItem() 
                        .InsertElementAndSetValue(DicomTag.WindowCenter, 100) 
                        .InsertElementAndSetValue(DicomTag.WindowWidth, 200) 
                     .EndEditItem() 
               .EndEditSequence() 
        .EndEditItem() 
     .EndEditSequence(); 
 
   // Now read the per-frame functional groups sequence with two items 
   string sWindowCenter1; 
   string sWindowWidth1; 
   string sWindowCenter2; 
   string sWindowWidth2; 
   ds.BeginReadSequence(DicomTag.PerFrameFunctionalGroupsSequence) 
      .BeginReadItem() 
         .BeginReadSequence(DicomTag.FrameVOILUTSequence) 
            .BeginReadItem() 
                .GetValue<string>(DicomTag.WindowCenter, null, out sWindowCenter1) 
                .GetValue<string>(DicomTag.WindowWidth, null, out sWindowWidth1) 
            .EndReadItem() 
            .BeginReadItem() 
                .GetValue<string>(DicomTag.WindowCenter, null, out sWindowCenter2) 
                .GetValue<string>(DicomTag.WindowWidth, null, out sWindowWidth2) 
            .EndReadItem() 
         .EndReadSequence() 
      .EndReadItem() 
   .EndReadSequence(); 
 
   ds.Save(Path.Combine(LEAD_VARS.ImagesDir, "test.dcm"), DicomDataSetSaveFlags.None); 
 
} 
 
static class LEAD_VARS 
{ 
   public const string ImagesDir = @"C:\LEADTOOLS23\Resources\Images"; 
}