2.8. Rendering

Rendering, the generation of images from data, is a key component to visualization. To assist with rendering, VTK‑m provides a rendering package to produce imagery from data, which is located in the vtkm::rendering namespace.

The rendering package in VTK‑m is not intended to be a fully featured rendering system or library. Rather, it is a lightweight rendering package with two primary use cases:

• New users getting started with VTK‑m need a “quick and dirty” render method to see their visualization results.

• In situ visualization that integrates VTK‑m with a simulation or other data-generation system might need a lightweight rendering method.

Both of these use cases require just a basic rendering platform. Because VTK‑m is designed to be integrated into larger systems, it does not aspire to have a fully featured rendering system.

Did You Know?

VTK‑m’s big sister toolkit VTK is already integrated with VTK‑m and has its own fully featured rendering system. If you need more rendering capabilities than what VTK‑m provides, you can leverage VTK instead.

2.8.1. Scenes and Actors

The primary intent of the rendering package in VTK‑m is to visually display the data that is loaded and processed. Data are represented in VTK‑m by vtkm::cont::DataSet objects, which are described in Chapter 2.4 (Data Sets). They are also the object created from Chapter 2.5 (File I/O) and Chapter 2.6 (Running Filters).

To render a vtkm::cont::DataSet, the data are wrapped in a vtkm::rendering::Actor class. The vtkm::rendering::Actor holds the components of the vtkm::cont::DataSet to render (a cell set, a coordinate system, and a field). A color table can also be optionally be specified, but a default color table will be specified otherwise.

Example 2.38 Creating an vtkm::rendering::Actor and adding it to a vtkm::rendering::Scene.

  vtkm::rendering::Actor actor(surfaceData.GetCellSet(),
                               surfaceData.GetCoordinateSystem(),
                               surfaceData.GetField("RandomPointScalars"));

  vtkm::rendering::Scene scene;
  scene.AddActor(actor);

class Actor

An item to be rendered.

The Actor holds the geometry from a vtkm::cont::DataSet as well as other visual properties that define how the geometry should look when it is rendered.

Public Functions

Actor(const vtkm::cont::UnknownCellSet &cells, const vtkm::cont::CoordinateSystem &coordinates, const vtkm::cont::Field &scalarField)

Create an Actor object that renders a set of cells positioned by a given coordiante system.

A field to apply psudocoloring is also provided. The default colormap is applied. The cells, coordinates, and field are typically pulled from a vtkm::cont::DataSet object.

Actor(const vtkm::cont::UnknownCellSet &cells, const vtkm::cont::CoordinateSystem &coordinates, const vtkm::cont::Field &scalarField, const vtkm::cont::ColorTable &colorTable)

Create an Actor object that renders a set of cells positioned by a given coordiante system.

A field to apply psudocoloring is also provided. A color table providing the map from scalar values to colors is also provided. The cells, coordinates, and field are typically pulled from a vtkm::cont::DataSet object.

Actor(const vtkm::cont::UnknownCellSet &cells, const vtkm::cont::CoordinateSystem &coordinates, const vtkm::cont::Field &scalarField, const vtkm::rendering::Color &color)

Create an Actor object that renders a set of cells positioned by a given coordiante system.

A constant color to apply to the object is also provided. The cells and coordinates are typically pulled from a vtkm::cont::DataSet object.

void SetScalarRange(const vtkm::Range &scalarRange)

Specifies the range for psudocoloring.

When coloring data by mapping a scalar field to colors, this is the range used for the colors provided by the table. If a range is not provided, the range of data in the field is used.

vtkm::rendering::Actor objects are collected together in an object called vtkm::rendering::Scene.

An vtkm::rendering::Actor is added to a vtkm::rendering::Scene with the vtkm::rendering::Scene::AddActor() method.

class Scene

A simple collection of things to render.

The Scene is a simple collection of Actor objects.

Public Functions

void AddActor(vtkm::rendering::Actor actor)

Add an Actor to the scene.

const vtkm::rendering::Actor &GetActor(vtkm::IdComponent index) const

Get one of the Actors from the scene.

vtkm::IdComponent GetNumberOfActors() const

Get the number of Actors in the scene.

vtkm::Bounds GetSpatialBounds() const

The computed spatial bounds of combined data from all contained Actors.

The following example demonstrates creating a vtkm::rendering::Scene with one vtkm::rendering::Actor.

2.8.2. Canvas

A canvas is a unit that represents the image space that is the target of the rendering. The canvas’ primary function is to manage the buffers that hold the working image data during the rendering. The canvas also manages the context and state of the rendering subsystem.

vtkm::rendering::Canvas is the base class of all canvas objects. Each type of rendering system has its own canvas subclass, but currently the only rendering system provided by VTK‑m is the internal ray tracer. The canvas for the ray tracer is vtkm::rendering::CanvasRayTracer. vtkm::rendering::CanvasRayTracer is typically constructed by giving the width and height of the image to render.

Example 2.39 Creating a canvas for rendering.

  vtkm::rendering::CanvasRayTracer canvas(1920, 1080);

class CanvasRayTracer : public vtkm::rendering::Canvas

Represents the image space that is the target of rendering using the internal ray tracing code.

Public Functions

CanvasRayTracer(vtkm::Id width = 1024, vtkm::Id height = 1024)

Construct a canvas of a given width and height.

virtual vtkm::rendering::Canvas *NewCopy() const override

Create a new Canvas object of the same subtype as this one.

class Canvas

Represents the image space that is the target of rendering.

Subclassed by vtkm::rendering::CanvasRayTracer

Public Functions

Canvas(vtkm::Id width = 1024, vtkm::Id height = 1024)

Construct a canvas of a given width and height.

virtual vtkm::rendering::Canvas *NewCopy() const

Create a new Canvas object of the same subtype as this one.

virtual void Clear()

Clear out the image buffers.

virtual void BlendBackground()

Blend the foreground data with the background color.

When a render is started, it is given a zeroed background rather than the background color specified by SetBackgroundColor(). This is because when blending pixel fragments of transparent objects the background color can interfere. Call this method after the render is completed for the final blend to get the proper background color.

vtkm::Id GetWidth() const

The width of the image.

vtkm::Id GetHeight() const

The height of the image.

const ColorBufferType &GetColorBuffer() const

Get the color channels of the image.

ColorBufferType &GetColorBuffer()

Get the color channels of the image.

const DepthBufferType &GetDepthBuffer() const

Get the depth channel of the image.

DepthBufferType &GetDepthBuffer()

Get the depth channel of the image.

vtkm::cont::DataSet GetDataSet(const std::string &colorFieldName = "color", const std::string &depthFieldName = "depth") const

Gets the image in this Canvas as a vtkm::cont::DataSet.

The returned DataSet will be a uniform structured 2D grid. The color and depth buffers will be attached as field with the given names. If the name for the color or depth field is empty, then that respective field will not be added.

The arrays of the color and depth buffer are shallow copied. Thus, changes in the Canvas may cause unexpected behavior in the DataSet.

vtkm::cont::DataSet GetDataSet(const char *colorFieldName, const char *depthFieldName = "depth") const

Gets the image in this Canvas as a vtkm::cont::DataSet.

The returned DataSet will be a uniform structured 2D grid. The color and depth buffers will be attached as field with the given names. If the name for the color or depth field is empty, then that respective field will not be added.

The arrays of the color and depth buffer are shallow copied. Thus, changes in the Canvas may cause unexpected behavior in the DataSet.

void ResizeBuffers(vtkm::Id width, vtkm::Id height)

Change the size of the image.

const vtkm::rendering::Color &GetBackgroundColor() const

Specify the background color.

void SetBackgroundColor(const vtkm::rendering::Color &color)

Specify the background color.

const vtkm::rendering::Color &GetForegroundColor() const

Specify the foreground color used for annotations.

void SetForegroundColor(const vtkm::rendering::Color &color)

Specify the foreground color used for annotations.

virtual void SaveAs(const std::string &fileName) const

Save the rendered image.

If the filename ends with “.png”, it will be saved in the portable network graphic format. Otherwise, the file will be saved in Netbpm portable pixmap format.

virtual vtkm::rendering::WorldAnnotator *CreateWorldAnnotator() const

Creates a WorldAnnotator of a type that is paired with this Canvas.

Other types of world annotators might work, but this provides a default.

The WorldAnnotator is created with the C++ new keyword (so it should be deleted with delete later). A pointer to the created WorldAnnotator is returned.

2.8.3. Mappers

A mapper is a unit that converts data (managed by an vtkm::rendering::Actor) and issues commands to the rendering subsystem to generate images. All mappers in VTK‑m are a subclass of vtkm::rendering::Mapper. Different mappers could render different types of data in different ways. For example, one mapper might render polygonal surfaces whereas another might render polyhedra as a translucent volume.

class Mapper

Converts data into commands to a rendering system.

This is the base class for all mapper classes in VTK-m. Different concrete derived classes can provide different representations and rendering techniques.

Subclassed by vtkm::rendering::MapperConnectivity, vtkm::rendering::MapperCylinder, vtkm::rendering::MapperGlyphBase, vtkm::rendering::MapperPoint, vtkm::rendering::MapperQuad, vtkm::rendering::MapperRayTracer, vtkm::rendering::MapperVolume, vtkm::rendering::MapperWireframer

The following mappers are provided by VTK‑m.

class MapperCylinder : public vtkm::rendering::Mapper

MapperCylinder renderers edges from a cell set and renders them as cylinders via ray tracing.

Public Functions

void UseVariableRadius(bool useVariableRadius)

render points using a variable radius based on the scalar field.

The default is false.

void SetRadius(const vtkm::Float32 &radius)

Set a base radius for all points.

If a radius is never specified the default heuristic is used.

void SetRadiusDelta(const vtkm::Float32 &delta)

When using a variable radius for all cylinder, the radius delta controls how much larger and smaller radii become based on the scalar field.

If the delta is 0 all points will have the same radius. If the delta is 0.5 then the max/min scalar values would have a radii of base +/- base * 0.5.

class MapperGlyphBase : public vtkm::rendering::Mapper

Base class for glyph mappers.

Glyph mappers place 3D icons at various places in the mesh. The icons are placed based on the location of points or cells in the mesh.

Subclassed by vtkm::rendering::MapperGlyphScalar, vtkm::rendering::MapperGlyphVector

Public Functions

virtual vtkm::cont::Field::Association GetAssociation() const

Specify the elements the glyphs will be associated with.

The glyph mapper will place glyphs over locations specified by either the points or the cells of a mesh. The glyph may also be oriented by a scalar field with the same association.

virtual void SetAssociation(vtkm::cont::Field::Association association)

Specify the elements the glyphs will be associated with.

The glyph mapper will place glyphs over locations specified by either the points or the cells of a mesh. The glyph may also be oriented by a scalar field with the same association.

virtual bool GetUseCells() const

Specify the elements the glyphs will be associated with.

The glyph mapper will place glyphs over locations specified by either the points or the cells of a mesh. The glyph may also be oriented by a scalar field with the same association.

virtual void SetUseCells()

Specify the elements the glyphs will be associated with.

The glyph mapper will place glyphs over locations specified by either the points or the cells of a mesh. The glyph may also be oriented by a scalar field with the same association.

virtual bool GetUsePoints() const

Specify the elements the glyphs will be associated with.

The glyph mapper will place glyphs over locations specified by either the points or the cells of a mesh. The glyph may also be oriented by a scalar field with the same association.

virtual void SetUsePoints()

Specify the elements the glyphs will be associated with.

The glyph mapper will place glyphs over locations specified by either the points or the cells of a mesh. The glyph may also be oriented by a scalar field with the same association.

virtual vtkm::Float32 GetBaseSize() const

Specify the size of each glyph (before scaling).

If the base size is not set to a positive value, it is automatically sized with a heuristic based off the bounds of the geometry.

virtual void SetBaseSize(vtkm::Float32 size)

Specify the size of each glyph (before scaling).

If the base size is not set to a positive value, it is automatically sized with a heuristic based off the bounds of the geometry.

virtual bool GetScaleByValue() const

Specify whether to scale the glyphs by a field.

virtual void SetScaleByValue(bool on)

Specify whether to scale the glyphs by a field.

virtual vtkm::Float32 GetScaleDelta() const

Specify the range of values to scale the glyphs.

When ScaleByValue is on, the glyphs will be scaled proportionally to the field magnitude. The ScaleDelta determines how big and small they get. For a ScaleDelta of one, the smallest field values will have glyphs of zero size and the maximum field values will be twice the base size. A ScaleDelta of 0.5 will result in glyphs sized in the range of 0.5 times the base size to 1.5 times the base size. ScaleDelta outside the range [0, 1] is undefined.

virtual void SetScaleDelta(vtkm::Float32 delta)

Specify the range of values to scale the glyphs.

When ScaleByValue is on, the glyphs will be scaled proportionally to the field magnitude. The ScaleDelta determines how big and small they get. For a ScaleDelta of one, the smallest field values will have glyphs of zero size and the maximum field values will be twice the base size. A ScaleDelta of 0.5 will result in glyphs sized in the range of 0.5 times the base size to 1.5 times the base size. ScaleDelta outside the range [0, 1] is undefined.

class MapperGlyphScalar : public vtkm::rendering::MapperGlyphBase

A mapper that produces unoriented glyphs.

This mapper is meant to be used with scalar fields. The glyphs can be optionally sized based on the field.

Public Functions

vtkm::rendering::GlyphType GetGlyphType() const

Specify the shape of the glyphs.

void SetGlyphType(vtkm::rendering::GlyphType glyphType)

Specify the shape of the glyphs.

class MapperGlyphVector : public vtkm::rendering::MapperGlyphBase

A mapper that produces oriented glyphs.

This mapper is meant to be used with 3D vector fields. The glyphs are oriented in the direction of the vector field. The glyphs can be optionally sized based on the magnitude of the field.

Public Functions

vtkm::rendering::GlyphType GetGlyphType() const

Specify the shape of the glyphs.

void SetGlyphType(vtkm::rendering::GlyphType glyphType)

Specify the shape of the glyphs.

class MapperPoint : public vtkm::rendering::Mapper

This mapper renders points from a cell set.

This mapper can natively create points from vertex cell shapes as well as use the points defined by a coordinate system.

Public Functions

virtual vtkm::cont::Field::Association GetAssociation() const

Specify the elements the points will be associated with.

The point mapper will place visible points over locations specified by either the points or the cells of a mesh.

virtual void SetAssociation(vtkm::cont::Field::Association association)

Specify the elements the points will be associated with.

The point mapper will place visible points over locations specified by either the points or the cells of a mesh.

virtual bool GetUseCells() const

Specify the elements the points will be associated with.

The point mapper will place visible points over locations specified by either the points or the cells of a mesh.

virtual void SetUseCells()

Specify the elements the points will be associated with.

The point mapper will place visible points over locations specified by either the points or the cells of a mesh.

virtual bool GetUsePoints() const

Specify the elements the points will be associated with.

The point mapper will place visible points over locations specified by either the points or the cells of a mesh.

virtual void SetUsePoints()

Specify the elements the points will be associated with.

The point mapper will place visible points over locations specified by either the points or the cells of a mesh.

void UseVariableRadius(bool useVariableRadius)

Render points using a variable radius based on the scalar field.

The default is false.

void SetRadius(const vtkm::Float32 &radius)

Set a base raidus for all points.

If a radius is never specified the default heuristic is used.

void SetRadiusDelta(const vtkm::Float32 &delta)

When using a variable raidus for all points, the radius delta controls how much larger and smaller radii become based on the scalar field.

If the delta is 0 all points will have the same radius. If the delta is 0.5 then the max/min scalar values would have a radii of base +/- base * 0.5.

class MapperQuad : public vtkm::rendering::Mapper

A mapper that renderers quad faces from a cell set via ray tracing.

   As opposed to breaking quads into two trianges, scalars are
   interpolated using all 4 points of the quad resulting in more
   accurate interpolation.

class MapperRayTracer : public vtkm::rendering::Mapper

Mapper to render surfaces using ray tracing.

Provides a “standard” data mapper that uses ray tracing to render the surfaces of DataSet objects.

class MapperVolume : public vtkm::rendering::Mapper

Mapper that renders a volume as a translucent cloud.

Public Functions

void SetSampleDistance(const vtkm::Float32 distance)

Specify how much space is between samples of rays that traverse the volume.

The volume rendering ray caster finds the entry point of the ray through the volume and then samples the volume along the direction of the ray at regular intervals. This parameter specifies how far these samples occur.

class MapperWireframer : public vtkm::rendering::Mapper

Mapper that renders the edges of a mesh.

Each edge in the mesh is rendered as a line, which provides a wireframe representation of the data.

Public Functions

bool GetShowInternalZones() const

Specify whether to show interior edges.

When rendering a 3D volume of data, the MapperWireframer can show either the wireframe of the external surface of the data (the default) or render the entire wireframe including the internal edges.

void SetShowInternalZones(bool showInternalZones)

Specify whether to show interior edges.

When rendering a 3D volume of data, the MapperWireframer can show either the wireframe of the external surface of the data (the default) or render the entire wireframe including the internal edges.

2.8.4. Views

A view is a unit that collects all the structures needed to perform rendering. It contains everything needed to take a vtkm::rendering::Scene and use a vtkm::rendering::Mapper to render it onto a vtkm::rendering::Canvas. The view also annotates the image with spatial and scalar properties.

The base class for all views is vtkm::rendering::View, which is an abstract class. You must choose one of the three provided subclasses, vtkm::rendering::View3D, vtkm::rendering::View2D, and vtkm::rendering::View3D, depending on the type of data being presented. All three view classes take a vtkm::rendering::Scene, a vtkm::rendering::Mapper, and a vtkm::rendering::Canvas as arguments to their constructor.

Example 2.40 Constructing a vtkm::rendering::View.

  vtkm::rendering::Actor actor(surfaceData.GetCellSet(),
                               surfaceData.GetCoordinateSystem(),
                               surfaceData.GetField("RandomPointScalars"));

  vtkm::rendering::Scene scene;
  scene.AddActor(actor);

  vtkm::rendering::MapperRayTracer mapper;
  vtkm::rendering::CanvasRayTracer canvas(1920, 1080);

  vtkm::rendering::View3D view(scene, mapper, canvas);

class View

The abstract class representing the view of a rendering scene.

Subclassed by vtkm::rendering::View1D, vtkm::rendering::View2D, vtkm::rendering::View3D

Public Functions

const vtkm::rendering::Scene &GetScene() const

Specify the scene object holding the objects to render.

vtkm::rendering::Scene &GetScene()

Specify the scene object holding the objects to render.

void SetScene(const vtkm::rendering::Scene &scene)

Specify the scene object holding the objects to render.

const vtkm::rendering::Mapper &GetMapper() const

Specify the mapper object determining how objects are rendered.

vtkm::rendering::Mapper &GetMapper()

Specify the mapper object determining how objects are rendered.

const vtkm::rendering::Canvas &GetCanvas() const

Specify the canvas object that holds the buffer to render into.

vtkm::rendering::Canvas &GetCanvas()

Specify the canvas object that holds the buffer to render into.

const vtkm::rendering::Camera &GetCamera() const

Specify the perspective from which to render a scene.

vtkm::rendering::Camera &GetCamera()

Specify the perspective from which to render a scene.

void SetCamera(const vtkm::rendering::Camera &camera)

Specify the perspective from which to render a scene.

const vtkm::rendering::Color &GetBackgroundColor() const

Specify the color used where nothing is rendered.

void SetBackgroundColor(const vtkm::rendering::Color &color)

Specify the color used where nothing is rendered.

void SetForegroundColor(const vtkm::rendering::Color &color)

Specify the color of foreground elements.

The foreground is typically used for annotation elements. The foreground should contrast well with the background.

virtual void Paint() = 0

Render a scene and store the result in the canvas’ buffers.

void SaveAs(const std::string &fileName) const

Save the rendered image.

If the filename ends with “.png”, it will be saved in the portable network graphic format. Otherwise, the file will be saved in Netbpm portable pixmap format.

class View1D : public vtkm::rendering::View

A view for a 1D data set.

1D data are rendered as an X-Y plot with the values shone on the Y axis.

Public Functions

virtual void Paint() override

Render a scene and store the result in the canvas’ buffers.

inline void SetLogX(bool l)

Specify whether log scaling should be used on the X axis.

inline void SetLogY(bool l)

Specify whether log scaling should be used on the Y axis.

class View2D : public vtkm::rendering::View

A view for a 3D data set.

2D data are rendered directly on the X-Y plane.

Public Functions

virtual void Paint() override

Render a scene and store the result in the canvas’ buffers.

class View3D : public vtkm::rendering::View

A view for a 3D data set.

Public Functions

virtual void Paint() override

Render a scene and store the result in the canvas’ buffers.

The vtkm::rendering::View also maintains a background color (the color used in areas where nothing is drawn) and a foreground color (the color used for annotation elements). By default, the vtkm::rendering::View has a black background and a white foreground. These can be set in the view’s constructor, but it is a bit more readable to set them using the vtkm::rendering::View::SetBackground() and vtkm::rendering::View::SetForeground() methods. In either case, the colors are specified using the vtkm::rendering::Color helper class, which manages the red, green, and blue color channels as well as an optional alpha channel. These channel values are given as floating point values between 0 and 1.

Example 2.41 Changing the background and foreground colors of a vtkm::rendering::View.

  view.SetBackgroundColor(vtkm::rendering::Color(1.0f, 1.0f, 1.0f));
  view.SetForegroundColor(vtkm::rendering::Color(0.0f, 0.0f, 0.0f));

Common Errors

Although the background and foreground colors are set independently, it will be difficult or impossible to see the annotation if there is not enough contrast between the background and foreground colors. Thus, when changing a vtkm::rendering::View’s background color, it is always good practice to also change the foreground color.

class Color

Representation of a color.

The color is defined as red, green, and blue intensities as well as an alpha representation of transparency (RGBA). The class provides mechanisms to retrieve the color as 8-bit integers or floating point values in the range [0, 1].

Public Functions

inline Color()

Create a black color.

inline Color(vtkm::Float32 r_, vtkm::Float32 g_, vtkm::Float32 b_, vtkm::Float32 a_ = 1.f)

Create a color with specified RGBA values.

The values are floating point and in the range [0, 1].

inline Color(const vtkm::Vec4f_32 &components)

Create a color with specified RGBA values.

The values are floating point and in the range [0, 1].

inline void SetComponentFromByte(vtkm::Int32 i, vtkm::UInt8 v)

Set the color value from 8 bit RGBA components.

The components are packed together into a 32-bit (4-byte) values.

Once the vtkm::rendering::View is constructed, intialized, and set up, it is ready to render. This is done by calling the vtkm::rendering::View::Paint() method.

Example 2.42 Using vtkm::rendering::Canvas::Paint() in a display callback.

  view.Paint();

Putting together Example 2.40, Example 2.41, and Example 2.42, the final render of a view looks like that in Figure 2.8.

Figure 2.8 Example output of VTK‑m’s rendering system.

Of course, the vtkm::rendering::CanvasRayTracer created in Example 2.40 is an offscreen rendering buffer, so you cannot immediately see the image. When doing batch visualization, an easy way to output the image to a file for later viewing is with the vtkm::rendering::View::SaveAs() method. This method can save the image in either PNG or in the portable pixelmap (PPM) format.

Example 2.43 Saving the result of a render as an image file.

  view.SaveAs("BasicRendering.png");

We visit doing interactive rendering in a GUI later in Section 2.8.7 (Interactive Rendering).

2.8.5. Changing Rendering Modes

Example 2.40 constructs the default mapper for ray tracing, which renders the data as an opaque solid. However, you can change the rendering mode by using one of the other mappers listed in Section 2.8.3 (Mappers). For example, say you just wanted to see a wireframe representation of your data. You can achieve this by using vtkm::rendering::MapperWireframer.

Example 2.44 Creating a mapper for a wireframe representation.

  vtkm::rendering::MapperWireframer mapper;
  vtkm::rendering::View3D view(scene, mapper, canvas);

Alternatively, perhaps you wish to render just the points of mesh. vtkm::rendering::MapperGlyphScalar renders the points as glyphs and also optionally can scale the glyphs based on field values.

Example 2.45 Creating a mapper for point representation.

  vtkm::rendering::MapperGlyphScalar mapper;
  mapper.SetGlyphType(vtkm::rendering::GlyphType::Cube);
  mapper.SetScaleByValue(true);
  mapper.SetScaleDelta(10.0f);

  vtkm::rendering::View3D view(scene, mapper, canvas);

These mappers respectively render the images shown in Figure 2.9. Other mappers, such as those that can render translucent volumes, are also available.

Figure 2.9 Examples of alternate rendering modes using different mappers. The top left image is rendered with vtkm::rendering::MapperWireframer. The top right and bottom left images are rendered with vtkm::rendering::MapperGlyphScalar. The bottom right image is rendered with vtkm::rendering::MapperGlyphVector.

2.8.6. Manipulating the Camera

The vtkm::rendering::View uses an object called vtkm::rendering::Camera to describe the vantage point from which to draw the geometry. The camera can be retrieved from the vtkm::rendering::View::GetCamera() method. That retrieved camera can be directly manipulated or a new camera can be provided by calling vtkm::rendering::View::SetCamera(). In this section we discuss camera setups typical during view set up. Camera movement during interactive rendering is revisited in Section 2.8.7.2 (Camera Movement).

class Camera

Specifies the viewport for a rendering.

The vtkm::rendering::View object holds a Camera object to specify from what perspective the rendering should take place.

A Camera operates in one of two major modes: 2D mode or 3D mode. 2D mode is designed for looking at flat geometry (or close to flat geometry) that is parallel to the x-y plane. 3D mode provides the freedom to place the camera anywhere in 3D space.

Public Functions

inline vtkm::rendering::Camera::Mode GetMode() const

The mode of the camera (2D or 3D).

vtkm::rendering::Camera can be set to a 2D or 3D mode. 2D mode is used for looking at data in the x-y plane. 3D mode allows the camera to be positioned anywhere and pointing at any place in 3D.

inline void SetMode(vtkm::rendering::Camera::Mode mode)

The mode of the camera (2D or 3D).

vtkm::rendering::Camera can be set to a 2D or 3D mode. 2D mode is used for looking at data in the x-y plane. 3D mode allows the camera to be positioned anywhere and pointing at any place in 3D.

inline void SetModeTo3D()

The mode of the camera (2D or 3D).

vtkm::rendering::Camera can be set to a 2D or 3D mode. 2D mode is used for looking at data in the x-y plane. 3D mode allows the camera to be positioned anywhere and pointing at any place in 3D.

inline void SetModeTo2D()

The mode of the camera (2D or 3D).

vtkm::rendering::Camera can be set to a 2D or 3D mode. 2D mode is used for looking at data in the x-y plane. 3D mode allows the camera to be positioned anywhere and pointing at any place in 3D.

inline vtkm::Range GetClippingRange() const

The clipping range of the camera.

The clipping range establishes the near and far clipping planes. These clipping planes are parallel to the viewing plane. The planes are defined by simply specifying the distance from the viewpoint. Renderers can (and usually do) remove any geometry closer than the near plane and further than the far plane.

For precision purposes, it is best to place the near plane as far away as possible (while still being in front of any geometry). The far plane usually has less effect on the depth precision, so can be placed well far behind the geometry.

inline void SetClippingRange(vtkm::Float32 nearPlane, vtkm::Float32 farPlane)

The clipping range of the camera.

The clipping range establishes the near and far clipping planes. These clipping planes are parallel to the viewing plane. The planes are defined by simply specifying the distance from the viewpoint. Renderers can (and usually do) remove any geometry closer than the near plane and further than the far plane.

For precision purposes, it is best to place the near plane as far away as possible (while still being in front of any geometry). The far plane usually has less effect on the depth precision, so can be placed well far behind the geometry.

inline void SetClippingRange(vtkm::Float64 nearPlane, vtkm::Float64 farPlane)

The clipping range of the camera.

The clipping range establishes the near and far clipping planes. These clipping planes are parallel to the viewing plane. The planes are defined by simply specifying the distance from the viewpoint. Renderers can (and usually do) remove any geometry closer than the near plane and further than the far plane.

For precision purposes, it is best to place the near plane as far away as possible (while still being in front of any geometry). The far plane usually has less effect on the depth precision, so can be placed well far behind the geometry.

inline void SetClippingRange(const vtkm::Range &nearFarRange)

The clipping range of the camera.

The clipping range establishes the near and far clipping planes. These clipping planes are parallel to the viewing plane. The planes are defined by simply specifying the distance from the viewpoint. Renderers can (and usually do) remove any geometry closer than the near plane and further than the far plane.

For precision purposes, it is best to place the near plane as far away as possible (while still being in front of any geometry). The far plane usually has less effect on the depth precision, so can be placed well far behind the geometry.

inline void GetViewport(vtkm::Float32 &left, vtkm::Float32 &right, vtkm::Float32 &bottom, vtkm::Float32 &top) const

The viewport of the projection.

The projection of the camera can be offset to be centered around a subset of the rendered image. This is established with a “viewport,” which is defined by the left/right and bottom/top of this viewport. The values of the viewport are relative to the rendered image’s bounds. The left and bottom of the image are at -1 and the right and top are at 1.

inline void GetViewport(vtkm::Float64 &left, vtkm::Float64 &right, vtkm::Float64 &bottom, vtkm::Float64 &top) const

The viewport of the projection.

The projection of the camera can be offset to be centered around a subset of the rendered image. This is established with a “viewport,” which is defined by the left/right and bottom/top of this viewport. The values of the viewport are relative to the rendered image’s bounds. The left and bottom of the image are at -1 and the right and top are at 1.

inline vtkm::Bounds GetViewport() const

The viewport of the projection.

The projection of the camera can be offset to be centered around a subset of the rendered image. This is established with a “viewport,” which is defined by the left/right and bottom/top of this viewport. The values of the viewport are relative to the rendered image’s bounds. The left and bottom of the image are at -1 and the right and top are at 1.

inline void SetViewport(vtkm::Float32 left, vtkm::Float32 right, vtkm::Float32 bottom, vtkm::Float32 top)

The viewport of the projection.

The projection of the camera can be offset to be centered around a subset of the rendered image. This is established with a “viewport,” which is defined by the left/right and bottom/top of this viewport. The values of the viewport are relative to the rendered image’s bounds. The left and bottom of the image are at -1 and the right and top are at 1.

inline void SetViewport(vtkm::Float64 left, vtkm::Float64 right, vtkm::Float64 bottom, vtkm::Float64 top)

The viewport of the projection.

The projection of the camera can be offset to be centered around a subset of the rendered image. This is established with a “viewport,” which is defined by the left/right and bottom/top of this viewport. The values of the viewport are relative to the rendered image’s bounds. The left and bottom of the image are at -1 and the right and top are at 1.

inline void SetViewport(const vtkm::Bounds &viewportBounds)

The viewport of the projection.

The projection of the camera can be offset to be centered around a subset of the rendered image. This is established with a “viewport,” which is defined by the left/right and bottom/top of this viewport. The values of the viewport are relative to the rendered image’s bounds. The left and bottom of the image are at -1 and the right and top are at 1.

inline const vtkm::Vec3f_32 &GetLookAt() const

The focal point the camera is looking at in 3D mode.

When in 3D mode, the camera is set up to be facing the LookAt position. If LookAt is set, the mode is changed to 3D mode.

inline void SetLookAt(const vtkm::Vec3f_32 &lookAt)

The focal point the camera is looking at in 3D mode.

When in 3D mode, the camera is set up to be facing the LookAt position. If LookAt is set, the mode is changed to 3D mode.

inline void SetLookAt(const vtkm::Vec<Float64, 3> &lookAt)

The focal point the camera is looking at in 3D mode.

When in 3D mode, the camera is set up to be facing the LookAt position. If LookAt is set, the mode is changed to 3D mode.

inline const vtkm::Vec3f_32 &GetPosition() const

The spatial position of the camera in 3D mode.

When in 3D mode, the camera is modeled to be at a particular location. If Position is set, the mode is changed to 3D mode.

inline void SetPosition(const vtkm::Vec3f_32 &position)

The spatial position of the camera in 3D mode.

When in 3D mode, the camera is modeled to be at a particular location. If Position is set, the mode is changed to 3D mode.

inline void SetPosition(const vtkm::Vec3f_64 &position)

The spatial position of the camera in 3D mode.

When in 3D mode, the camera is modeled to be at a particular location. If Position is set, the mode is changed to 3D mode.

inline const vtkm::Vec3f_32 &GetViewUp() const

The up orientation of the camera in 3D mode.

When in 3D mode, the camera is modeled to be at a particular location and looking at a particular spot. The view up vector orients the rotation of the image so that the top of the image is in the direction pointed to by view up. If ViewUp is set, the mode is changed to 3D mode.

inline void SetViewUp(const vtkm::Vec3f_32 &viewUp)

The up orientation of the camera in 3D mode.

When in 3D mode, the camera is modeled to be at a particular location and looking at a particular spot. The view up vector orients the rotation of the image so that the top of the image is in the direction pointed to by view up. If ViewUp is set, the mode is changed to 3D mode.

inline void SetViewUp(const vtkm::Vec3f_64 &viewUp)

The up orientation of the camera in 3D mode.

When in 3D mode, the camera is modeled to be at a particular location and looking at a particular spot. The view up vector orients the rotation of the image so that the top of the image is in the direction pointed to by view up. If ViewUp is set, the mode is changed to 3D mode.

inline vtkm::Float32 GetXScale() const

The xscale of the camera.

The xscale forces the 2D curves to be full-frame

Setting the xscale changes the mode to 2D.

inline void SetXScale(vtkm::Float32 xscale)

The xscale of the camera.

The xscale forces the 2D curves to be full-frame

Setting the xscale changes the mode to 2D.

inline void SetXScale(vtkm::Float64 xscale)

The xscale of the camera.

The xscale forces the 2D curves to be full-frame

Setting the xscale changes the mode to 2D.

inline vtkm::Float32 GetFieldOfView() const

The field of view angle.

The field of view defines the angle (in degrees) that are visible from the camera position.

Setting the field of view changes the mode to 3D.

inline void SetFieldOfView(vtkm::Float32 fov)

The field of view angle.

The field of view defines the angle (in degrees) that are visible from the camera position.

Setting the field of view changes the mode to 3D.

inline void SetFieldOfView(vtkm::Float64 fov)

The field of view angle.

The field of view defines the angle (in degrees) that are visible from the camera position.

Setting the field of view changes the mode to 3D.

void Pan(vtkm::Float32 dx, vtkm::Float32 dy)

Pans the camera.

Panning the camera shifts the view horizontially and/or vertically with respect to the image plane.

Panning works in either 2D or 3D mode.

inline void Pan(vtkm::Float64 dx, vtkm::Float64 dy)

Pans the camera.

Panning the camera shifts the view horizontially and/or vertically with respect to the image plane.

Panning works in either 2D or 3D mode.

inline void Pan(vtkm::Vec2f_32 direction)

Pans the camera.

Panning the camera shifts the view horizontially and/or vertically with respect to the image plane.

Panning works in either 2D or 3D mode.

inline void Pan(vtkm::Vec2f_64 direction)

Pans the camera.

Panning the camera shifts the view horizontially and/or vertically with respect to the image plane.

Panning works in either 2D or 3D mode.

inline vtkm::Vec2f_32 GetPan() const

Pans the camera.

Panning the camera shifts the view horizontially and/or vertically with respect to the image plane.

Panning works in either 2D or 3D mode.

void Zoom(vtkm::Float32 zoom)

Zooms the camera in or out.

Zooming the camera scales everything in the image up or down. Positive zoom makes the geometry look bigger or closer. Negative zoom has the opposite effect. A zoom of 0 has no effect.

Zooming works in either 2D or 3D mode.

inline void Zoom(vtkm::Float64 zoom)

Zooms the camera in or out.

Zooming the camera scales everything in the image up or down. Positive zoom makes the geometry look bigger or closer. Negative zoom has the opposite effect. A zoom of 0 has no effect.

Zooming works in either 2D or 3D mode.

inline vtkm::Float32 GetZoom() const

Zooms the camera in or out.

Zooming the camera scales everything in the image up or down. Positive zoom makes the geometry look bigger or closer. Negative zoom has the opposite effect. A zoom of 0 has no effect.

Zooming works in either 2D or 3D mode.

void TrackballRotate(vtkm::Float32 startX, vtkm::Float32 startY, vtkm::Float32 endX, vtkm::Float32 endY)

Moves the camera as if a point was dragged along a sphere.

TrackballRotate() takes the normalized screen coordinates (in the range -1 to 1) and rotates the camera around the LookAt position. The rotation first projects the points to a sphere around the LookAt position. The camera is then rotated as if the start point was dragged to the end point along with the world.

TrackballRotate() changes the mode to 3D.

inline void TrackballRotate(vtkm::Float64 startX, vtkm::Float64 startY, vtkm::Float64 endX, vtkm::Float64 endY)

Moves the camera as if a point was dragged along a sphere.

TrackballRotate() takes the normalized screen coordinates (in the range -1 to 1) and rotates the camera around the LookAt position. The rotation first projects the points to a sphere around the LookAt position. The camera is then rotated as if the start point was dragged to the end point along with the world.

TrackballRotate() changes the mode to 3D.

void ResetToBounds(const vtkm::Bounds &dataBounds)

Set up the camera to look at geometry.

ResetToBounds() takes a vtkm::Bounds structure containing the bounds in 3D space that contain the geometry being rendered. This method sets up the camera so that it is looking at this region in space. The view direction is preserved. ResetToBounds() can also take optional padding that the viewpoint should preserve around the object. Padding is specified as the fraction of the bounds to add as padding.

void ResetToBounds(const vtkm::Bounds &dataBounds, vtkm::Float64 dataViewPadding)

Set up the camera to look at geometry.

ResetToBounds() takes a vtkm::Bounds structure containing the bounds in 3D space that contain the geometry being rendered. This method sets up the camera so that it is looking at this region in space. The view direction is preserved. ResetToBounds() can also take optional padding that the viewpoint should preserve around the object. Padding is specified as the fraction of the bounds to add as padding.

void ResetToBounds(const vtkm::Bounds &dataBounds, vtkm::Float64 XDataViewPadding, vtkm::Float64 YDataViewPadding, vtkm::Float64 ZDataViewPadding)

Set up the camera to look at geometry.

ResetToBounds() takes a vtkm::Bounds structure containing the bounds in 3D space that contain the geometry being rendered. This method sets up the camera so that it is looking at this region in space. The view direction is preserved. ResetToBounds() can also take optional padding that the viewpoint should preserve around the object. Padding is specified as the fraction of the bounds to add as padding.

void Roll(vtkm::Float32 angleDegrees)

Roll the camera.

Rotates the camera around the view direction by the given angle. The angle is given in degrees.

Roll is currently only supported for 3D cameras.

inline void Roll(vtkm::Float64 angleDegrees)

Roll the camera.

Rotates the camera around the view direction by the given angle. The angle is given in degrees.

Roll is currently only supported for 3D cameras.

void Azimuth(vtkm::Float32 angleDegrees)

Rotate the camera about the view up vector centered at the focal point.

Note that the view up vector is whatever was set via SetViewUp(), and is not necessarily perpendicular to the direction of projection. The angle is given in degrees.

Azimuth() only makes sense for 3D cameras, so the camera mode will be set to 3D when this method is called.

inline void Azimuth(vtkm::Float64 angleDegrees)

Rotate the camera about the view up vector centered at the focal point.

Note that the view up vector is whatever was set via SetViewUp(), and is not necessarily perpendicular to the direction of projection. The angle is given in degrees.

Azimuth() only makes sense for 3D cameras, so the camera mode will be set to 3D when this method is called.

void Elevation(vtkm::Float32 angleDegrees)

Rotate the camera vertically around the focal point.

Specifically, this rotates the camera about the cross product of the negative of the direction of projection and the view up vector, using the focal point (LookAt) as the center of rotation. The angle is given in degrees.

Elevation() only makes sense for 3D cameras, so the camera mode will be set to 3D when this method is called.

inline void Elevation(vtkm::Float64 angleDegrees)

Rotate the camera vertically around the focal point.

Specifically, this rotates the camera about the cross product of the negative of the direction of projection and the view up vector, using the focal point (LookAt) as the center of rotation. The angle is given in degrees.

Elevation() only makes sense for 3D cameras, so the camera mode will be set to 3D when this method is called.

void Dolly(vtkm::Float32 value)

Move the camera toward or away from the focal point.

Specifically, this divides the camera’s distance from the focal point (LookAt) by the given value. Use a value greater than one to dolly in toward the focal point, and use a value less than one to dolly-out away from the focal point.

Dolly() has a similar effect as Zoom() since an object will appear larger when the camera is closer. However, because you are moving the camera, Dolly() can change the perspective relative to objects such as moving inside an object for an interior perspective whereas Zoom() will just change the size of the visible objects.

Dolly() only makes sense for 3D cameras, so the camera mode will be set to 3D when this method is called.

inline void Dolly(vtkm::Float64 value)

Move the camera toward or away from the focal point.

Specifically, this divides the camera’s distance from the focal point (LookAt) by the given value. Use a value greater than one to dolly in toward the focal point, and use a value less than one to dolly-out away from the focal point.

Dolly() has a similar effect as Zoom() since an object will appear larger when the camera is closer. However, because you are moving the camera, Dolly() can change the perspective relative to objects such as moving inside an object for an interior perspective whereas Zoom() will just change the size of the visible objects.

Dolly() only makes sense for 3D cameras, so the camera mode will be set to 3D when this method is called.

inline void GetViewRange2D(vtkm::Float32 &left, vtkm::Float32 &right, vtkm::Float32 &bottom, vtkm::Float32 &top) const

The viewable region in the x-y plane.

When the camera is in 2D, it is looking at some region of the x-y plane. The region being looked at is defined by the range in x (determined by the left and right sides) and by the range in y (determined by the bottom and top sides).

SetViewRange2D() changes the camera mode to 2D.

inline vtkm::Bounds GetViewRange2D() const

The viewable region in the x-y plane.

When the camera is in 2D, it is looking at some region of the x-y plane. The region being looked at is defined by the range in x (determined by the left and right sides) and by the range in y (determined by the bottom and top sides).

SetViewRange2D() changes the camera mode to 2D.

inline void SetViewRange2D(vtkm::Float32 left, vtkm::Float32 right, vtkm::Float32 bottom, vtkm::Float32 top)

The viewable region in the x-y plane.

When the camera is in 2D, it is looking at some region of the x-y plane. The region being looked at is defined by the range in x (determined by the left and right sides) and by the range in y (determined by the bottom and top sides).

SetViewRange2D() changes the camera mode to 2D.

inline void SetViewRange2D(vtkm::Float64 left, vtkm::Float64 right, vtkm::Float64 bottom, vtkm::Float64 top)

The viewable region in the x-y plane.

When the camera is in 2D, it is looking at some region of the x-y plane. The region being looked at is defined by the range in x (determined by the left and right sides) and by the range in y (determined by the bottom and top sides).

SetViewRange2D() changes the camera mode to 2D.

inline void SetViewRange2D(const vtkm::Range &xRange, const vtkm::Range &yRange)

The viewable region in the x-y plane.

When the camera is in 2D, it is looking at some region of the x-y plane. The region being looked at is defined by the range in x (determined by the left and right sides) and by the range in y (determined by the bottom and top sides).

SetViewRange2D() changes the camera mode to 2D.

A vtkm::rendering::Camera operates in one of two major modes: 2D mode or 3D mode. 2D mode is designed for looking at flat geometry (or close to flat geometry) that is parallel to the x-y plane. 3D mode provides the freedom to place the camera anywhere in 3D space. The different modes can be set with vtkm::rendering::Camera::SetModeTo2D() and vtkm::rendering::Camera::SetModeTo3D(), respectively. The interaction with the camera in these two modes is very different.

2.8.6.1. Common Camera Controls

Some camera controls operate relative to the rendered image and are common among the 2D and 3D camera modes.

2.8.6.1.1. Pan

A camera pan moves the viewpoint left, right, up, or down. A camera pan is performed by calling the vtkm::cont::Camera::Pan() method. vtkm::cont::Camera::Pan() takes two arguments: the amount to pan in x and the amount to pan in y.

The pan is given with respect to the projected space. So a pan of \(1\) in the x direction moves the camera to focus on the right edge of the image whereas a pan of \(-1\) in the x direction moves the camera to focus on the left edge of the image.

Example 2.46 Panning the camera.

  view.GetCamera().Pan(deltaX, deltaY);

2.8.6.1.2. Zoom

A camera zoom draws the geometry larger or smaller. A camera zoom is performed by calling the vtkm::rendering::Camera::Zoom() method. vtkm::rendering::Camera::Zoom() takes a single argument specifying the zoom factor. A positive number draws the geometry larger (zoom in), and larger zoom factor results in larger geometry. Likewise, a negative number draws the geometry smaller (zoom out). A zoom factor of 0 has no effect.

Example 2.47 Zooming the camera.

  view.GetCamera().Zoom(zoomFactor);

2.8.6.2. 2D Camera Mode

The 2D camera is restricted to looking at some region of the x-y plane.

2.8.6.2.1. View Range

The vantage point of a 2D camera can be specified by simply giving the region in the x-y plane to look at. This region is specified by calling vtkm::rendering::Camera::SetViewRange2D(). This method takes the left, right, bottom, and top of the region to view. Typically these are set to the range of the geometry in world space as shown in Figure 2.10.

Figure 2.10 The view range bounds to give a vtkm::rendering::Camera.

2.8.6.3. 3D Camera Mode

The 3D camera is a free-form camera that can be placed anywhere in 3D space and can look in any direction. The projection of the 3D camera is based on the pinhole camera pinhole camera model in which all viewing rays intersect a single point. This single point is the camera’s position.

2.8.6.3.1. Position and Orientation

The position of the camera, which is the point where the observer is viewing the scene, can be set with the vtkm::rendering::Camera::SetPosition() method. The direction the camera is facing is specified by giving a position to focus on. This is called either the “look at” point or the focal point and is specified with the vtkm::rendering::Camera::SetLookAt() method. Figure 2.11 shows the relationship between the position and look at points.

Figure 2.11 The position and orientation parameters for a vtkm::rendering::Camera.

In addition to specifying the direction to point the camera, the camera must also know which direction is considered “up.” This is specified with the view up vector using the vtkm::rendering::Camera::SetViewUp() method. The view up vector points from the camera position (in the center of the image) to the top of the image. The view up vector in relation to the camera position and orientation is shown in Figure 2.11.

Another important parameter for the camera is its field of view. The field of view specifies how wide of a region the camera can see. It is specified by giving the angle in degrees of the cone of visible region emanating from the pinhole of the camera to the vtkm::rendering::Camera::SetFieldOfView() method. The field of view angle in relation to the camera orientation is shown in Figure 2.11. A field of view angle of \(60^{\circ}\) usually works well.

Finally, the camera must specify a clipping region that defines the valid range of depths for the object. This is a pair of planes parallel to the image that all visible data must lie in. Each of these planes is defined simply by their distance to the camera position. The near clip plane is closer to the camera and must be in front of all geometry. The far clip plane is further from the camera and must be behind all geometry. The distance to both the near and far planes are specified with the vtkm::rendering::Camera::SetClippingRange() method. Figure 2.11 shows the clipping planes in relationship to the camera position and orientation.

Example 2.48 Directly setting vtkm::rendering::Camera position and orientation.

  camera.SetPosition(vtkm::make_Vec(10.0, 6.0, 6.0));
  camera.SetLookAt(vtkm::make_Vec(0.0, 0.0, 0.0));
  camera.SetViewUp(vtkm::make_Vec(0.0, 1.0, 0.0));
  camera.SetFieldOfView(60.0);
  camera.SetClippingRange(0.1, 100.0);

2.8.6.3.2. Movement

In addition to specifically setting the position and orientation of the camera, vtkm::rendering::Camera contains several convenience methods that move the camera relative to its position and look at point.

Two such methods are elevation and azimuth, which move the camera around the sphere centered at the look at point. vtkm::rendering::Camera::Elevation() raises or lowers the camera. Positive values raise the camera up (in the direction of the view up vector) whereas negative values lower the camera down. vtkm::rendering::Camera::Azimuth() moves the camera around the look at point to the left or right. Positive values move the camera to the right whereas negative values move the camera to the left. Both vtkm::rendering::Camera::Elevation() and vtkm::rendering::Camera::Azimuth() specify the amount of rotation in terms of degrees. Figure 2.12 shows the relative movements of vtkm::rendering::Camera::Elevation() and vtkm::rendering::Camera::Azimuth().

Figure 2.12 vtkm::rendering::Camera movement functions relative to position and orientation.

Example 2.49 Moving the camera around the look at point.

  view.GetCamera().Azimuth(45.0);
  view.GetCamera().Elevation(45.0);

Common Errors

The vtkm::rendering::Camera::Elevation() and vtkm::rendering::Camera::Azimuth() methods change the position of the camera, but not the view up vector. This can cause some wild camera orientation changes when the direction of the camera view is near parallel to the view up vector, which often happens when the elevation is raised or lowered by about 90 degrees.

In addition to rotating the camera around the look at point, you can move the camera closer or further from the look at point. This is done with the vtkm::rendering::Camera::Dolly() method. The vtkm::rendering::Camera::Dolly() method takes a single value that is the factor to scale the distance between camera and look at point. Values greater than one move the camera away, values less than one move the camera closer. The direction of dolly movement is shown in Figure 2.12.

Finally, the vtkm::rendering::Camera::Roll() method rotates the camera around the viewing direction. It has the effect of rotating the rendered image. The vtkm::rendering::Camera::Roll() method takes a single value that is the angle to rotate in degrees. The direction of roll movement is shown in Figure 2.12.

2.8.6.3.3. Reset

Setting a specific camera position and orientation can be frustrating, particularly when the size, shape, and location of the geometry is not known a priori. Typically this involves querying the data and finding a good camera orientation.

To make this process simpler, the vtkm::rendering::Camera::ResetToBounds() convenience method automatically positions the camera based on the spatial bounds of the geometry. The most expedient method to find the spatial bounds of the geometry being rendered is to get the vtkm::rendering::Scene object and call vtkm::rendering::Scene::GetSpatialBounds(). The vtkm::rendering::Scene object can be retrieved from the vtkm::rendering::View, which, as described in Section 2.8.4 (Views), is the central object for managing rendering.

Example 2.50 Resetting a vtkm::rendering::Camera to view geometry.

void ResetCamera(vtkm::rendering::View& view)
{
  vtkm::Bounds bounds = view.GetScene().GetSpatialBounds();
  view.GetCamera().ResetToBounds(bounds);
}

The vtkm::rendering::Camera::ResetToBounds() method operates by placing the look at point in the center of the bounds and then placing the position of the camera relative to that look at point. The position is such that the view direction is the same as before the call to vtkm::rendering::Camera::ResetToBounds() and the distance between the camera position and look at point has the bounds roughly fill the rendered image. This behavior is a convenient way to update the camera to make the geometry most visible while still preserving the viewing position. If you want to reset the camera to a new viewing angle, it is best to set the camera to be pointing in the right direction and then calling vtkm::rendering::Camera::ResetToBounds() to adjust the position.

Example 2.51 Resetting a vtkm::rendering::Camera to be axis aligned.

  view.GetCamera().SetPosition(vtkm::make_Vec(0.0, 0.0, 0.0));
  view.GetCamera().SetLookAt(vtkm::make_Vec(0.0, 0.0, -1.0));
  view.GetCamera().SetViewUp(vtkm::make_Vec(0.0, 1.0, 0.0));
  vtkm::Bounds bounds = view.GetScene().GetSpatialBounds();
  view.GetCamera().ResetToBounds(bounds);

2.8.7. Interactive Rendering

So far in our description of VTK‑m’s rendering capabilities we have talked about doing rendering of fixed scenes. However, an important use case of scientific visualization is to provide an interactive rendering system to explore data. In this case, you want to render into a GUI application that lets the user interact manipulate the view. The full design of a 3D visualization application is well outside the scope of this book, but we discuss in general terms what you need to plug VTK‑m’s rendering into such a system.

In this section we discuss two important concepts regarding interactive rendering. First, we need to write images into a GUI while they are being rendered. Second, we want to translate user interaction to camera movement.

2.8.7.1. Rendering Into a GUI

Before being able to show rendering to a user, we need a system rendering context in which to push the images. In this section we demonstrate the display of images using the OpenGL rendering system, which is common for scientific visualization applications. That said, you could also use other rendering systems like DirectX or even paste images into a blank widget.

Creating an OpenGL context varies depending on the OS platform you are using. If you do not already have an application you want to integrate with VTK‑m’s rendering, you may wish to start with graphics utility API such as GLUT or GLFW. The process of initializing an OpenGL context is not discussed here.

The process of rendering into an OpenGL context is straightforward. First call vtkm::rendering::View::Paint() on the vtkm::rendering::View object to do the actual rendering. Second, get the image color data out of the vtkm::rendering::View’s vtkm::rendering::Canvas object. This is done by calling vtkm::rendering::Canvas::GetColorBuffer(). This will return a vtkm::cont::ArrayHandle object containing the image’s pixel color data. (vtkm::cont::ArrayHandle is discussed in detail in Chapter 3.2 (Basic Array Handles) and subsequent chapters.) A raw pointer can be pulled out of this vtkm::cont::ArrayHandle by casting it to the vtkm::cont::ArrayHandleBase subclass and calling the vtkm::cont::ArrayHandleBase::GetReadPointer() method on that. Third, the pixel color data are pasted into the OpenGL render context. There are multiple ways to do so, but the most straightforward way is to use the glDrawPixels function provided by OpenGL. Fourth, swap the OpenGL buffers. The method to swap OpenGL buffers varies by OS platform. The aforementioned graphics libraries GLUT and GLFW each provide a function for doing so.

Example 2.52 Rendering a vtkm::rendering::View and pasting the result to an active OpenGL context.

  view.Paint();

  // Get the color buffer containing the rendered image.
  vtkm::cont::ArrayHandle<vtkm::Vec4f_32> colorBuffer =
    view.GetCanvas().GetColorBuffer();

  // Pull the C array out of the arrayhandle.
  const void* colorArray =
    vtkm::cont::ArrayHandleBasic<vtkm::Vec4f_32>(colorBuffer).GetReadPointer();

  // Write the C array to an OpenGL buffer.
  glDrawPixels((GLint)view.GetCanvas().GetWidth(),
               (GLint)view.GetCanvas().GetHeight(),
               GL_RGBA,
               GL_FLOAT,
               colorArray);

  // Swap the OpenGL buffers (system dependent).

2.8.7.2. Camera Movement

When interactively manipulating the camera in a windowing system, the camera is usually moved in response to mouse movements. Typically, mouse movements are detected through callbacks from the windowing system back to your application. Once again, the details on how this works depend on your windowing system. The assumption made in this section is that through the windowing system you will be able to track the x-y pixel location of the mouse cursor at the beginning of the movement and the end of the movement. Using these two pixel coordinates, as well as the current width and height of the render space, we can make several typical camera movements.

Common Errors

Pixel coordinates in VTK‑m’s rendering system originate in the lower-left corner of the image. However, windowing systems generally report mouse coordinates with the origin in the upper-left corner. The upshot is that the y coordinates will have to be reversed when translating mouse coordinates to VTK‑m image coordinates. This inverting is present in all the following examples.

2.8.7.2.1. Interactive Rotate

A common and important mode of interaction with 3D views is to allow the user to rotate the object under inspection by dragging the mouse. To facilitate this type of interactive rotation, vtkm::rendering::Camera provides a convenience method named vtkm::rendering::Camera::TrackballRotate(). It takes a start and end position of the mouse on the image and rotates viewpoint as if the user grabbed a point on a sphere centered in the image at the start position and moved under the end position.

The vtkm::rendering::Camera::TrackballRotate() method is typically called from within a mouse movement callback. The callback must record the pixel position from the last event and the new pixel position of the mouse. Those pixel positions must be normalized to the range -1 to 1 where the position (-1,-1) refers to the lower left of the image and (1,1) refers to the upper right of the image. The following example demonstrates the typical operations used to establish rotations when dragging the mouse.

Example 2.53 Interactive rotations through mouse dragging with vtkm::rendering::Camera::TrackballRotate().

void DoMouseRotate(vtkm::rendering::View& view,
                   vtkm::Id mouseStartX,
                   vtkm::Id mouseStartY,
                   vtkm::Id mouseEndX,
                   vtkm::Id mouseEndY)
{
  vtkm::Id screenWidth = view.GetCanvas().GetWidth();
  vtkm::Id screenHeight = view.GetCanvas().GetHeight();

  // Convert the mouse position coordinates, given in pixels from 0 to
  // width/height, to normalized screen coordinates from -1 to 1. Note that y
  // screen coordinates are usually given from the top down whereas our
  // geometry transforms are given from bottom up, so you have to reverse the y
  // coordiantes.
  vtkm::Float32 startX = (2.0f * mouseStartX) / screenWidth - 1.0f;
  vtkm::Float32 startY = -((2.0f * mouseStartY) / screenHeight - 1.0f);
  vtkm::Float32 endX = (2.0f * mouseEndX) / screenWidth - 1.0f;
  vtkm::Float32 endY = -((2.0f * mouseEndY) / screenHeight - 1.0f);

  view.GetCamera().TrackballRotate(startX, startY, endX, endY);
}

2.8.7.2.2. Interactive Pan

Panning can be performed by calling vtkm::rendering::Camera::Pan() with the translation relative to the width and height of the canvas. For the translation to track the movement of the mouse cursor, simply scale the pixels the mouse has traveled by the width and height of the image.

Example 2.54 Pan the view based on mouse movements.

void DoMousePan(vtkm::rendering::View& view,
                vtkm::Id mouseStartX,
                vtkm::Id mouseStartY,
                vtkm::Id mouseEndX,
                vtkm::Id mouseEndY)
{
  vtkm::Id screenWidth = view.GetCanvas().GetWidth();
  vtkm::Id screenHeight = view.GetCanvas().GetHeight();

  // Convert the mouse position coordinates, given in pixels from 0 to
  // width/height, to normalized screen coordinates from -1 to 1. Note that y
  // screen coordinates are usually given from the top down whereas our
  // geometry transforms are given from bottom up, so you have to reverse the y
  // coordiantes.
  vtkm::Float32 startX = (2.0f * mouseStartX) / screenWidth - 1.0f;
  vtkm::Float32 startY = -((2.0f * mouseStartY) / screenHeight - 1.0f);
  vtkm::Float32 endX = (2.0f * mouseEndX) / screenWidth - 1.0f;
  vtkm::Float32 endY = -((2.0f * mouseEndY) / screenHeight - 1.0f);

  vtkm::Float32 deltaX = endX - startX;
  vtkm::Float32 deltaY = endY - startY;

  view.GetCamera().Pan(deltaX, deltaY);
}

2.8.7.2.3. Interactive Zoom

Zooming can be performed by calling vtkm::rendering::Camera::Zoom() with a positive or negative zoom factor. When using vtkm::rendering::Camera::Zoom() to respond to mouse movements, a natural zoom will divide the distance traveled by the mouse pointer by the width or height of the screen as demonstrated in the following example.

Example 2.55 Zoom the view based on mouse movements.

void DoMouseZoom(vtkm::rendering::View& view, vtkm::Id mouseStartY, vtkm::Id mouseEndY)
{
  vtkm::Id screenHeight = view.GetCanvas().GetHeight();

  // Convert the mouse position coordinates, given in pixels from 0 to height,
  // to normalized screen coordinates from -1 to 1. Note that y screen
  // coordinates are usually given from the top down whereas our geometry
  // transforms are given from bottom up, so you have to reverse the y
  // coordiantes.
  vtkm::Float32 startY = -((2.0f * mouseStartY) / screenHeight - 1.0f);
  vtkm::Float32 endY = -((2.0f * mouseEndY) / screenHeight - 1.0f);

  vtkm::Float32 zoomFactor = endY - startY;

  view.GetCamera().Zoom(zoomFactor);
}

2.8.8. Color Tables

An important feature of VTK‑m’s rendering units is the ability to pseudocolor objects based on scalar data. This technique maps each scalar to a potentially unique color. This mapping from scalars to colors is defined by a vtkm::cont::ColorTable object. A vtkm::cont::ColorTable can be specified as an optional argument when constructing a vtkm::rendering::Actor. (Use of vtkm::rendering::Actor is discussed in Section 2.8.1 (Scenes and Actors).)

Example 2.56 Specifying a vtkm::cont::ColorTable for a vtkm::rendering::Actor.

  vtkm::rendering::Actor actor(surfaceData.GetCellSet(),
                               surfaceData.GetCoordinateSystem(),
                               surfaceData.GetField("RandomPointScalars"),
                               vtkm::cont::ColorTable("inferno"));

class ColorTable : public vtkm::cont::ExecutionObjectBase

Color Table for coloring arbitrary fields.

The vtkm::cont::ColorTable allows for color mapping in RGB or HSV space and uses a piecewise hermite functions to allow opacity interpolation that can be piecewise constant, piecewise linear, or somewhere in-between (a modified piecewise hermite function that squishes the function according to a sharpness parameter).

For colors interpolation is handled using a piecewise linear function.

For opacity we define a piecewise function mapping. This mapping allows the addition of control points, and allows the user to control the function between the control points. A piecewise hermite curve is used between control points, based on the sharpness and midpoint parameters. A sharpness of 0 yields a piecewise linear function and a sharpness of 1 yields a piecewise constant function. The midpoint is the normalized distance between control points at which the curve reaches the median Y value. The midpoint and sharpness values specified when adding a node are used to control the transition to the next node with the last node’s values being ignored.

When adding opacity nodes without an explicit midpoint and sharpness we will default to to Midpoint = 0.5 (halfway between the control points) and Sharpness = 0.0 (linear).

ColorTable also contains which ColorSpace should be used for interpolation. The color space is selected with the vtkm::ColorSpace enumeration. Currently the valid ColorSpaces are:

• RGB

• HSV

• HSVWrap

• Lab

• Diverging

In HSVWrap mode, it will take the shortest path in Hue (going back through 0 if that is the shortest way around the hue circle) whereas HSV will not go through 0 (in order to match the current functionality of vtkLookupTable). In Lab mode, it will take the shortest path in the Lab color space with respect to the CIE Delta E 2000 color distance measure. Diverging is a special mode where colors will pass through white when interpolating between two saturated colors.

To map a field from a vtkm::cont::DataSet through the color and opacity transfer functions and into a RGB or RGBA array you should use vtkm::filter::FieldToColor.

Note that modifications of vtkm::cont::ColorTable are not thread safe. You should not modify a ColorTable simultaneously in 2 or more threads. Also, you should not modify a ColorTable that might be used in the execution environment. However, the ColorTable can be used in multiple threads and on multiple devices as long as no modifications are made.

Public Functions

ColorTable(vtkm::cont::ColorTable::Preset preset = vtkm::cont::ColorTable::Preset::Default)

Construct a color table from a preset.

Constructs a color table from a given preset, which might include a NaN color. The alpha table will have 2 entries of alpha = 1.0 with linear interpolation

Note: these are a select set of the presets you can get by providing a string identifier.

explicit ColorTable(const std::string &name)

Construct a color table from a preset color table.

Constructs a color table from a given preset, which might include a NaN color. The alpha table will have 2 entries of alpha = 1.0 with linear interpolation

Note: Names are case insensitive Currently supports the following color tables:

“Default” “Cool to Warm” “Cool to Warm Extended” “Viridis” “Inferno” “Plasma” “Black-Body Radiation” “X Ray” “Green” “Black - Blue - White” “Blue to Orange” “Gray to Red” “Cold and Hot” “Blue - Green - Orange” “Yellow - Gray - Blue” “Rainbow Uniform” “Jet” “Rainbow Desaturated”

explicit ColorTable(vtkm::ColorSpace space)

Construct a color table with a zero positions, and an invalid range.

Note: The color table will have 0 entries Note: The alpha table will have 0 entries

ColorTable(const vtkm::Range &range, vtkm::ColorSpace space = vtkm::ColorSpace::Lab)

Construct a color table with a 2 positions.

Note: The color table will have 2 entries of rgb = {1.0,1.0,1.0} Note: The alpha table will have 2 entries of alpha = 1.0 with linear interpolation

ColorTable(const vtkm::Range &range, const vtkm::Vec3f_32 &rgb1, const vtkm::Vec3f_32 &rgb2, vtkm::ColorSpace space = vtkm::ColorSpace::Lab)

Construct a color table with 2 positions.

Note: The alpha table will have 2 entries of alpha = 1.0 with linear interpolation

ColorTable(const vtkm::Range &range, const vtkm::Vec4f_32 &rgba1, const vtkm::Vec4f_32 &rgba2, vtkm::ColorSpace space = vtkm::ColorSpace::Lab)

Construct color and alpha and table with 2 positions.

Note: The alpha table will use linear interpolation

ColorTable(const std::string &name, vtkm::ColorSpace colorSpace, const vtkm::Vec3f_64 &nanColor, const std::vector<vtkm::Float64> &rgbPoints, const std::vector<vtkm::Float64> &alphaPoints = {0.0, 1.0, 0.5, 0.0, 1.0, 1.0, 0.5, 0.0})

Construct a color table with a list of colors and alphas.

For this version you must also specify a name.

This constructor is mostly used for presets.

bool LoadPreset(const std::string &name)

Load a preset color table.

Removes all existing all values in both color and alpha tables, and will reset the NaN Color if the color table has that information. Will not modify clamping, below, and above range state.

Note: Names are case insensitive

Currently supports the following color tables: “Default” “Cool to Warm” “Cool to Warm Extended” “Viridis” “Inferno” “Plasma” “Black-Body Radiation” “X Ray” “Green” “Black - Blue - White” “Blue to Orange” “Gray to Red” “Cold and Hot” “Blue - Green - Orange” “Yellow - Gray - Blue” “Rainbow Uniform” “Jet” “Rainbow Desaturated”

ColorTable MakeDeepCopy()

Make a deep copy of the current color table.

The ColorTable is implemented so that all stack based copies are ‘shallow’ copies. This means that they all alter the same internal instance. But sometimes you need to make an actual fully independent copy.

inline void SetClampingOn()

If clamping is disabled values that lay out side the color table range are colored based on Below and Above settings.

By default clamping is enabled

void SetBelowRangeColor(const vtkm::Vec3f_32 &c)

Color to use when clamping is disabled for any value that is below the given range.

Default value is {0,0,0}

void SetAboveRangeColor(const vtkm::Vec3f_32 &c)

Color to use when clamping is disabled for any value that is above the given range.

Default value is {0,0,0}

void Clear()

Remove all existing values in both color and alpha tables.

Does not remove the clamping, below, and above range state or colors.

void ClearColors()

Remove only color table values.

void ClearAlpha()

Remove only alpha table values.

void ReverseColors()

Reverse the rgb values inside the color table.

void ReverseAlpha()

Reverse the alpha, mid, and sharp values inside the opacity table.

Note: To keep the shape correct the mid and sharp values of the last node are not included in the reversal

const vtkm::Range &GetRange() const

Returns min and max position of all function points.

void RescaleToRange(const vtkm::Range &range)

Rescale the color and opacity transfer functions to match the input range.

vtkm::Int32 AddPoint(vtkm::Float64 x, const vtkm::Vec3f_32 &rgb)

Adds a point to the color function.

If the point already exists, it will be updated to the new value.

Note: rgb values need to be between 0 and 1.0 (inclusive). Return the index of the point (0 based), or -1 osn error.

vtkm::Int32 AddPointHSV(vtkm::Float64 x, const vtkm::Vec3f_32 &hsv)

Adds a point to the color function.

If the point already exists, it will be updated to the new value.

Note: hsv values need to be between 0 and 1.0 (inclusive). Return the index of the point (0 based), or -1 on error.

vtkm::Int32 AddSegment(vtkm::Float64 x1, const vtkm::Vec3f_32 &rgb1, vtkm::Float64 x2, const vtkm::Vec3f_32 &rgb2)

Add a line segment to the color function.

All points which lay between x1 and x2 (inclusive) are removed from the function.

Note: rgb1, and rgb2 values need to be between 0 and 1.0 (inclusive). Return the index of the point x1 (0 based), or -1 on error.

vtkm::Int32 AddSegmentHSV(vtkm::Float64 x1, const vtkm::Vec3f_32 &hsv1, vtkm::Float64 x2, const vtkm::Vec3f_32 &hsv2)

Add a line segment to the color function.

All points which lay between x1 and x2 (inclusive) are removed from the function.

Note: hsv1, and hsv2 values need to be between 0 and 1.0 (inclusive) Return the index of the point x1 (0 based), or -1 on error

bool GetPoint(vtkm::Int32 index, vtkm::Vec4f_64&) const

Get the location, and rgb information for an existing point in the opacity function.

Note: components 1-3 are rgb and will have values between 0 and 1.0 (inclusive) Return the index of the point (0 based), or -1 on error.

vtkm::Int32 UpdatePoint(vtkm::Int32 index, const vtkm::Vec4f_64&)

Update the location, and rgb information for an existing point in the color function.

If the location value for the index is modified the point is removed from the function and re-inserted in the proper sorted location.

Note: components 1-3 are rgb and must have values between 0 and 1.0 (inclusive). Return the new index of the updated point (0 based), or -1 on error.

bool RemovePoint(vtkm::Float64 x)

Remove the Color function point that exists at exactly x.

Return true if the point x exists and has been removed

bool RemovePoint(vtkm::Int32 index)

Remove the Color function point n.

Return true if n >= 0 && n < GetNumberOfPoints

vtkm::Int32 GetNumberOfPoints() const

Returns the number of points in the color function.

inline vtkm::Int32 AddPointAlpha(vtkm::Float64 x, vtkm::Float32 alpha)

Adds a point to the opacity function.

If the point already exists, it will be updated to the new value. Uses a midpoint of 0.5 (halfway between the control points) and sharpness of 0.0 (linear).

Note: alpha needs to be a value between 0 and 1.0 (inclusive). Return the index of the point (0 based), or -1 on error.

vtkm::Int32 AddPointAlpha(vtkm::Float64 x, vtkm::Float32 alpha, vtkm::Float32 midpoint, vtkm::Float32 sharpness)

Adds a point to the opacity function.

If the point already exists, it will be updated to the new value.

Note: alpha, midpoint, and sharpness values need to be between 0 and 1.0 (inclusive) Return the index of the point (0 based), or -1 on error.

inline vtkm::Int32 AddSegmentAlpha(vtkm::Float64 x1, vtkm::Float32 alpha1, vtkm::Float64 x2, vtkm::Float32 alpha2)

Add a line segment to the opacity function.

All points which lay between x1 and x2 (inclusive) are removed from the function. Uses a midpoint of 0.5 (halfway between the control points) and sharpness of 0.0 (linear).

Note: alpha values need to be between 0 and 1.0 (inclusive) Return the index of the point x1 (0 based), or -1 on error

vtkm::Int32 AddSegmentAlpha(vtkm::Float64 x1, vtkm::Float32 alpha1, vtkm::Float64 x2, vtkm::Float32 alpha2, const vtkm::Vec2f_32 &mid_sharp1, const vtkm::Vec2f_32 &mid_sharp2)

Add a line segment to the opacity function.

All points which lay between x1 and x2 (inclusive) are removed from the function.

Note: alpha, midpoint, and sharpness values need to be between 0 and 1.0 (inclusive) Return the index of the point x1 (0 based), or -1 on error

bool GetPointAlpha(vtkm::Int32 index, vtkm::Vec4f_64&) const

Get the location, alpha, midpoint and sharpness information for an existing point in the opacity function.

Note: alpha, midpoint, and sharpness values all will be between 0 and 1.0 (inclusive) Return the index of the point (0 based), or -1 on error.

vtkm::Int32 UpdatePointAlpha(vtkm::Int32 index, const vtkm::Vec4f_64&)

Update the location, alpha, midpoint and sharpness information for an existing point in the opacity function.

If the location value for the index is modified the point is removed from the function and re-inserted in the proper sorted location

Note: alpha, midpoint, and sharpness values need to be between 0 and 1.0 (inclusive) Return the new index of the updated point (0 based), or -1 on error.

bool RemovePointAlpha(vtkm::Float64 x)

Remove the Opacity function point that exists at exactly x.

Return true if the point x exists and has been removed

bool RemovePointAlpha(vtkm::Int32 index)

Remove the Opacity function point n.

Return true if n >= 0 && n < GetNumberOfPointsAlpha

vtkm::Int32 GetNumberOfPointsAlpha() const

Returns the number of points in the alpha function.

bool FillColorTableFromDataPointer(vtkm::Int32 n, const vtkm::Float64 *ptr)

Fill the Color table from a vtkm::Float64 pointer.

The vtkm::Float64 pointer is required to have the layout out of [X1, R1, G1, B1, X2, R2, G2, B2, …, Xn, Rn, Gn, Bn] where n is the number of nodes. This will remove any existing color control points.

Note: n represents the length of the array, so ( n/4 == number of control points )

Note: This is provided as a interoperability method with VTK Will return false and not modify anything if n is <= 0 or ptr == nullptr

bool FillColorTableFromDataPointer(vtkm::Int32 n, const vtkm::Float32 *ptr)

Fill the Color table from a vtkm::Float32 pointer.

The vtkm::Float64 pointer is required to have the layout out of [X1, R1, G1, B1, X2, R2, G2, B2, …, Xn, Rn, Gn, Bn] where n is the number of nodes. This will remove any existing color control points.

Note: n represents the length of the array, so ( n/4 == number of control points )

Note: This is provided as a interoperability method with VTK Will return false and not modify anything if n is <= 0 or ptr == nullptr

bool FillOpacityTableFromDataPointer(vtkm::Int32 n, const vtkm::Float64 *ptr)

Fill the Opacity table from a vtkm::Float64 pointer.

The vtkm::Float64 pointer is required to have the layout out of [X1, A1, M1, S1, X2, A2, M2, S2, …, Xn, An, Mn, Sn] where n is the number of nodes. The Xi values represent the value to map, the Ai values represent alpha (opacity) value, the Mi values represent midpoints, and the Si values represent sharpness. Use 0.5 for midpoint and 0.0 for sharpness to have linear interpolation of the alpha.

This will remove any existing opacity control points.

Note: n represents the length of the array, so ( n/4 == number of control points )

Will return false and not modify anything if n is <= 0 or ptr == nullptr

bool FillOpacityTableFromDataPointer(vtkm::Int32 n, const vtkm::Float32 *ptr)

Fill the Opacity table from a vtkm::Float32 pointer.

The vtkm::Float32 pointer is required to have the layout out of [X1, A1, M1, S1, X2, A2, M2, S2, …, Xn, An, Mn, Sn] where n is the number of nodes. The Xi values represent the value to map, the Ai values represent alpha (opacity) value, the Mi values represent midpoints, and the Si values represent sharpness. Use 0.5 for midpoint and 0.0 for sharpness to have linear interpolation of the alpha.

This will remove any existing opacity control points.

Note: n represents the length of the array, so ( n/4 == number of control points )

Will return false and not modify anything if n is <= 0 or ptr == nullptr

bool Sample(vtkm::Int32 numSamples, vtkm::cont::ColorTableSamplesRGBA &samples, vtkm::Float64 tolerance = 0.002) const

generate RGB colors using regular spaced samples along the range.

Will use the current range of the color table to generate evenly spaced values using either vtkm::Float32 or vtkm::Float64 space. Will use vtkm::Float32 space when the difference between the vtkm::Float32 and vtkm::Float64 values when the range is within vtkm::Float32 space and the following are within a tolerance:

• (max-min) / numSamples

• ((max-min) / numSamples) * numSamples

Note: This will return false if the number of samples is less than 2

bool Sample(vtkm::Int32 numSamples, vtkm::cont::ColorTableSamplesRGB &samples, vtkm::Float64 tolerance = 0.002) const

generate a sample lookup table using regular spaced samples along the range.

Will use the current range of the color table to generate evenly spaced values using either vtkm::Float32 or vtkm::Float64 space. Will use vtkm::Float32 space when the difference between the vtkm::Float32 and vtkm::Float64 values when the range is within vtkm::Float32 space and the following are within a tolerance:

• (max-min) / numSamples

• ((max-min) / numSamples) * numSamples

Note: This will return false if the number of samples is less than 2

bool Sample(vtkm::Int32 numSamples, vtkm::cont::ArrayHandle<vtkm::Vec4ui_8> &colors, vtkm::Float64 tolerance = 0.002) const

generate RGBA colors using regular spaced samples along the range.

Will use the current range of the color table to generate evenly spaced values using either vtkm::Float32 or vtkm::Float64 space. Will use vtkm::Float32 space when the difference between the vtkm::Float32 and vtkm::Float64 values when the range is within vtkm::Float32 space and the following are within a tolerance:

• (max-min) / numSamples

• ((max-min) / numSamples) * numSamples

Note: This will return false if the number of samples is less than 2

bool Sample(vtkm::Int32 numSamples, vtkm::cont::ArrayHandle<vtkm::Vec3ui_8> &colors, vtkm::Float64 tolerance = 0.002) const

generate RGB colors using regular spaced samples along the range.

Will use the current range of the color table to generate evenly spaced values using either vtkm::Float32 or vtkm::Float64 space. Will use vtkm::Float32 space when the difference between the vtkm::Float32 and vtkm::Float64 values when the range is within vtkm::Float32 space and the following are within a tolerance:

• (max-min) / numSamples

• ((max-min) / numSamples) * numSamples

Note: This will return false if the number of samples is less than 2

vtkm::exec::ColorTable PrepareForExecution(vtkm::cont::DeviceAdapterId deviceId, vtkm::cont::Token &token) const

returns a virtual object pointer of the exec color table

This pointer is only valid as long as the ColorTable is unmodified

vtkm::Id GetModifiedCount() const

Returns the modified count for changes of the color table.

The ModifiedCount of the color table starts at 1 and gets incremented every time a change is made to the color table. The modified count allows consumers of a shared color table to keep track if the color table has been modified since the last time they used it. This is important for consumers that need to sample the color table. You only want to resample the color table if changes have been made.

Public Static Functions

static std::set<std::string> GetPresets()

Returns the name of all preset color tables.

This list will include all presets defined in vtkm::cont::ColorTable::Preset and could include extras as well.

The easiest way to create a vtkm::cont::ColorTable is to provide the name of one of the many predefined sets of color provided by VTK-m. A list of all available predefined color tables is provided below.

• Viridis Matplotlib Virdis, which is designed to have perceptual uniformity, accessibility to color blind viewers, and good conversion to black and white. This is the default color map.

• Cool to Warm A color table designed to be perceptually even, to work well on shaded 3D surfaces, and to generally perform well across many uses.

• Cool to Warm Extended This colormap is an expansion on cool to warm that moves through a wider range of hue and saturation. Useful if you are looking for a greater level of detail, but the darker colors at the end might interfere with 3D surfaces.

• Inferno Matplotlib Inferno, which is designed to have perceptual uniformity, accessibility to color blind viewers, and good conversion to black and white.

• Plasma Matplotlib Plasma, which is designed to have perceptual uniformity, accessibility to color blind viewers, and good conversion to black and white.

• Black Body Radiation The colors are inspired by the wavelengths of light from black body radiation. The actual colors used are designed to be perceptually uniform.

• X Ray Greyscale colormap useful for making volume renderings similar to what you would expect in an x-ray.

• Green A sequential color map of green varied by saturation.

• Black - Blue - White A sequential color map from black to blue to white.

• Blue to Orange A double-ended (diverging) color table that goes from dark blues to a neutral white and then a dark orange at the other end.

• Gray to Red A double-ended (diverging) color table with black/gray at the low end and orange/red at the high end.

• Cold and Hot A double-ended color map with a black middle color and diverging values to either side. Colors go from red to yellow on the positive side and through blue on the negative side.

• Blue - Green - Orange A three-part color map with blue at the low end, green in the middle, and orange at the high end.

• Yellow - Gray - Blue A three-part color map with yellow at the low end, gray in the middle, and blue at the high end.

• Rainbow Uniform A color table that spans the hues of a rainbow. This color table modifies the hues to make them more perceptually uniform than the raw color wavelengths.

• Jet A rainbow color table that adds some darkness for greater perceptual resolution.

• Rainbow Desaturated Basic rainbow colors with periodic dark points to increase the local discriminability.