itkProcessObject.h

Go to the documentation of this file.

/*=========================================================================
 *
 *  Copyright NumFOCUS
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *         https://www.apache.org/licenses/LICENSE-2.0.txt
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *
 *=========================================================================*/
/*=========================================================================
 *
 *  Portions of this file are subject to the VTK Toolkit Version 3 copyright.
 *
 *  Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
 *
 *  For complete copyright, license and disclaimer of warranty information
 *  please refer to the NOTICE file at the top of the ITK source tree.
 *
 *=========================================================================*/
#ifndef itkProcessObject_h
#define itkProcessObject_h
 
#include "itkDataObject.h"
#include "itkObjectFactory.h"
#include "itkNumericTraits.h"
#include "itkThreadSupport.h"
#include "itkIntTypes.h"
#include <vector>
#include <map>
#include <set>
#include <algorithm>
#include <thread>
 
namespace itk
{
 
class MultiThreaderBase;

class ITKCommon_EXPORT ProcessObject : public Object
{
public:
  ITK_DISALLOW_COPY_AND_MOVE(ProcessObject);

  using Self = ProcessObject;
  using Superclass = Object;
  using Pointer = SmartPointer<Self>;
  using ConstPointer = SmartPointer<const Self>;

  itkOverrideGetNameOfClassMacro(ProcessObject);

  using DataObjectPointer = DataObject::Pointer;

  // using ConstDataObjectPointerArray = std::vector< const DataObject * >;

  using DataObjectPointerArray = std::vector<DataObjectPointer>;
 
  using DataObjectIdentifierType = DataObject::DataObjectIdentifierType;

  using NameArray = std::vector<DataObjectIdentifierType>;
 
#ifndef ITK_FUTURE_LEGACY_REMOVE
  using MultiThreaderType [[deprecated("Please use `itk::MultiThreaderBase` directly.")]] = MultiThreaderBase;
#endif

  NameArray
  GetInputNames() const;

  NameArray
  GetRequiredInputNames() const;

  DataObjectPointerArray
  GetInputs();

  bool
  HasInput(const DataObjectIdentifierType & key) const;
 
  using DataObjectPointerArraySizeType = DataObjectPointerArray::size_type;

  DataObjectPointerArraySizeType
  GetNumberOfInputs() const;

  DataObjectPointerArraySizeType
  GetNumberOfOutputs() const;

  NameArray
  GetOutputNames() const;

  DataObjectPointerArray
  GetOutputs();

  bool
  HasOutput(const DataObjectIdentifierType & key) const;

  DataObjectPointerArray
  GetIndexedInputs();

  DataObjectPointerArraySizeType
  GetNumberOfIndexedInputs() const;

  virtual DataObjectPointerArraySizeType
  GetNumberOfValidRequiredInputs() const;

  DataObjectPointerArray
  GetIndexedOutputs();

  DataObjectPointerArraySizeType
  GetNumberOfIndexedOutputs() const;

  virtual DataObjectPointer
  MakeOutput(DataObjectPointerArraySizeType idx);

  itkSetMacro(AbortGenerateData, bool);

  itkGetConstReferenceMacro(AbortGenerateData, bool);

  itkBooleanMacro(AbortGenerateData);

#if !defined(ITK_LEGACY_REMOVE)
  void
  SetProgress(float progress)
  {
    m_Progress = progressFloatToFixed(progress);
  }
#endif

  virtual float
  GetProgress() const
  {
    return progressFixedToFloat(m_Progress);
  }

  void
  UpdateProgress(float progress);

  void
  IncrementProgress(float increment);

  virtual void
  Update();

  virtual void
  UpdateLargestPossibleRegion();

  virtual void
  UpdateOutputInformation();

  virtual void
  PropagateRequestedRegion(DataObject * output);

  virtual void
  UpdateOutputData(DataObject * output);

  virtual void
  EnlargeOutputRequestedRegion(DataObject * itkNotUsed(output))
  {}

  virtual void
  ResetPipeline();

  virtual DataObjectPointer
  MakeOutput(const DataObjectIdentifierType &);

  virtual void
  SetReleaseDataFlag(bool val);
  virtual bool
  GetReleaseDataFlag() const;
  void
  ReleaseDataFlagOn()
  {
    this->SetReleaseDataFlag(true);
  }
  void
  ReleaseDataFlagOff()
  {
    this->SetReleaseDataFlag(false);
  }


  itkSetMacro(ReleaseDataBeforeUpdateFlag, bool);
  itkGetConstReferenceMacro(ReleaseDataBeforeUpdateFlag, bool);
  itkBooleanMacro(ReleaseDataBeforeUpdateFlag);

  itkSetClampMacro(NumberOfWorkUnits, ThreadIdType, 1, ITK_MAX_THREADS);
  itkGetConstReferenceMacro(NumberOfWorkUnits, ThreadIdType);

  MultiThreaderBase *
  GetMultiThreader() const
  {
    return m_MultiThreader;
  }

  void
  SetMultiThreader(MultiThreaderBase * threader);

  virtual void
  PrepareOutputs();
 
protected:
  ProcessObject();
  ~ProcessObject() override;
 
  void
  PrintSelf(std::ostream & os, Indent indent) const override;
 
  //
  // Input Methods
  //

  DataObject *
  GetInput(const DataObjectIdentifierType & key);
  const DataObject *
  GetInput(const DataObjectIdentifierType & key) const;

  DataObject *
  GetInput(DataObjectPointerArraySizeType idx)
  {
    return idx < m_IndexedInputs.size() ? m_IndexedInputs[idx]->second.GetPointer() : nullptr;
  }
  const DataObject *
  GetInput(DataObjectPointerArraySizeType idx) const
  {
    return idx < m_IndexedInputs.size() ? m_IndexedInputs[idx]->second.GetPointer() : nullptr;
  }


  virtual void
  SetInput(const DataObjectIdentifierType & key, DataObject * input);
  virtual void
  SetNthInput(DataObjectPointerArraySizeType idx, DataObject * input);

  virtual void
  AddInput(DataObject * input);

  virtual void
  PushBackInput(const DataObject * input);
  virtual void
  PopBackInput();
  virtual void
  PushFrontInput(const DataObject * input);
  virtual void
  PopFrontInput();

  virtual void
               RemoveInput(const DataObjectIdentifierType & key);
  virtual void RemoveInput(DataObjectPointerArraySizeType);

  DataObject *
  GetPrimaryInput()
  {
    return m_IndexedInputs[0]->second;
  }
  const DataObject *
  GetPrimaryInput() const
  {
    return m_IndexedInputs[0]->second;
  }


  virtual void
  SetPrimaryInputName(const DataObjectIdentifierType & key);
  virtual const char *
  GetPrimaryInputName() const
  {
    return this->m_IndexedInputs[0]->first.c_str();
  }


  virtual void
  SetPrimaryInput(DataObject * object);

  void
  SetNumberOfIndexedInputs(DataObjectPointerArraySizeType num);

  virtual void SetNumberOfRequiredInputs(DataObjectPointerArraySizeType);
  itkGetConstReferenceMacro(NumberOfRequiredInputs, DataObjectPointerArraySizeType);
 

  bool
  RemoveRequiredInputName(const DataObjectIdentifierType &);

  bool
  IsRequiredInputName(const DataObjectIdentifierType &) const;

  void
  SetRequiredInputNames(const NameArray &);

  bool
  AddRequiredInputName(const DataObjectIdentifierType &);
  bool
  AddRequiredInputName(const DataObjectIdentifierType &, DataObjectPointerArraySizeType idx);

  void
  AddOptionalInputName(const DataObjectIdentifierType &);
  void
  AddOptionalInputName(const DataObjectIdentifierType &, DataObjectPointerArraySizeType idx);
 
 
  //
  // Output Methods
  //

  DataObject *
  GetOutput(const DataObjectIdentifierType & key);
  const DataObject *
  GetOutput(const DataObjectIdentifierType & key) const;

  virtual void
  SetPrimaryOutputName(const DataObjectIdentifierType & key);
  virtual const char *
  GetPrimaryOutputName() const
  {
    return this->m_IndexedOutputs[0]->first.c_str();
  }


  DataObject *
  GetOutput(DataObjectPointerArraySizeType i);
  const DataObject *
  GetOutput(DataObjectPointerArraySizeType i) const;

  virtual void
  SetOutput(const DataObjectIdentifierType & name, DataObject * output);

  virtual void
  RemoveOutput(const DataObjectIdentifierType & key);

  DataObject *
  GetPrimaryOutput()
  {
    return m_IndexedOutputs[0]->second;
  }
  const DataObject *
  GetPrimaryOutput() const
  {
    return m_IndexedOutputs[0]->second;
  }


  virtual void
  SetPrimaryOutput(DataObject * object);

  virtual void
  SetNthOutput(DataObjectPointerArraySizeType idx, DataObject * output);
 
  virtual void
  AddOutput(DataObject * output);
 
  virtual void
  RemoveOutput(DataObjectPointerArraySizeType idx);
 
  itkSetMacro(NumberOfRequiredOutputs, DataObjectPointerArraySizeType);
  itkGetConstReferenceMacro(NumberOfRequiredOutputs, DataObjectPointerArraySizeType);

  void
  SetNumberOfIndexedOutputs(DataObjectPointerArraySizeType num);
 
 
  DataObjectIdentifierType
  MakeNameFromInputIndex(DataObjectPointerArraySizeType idx) const;
  DataObjectIdentifierType
  MakeNameFromOutputIndex(DataObjectPointerArraySizeType idx) const;
  DataObjectPointerArraySizeType
  MakeIndexFromInputName(const DataObjectIdentifierType & name) const;
  DataObjectPointerArraySizeType
  MakeIndexFromOutputName(const DataObjectIdentifierType & name) const;
  bool
  IsIndexedInputName(const DataObjectIdentifierType &) const;
  bool
  IsIndexedOutputName(const DataObjectIdentifierType &) const;
 
  //
  // Pipeline Methods
  //

  virtual void
  VerifyPreconditions() const;

  virtual void
  VerifyInputInformation() const;

  virtual void
  GenerateInputRequestedRegion();

  virtual void
  GenerateOutputRequestedRegion(DataObject * output);

  virtual void
  GenerateOutputInformation();

  virtual void
  GenerateData()
  {}


  virtual void
  PropagateResetPipeline();

  virtual void
  ReleaseInputs();

  virtual void
  CacheInputReleaseDataFlags();

  virtual void
  RestoreInputReleaseDataFlags();

  itkGetConstMacro(ThreaderUpdateProgress, bool);
  itkBooleanMacro(ThreaderUpdateProgress);
  virtual void
  SetThreaderUpdateProgress(bool arg);

  static inline constexpr float
  progressFixedToFloat(uint32_t fixed)
  {
    return static_cast<double>(fixed) / static_cast<double>(std::numeric_limits<uint32_t>::max());
  }

  static inline uint32_t
  progressFloatToFixed(float f)
  {
    if (f <= 0.0f)
    {
      return 0;
    }
    if (f >= 1.0f)
    {
      return std::numeric_limits<uint32_t>::max();
    }
    const double temp = static_cast<double>(f) * std::numeric_limits<uint32_t>::max();
    return static_cast<uint32_t>(temp);
  }

  template <typename TSourceObject>
  static void
  MakeRequiredOutputs(TSourceObject & sourceObject, const DataObjectPointerArraySizeType numberOfRequiredOutputs)
  {
    sourceObject.ProcessObject::SetNumberOfRequiredOutputs(numberOfRequiredOutputs);
 
    for (unsigned int i{}; i < numberOfRequiredOutputs; ++i)
    {
      sourceObject.ProcessObject::SetNthOutput(i, sourceObject.TSourceObject::MakeOutput(i));
    }
  }


  bool m_Updating{};

  TimeStamp m_OutputInformationMTime{};
 
private:
  DataObjectIdentifierType MakeNameFromIndex(DataObjectPointerArraySizeType) const;
  DataObjectPointerArraySizeType
  MakeIndexFromName(const DataObjectIdentifierType &) const;

  using DataObjectPointerMap = std::map<DataObjectIdentifierType, DataObjectPointer>;
 

  DataObjectPointerMap m_Inputs{};
  DataObjectPointerMap m_Outputs{};
 
  std::vector<DataObjectPointerMap::iterator> m_IndexedInputs{};
  std::vector<DataObjectPointerMap::iterator> m_IndexedOutputs{};

  std::map<DataObjectIdentifierType, bool> m_CachedInputReleaseDataFlags{};
 
  DataObjectPointerArraySizeType m_NumberOfRequiredInputs{};
  DataObjectPointerArraySizeType m_NumberOfRequiredOutputs{};

  using NameSet = std::set<DataObjectIdentifierType>;

  NameSet m_RequiredInputNames{};

  bool                  m_AbortGenerateData{};
  std::atomic<uint32_t> m_Progress{};
 
 
  std::thread::id m_UpdateThreadID{};

  itk::SmartPointer<MultiThreaderBase> m_MultiThreader;
  ThreadIdType                         m_NumberOfWorkUnits{};
 
  bool m_ThreaderUpdateProgress{ true };

  bool m_ReleaseDataBeforeUpdateFlag{};

  friend class DataObject;
 
  friend class ProgressReporter;
  friend class TotalProgressReporter;
 
  friend class DataObjectConstIterator;
  friend class InputDataObjectConstIterator;
  friend class OutputDataObjectConstIterator;
 
  friend class DataObjectIterator;
  friend class InputDataObjectIterator;
  friend class OutputDataObjectIterator;
 
  friend class TestProcessObject;
};
} // end namespace itk
 
#endif