FindFirstDescendant Method

Finds the first descendant of a parentElement with the specified tag.

Syntax

C#
Visual Basic
WinRT C#
Objective-C
Java
WinRT JavaScript
C++

public DicomElement FindFirstDescendant( 
   DicomElement parentElement,
   long tag,
   bool nextLevelOnly
)

'Declaration

Public Function FindFirstDescendant( _
   ByVal parentElement As DicomElement, _
   ByVal tag As Long, _
   ByVal nextLevelOnly As Boolean _
) As DicomElement

'Usage

Dim instance As DicomDataSet
Dim parentElement As DicomElement
Dim tag As Long
Dim nextLevelOnly As Boolean
Dim value As DicomElement
 
value = instance.FindFirstDescendant(parentElement, tag, nextLevelOnly)

public DicomElement FindFirstDescendant( 
   DicomElement parentElement,
   long tag,
   bool nextLevelOnly
)

 function Leadtools.Dicom.DicomDataSet.FindFirstDescendant( 
   parentElement ,
   tag ,
   nextLevelOnly 
)

public:
DicomElement^ FindFirstDescendant( 
   DicomElement^ parentElement,
   int64 tag,
   bool nextLevelOnly
)

Parameters

parentElement: a parent item in the Data Set.
tag: tag for the item to find.
nextLevelOnly: if set to true, search for items in the next level only; otherwise, search for items recursively in all of the next levels.

Return Value

The first item in the Data Set with the specified Tag, or a null reference (Nothing in Visual Basic) if an item with the specified Tag was not found.

Remarks

This method finds the first descendant of the parentElement element that has a DICOM tag equivalent to the specified tag.

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

Behavior when nextLevelOnly is true
Returns the first item on the next level of parentElement with that has tag equivalent to tag. Elements included in the search include child elements in the next level only.

Example 1
nextLevelOnly is true
parentElement points to element 1
Searches elements 2, 8, 11, 12 and returns the first element that has a tag of tag.

Example 2 nextLevelOnly is true
parentElement points to element 2
Searches elements 3, 4, 7 and returns the first element that has a tag of tag.

Example 3
nextLevelOnly is true
parentElement points to element 4
Searches nodes 5, 6 and returns the first element that has a tag of tag.

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

Behavior when nextLevelOnly is false:
Returns the first item that has a tag equivalent to tag using a pre-order search algorithm rooted at the parentElement.

Example 5
nextLevelOnly is false
parentElement points to element 1
Searches elements 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 and returns the first element that has a tag of tag.

Example 6
nextLevelOnly is false
parentElement points to element 2
Searches elements 3, 4, 5, 6, 7 and returns the first element that has a tag of tag.

Example 7
nextLevelOnly is false
parentElement points to element 4
Searches elements 5, 6 and returns the first element that has a tag of tag.

To find elements in the Data Set with a specific Tag, use the following methods:

To find specific modules in the Data Set, use the following methods:

FindModule

FindModuleByIndex

Example

This example displays searches for TAG_CODE_VALUE values in 'image1.dcm' using the FindFirstDescendant() and FindNextDescendant() methods.

C#
Visual Basic
WinRT C#
WinRT JavaScript
Silverlight C#
Silverlight VB

Copy Code

Imports Leadtools
Imports Leadtools.Dicom

'''
''' 
Private Sub DisplayElementValue(ByVal ds As DicomDataSet, ByVal element As DicomElement)
   If element IsNot Nothing Then
      Dim value As String = ds.GetStringValue(element, 0)
      Console.WriteLine(value)
   End If
End Sub
Private Sub DicomFindFirstDescendantTest()
   Dim file As String = Path.Combine(LEAD_VARS.ImagesDir, "IMAGE1.dcm")
   Dim ds As 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")
   Dim element As DicomElement = ds.FindFirstDescendant(Nothing, DicomTag.CodeValue, False)
   Do While element IsNot Nothing
      DisplayElementValue(ds, element)
      element = ds.FindNextDescendant(Nothing, element, False)
   Loop

   ' For the next examples, we need the two parent sequences that contain the code items
   Dim elementAnatomicRegionSequence As DicomElement = ds.FindFirstDescendant(Nothing, DicomTag.AnatomicRegionSequence, True)
   Dim elementPatientOrientationCodeSequence As DicomElement = ds.FindFirstDescendant(Nothing, DicomTag.PatientOrientationCodeSequence, True)

   Debug.Assert(elementAnatomicRegionSequence IsNot Nothing)
   Debug.Assert(elementPatientOrientationCodeSequence IsNot Nothing)

   ' 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)
   Do While element IsNot Nothing
      DisplayElementValue(ds, element)
      element = ds.FindNextDescendant(elementAnatomicRegionSequence, element, True)
   Loop

   ' 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)
   Do While element IsNot Nothing
      DisplayElementValue(ds, element)
      element = ds.FindNextDescendant(elementAnatomicRegionSequence, element, False)
   Loop

   ' 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)
   Do While element IsNot Nothing
      DisplayElementValue(ds, element)
      element = ds.FindNextDescendant(elementPatientOrientationCodeSequence, element, False)
   Loop

   Console.WriteLine("Finished")
End Sub
''' 

Public NotInheritable Class LEAD_VARS
Public Const ImagesDir As String = "C:\Users\Public\Documents\LEADTOOLS Images"
End Class

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, "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);

   Debug.Assert(elementAnatomicRegionSequence != null);
   Debug.Assert(elementPatientOrientationCodeSequence != null);

   // 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:\Users\Public\Documents\LEADTOOLS Images";
}

Requirements

Target Platforms

Reference

DicomDataSet Class
DicomDataSet Members
FindNextDescendant Method
FindFirstElement Method
FindLastElement Method
FindPreviousElement Method
FindNextElement Method
FindModule Method
FindModuleByIndex Method