VTK  9.3.1
vtkStreamTracer.h
Go to the documentation of this file.
1 // SPDX-FileCopyrightText: Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
2 // SPDX-License-Identifier: BSD-3-Clause
91 #ifndef vtkStreamTracer_h
92 #define vtkStreamTracer_h
93 
94 #include "vtkFiltersFlowPathsModule.h" // For export macro
95 #include "vtkPolyDataAlgorithm.h"
96 
97 #include "vtkDataSetAttributesFieldList.h" // Needed to identify common data arrays
98 #include "vtkInitialValueProblemSolver.h" // Needed for constants
99 
100 VTK_ABI_NAMESPACE_BEGIN
102 class vtkCompositeDataSet;
103 class vtkDataArray;
105 class vtkDoubleArray;
106 class vtkExecutive;
107 class vtkGenericCell;
108 class vtkIdList;
109 class vtkIntArray;
110 class vtkPoints;
111 
112 VTK_ABI_NAMESPACE_END
113 #include <vector> // for std::vector
114 
115 // Helper struct to convert between different length scales.
116 VTK_ABI_NAMESPACE_BEGIN
117 struct VTKFILTERSFLOWPATHS_EXPORT vtkIntervalInformation
118 {
119  double Interval;
120  int Unit;
121 
122  static double ConvertToLength(double interval, int unit, double cellLength);
123  static double ConvertToLength(vtkIntervalInformation& interval, double cellLength);
124 };
125 
137  void* clientdata, vtkPoints* points, vtkDataArray* velocity, int integrationDirection);
138 
139 class VTKFILTERSFLOWPATHS_EXPORT vtkStreamTracer : public vtkPolyDataAlgorithm
140 {
141 public:
149  static vtkStreamTracer* New();
150 
152 
156  void PrintSelf(ostream& os, vtkIndent indent) override;
158 
160 
165  vtkSetVector3Macro(StartPosition, double);
166  vtkGetVector3Macro(StartPosition, double);
168 
170 
179 
186 
187  // The previously-supported TIME_UNIT is excluded in this current
188  // enumeration definition because the underlying step size is ALWAYS in
189  // arc length unit (LENGTH_UNIT) while the 'real' time interval (virtual
190  // for steady flows) that a particle actually takes to trave in a single
191  // step is obtained by dividing the arc length by the LOCAL speed. The
192  // overall elapsed time (i.e., the life span) of the particle is the sum
193  // of those individual step-wise time intervals. The arc-length-to-time
194  // conversion only occurs for vorticity computation and for generating a
195  // point data array named 'IntegrationTime'.
196  enum Units
197  {
198  LENGTH_UNIT = 1,
199  CELL_LENGTH_UNIT = 2
200  };
201 
202  enum Solvers
203  {
208  UNKNOWN
209  };
210 
212  {
216  OUT_OF_LENGTH = 4,
217  OUT_OF_STEPS = 5,
218  STAGNATION = 6,
219  FIXED_REASONS_FOR_TERMINATION_COUNT
220  };
221 
223 
234  vtkGetObjectMacro(Integrator, vtkInitialValueProblemSolver);
237  void SetIntegratorTypeToRungeKutta2() { this->SetIntegratorType(RUNGE_KUTTA2); }
238  void SetIntegratorTypeToRungeKutta4() { this->SetIntegratorType(RUNGE_KUTTA4); }
239  void SetIntegratorTypeToRungeKutta45() { this->SetIntegratorType(RUNGE_KUTTA45); }
241 
252 
260 
262 
265  vtkSetMacro(MaximumPropagation, double);
266  vtkGetMacro(MaximumPropagation, double);
268 
275  void SetIntegrationStepUnit(int unit);
276  int GetIntegrationStepUnit() { return this->IntegrationStepUnit; }
277 
279 
286  vtkSetMacro(InitialIntegrationStep, double);
287  vtkGetMacro(InitialIntegrationStep, double);
289 
291 
297  vtkSetMacro(MinimumIntegrationStep, double);
298  vtkGetMacro(MinimumIntegrationStep, double);
300 
302 
308  vtkSetMacro(MaximumIntegrationStep, double);
309  vtkGetMacro(MaximumIntegrationStep, double);
311 
313 
316  vtkSetMacro(MaximumError, double);
317  vtkGetMacro(MaximumError, double);
319 
321 
329  vtkSetMacro(MaximumNumberOfSteps, vtkIdType);
330  vtkGetMacro(MaximumNumberOfSteps, vtkIdType);
332 
334 
338  vtkSetMacro(TerminalSpeed, double);
339  vtkGetMacro(TerminalSpeed, double);
341 
343 
347  vtkGetMacro(SurfaceStreamlines, bool);
348  vtkSetMacro(SurfaceStreamlines, bool);
349  vtkBooleanMacro(SurfaceStreamlines, bool);
351 
352  enum
353  {
356  BOTH
357  };
358 
359  enum
360  {
362  INTERPOLATOR_WITH_CELL_LOCATOR
363  };
364 
366 
373  vtkSetClampMacro(IntegrationDirection, int, FORWARD, BOTH);
374  vtkGetMacro(IntegrationDirection, int);
375  void SetIntegrationDirectionToForward() { this->SetIntegrationDirection(FORWARD); }
376  void SetIntegrationDirectionToBackward() { this->SetIntegrationDirection(BACKWARD); }
377  void SetIntegrationDirectionToBoth() { this->SetIntegrationDirection(BOTH); }
379 
381 
386  vtkSetMacro(ComputeVorticity, bool);
387  vtkGetMacro(ComputeVorticity, bool);
389 
391 
395  vtkSetMacro(RotationScale, double);
396  vtkGetMacro(RotationScale, double);
398 
409 
419  void SetInterpolatorType(int interpType);
420 
422 
426  vtkGetMacro(ForceSerialExecution, bool);
427  vtkSetMacro(ForceSerialExecution, bool);
428  vtkBooleanMacro(ForceSerialExecution, bool);
430 
440  CustomTerminationCallbackType callback, void* clientdata, int reasonForTermination);
441 
451  double& step, double& minStep, double& maxStep, int direction, double cellLength);
452 
454 
458  void GenerateNormals(vtkPolyData* output, double* firstNormal, const char* vecName);
460  vtkGenericCell* cell, double pcoords[3], vtkDoubleArray* cellVectors, double vorticity[3]);
462 
464 
474  vtkSetMacro(UseLocalSeedSource, bool);
475  vtkGetMacro(UseLocalSeedSource, bool);
476  vtkBooleanMacro(UseLocalSeedSource, bool);
478 
479 protected:
481  ~vtkStreamTracer() override;
482 
483  // Create a default executive.
485 
486  // hide the superclass' AddInput() from the user and the compiler
488  {
489  vtkErrorMacro(<< "AddInput() must be called with a vtkDataSet not a vtkDataObject.");
490  }
491 
494 
495  void Integrate(vtkPointData* inputData, vtkPolyData* output, vtkDataArray* seedSource,
496  vtkIdList* seedIds, vtkIntArray* integrationDirections,
497  vtkAbstractInterpolatedVelocityField* func, int maxCellSize, int vecType,
498  const char* vecFieldName, double& propagation, vtkIdType& numSteps, double& integrationTime,
499  std::vector<CustomTerminationCallbackType>& customTerminationCallback,
500  std::vector<void*>& customTerminationClientData, std::vector<int>& customReasonForTermination);
501 
502  double SimpleIntegrate(double seed[3], double lastPoint[3], double stepSize,
504  int CheckInputs(vtkAbstractInterpolatedVelocityField*& func, int* maxCellSize);
505 
507 
508  // starting from global x-y-z position
509  double StartPosition[3];
510 
511  static const double EPSILON;
513 
514  // Used by subclasses, leave alone
516 
521 
522  int SetupOutput(vtkInformation* inInfo, vtkInformation* outInfo);
523  void InitializeSeeds(vtkDataArray*& seeds, vtkIdList*& seedIds,
524  vtkIntArray*& integrationDirections, vtkDataSet* source);
525 
528 
529  // Prototype showing the integrator type to be set by the user.
531 
532  double MaximumError;
534 
537 
538  // Compute streamlines only on surface.
540 
542 
543  // These are used to manage complex input types such as
544  // multiblock / composite datasets. Basically the filter input is
545  // converted to a composite dataset, and the point data attributes
546  // are intersected to produce a common set of output data arrays.
547  vtkCompositeDataSet* InputData; // convert input data to composite dataset
548  vtkDataSetAttributesFieldList InputPD; // intersect attributes of all datasets
549  bool
550  HasMatchingPointAttributes; // does the point data in the multiblocks have the same attributes?
551 
552  // Control execution as serial or threaded
554  bool SerialExecution; // internal use to combine information
555 
556  std::vector<CustomTerminationCallbackType> CustomTerminationCallback;
557  std::vector<void*> CustomTerminationClientData;
558  std::vector<int> CustomReasonForTermination;
559 
560  // Only relevant for this derived parallel version of vtkStreamTracer,
561  // but needs to be defined in this class to have a uniform interface
562  // between this class and the parallel override vtkPStreamTracer
564 
565  friend class PStreamTracerUtils;
566 
567 private:
568  vtkStreamTracer(const vtkStreamTracer&) = delete;
569  void operator=(const vtkStreamTracer&) = delete;
570 };
571 
572 VTK_ABI_NAMESPACE_END
573 #endif
An abstract class for obtaining the interpolated velocity values at a point.
Proxy object to connect input/output ports.
abstract superclass for composite (multi-block or AMR) datasets
abstract superclass for arrays of numeric data
Definition: vtkDataArray.h:54
general representation of visualization data
Definition: vtkDataObject.h:64
helps manage arrays from multiple vtkDataSetAttributes.
represent and manipulate attribute data in a dataset
abstract class to specify dataset behavior
Definition: vtkDataSet.h:62
dynamic, self-adjusting array of double
Superclass for all pipeline executives in VTK.
Definition: vtkExecutive.h:48
provides thread-safe access to cells
list of point or cell ids
Definition: vtkIdList.h:32
a simple class to control print indentation
Definition: vtkIndent.h:38
Store zero or more vtkInformation instances.
Store vtkAlgorithm input/output information.
Integrate a set of ordinary differential equations (initial value problem) in time.
dynamic, self-adjusting array of int
Definition: vtkIntArray.h:44
represent and manipulate point attribute data
Definition: vtkPointData.h:39
represent and manipulate 3D points
Definition: vtkPoints.h:38
Superclass for algorithms that produce only polydata as output.
concrete dataset represents vertices, lines, polygons, and triangle strips
Definition: vtkPolyData.h:89
Streamline generator.
void SetIntegratorTypeToRungeKutta45()
Set/get the integrator type to be used for streamline generation.
int FillInputPortInformation(int, vtkInformation *) override
Fill the input port information objects for this algorithm.
int SetupOutput(vtkInformation *inInfo, vtkInformation *outInfo)
std::vector< void * > CustomTerminationClientData
vtkDataSetAttributesFieldList InputPD
void SetSourceData(vtkDataSet *source)
Specify the source object used to generate starting points (seeds).
double InitialIntegrationStep
vtkAbstractInterpolatedVelocityField * InterpolatorPrototype
void SetInterpolatorTypeToCellLocator()
Set the velocity field interpolator type to one that uses a cell locator to perform spatial searching...
void PrintSelf(ostream &os, vtkIndent indent) override
Standard methods to obtain type information and print object state.
void CalculateVorticity(vtkGenericCell *cell, double pcoords[3], vtkDoubleArray *cellVectors, double vorticity[3])
Helper methods to generate normals on streamlines.
double MinimumIntegrationStep
void SetIntegratorTypeToRungeKutta4()
Set/get the integrator type to be used for streamline generation.
vtkDataSet * GetSource()
Specify the source object used to generate starting points (seeds).
@ INTERPOLATOR_WITH_DATASET_POINT_LOCATOR
void SetIntegrator(vtkInitialValueProblemSolver *)
Set/get the integrator type to be used for streamline generation.
void SetSourceConnection(vtkAlgorithmOutput *algOutput)
Specify the source object used to generate starting points (seeds).
std::vector< int > CustomReasonForTermination
int CheckInputs(vtkAbstractInterpolatedVelocityField *&func, int *maxCellSize)
void ConvertIntervals(double &step, double &minStep, double &maxStep, int direction, double cellLength)
The following methods should not be called by the user.
void GenerateNormals(vtkPolyData *output, double *firstNormal, const char *vecName)
Helper methods to generate normals on streamlines.
static const double EPSILON
vtkIdType MaximumNumberOfSteps
void SetIntegrationDirectionToForward()
Specify whether the streamline is integrated in the upstream or downstream direction,...
std::vector< CustomTerminationCallbackType > CustomTerminationCallback
bool HasMatchingPointAttributes
vtkCompositeDataSet * InputData
vtkExecutive * CreateDefaultExecutive() override
Create a default executive.
void SetInterpolatorType(int interpType)
Set the type of the velocity field interpolator to determine whether INTERPOLATOR_WITH_DATASET_POINT_...
double MaximumIntegrationStep
int RequestData(vtkInformation *, vtkInformationVector **, vtkInformationVector *) override
This is called by the superclass.
bool GenerateNormalsInIntegrate
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)
void SetIntegrationDirectionToBackward()
Specify whether the streamline is integrated in the upstream or downstream direction,...
void SetInterpolatorTypeToDataSetPointLocator()
Set the velocity field interpolator type to one that uses a point locator to perform local spatial se...
int GetIntegratorType()
Set/get the integrator type to be used for streamline generation.
void AddCustomTerminationCallback(CustomTerminationCallbackType callback, void *clientdata, int reasonForTermination)
Adds a custom termination callback.
void InitializeSeeds(vtkDataArray *&seeds, vtkIdList *&seedIds, vtkIntArray *&integrationDirections, vtkDataSet *source)
void SetIntegratorTypeToRungeKutta2()
Set/get the integrator type to be used for streamline generation.
static vtkStreamTracer * New()
Construct the object to start from position (0,0,0), with forward integration, terminal speed 1....
void SetIntegrationDirectionToBoth()
Specify whether the streamline is integrated in the upstream or downstream direction,...
double SimpleIntegrate(double seed[3], double lastPoint[3], double stepSize, vtkAbstractInterpolatedVelocityField *func)
~vtkStreamTracer() override
void AddInput(vtkDataObject *)
vtkInitialValueProblemSolver * Integrator
void SetInterpolatorPrototype(vtkAbstractInterpolatedVelocityField *ivf)
The object used to interpolate the velocity field during integration is of the same class as this pro...
void SetIntegrationStepUnit(int unit)
Specify a uniform integration step unit for MinimumIntegrationStep, InitialIntegrationStep,...
void SetIntegratorType(int type)
Set/get the integrator type to be used for streamline generation.
int GetIntegrationStepUnit()
@ points
Definition: vtkX3D.h:446
@ direction
Definition: vtkX3D.h:260
@ type
Definition: vtkX3D.h:516
static double ConvertToLength(double interval, int unit, double cellLength)
static double ConvertToLength(vtkIntervalInformation &interval, double cellLength)
boost::graph_traits< vtkGraph * >::vertex_descriptor source(boost::graph_traits< vtkGraph * >::edge_descriptor e, vtkGraph *)
bool(* CustomTerminationCallbackType)(void *clientdata, vtkPoints *points, vtkDataArray *velocity, int integrationDirection)
Used to specify custom conditions which are evaluated to determine whether a streamline should be ter...
int vtkIdType
Definition: vtkType.h:315