mlDicomSingleFrameSelectionTools.h

Go to the documentation of this file.

// Copyright (c) Fraunhofer MEVIS, Germany. All rights reserved.
// **InsertLicense** code
//----------------------------------------------------------------------------------

//----------------------------------------------------------------------------------
 
#pragma once
 
#include "MLDicomToMLToolsSystem.h"
#include <mlModuleIncludes.h>
#include <DCMTree_Lib.h>
#include <DCMTree_Exception.h>
#include <DCMTree_Tag.h>
#include <DCMTree_Tree.h>
#include <DCMTree_StructuredMF.h>
 
ML_START_NAMESPACE

namespace DicomToMLTools {

    struct FrameSpecificTag {
      inline FrameSpecificTag()
      {
        pos.resize(3);
        pos[0] = 0;
        pos[1] = 0;
        pos[2] = 0;
      }

      inline FrameSpecificTag(const DCMTree::StructuredMF::IndexVector &posIn, 
                              DCMTree::RawTagId rawTagIdIn = 0,
                              DCMTree::Const_TagPtr tagPtrIn = DCMTree::Const_TagPtr(),
                              bool isFromRootIn = false)
      {
        pos.resize(3);
        pos = posIn;
        tagId = rawTagIdIn;
        tagPtr = tagPtrIn;
        isFromRoot = isFromRootIn;
      }

      inline FrameSpecificTag(const FrameSpecificTag &inputInfos) = default;

      inline FrameSpecificTag& operator=(const FrameSpecificTag &inputInfos) = default;

      inline void setPos(unsigned int z, unsigned int t, unsigned int u)
      {
        pos.resize(3);
        pos[0] = z;
        pos[1] = t;
        pos[2] = u;
      }

      inline void setUpFrameSpecificTagInfos(const DCMTree::StructuredMF& smfTree,
                                             bool doFrameExistsAtPosCheck = true,
                                             bool frameExistsAtPosIn = false)
      {
        // Check whether we have a specific frame to search the tags.
        boost::uint32_t gridDimension = smfTree.getGridDimension();
        DCMTree::StructuredMF::IndexVector localPos = pos;
        //localPos.resize(gridDimension);
        //std::cerr << "gridDimension = " << gridDimension << std::endl;
        //std::cerr << "doFrameExistsAtPosCheck = " << doFrameExistsAtPosCheck << std::endl;
        //std::cerr << "frameExistsAtPosIn = " << frameExistsAtPosIn << std::endl;
        //std::cerr << "checking at ( " << localPos[0] << ", " << localPos[1] << ", " << localPos[2] << ")" << std::endl;
        bool frameExistsAtPos = doFrameExistsAtPosCheck ? (smfTree.tagTree() ? true : false) : frameExistsAtPosIn;
        
        // Determine at most z, t, and u dimension extents if they are available.
        const DCMTree::StructuredMF::IndexVector gridExtent = smfTree.getGridExtent();
        const unsigned int zExt = gridExtent.size() > 0u ? gridExtent[0] : 1u; 
        const unsigned int tExt = gridExtent.size() > 1u ? gridExtent[1] : 1u; 
        const unsigned int uExt = gridExtent.size() > 2u ? gridExtent[2] : 1u;
 
        // Clamp position to an existing frame position, which, however, is difficult to understand.
        // Important for understanding: The highest existing grid dimension (often the temporal one) is the highest level in SMF dicom 
        //                              (i.e. the entries in root-nearest SMF-sequence), and spatial tags are entries of an SMF sequence 
        //                              inside of items of the temporal ones (i.e. often the leaves).
        // Examples:
        // gridExtent=(5,10,1), position=(0,0,10): u-frame does not exist and is outside valid dimensions, the tree root should be taken instead.
        // gridExtent=(1,10,1), position=(10,2,0): z-frame does not exist, however, it is located inside a valid temporal extent, i.e. 
        //                                         it should be taken from frame (0,2,0), because the temporal tree level contains tags also 
        //                                         valid for its spatial subtrees.
        // That means: Spatial spatial positions should be clamped to the maximum  grid extent in z if its temporal extent is located inside a valid range,
        //             but a temporal location outside the valid range should return no valid frame if there is no valid u-dimension.
        //             u-locations outside always should return no valid frame.
        // Anyway: If temporal or spatial dimensions in tree do not match the extents of the image, these checks do not really make sense any more.
        //         Therefore: getting reliable rescale/slope values, for example, will only work reliably if the tree has real frame entries and the tree
        //         really matches the image extents. 
        if (gridDimension > 0){
          // spatial dimension is valid.
          if (localPos[0] >= zExt){
            if (gridDimension < 2){ 
              // temporal dimension does not exist, i.e. z is also out of range.
              frameExistsAtPos = false;
            }
            else{
              // t exist, i.e. z can be clamped if t location is in valid range.
              if (localPos[1] < tExt) {
                localPos[0] = zExt-1;
              }
            }
          }
        }
        if (gridDimension > 1){
          // temporal dimension is valid.
          if (localPos[1] >= tExt){
            if (gridDimension < 3){ 
              // u dimension does not exist, i.e. t is also out of range.
              frameExistsAtPos = false;
            }
            else{
              // u dimension exists, i.e. t can be clamped if u location is in valid range.
              if (localPos[2] < uExt) {
                localPos[1] = uExt-1;
              }
            }
          }
        }
        if (localPos[2] >= uExt){ 
          // u locations outside are never part of higher dimensions and thefore are always out of range if not in corresponding grid extent.
          frameExistsAtPos = false;
        }
        //std::cerr << "gridExt = (" << zExt << ", "<< tExt << ", "<< uExt << ")" << std::endl;
 
        //std::cerr << "calculated frameExistsAtPos = " << frameExistsAtPos << std::endl;
        tagPtr.reset();
        isFromRoot = false;
        try{
          // Get the tag from the frame if it exists; if not then get it from the normal tree.
          if (frameExistsAtPos) {
            //std::cerr << "Frame exists at localPos, getting tag for grid position" << std::endl;
            tagPtr = smfTree.tagForGridPosition(tagId, localPos);
            if (!tagPtr){
              // Here we have the same problem as we have it with validity of frames, we need to look for the tags
              // e.g. in the temporal tree level if the spatial does not exist.
              //std::cerr << "tag not found, checking upper dimension! TODO/TOTEST!" << std::endl;
            }
          }
          if(!tagPtr && smfTree.tagTree()){
            tagPtr = smfTree.tagTree()->getTag(tagId);
            if (tagPtr){ isFromRoot = true; }
          }
        }
        catch(const DCMTree::Exception&) {
          // Ignore, the frame does not exist or the tag was not found.
          //std::cerr << "Exiting with exception from getTagForGridPosition!" << std::endl;
        }
      }

      DCMTree::StructuredMF::IndexVector pos;

      DCMTree::RawTagId tagId = 0;

      DCMTree::Const_TagPtr tagPtr;

      bool isFromRoot = false;
    };

    template <typename VALUE_TYPE>
    struct FrameSpecificValueTag {
      inline FrameSpecificValueTag(){}

      inline FrameSpecificValueTag(const FrameSpecificValueTag &inputInfos) = default;

      inline FrameSpecificValueTag& operator=(const FrameSpecificValueTag &inputInfos) = default;

      inline FrameSpecificValueTag(const FrameSpecificTag& frameSpecificTagIn, VALUE_TYPE valueIn, bool valueIsValidIn) :
        frameSpecificTag(frameSpecificTagIn),
        value(valueIn),
        valueIsValid(valueIsValidIn){}

      template <typename GET_VALUE_FUNC_TYPE>
      inline void getFrameSpecificValueTag(const DCMTree::StructuredMF& smfTree,
                                           const unsigned int z, const unsigned int t, const unsigned int u,
                                           const DCMTree::RawTagId rawTagId,
                                           const GET_VALUE_FUNC_TYPE & getTagValueFunc)
      {
        frameSpecificTag.setPos(z,t,u);
        frameSpecificTag.tagId = rawTagId;
        // Determine pos and isFromRoot.
        frameSpecificTag.setUpFrameSpecificTagInfos(smfTree, true, false);
 
        try{
          if (frameSpecificTag.tagPtr){
            // Try to convert/get the tag value; throws on failure.
            value = getTagValueFunc(frameSpecificTag.tagPtr);
            valueIsValid = true;
          }
        }
        catch(const DCMTree::Exception &){}
      }

      FrameSpecificTag frameSpecificTag;

      VALUE_TYPE value;

      bool valueIsValid = false;
    };

    inline void getFrameSpecificDoubleTag(const DCMTree::StructuredMF& smfTree,
                                          const unsigned int z, const unsigned int t, const unsigned int u,
                                          const DCMTree::RawTagId rawTagId,
                                          FrameSpecificValueTag<double> &valTagInfos)
    {
      valTagInfos.getFrameSpecificValueTag(smfTree, z,t,u, rawTagId, 
                                           [](DCMTree::Const_TagPtr tagPtr){
                                             try{
                                               return tagPtr ? tagPtr->toDouble() : 0.;
                                             }
                                             catch(const DCMTree::Exception &){ /* Handle any invalid or inconvertible value as 0. */ }
                                             return 0.; 
                                           } );
    }
 

    inline void getFrameSpecificStringTag(const DCMTree::StructuredMF& smfTree,
                                          const unsigned int z, const unsigned int t, const unsigned int u,
                                          const DCMTree::RawTagId rawTagId,
                                          FrameSpecificValueTag<std::string> &valTagInfos)
    {
      valTagInfos.getFrameSpecificValueTag(smfTree, z,t,u, rawTagId, 
                                           [](DCMTree::Const_TagPtr tagPtr){
                                             try{
                                               return tagPtr ? tagPtr->toString() : std::string();
                                             }
                                             catch(const DCMTree::Exception &){ /* Handle any invalid or inconvertible value as "". */ }
                                             return std::string(); 
                                           } );
    }
};
 
ML_END_NAMESPACE