vtkStreamTracer.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
// SPDX-License-Identifier: BSD-3-Clause
#ifndef vtkStreamTracer_h
#define vtkStreamTracer_h

#include "vtkDeprecation.h"            // VTK_DEPRECATED_IN_9_7_0
#include "vtkFiltersFlowPathsModule.h" // For export macro
#include "vtkPolyDataAlgorithm.h"

#include "vtkDataSetAttributesFieldList.h" // Needed to identify common data arrays
#include "vtkInitialValueProblemSolver.h"  // Needed for constants

VTK_ABI_NAMESPACE_BEGIN
class vtkAbstractCellLocator;
class vtkAbstractInterpolatedVelocityField;
class vtkCompositeDataSet;
class vtkDataArray;
class vtkDataSetAttributes;
class vtkDoubleArray;
class vtkExecutive;
class vtkGenericCell;
class vtkIdList;
class vtkIntArray;
class vtkPoints;

VTK_ABI_NAMESPACE_END
#include <vector> // for std::vector

// Helper struct to convert between different length scales.
VTK_ABI_NAMESPACE_BEGIN
struct VTKFILTERSFLOWPATHS_EXPORT vtkIntervalInformation
{
  double Interval;
  int Unit;

  static double ConvertToLength(double interval, int unit, double cellLength);
  static double ConvertToLength(vtkIntervalInformation& interval, double cellLength);
};

typedef bool (*CustomTerminationCallbackType)(
  void* clientdata, vtkPoints* points, vtkDataArray* velocity, int integrationDirection);

class VTKFILTERSFLOWPATHS_EXPORT vtkStreamTracer : public vtkPolyDataAlgorithm
{
public:
  static vtkStreamTracer* New();


  vtkTypeMacro(vtkStreamTracer, vtkPolyDataAlgorithm);
  void PrintSelf(ostream& os, vtkIndent indent) override;


  vtkSetVector3Macro(StartPosition, double);
  vtkGetVector3Macro(StartPosition, double);


  void SetSourceData(vtkDataSet* source);
  vtkDataSet* GetSource();

  void SetSourceConnection(vtkAlgorithmOutput* algOutput);

  // The previously-supported TIME_UNIT is excluded in this current
  // enumeration definition because the underlying step size is ALWAYS in
  // arc length unit (LENGTH_UNIT) while the 'real' time interval (virtual
  // for steady flows) that a particle actually takes to trave in a single
  // step is obtained by dividing the arc length by the LOCAL speed. The
  // overall elapsed time (i.e., the life span) of the particle is the sum
  // of those individual step-wise time intervals. The arc-length-to-time
  // conversion only occurs for vorticity computation and for generating a
  // point data array named 'IntegrationTime'.
  enum Units
  {
    LENGTH_UNIT = 1,
    CELL_LENGTH_UNIT = 2
  };

  enum Solvers
  {
    RUNGE_KUTTA2,
    RUNGE_KUTTA4,
    RUNGE_KUTTA45,
    NONE,
    UNKNOWN
  };

  enum ReasonForTermination
  {
    OUT_OF_DOMAIN = vtkInitialValueProblemSolver::OUT_OF_DOMAIN,
    NOT_INITIALIZED = vtkInitialValueProblemSolver::NOT_INITIALIZED,
    UNEXPECTED_VALUE = vtkInitialValueProblemSolver::UNEXPECTED_VALUE,
    OUT_OF_LENGTH = 4,
    OUT_OF_STEPS = 5,
    STAGNATION = 6,
    FIXED_REASONS_FOR_TERMINATION_COUNT = 7,
  };


  void SetIntegrator(vtkInitialValueProblemSolver*);
  vtkGetObjectMacro(Integrator, vtkInitialValueProblemSolver);
  void SetIntegratorType(int type);
  int GetIntegratorType();
  void SetIntegratorTypeToRungeKutta2() { this->SetIntegratorType(RUNGE_KUTTA2); }
  void SetIntegratorTypeToRungeKutta4() { this->SetIntegratorType(RUNGE_KUTTA4); }
  void SetIntegratorTypeToRungeKutta45() { this->SetIntegratorType(RUNGE_KUTTA45); }

  VTK_DEPRECATED_IN_9_7_0("Use SetCellLocatorToJumpAndWalkCellLocator() instead")
  void SetInterpolatorTypeToDataSetPointLocator();

  VTK_DEPRECATED_IN_9_7_0("Use SetCellLocatorToStaticCellLocator() instead")
  void SetInterpolatorTypeToCellLocator();


  vtkSetMacro(MaximumPropagation, double);
  vtkGetMacro(MaximumPropagation, double);

  void SetIntegrationStepUnit(int unit);
  int GetIntegrationStepUnit() { return this->IntegrationStepUnit; }


  vtkSetMacro(InitialIntegrationStep, double);
  vtkGetMacro(InitialIntegrationStep, double);


  vtkSetMacro(MinimumIntegrationStep, double);
  vtkGetMacro(MinimumIntegrationStep, double);


  vtkSetMacro(MaximumIntegrationStep, double);
  vtkGetMacro(MaximumIntegrationStep, double);


  vtkSetMacro(MaximumError, double);
  vtkGetMacro(MaximumError, double);


  vtkSetMacro(MaximumNumberOfSteps, vtkIdType);
  vtkGetMacro(MaximumNumberOfSteps, vtkIdType);


  vtkSetMacro(TerminalSpeed, double);
  vtkGetMacro(TerminalSpeed, double);


  vtkGetMacro(SurfaceStreamlines, bool);
  vtkSetMacro(SurfaceStreamlines, bool);
  vtkBooleanMacro(SurfaceStreamlines, bool);

  enum
  {
    FORWARD,
    BACKWARD,
    BOTH
  };

  enum
  {
    INTERPOLATOR_WITH_DATASET_POINT_LOCATOR VTK_DEPRECATED_IN_9_7_0(
      "Use SetCellLocatorToJumpAndWalkCellLocator() instead"),
    INTERPOLATOR_WITH_CELL_LOCATOR VTK_DEPRECATED_IN_9_7_0(
      "Use SetCellLocatorToStaticCellLocator() instead")
  };


  vtkSetClampMacro(IntegrationDirection, int, FORWARD, BOTH);
  vtkGetMacro(IntegrationDirection, int);
  void SetIntegrationDirectionToForward() { this->SetIntegrationDirection(FORWARD); }
  void SetIntegrationDirectionToBackward() { this->SetIntegrationDirection(BACKWARD); }
  void SetIntegrationDirectionToBoth() { this->SetIntegrationDirection(BOTH); }


  vtkSetMacro(ComputeVorticity, bool);
  vtkGetMacro(ComputeVorticity, bool);


  vtkSetMacro(RotationScale, double);
  vtkGetMacro(RotationScale, double);

  VTK_DEPRECATED_IN_9_7_0("Use SetCellLocator(vtkAbstractCellLocator*) instead")
  void SetInterpolatorPrototype(vtkAbstractInterpolatedVelocityField* ivf);

  VTK_DEPRECATED_IN_9_7_0("Use SetCellLocator(vtkAbstractCellLocator*) instead")
  void SetInterpolatorType(int interpType);


  virtual void SetCellLocator(vtkAbstractCellLocator*);
  virtual void SetCellLocatorToStaticCellLocator();
  virtual void SetCellLocatorToJumpAndWalkCellLocator();
  vtkGetObjectMacro(CellLocator, vtkAbstractCellLocator);


  vtkGetMacro(ForceSerialExecution, bool);
  vtkSetMacro(ForceSerialExecution, bool);
  vtkBooleanMacro(ForceSerialExecution, bool);

  void AddCustomTerminationCallback(
    CustomTerminationCallbackType callback, void* clientdata, int reasonForTermination);

  void ConvertIntervals(
    double& step, double& minStep, double& maxStep, int direction, double cellLength);


  void GenerateNormals(vtkPolyData* output, double* firstNormal, const char* vecName);
  void CalculateVorticity(
    vtkGenericCell* cell, double pcoords[3], vtkDoubleArray* cellVectors, double vorticity[3]);


  vtkSetMacro(UseLocalSeedSource, bool);
  vtkGetMacro(UseLocalSeedSource, bool);
  vtkBooleanMacro(UseLocalSeedSource, bool);

protected:
  vtkStreamTracer();
  ~vtkStreamTracer() override;

  // Create a default executive.
  vtkExecutive* CreateDefaultExecutive() override;

  // hide the superclass' AddInput() from the user and the compiler
  void AddInput(vtkDataObject*)
  {
    vtkErrorMacro(<< "AddInput() must be called with a vtkDataSet not a vtkDataObject.");
  }

  int RequestData(vtkInformation*, vtkInformationVector**, vtkInformationVector*) override;
  int FillInputPortInformation(int, vtkInformation*) override;

  void Integrate(vtkPointData* inputData, vtkPolyData* output, vtkDataArray* seedSource,
    vtkIdList* seedIds, vtkIntArray* integrationDirections,
    vtkAbstractInterpolatedVelocityField* func, int maxCellSize, int vecType,
    const char* vecFieldName, double& propagation, vtkIdType& numSteps, double& integrationTime,
    std::vector<CustomTerminationCallbackType>& customTerminationCallback,
    std::vector<void*>& customTerminationClientData, std::vector<int>& customReasonForTermination);

  double SimpleIntegrate(double seed[3], double lastPoint[3], double stepSize,
    vtkAbstractInterpolatedVelocityField* func);
  int CheckInputs(vtkAbstractInterpolatedVelocityField*& func, int* maxCellSize);

  bool GenerateNormalsInIntegrate;

  // starting from global x-y-z position
  double StartPosition[3];

  static const double EPSILON;
  double TerminalSpeed;

  // Used by subclasses, leave alone
  double LastUsedStepSize;

  double MaximumPropagation;
  double MinimumIntegrationStep;
  double MaximumIntegrationStep;
  double InitialIntegrationStep;

  int SetupOutput(vtkInformation* inInfo, vtkInformation* outInfo);
  void InitializeSeeds(vtkDataArray*& seeds, vtkIdList*& seedIds,
    vtkIntArray*& integrationDirections, vtkDataSet* source);

  int IntegrationStepUnit;
  int IntegrationDirection;

  // Prototype showing the integrator type to be set by the user.
  vtkInitialValueProblemSolver* Integrator;

  double MaximumError;
  vtkIdType MaximumNumberOfSteps;

  bool ComputeVorticity;
  double RotationScale;

  // Compute streamlines only on surface.
  bool SurfaceStreamlines;

  vtkAbstractCellLocator* CellLocator;

  // These are used to manage complex input types such as
  // multiblock / composite datasets. Basically the filter input is
  // converted to a composite dataset, and the point data attributes
  // are intersected to produce a common set of output data arrays.
  vtkCompositeDataSet* InputData;        // convert input data to composite dataset
  vtkDataSetAttributesFieldList InputPD; // intersect attributes of all datasets
  bool
    HasMatchingPointAttributes; // does the point data in the multiblocks have the same attributes?

  // Control execution as serial or threaded
  bool ForceSerialExecution;
  bool SerialExecution; // internal use to combine information

  std::vector<CustomTerminationCallbackType> CustomTerminationCallback;
  std::vector<void*> CustomTerminationClientData;
  std::vector<int> CustomReasonForTermination;

  // Only relevant for this derived parallel version of vtkStreamTracer,
  // but needs to be defined in this class to have a uniform interface
  // between this class and the parallel override vtkPStreamTracer
  bool UseLocalSeedSource;

  friend class PStreamTracerUtils;

private:
  vtkStreamTracer(const vtkStreamTracer&) = delete;
  void operator=(const vtkStreamTracer&) = delete;
};

VTK_ABI_NAMESPACE_END
#endif