FindNextDescendant Method

Summary

Finds the next descendant of parentElement with the specified tag.

Syntax

Objective-C

C++/CLI

public DicomElement FindNextDescendant( 
   DicomElement parentElement, 
   DicomElement childElement, 
   bool nextLevelOnly 
)

- (nullable LTDicomElement *)findNextDescendant:(LTDicomElement *)parentElement childElement:(LTDicomElement *)childElement nextLevelOnly:(BOOL)nextLevelOnly;

public: 
DicomElement^ FindNextDescendant(  
   DicomElement^ parentElement, 
   DicomElement^ childElement, 
   bool nextLevelOnly 
)

Parameters

parentElement
a parent item in the Data Set.

childElement
a child item of the parentElement

nextLevelOnly
if set to true search for items in the next level only; otherwise search for items recursively in all the next levels.

Return Value

The next item in the Data Set with a specific, or a null reference (Nothing in VB) if an item with the specified Tag was not found.

Remarks

Note: This function does not specify a tag to use when searching. However the tag that was used in the last call to FindFirstDescendant is used by default when searching.

This method finds the next descendant of the parentElement element that has a DICOM tag equivalent to the tag argument (FindFirstDescendant), where the entire search is rooted at the Parent element (i.e. parentElement).

The diagram below represents DICOM elements stored in a DICOM dataset.

Behavior when nextLevelOnly is true Returns the next element on the next level of parentElement with that has a tag equivalent to the tag argument in the previous call of FindFirstDescendant. Elements included in the search include child elements in the next level only.

Example 1 nextLevelOnly is true parentElement points to element 1 childElement points to element 8 Searches elements 11, 12 and returns the first element that matches the tag argument used in the previous call to FindFirstDescendant.

Example 2 nextLevelOnly is true parentElement points to element 2 childElement points to element 3 Searches elements 4, 7 and returns the first element that matches the tag argument used in the previous call to FindFirstDescendant.

Example 3 nextLevelOnly is true parentElement points to element 4 childElement points to element 5 Searches element 6 only, and returns element 6 if it has a tag equivalent to the tag argument used in the previous call to FindFirstDescendant.

Example 4 nextLevelOnly is true parentElement points to element 11 childElement points to element 12 Returns null

Behavior when nextLevelOnly is false: Returns the next element that matches the tag argument used in the previous call to FindFirstDescendant, using a pre-order search algorithm rooted at parentElement.

Example 5 nextLevelOnly is false parentElement points to element 1 childElement points to element 4 Searches elements 5, 6, 7, 8, 9, 10, 11, 12 and returns the first element that has a tag equivalent to the tag argument used in the previous call to FindFirstDescendant.

Example 6 nextLevelOnly is false parentElement points to element 2 childElement points to element 4 Searches elements 5, 6, 7 and returns the first element that has a tag equivalent to the tag argument used in the previous call to FindFirstDescendant.

Example 7 nextLevelOnly is false parentElement points to element 4 childElement points to element 5 Searches element 6 only, and returns element 6 if is has a tag equivalent to the tag argument used in the previous call to FindFirstDescendant.

The following methods will also help you find elements in the Data Set with a specific Tag:

The following methods will help you find specific modules in the Data Set:

FindModule

FindModuleByIndex

Example

using Leadtools; 
using Leadtools.Dicom; 
 
 
/// 
///  
void DisplayElementValue(DicomDataSet ds, DicomElement element) 
{ 
   if (element != null) 
   { 
      string value = ds.GetStringValue(element, 0); 
      Console.WriteLine(value); 
   } 
} 
 
private void DicomFindFirstDescendantTest() 
{ 
   string file = Path.Combine(LEAD_VARS.ImagesDir, "DICOM", "image1.dcm"); 
   DicomDataSet ds = new DicomDataSet(); 
   ds.Load(file, DicomDataSetLoadFlags.None); 
 
   // Example 1:  
   // Find all occurrences of TAG_CODE_VALUE in the dataset, searching recursively 
   // Output should be: 
   //    T-A2000 
   //    F-10450 
   Console.WriteLine("Example 1"); 
   DicomElement element = ds.FindFirstDescendant(null, DicomTag.CodeValue, false); 
   while (element != null) 
   { 
      DisplayElementValue(ds, element); 
      element = ds.FindNextDescendant(null, element, false); 
   } 
 
   // For the next examples, we need the two parent sequences that contain the code items 
   DicomElement elementAnatomicRegionSequence = ds.FindFirstDescendant(null, DicomTag.AnatomicRegionSequence, true); 
   DicomElement elementPatientOrientationCodeSequence = ds.FindFirstDescendant(null, DicomTag.PatientOrientationCodeSequence, true); 
 
   Assert.IsNotNull(elementAnatomicRegionSequence, elementAnatomicRegionSequence.ToString()); 
   Assert.IsNotNull(elementPatientOrientationCodeSequence, elementPatientOrientationCodeSequence.ToString()); 
 
   // Example 2: 
   // Find all occurrences of TAG_CODE_VALUE with (0028,2218) Anatomic Region Sequence as pParent 
   // Search only the next level 
   // Output should be empty, because TAG_CODE_VALUE are not at next level 
   Console.WriteLine("Example 2"); 
   element = ds.FindFirstDescendant(elementAnatomicRegionSequence, DicomTag.CodeValue, true); 
   while (element != null) 
   { 
      DisplayElementValue(ds, element); 
      element = ds.FindNextDescendant(elementAnatomicRegionSequence, element, true); 
   } 
 
   // Example 3: 
   // Find all occurrences of TAG_CODE_VALUE with (0028,2218) Anatomic Region Sequence as pParent 
   // Search recursively 
   // Output should be 
   //    T-A2000 
   Console.WriteLine("Example 3"); 
   element = ds.FindFirstDescendant(elementAnatomicRegionSequence, DicomTag.CodeValue, false); 
   while (element != null) 
   { 
      DisplayElementValue(ds, element); 
      element = ds.FindNextDescendant(elementAnatomicRegionSequence, element, false); 
   } 
 
   // Example 4: 
   // Find all occurrences of TAG_CODE_VALUE with (0028,2218) Anatomic Region Sequence as pParent 
   // Search recursively 
   // Output should be 
   //    F-10450 
   Console.WriteLine("Example 4"); 
   element = ds.FindFirstDescendant(elementPatientOrientationCodeSequence, DicomTag.CodeValue, false); 
   while (element != null) 
   { 
      DisplayElementValue(ds, element); 
      element = ds.FindNextDescendant(elementPatientOrientationCodeSequence, element, false); 
   } 
 
   Console.WriteLine("Finished"); 
} 
///  
 
static class LEAD_VARS 
{ 
   public const string ImagesDir = @"C:\LEADTOOLS23\Resources\Images"; 
}