2.6. Sources

Before Viskores can process data, data must be placed in a viskores::cont::DataSet or viskores::cont::PartitionedDataSet. Files are one common way to get data into Viskores, as described in Chapter 2.5 (File I/O). Viskores also provides a set of source classes that generate synthetic data. These sources are useful for examples, tests, benchmarks, and for quickly constructing input to filters without managing external files.

All source classes provided by Viskores are located in the viskores::source namespace and declared in headers under viskores/source. Most sources derive from viskores::source::Source. The general interface is to construct a source, set any desired parameters, and call Execute to generate the data.

class Source

Base class for sources that generate a single data set.

A source creates a new viskores::cont::DataSet when Execute is called. Subclasses implement DoExecute to construct the concrete data set.

Subclassed by viskores::source::Oscillator, viskores::source::PerlinNoise, viskores::source::Tangle, viskores::source::Wavelet

Public Functions

inline viskores::cont::DataSet Execute() const

Generates the data set for this source.

The returned data set is newly generated from the current source parameters.

2.6.1. Uniform Grid Sources

Several source classes generate structured 3D data sets with uniform point coordinates. Most of these sources provide SetPointDimensions and SetCellDimensions methods. Point dimensions specify the number of points in each direction. Cell dimensions specify the number of cells in each direction, and the source will create one more point than cell in each direction.

2.6.1.1. Tangle

The viskores::source::Tangle source creates a uniform structured data set over the unit cube. It adds a scalar point field named tangle. The field is computed from a polynomial with a smooth, rounded shape that is useful for contouring, clipping, and other scalar-field operations. The tangle field usually ranges from just below 0 to about 25, with the most interesting contour surfaces near the lower end of that range. Good starting contour values are 0, 0.5, 1, and 2.

class Tangle : public viskores::source::Source

The Tangle source creates a uniform dataset.

This class generates a predictable uniform grid dataset with an interesting point field, which is useful for testing and benchmarking.

The Execute method creates a complete structured dataset of a resolution specified in the constructor that is bounded by the cube in the range [0,1] in each dimension. The dataset has a point field named ‘tangle’ computed with the following formula

x^4 - 5x^2 + y^4 - 5y^2 + z^4 - 5z^2

Public Functions

Tangle() = default

Constructs a tangle source with the default point dimensions.

The default point dimensions are {16, 16, 16}, which produces {15, 15, 15} cells.

inline viskores::Id3 GetPointDimensions() const

Gets the number of points in each dimension.

The generated structured data set has one fewer cell than point in each dimension.

inline void SetPointDimensions(viskores::Id3 dims)

Sets the number of points in each dimension.

The dimensions must be greater than 1 in each direction to generate cells.

inline viskores::Id3 GetCellDimensions() const

Gets the number of cells in each dimension.

This value is computed from the point dimensions by subtracting 1 in each direction.

inline void SetCellDimensions(viskores::Id3 dims)

Sets the number of cells in each dimension.

The point dimensions are set to one more than the given cell dimensions in each direction.

Example 2.25 Creating a tangle data set.
1  viskores::source::Tangle tangle;
2  tangle.SetCellDimensions({ 64, 64, 64 });
3
4  viskores::cont::DataSet dataSet = tangle.Execute();

2.6.1.2. Perlin Noise

The viskores::source::PerlinNoise source creates a uniform structured data set with a scalar point field named perlinnoise. The field contains tileable Perlin noise, which provides a smooth random-looking field for testing algorithms on noisy data. The perlinnoise field is normalized to values typically between 0 and 1. Contours at 0.3, 0.4, 0.5, 0.6, and 0.7 usually provide a useful spread of features.

If a seed is set with viskores::source::PerlinNoise::SetSeed(), repeated executions produce the same field values. If no seed is set, a new seed is selected each time Execute is called. The origin of the generated coordinate system can be changed with viskores::source::PerlinNoise::SetOrigin().

class PerlinNoise : public viskores::source::Source

The PerlinNoise source creates a uniform dataset.

This class generates a uniform grid dataset with a tileable perlin noise scalar point field.

The Execute method creates a complete structured dataset that have a scalar point field named ‘perlinnoise’.

Public Functions

PerlinNoise() = default

Constructs a Perlin noise source with default parameters.

The default point dimensions are 16 by 16 by 16, the origin is at 0, 0, 0, and no deterministic seed is selected.

inline viskores::Id3 GetPointDimensions() const

Gets the number of points in each dimension.

The generated structured data set has one fewer cell than point in each dimension.

inline void SetPointDimensions(viskores::Id3 dims)

Sets the number of points in each dimension.

The dimensions must be greater than 1 in each direction to generate cells.

inline viskores::Id3 GetCellDimensions() const

Gets the number of cells in each dimension.

This value is computed from the point dimensions by subtracting 1 in each direction.

inline void SetCellDimensions(viskores::Id3 dims)

Sets the number of cells in each dimension.

The point dimensions are set to one more than the given cell dimensions in each direction.

inline viskores::Vec3f GetOrigin() const

Gets the origin of the generated coordinate system.

inline void SetOrigin(const viskores::Vec3f &origin)

Sets the origin of the generated coordinate system.

inline viskores::IdComponent GetSeed() const

Gets the seed used for the pseudorandom generation of the noise.

If the seed is not set, then a new seed is picked each time Execute is run.

inline void SetSeed(viskores::IdComponent seed)

Sets the seed used for pseudorandom noise generation.

Setting a seed makes repeated calls to Execute produce the same scalar field for the same source parameters. If the seed is not set, then a new seed is picked each time Execute is run.

Example 2.26 Creating a deterministic Perlin noise data set.
1  viskores::source::PerlinNoise noise;
2  noise.SetCellDimensions({ 64, 64, 64 });
3  noise.SetOrigin({ 0.0f, 0.0f, 0.0f });
4  noise.SetSeed(12345);
5
6  viskores::cont::DataSet dataSet = noise.Execute();

2.6.1.3. Oscillator

The viskores::source::Oscillator source creates a time-varying uniform structured data set. It adds a scalar point field named oscillating. The field is formed from one or more Gaussian oscillator terms. The oscillators are configured by adding periodic, damped, or decaying oscillators and by setting the current time.

Each oscillator is specified by a center point, radius, angular frequency, and damping factor. The generated coordinate system spans the unit cube. The range of the oscillating field depends on the oscillators that have been added and the selected time. With a small number of moderate oscillators, values often fall near -1 to 1. For contouring, inspect the generated field range and start with values around 0, or with several values symmetrically distributed around 0 such as -0.5, 0, and 0.5.

class Oscillator : public viskores::source::Source

An analytical, time-varying uniform dataset with a point based array.

The Execute method creates a complete structured dataset that have a point field names ‘oscillating’

This array is based on the coordinates and evaluates to a sum of time-varying Gaussian exponentials specified in its configuration.

Public Functions

Oscillator()

Constructs an oscillator source with default parameters.

The default point dimensions are 3 by 3 by 3. Oscillators can be added with AddPeriodic, AddDamped, and AddDecaying.

void SetPointDimensions(viskores::Id3 pointDimensions)

Sets the number of points in each dimension.

The dimensions must be greater than 1 in each direction to generate cells.

viskores::Id3 GetPointDimensions() const

Gets the number of points in each dimension.

void SetCellDimensions(viskores::Id3 pointDimensions)

Sets the number of cells in each dimension.

The point dimensions are set to one more than the given cell dimensions in each direction.

viskores::Id3 GetCellDimensions() const

Gets the number of cells in each dimension.

This value is computed from the point dimensions by subtracting 1 in each direction.

void SetTime(viskores::FloatDefault time)

Sets the time used to evaluate the oscillator field.

void AddPeriodic(viskores::FloatDefault x, viskores::FloatDefault y, viskores::FloatDefault z, viskores::FloatDefault radius, viskores::FloatDefault omega, viskores::FloatDefault zeta)

Adds a periodic oscillator contribution.

The first three parameters specify the oscillator center. The radius controls the Gaussian spatial falloff. The omega and zeta parameters control the oscillator’s temporal behavior.

void AddDamped(viskores::FloatDefault x, viskores::FloatDefault y, viskores::FloatDefault z, viskores::FloatDefault radius, viskores::FloatDefault omega, viskores::FloatDefault zeta)

Adds a damped oscillator contribution.

The first three parameters specify the oscillator center. The radius controls the Gaussian spatial falloff. The omega and zeta parameters control the oscillator’s temporal behavior.

void AddDecaying(viskores::FloatDefault x, viskores::FloatDefault y, viskores::FloatDefault z, viskores::FloatDefault radius, viskores::FloatDefault omega, viskores::FloatDefault zeta)

Adds a decaying oscillator contribution.

The first three parameters specify the oscillator center. The radius controls the Gaussian spatial falloff. The omega and zeta parameters control the oscillator’s temporal behavior.

Example 2.27 Creating a time-varying oscillator data set.
1  viskores::source::Oscillator oscillator;
2  oscillator.SetPointDimensions({ 65, 65, 65 });
3  oscillator.SetTime(0.25f);
4  oscillator.AddPeriodic(0.50f, 0.50f, 0.50f, 0.25f, 0.10f, 0.20f);
5  oscillator.AddDamped(0.25f, 0.25f, 0.25f, 0.30f, 0.15f, 0.10f);
6
7  viskores::cont::DataSet dataSet = oscillator.Execute();

2.6.1.4. Wavelet Source

The viskores::source::Wavelet source creates a structured data set similar to VTK’s vtkRTAnalyticSource. It adds a scalar point field named RTData. This source is useful for examples that need a smooth scalar field with nontrivial variation throughout the domain.

The geometry of the generated data set is controlled by the logical point extent, spacing, and origin. The source creates points for every logical index between the minimum and maximum extent values, inclusive. If the z extent has zero length, the generated data set uses a 2D structured cell set; otherwise it uses a 3D structured cell set.

The scalar field is controlled by parameters such as center, standard deviation, maximum value, frequency, and magnitude. By default the extent is {-10, -10, -10} to {10, 10, 10}, spacing is {1, 1, 1}, and the field center is at {0, 0, 0}. With the default parameters, the RTData field is typically between about 40 and 280. Useful contour values generally include 100, 150, 200, and 250.

class Wavelet : public viskores::source::Source

The Wavelet source creates a dataset similar to VTK’s vtkRTAnalyticSource.

This class generates a predictable structured dataset with a smooth yet interesting set of scalars, which is useful for testing and benchmarking.

The Execute method creates a complete structured dataset that has a point field named RTData

The RTData scalars are computed as:

MaxVal * Gauss + MagX * sin(FrqX*x) + MagY * sin(FrqY*y) + MagZ * cos(FrqZ*z)

The dataset properties are determined by:

  • Minimum/MaximumExtent: The logical point extents of the dataset.

  • Spacing: The distance between points of the dataset.

  • Center: The center of the dataset.

The scalar functions is control via:

  • Center: The center of a Gaussian contribution to the scalars.

  • StandardDeviation: The unscaled width of a Gaussian contribution.

  • MaximumValue: Upper limit of the scalar range.

  • Frequency: The Frq[XYZ] parameters of the periodic contributions.

  • Magnitude: The Mag[XYZ] parameters of the periodic contributions.

By default, the following parameters are used:

  • Extents: { -10, -10, -10 } --> { 10, 10, 10 }

  • Spacing: { 1, 1, 1 }

  • Center: { 0, 0, 0 }

  • StandardDeviation: 0.5

  • MaximumValue: 255

  • Frequency: { 60, 30, 40 }

  • Magnitude: { 10, 18, 5 }

    If the extent has zero length in the z-direction, a 2D dataset is generated.

Public Functions

Wavelet() = default

Constructs a wavelet source with default parameters.

The default extent is -10 to 10 in each dimension, the spacing is 1 by 1 by 1, and the generated point field is named RTData.

inline void SetCenter(const viskores::Vec3f &center)

Specifies the center of the wavelet function.

Note that the center of the function can be anywhere in space including outside the domain of the data created (as specified by the origin, spacing and extent).

inline viskores::Vec3f GetCenter() const

Specifies the center of the wavelet function.

Note that the center of the function can be anywhere in space including outside the domain of the data created (as specified by the origin, spacing and extent).

inline void SetOrigin(const viskores::Vec3f &origin)

Specifies the origin (lower left corner) of the dataset created.

If the origin is not specified, it will be placed such that extent index (0, 0, 0) is at the coordinate system origin.

inline viskores::Vec3f GetOrigin() const

Specifies the origin (lower left corner) of the dataset created.

If the origin is not specified, it will be placed such that extent index (0, 0, 0) is at the coordinate system origin.

inline void SetSpacing(const viskores::Vec3f &spacing)

Specifies the distance between adjacent points in each dimension.

inline viskores::Vec3f GetSpacing() const

Specifies the distance between adjacent points in each dimension.

inline void SetFrequency(const viskores::Vec3f &frequency)

Specifies the frequency of the periodic scalar contributions.

The components correspond to the x, y, and z periodic terms.

inline viskores::Vec3f GetFrequency() const

Specifies the frequency of the periodic scalar contributions.

The components correspond to the x, y, and z periodic terms.

inline void SetMagnitude(const viskores::Vec3f &magnitude)

Specifies the magnitude of the periodic scalar contributions.

The components correspond to the x, y, and z periodic terms.

inline viskores::Vec3f GetMagnitude() const

Specifies the magnitude of the periodic scalar contributions.

The components correspond to the x, y, and z periodic terms.

inline void SetMinimumExtent(const viskores::Id3 &minExtent)

Specifies the minimum logical point extent.

The minimum and maximum extents are inclusive. Use SetExtent to set both bounds at the same time.

inline viskores::Id3 GetMinimumExtent() const

Specifies the minimum logical point extent.

The minimum and maximum extents are inclusive. Use SetExtent to set both bounds at the same time.

inline void SetMaximumExtent(const viskores::Id3 &maxExtent)

Specifies the maximum logical point extent.

The minimum and maximum extents are inclusive. Use SetExtent to set both bounds at the same time.

inline viskores::Id3 GetMaximumExtent() const

Specifies the maximum logical point extent.

The minimum and maximum extents are inclusive. Use SetExtent to set both bounds at the same time.

inline void SetExtent(const viskores::Id3 &minExtent, const viskores::Id3 &maxExtent)

Sets the inclusive minimum and maximum logical point extents.

If the z extent has zero length, Execute generates a 2D structured data set. Otherwise, it generates a 3D structured data set.

inline void SetMaximumValue(const viskores::FloatDefault &maxVal)

Specifies the maximum value of the Gaussian scalar contribution.

inline viskores::FloatDefault GetMaximumValue() const

Specifies the maximum value of the Gaussian scalar contribution.

inline void SetStandardDeviation(const viskores::FloatDefault &stdev)

Specifies the width of the Gaussian scalar contribution.

Larger values produce a wider Gaussian contribution.

inline viskores::FloatDefault GetStandardDeviation() const

Specifies the width of the Gaussian scalar contribution.

Larger values produce a wider Gaussian contribution.

Example 2.28 Creating a 3D wavelet data set.
1  viskores::source::Wavelet wavelet;
2  wavelet.SetExtent({ -32, -32, -32 }, { 32, 32, 32 });
3  wavelet.SetSpacing({ 0.5f, 0.5f, 0.5f });
4  wavelet.SetCenter({ 0.0f, 0.0f, 0.0f });
5
6  viskores::cont::DataSet dataSet = wavelet.Execute();
Example 2.29 Creating a 2D wavelet data set by using a zero-length z extent.
1  viskores::source::Wavelet wavelet2D;
2  wavelet2D.SetExtent({ -32, -32, 0 }, { 32, 32, 0 });
3
4  viskores::cont::DataSet imageData = wavelet2D.Execute();

2.6.2. AMR Source

The viskores::source::Amr source creates a viskores::cont::PartitionedDataSet that represents a simple adaptive mesh refinement hierarchy. Unlike the other source classes in this chapter, Amr does not derive from viskores::source::Source because its Execute method returns a partitioned data set rather than a single data set.

Each partition is generated from a wavelet source and contains a point field named RTData and a cell field named RTDataCells. The source also runs viskores::filter::multi_block::AmrArrays to add helper arrays used by AMR-aware filters.

The source can generate either 2D or 3D AMR data. The number of cells per dimension must be even and greater than 1. The number of levels controls how many refinement levels are generated; level l contains 2^l partitions. Because the AMR source uses wavelet data for each partition, the point field RTData and cell field RTDataCells usually have values in roughly the same range as the wavelet source, about 40 to 285 for common parameters. Contours at 100, 150, 200, and 250 are good starting values for exploring the generated hierarchy.

class Amr

The Amr source creates a dataset similar to VTK’s vtkRTAnalyticSource.

This class generates a predictable structured dataset with a smooth yet interesting set of scalars, which is useful for testing and benchmarking.

The Execute method creates a complete structured dataset that have a point field names ‘scalars’

The scalars are computed as:

MaxVal * Gauss + MagX * sin(FrqX*x) + MagY * sin(FrqY*y) + MagZ * cos(FrqZ*z)

The dataset properties are determined by:

  • Minimum/MaximumExtent: The logical point extents of the dataset.

  • Spacing: The distance between points of the dataset.

  • Center: The center of the dataset.

The scalar functions is control via:

  • Center: The center of a Gaussian contribution to the scalars.

  • StandardDeviation: The unscaled width of a Gaussian contribution.

  • MaximumValue: Upper limit of the scalar range.

  • Frequency: The Frq[XYZ] parameters of the periodic contributions.

  • Magnitude: The Mag[XYZ] parameters of the periodic contributions.

By default, the following parameters are used:

  • Extents: { -10, -10, -10 } --> { 10, 10, 10 }

  • Spacing: { 1, 1, 1 }

  • Center: { 0, 0, 0 }

  • StandardDeviation: 0.5

  • MaximumValue: 255

  • Frequency: { 60, 30, 40 }

  • Magnitude: { 10, 18, 5 }

Public Functions

Amr() = default

Constructs an AMR source with default parameters.

The default source generates 2D AMR data with 6 cells per dimension and 4 refinement levels.

inline void SetDimension(viskores::IdComponent dimension)

Sets whether generated partitions are 2D or 3D.

Supported values are 2 and 3.

inline viskores::IdComponent GetDimension() const

Gets the dimension of the generated partitions.

inline void SetCellsPerDimension(viskores::IdComponent cellsPerDimension)

Sets the number of cells along each dimension of a partition.

The value must be even and greater than 1.

inline viskores::IdComponent GetCellsPerDimension() const

Gets the number of cells along each dimension of a partition.

inline void SetNumberOfLevels(viskores::IdComponent numberOfLevels)

Sets the number of AMR refinement levels to generate.

Level l contains 2 to the l partitions.

inline viskores::IdComponent GetNumberOfLevels() const

Gets the number of AMR refinement levels to generate.

viskores::cont::PartitionedDataSet Execute() const

Generates the AMR partitioned data set.

Each partition contains the point field RTData and the cell field RTDataCells. Additional AMR helper arrays are added to the result.

Example 2.30 Creating an AMR partitioned data set.
1  viskores::source::Amr amr;
2  amr.SetDimension(3);
3  amr.SetCellsPerDimension(8);
4  amr.SetNumberOfLevels(3);
5
6  viskores::cont::PartitionedDataSet dataSet = amr.Execute();