Filter.h

Go to the documentation of this file.

//============================================================================
//  The contents of this file are covered by the Viskores license. See
//  LICENSE.txt for details.
//
//  By contributing to this file, all contributors agree to the Developer
//  Certificate of Origin Version 1.1 (DCO 1.1) as stated in DCO.txt.
//============================================================================
 
//============================================================================
//  Copyright (c) Kitware, Inc.
//  All rights reserved.
//  See LICENSE.txt for details.
//
//  This software is distributed WITHOUT ANY WARRANTY; without even
//  the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
//  PURPOSE.  See the above copyright notice for more information.
//============================================================================
#ifndef viskores_filter_Filter_h
#define viskores_filter_Filter_h
 
#include <viskores/cont/ArrayCopy.h>
#include <viskores/cont/DataSet.h>
#include <viskores/cont/Field.h>
#include <viskores/cont/Invoker.h>
#include <viskores/cont/Logging.h>
#include <viskores/cont/PartitionedDataSet.h>
 
#include <viskores/filter/FieldSelection.h>
#include <viskores/filter/TaskQueue.h>
#include <viskores/filter/viskores_filter_core_export.h>
 
namespace viskores
{
namespace filter
{
class VISKORES_FILTER_CORE_EXPORT Filter
{
public:
  VISKORES_CONT Filter();
 
  VISKORES_CONT virtual ~Filter();
 
  VISKORES_CONT viskores::cont::DataSet Execute(const viskores::cont::DataSet& input);
 
  VISKORES_CONT viskores::cont::PartitionedDataSet Execute(
    const viskores::cont::PartitionedDataSet& input);
 
  VISKORES_CONT void SetFieldsToPass(const viskores::filter::FieldSelection& fieldsToPass);
  VISKORES_CONT void SetFieldsToPass(viskores::filter::FieldSelection&& fieldsToPass);
 
  VISKORES_DEPRECATED(2.0)
  VISKORES_CONT void SetFieldsToPass(const viskores::filter::FieldSelection& fieldsToPass,
                                     viskores::filter::FieldSelection::Mode mode);
 
  VISKORES_CONT void SetFieldsToPass(
    std::initializer_list<std::string> fields,
    viskores::filter::FieldSelection::Mode mode = viskores::filter::FieldSelection::Mode::Select);
 
  VISKORES_CONT void SetFieldsToPass(
    std::initializer_list<std::pair<std::string, viskores::cont::Field::Association>> fields,
    viskores::filter::FieldSelection::Mode mode = viskores::filter::FieldSelection::Mode::Select);
 
 
  VISKORES_CONT void SetFieldsToPass(
    const std::string& fieldname,
    viskores::cont::Field::Association association,
    viskores::filter::FieldSelection::Mode mode = viskores::filter::FieldSelection::Mode::Select);
 
  VISKORES_CONT void SetFieldsToPass(const std::string& fieldname,
                                     viskores::filter::FieldSelection::Mode mode)
  {
    this->SetFieldsToPass(fieldname, viskores::cont::Field::Association::Any, mode);
  }
 
  VISKORES_CONT
  const viskores::filter::FieldSelection& GetFieldsToPass() const { return this->FieldsToPass; }
  VISKORES_CONT
  viskores::filter::FieldSelection& GetFieldsToPass() { return this->FieldsToPass; }
 
  VISKORES_CONT void SetPassCoordinateSystems(bool flag) { this->PassCoordinateSystems = flag; }
  VISKORES_CONT bool GetPassCoordinateSystems() const { return this->PassCoordinateSystems; }
 
  VISKORES_CONT void SetOutputFieldName(const std::string& name) { this->OutputFieldName = name; }
 
  VISKORES_CONT const std::string& GetOutputFieldName() const { return this->OutputFieldName; }
 
  VISKORES_CONT void SetActiveField(
    const std::string& name,
    viskores::cont::Field::Association association = viskores::cont::Field::Association::Any)
  {
    this->SetActiveField(0, name, association);
  }
 
  VISKORES_CONT void SetActiveField(
    viskores::IdComponent index,
    const std::string& name,
    viskores::cont::Field::Association association = viskores::cont::Field::Association::Any)
  {
    auto index_st = static_cast<std::size_t>(index);
    this->ResizeIfNeeded(index_st);
    this->ActiveFieldNames[index_st] = name;
    this->ActiveFieldAssociation[index_st] = association;
  }
 
  VISKORES_CONT const std::string& GetActiveFieldName(viskores::IdComponent index = 0) const
  {
    VISKORES_ASSERT((index >= 0) &&
                    (index < static_cast<viskores::IdComponent>(this->ActiveFieldNames.size())));
    return this->ActiveFieldNames[index];
  }
 
  VISKORES_CONT viskores::cont::Field::Association GetActiveFieldAssociation(
    viskores::IdComponent index = 0) const
  {
    return this->ActiveFieldAssociation[index];
  }
 
  VISKORES_CONT void SetActiveCoordinateSystem(viskores::Id coord_idx)
  {
    this->SetActiveCoordinateSystem(0, coord_idx);
  }
 
  VISKORES_CONT void SetActiveCoordinateSystem(viskores::IdComponent index, viskores::Id coord_idx)
  {
    auto index_st = static_cast<std::size_t>(index);
    this->ResizeIfNeeded(index_st);
    this->ActiveCoordinateSystemIndices[index_st] = coord_idx;
  }
 
  VISKORES_CONT viskores::Id GetActiveCoordinateSystemIndex(viskores::IdComponent index = 0) const
  {
    auto index_st = static_cast<std::size_t>(index);
    return this->ActiveCoordinateSystemIndices[index_st];
  }
 
  VISKORES_CONT void SetUseCoordinateSystemAsField(bool val)
  {
    SetUseCoordinateSystemAsField(0, val);
  }
 
  VISKORES_CONT void SetUseCoordinateSystemAsField(viskores::IdComponent index, bool val)
  {
    auto index_st = static_cast<std::size_t>(index);
    this->ResizeIfNeeded(index_st);
    this->UseCoordinateSystemAsField[index] = val;
  }
 
  VISKORES_CONT
  bool GetUseCoordinateSystemAsField(viskores::IdComponent index = 0) const
  {
    VISKORES_ASSERT((index >= 0) &&
                    (index < static_cast<viskores::IdComponent>(this->ActiveFieldNames.size())));
    return this->UseCoordinateSystemAsField[index];
  }
 
  viskores::IdComponent GetNumberOfActiveFields() const
  {
    VISKORES_ASSERT(this->ActiveFieldNames.size() == this->UseCoordinateSystemAsField.size());
    return static_cast<viskores::IdComponent>(this->UseCoordinateSystemAsField.size());
  }
 
  VISKORES_CONT virtual bool CanThread() const;
 
  VISKORES_CONT void SetThreadsPerCPU(viskores::Id numThreads)
  {
    this->NumThreadsPerCPU = numThreads;
  }
  VISKORES_CONT void SetThreadsPerGPU(viskores::Id numThreads)
  {
    this->NumThreadsPerGPU = numThreads;
  }
 
  VISKORES_CONT viskores::Id GetThreadsPerCPU() const { return this->NumThreadsPerCPU; }
  VISKORES_CONT viskores::Id GetThreadsPerGPU() const { return this->NumThreadsPerGPU; }
 
  VISKORES_CONT bool GetRunMultiThreadedFilter() const
  {
    return this->CanThread() && this->RunFilterWithMultipleThreads;
  }
 
  VISKORES_CONT void SetRunMultiThreadedFilter(bool val)
  {
    if (this->CanThread())
      this->RunFilterWithMultipleThreads = val;
    else
    {
      std::string msg =
        "Multi threaded filter not supported for " + std::string(typeid(*this).name());
      VISKORES_LOG_S(viskores::cont::LogLevel::Info, msg);
    }
  }
 
  // FIXME: Is this actually materialize? Are there different kinds of Invoker?
  void SetInvoker(viskores::cont::Invoker inv) { this->Invoke = inv; }
 
protected:
  viskores::cont::Invoker Invoke;
 
  VISKORES_CONT viskores::cont::DataSet CreateResult(
    const viskores::cont::DataSet& inDataSet) const;
 
  VISKORES_CONT viskores::cont::DataSet CreateResultField(
    const viskores::cont::DataSet& inDataSet,
    const viskores::cont::Field& resultField) const;
 
  VISKORES_CONT viskores::cont::DataSet CreateResultField(
    const viskores::cont::DataSet& inDataSet,
    const std::string& resultFieldName,
    viskores::cont::Field::Association resultFieldAssociation,
    const viskores::cont::UnknownArrayHandle& resultFieldArray) const
  {
    return this->CreateResultField(
      inDataSet,
      viskores::cont::Field{ resultFieldName, resultFieldAssociation, resultFieldArray });
  }
 
  VISKORES_CONT viskores::cont::DataSet CreateResultFieldPoint(
    const viskores::cont::DataSet& inDataSet,
    const std::string& resultFieldName,
    const viskores::cont::UnknownArrayHandle& resultFieldArray) const
  {
    return this->CreateResultField(
      inDataSet,
      viskores::cont::Field{
        resultFieldName, viskores::cont::Field::Association::Points, resultFieldArray });
  }
 
  VISKORES_CONT viskores::cont::DataSet CreateResultFieldCell(
    const viskores::cont::DataSet& inDataSet,
    const std::string& resultFieldName,
    const viskores::cont::UnknownArrayHandle& resultFieldArray) const
  {
    return this->CreateResultField(inDataSet,
                                   viskores::cont::Field{ resultFieldName,
                                                          viskores::cont::Field::Association::Cells,
                                                          resultFieldArray });
  }
 
 
  VISKORES_CONT viskores::cont::PartitionedDataSet CreateResult(
    const viskores::cont::PartitionedDataSet& input,
    const viskores::cont::PartitionedDataSet& resultPartitions) const;
 
  template <typename FieldMapper>
  VISKORES_CONT viskores::cont::PartitionedDataSet CreateResult(
    const viskores::cont::PartitionedDataSet& input,
    const viskores::cont::PartitionedDataSet& resultPartitions,
    FieldMapper&& fieldMapper) const
  {
    viskores::cont::PartitionedDataSet output(resultPartitions.GetPartitions());
    this->MapFieldsOntoOutput(input, this->GetFieldsToPass(), output, fieldMapper);
    return output;
  }
 
  template <typename FieldMapper>
  VISKORES_CONT viskores::cont::DataSet CreateResult(
    const viskores::cont::DataSet& inDataSet,
    const viskores::cont::UnknownCellSet& resultCellSet,
    FieldMapper&& fieldMapper) const
  {
    viskores::cont::DataSet outDataSet;
    outDataSet.SetCellSet(resultCellSet);
    this->MapFieldsOntoOutput(inDataSet, this->GetFieldsToPass(), outDataSet, fieldMapper);
    return outDataSet;
  }
 
  template <typename FieldMapper>
  VISKORES_CONT viskores::cont::DataSet CreateResultCoordinateSystem(
    const viskores::cont::DataSet& inDataSet,
    const viskores::cont::UnknownCellSet& resultCellSet,
    const viskores::cont::CoordinateSystem& resultCoordSystem,
    FieldMapper&& fieldMapper) const
  {
    viskores::cont::DataSet outDataSet;
    outDataSet.SetCellSet(resultCellSet);
    viskores::filter::FieldSelection fieldSelection = this->GetFieldsToPass();
    if (this->GetPassCoordinateSystems() || fieldSelection.HasField(resultCoordSystem))
    {
      outDataSet.AddCoordinateSystem(resultCoordSystem);
      fieldSelection.AddField(resultCoordSystem, viskores::filter::FieldSelection::Mode::Exclude);
    }
    this->MapFieldsOntoOutput(inDataSet, fieldSelection, outDataSet, fieldMapper);
    return outDataSet;
  }
 
  template <typename FieldMapper>
  VISKORES_CONT viskores::cont::DataSet CreateResultCoordinateSystem(
    const viskores::cont::DataSet& inDataSet,
    const viskores::cont::UnknownCellSet& resultCellSet,
    const std::string& coordsName,
    const viskores::cont::UnknownArrayHandle& coordsData,
    FieldMapper&& fieldMapper) const
  {
    return this->CreateResultCoordinateSystem(
      inDataSet,
      resultCellSet,
      viskores::cont::CoordinateSystem{ coordsName, coordsData },
      fieldMapper);
  }
 
  VISKORES_CONT const viskores::cont::Field& GetFieldFromDataSet(
    const viskores::cont::DataSet& input) const
  {
    return this->GetFieldFromDataSet(0, input);
  }
 
  VISKORES_CONT const viskores::cont::Field& GetFieldFromDataSet(
    viskores::IdComponent index,
    const viskores::cont::DataSet& input) const
  {
    if (this->UseCoordinateSystemAsField[index])
    {
      // Note that we cannot use input.GetCoordinateSystem because that does not return
      // a reference to a field. Instead, get the field name for the coordinate system
      // and return the field.
      const std::string& coordSystemName =
        input.GetCoordinateSystemName(this->GetActiveCoordinateSystemIndex(index));
      return input.GetPointField(coordSystemName);
    }
    else
    {
      return input.GetField(this->GetActiveFieldName(index),
                            this->GetActiveFieldAssociation(index));
    }
  }
 
  VISKORES_CONT virtual viskores::cont::DataSet DoExecute(
    const viskores::cont::DataSet& inData) = 0;
  VISKORES_CONT virtual viskores::cont::PartitionedDataSet DoExecutePartitions(
    const viskores::cont::PartitionedDataSet& inData);
 
  template <typename Functor, typename... Args>
  VISKORES_CONT void CastAndCallScalarField(const viskores::cont::UnknownArrayHandle& fieldArray,
                                            Functor&& functor,
                                            Args&&... args) const
  {
    fieldArray.CastAndCallForTypesWithFloatFallback<viskores::TypeListFieldScalar,
                                                    VISKORES_DEFAULT_STORAGE_LIST>(
      std::forward<Functor>(functor), std::forward<Args>(args)...);
  }
  template <typename Functor, typename... Args>
  VISKORES_CONT void CastAndCallScalarField(const viskores::cont::Field& field,
                                            Functor&& functor,
                                            Args&&... args) const
  {
    this->CastAndCallScalarField(
      field.GetData(), std::forward<Functor>(functor), std::forward<Args>(args)...);
  }
 
  template <viskores::IdComponent VecSize, typename Functor, typename... Args>
  VISKORES_CONT void CastAndCallVecField(const viskores::cont::UnknownArrayHandle& fieldArray,
                                         Functor&& functor,
                                         Args&&... args) const
  {
    using VecList =
      viskores::ListTransform<viskores::TypeListFieldScalar, ScalarToVec<VecSize>::template type>;
    fieldArray.CastAndCallForTypesWithFloatFallback<VecList, VISKORES_DEFAULT_STORAGE_LIST>(
      std::forward<Functor>(functor), std::forward<Args>(args)...);
  }
  template <viskores::IdComponent VecSize, typename Functor, typename... Args>
  VISKORES_CONT void CastAndCallVecField(const viskores::cont::Field& field,
                                         Functor&& functor,
                                         Args&&... args) const
  {
    this->CastAndCallVecField<VecSize>(
      field.GetData(), std::forward<Functor>(functor), std::forward<Args>(args)...);
  }
 
  template <typename Functor, typename... Args>
  VISKORES_CONT void CastAndCallVariableVecField(
    const viskores::cont::UnknownArrayHandle& fieldArray,
    Functor&& functor,
    Args&&... args) const
  {
    if (fieldArray.IsBaseComponentType<viskores::Float32>())
    {
      functor(fieldArray.ExtractArrayFromComponents<viskores::Float32>(),
              std::forward<Args>(args)...);
    }
    else if (fieldArray.IsBaseComponentType<viskores::Float64>())
    {
      functor(fieldArray.ExtractArrayFromComponents<viskores::Float64>(),
              std::forward<Args>(args)...);
    }
    else
    {
      // Field component type is not directly supported. Copy to floating point array.
      viskores::cont::UnknownArrayHandle floatArray = fieldArray.NewInstanceFloatBasic();
      viskores::cont::ArrayCopy(fieldArray, floatArray);
      functor(floatArray.ExtractArrayFromComponents<viskores::FloatDefault>(),
              std::forward<Args>(args)...);
    }
  }
  template <typename Functor, typename... Args>
  VISKORES_CONT void CastAndCallVariableVecField(const viskores::cont::Field& field,
                                                 Functor&& functor,
                                                 Args&&... args) const
  {
    this->CastAndCallVariableVecField(
      field.GetData(), std::forward<Functor>(functor), std::forward<Args>(args)...);
  }
 
private:
  template <typename FieldMapper>
  VISKORES_CONT void MapFieldsOntoOutput(const viskores::cont::DataSet& input,
                                         const viskores::filter::FieldSelection& fieldSelection,
                                         viskores::cont::DataSet& output,
                                         FieldMapper&& fieldMapper) const
  {
    // Basic field mapping
    for (viskores::IdComponent cc = 0; cc < input.GetNumberOfFields(); ++cc)
    {
      auto field = input.GetField(cc);
      if (fieldSelection.IsFieldSelected(field))
      {
        fieldMapper(output, field);
      }
    }
 
    // Check if the ghost levels have been copied. If so, set so on the output.
    if (input.HasGhostCellField())
    {
      const std::string& ghostFieldName = input.GetGhostCellFieldName();
      if (output.HasCellField(ghostFieldName) && (output.GetGhostCellFieldName() != ghostFieldName))
      {
        output.SetGhostCellFieldName(ghostFieldName);
      }
    }
 
    for (viskores::IdComponent csIndex = 0; csIndex < input.GetNumberOfCoordinateSystems();
         ++csIndex)
    {
      auto coords = input.GetCoordinateSystem(csIndex);
      if (!output.HasCoordinateSystem(coords.GetName()))
      {
        if (!output.HasPointField(coords.GetName()) && this->GetPassCoordinateSystems())
        {
          fieldMapper(output, coords);
        }
        if (output.HasPointField(coords.GetName()))
        {
          output.AddCoordinateSystem(coords.GetName());
        }
      }
    }
  }
 
  template <typename FieldMapper>
  VISKORES_CONT void MapFieldsOntoOutput(const viskores::cont::PartitionedDataSet& input,
                                         const viskores::filter::FieldSelection& fieldSelection,
                                         viskores::cont::PartitionedDataSet& output,
                                         FieldMapper&& fieldMapper) const
  {
    for (viskores::IdComponent cc = 0; cc < input.GetNumberOfFields(); ++cc)
    {
      auto field = input.GetField(cc);
      if (fieldSelection.IsFieldSelected(field))
      {
        fieldMapper(output, field);
      }
    }
  }
 
  template <viskores::IdComponent VecSize>
  struct ScalarToVec
  {
    template <typename T>
    using type = viskores::Vec<T, VecSize>;
  };
 
  VISKORES_CONT
  virtual viskores::Id DetermineNumberOfThreads(const viskores::cont::PartitionedDataSet& input);
 
  void ResizeIfNeeded(size_t index_st);
 
  viskores::filter::FieldSelection FieldsToPass = viskores::filter::FieldSelection::Mode::All;
  bool PassCoordinateSystems = true;
  bool RunFilterWithMultipleThreads = false;
  viskores::Id NumThreadsPerCPU = 4;
  viskores::Id NumThreadsPerGPU = 8;
 
  std::string OutputFieldName;
 
  std::vector<std::string> ActiveFieldNames;
  std::vector<viskores::cont::Field::Association> ActiveFieldAssociation;
  std::vector<bool> UseCoordinateSystemAsField;
  std::vector<viskores::Id> ActiveCoordinateSystemIndices;
};
 
class VISKORES_DEPRECATED(2.2, "Inherit from `viskores::cont::Filter` directly.") FilterField
  : public viskores::filter::Filter
{
};
 
}
} // namespace viskores::filter
 
#endif