9.3 Users Guide
9.3 Users Guide
9.3 Users Guide
Contributors:
● Jeff Baumes — Wikipedia Browser
● David Cole — Technical Lead
● Jon Crall — Technical Contributor, Wikipedia Browser, examples
● Bill Hoffman — Technical Contributor
● Niki Russell — Documentation, web support
● Will Schroeder — Documentation, examples
● Tristan Coulange — Technical Contributor
● Lucas Gandel — Technical Lead
ActiViz .Net also includes the component ActiViz COM, a complete Microsoft COM
compatible interface to the Visualization Toolkit (VTK) software system. It is used to
embed VTK capabilities into Microsoft applications such as Word, PowerPoint, and
Excel.
1.4. Licensing
ActiViz .NET is licensed under a BSD license, a family of permissive free software
licenses, imposing minimal restrictions on the redistribution of covered software.
Therefore, your ActiViz developments can be integrated into commercial applications.
ActiViz .NET is licensed in two flavors: The OpenSource Edition and the Supported
Edition. Purchasing the Supported Edition removes some conditions for binary
redistribution.
Notes:
The latest Open-Source version available is ActiViz .NET 5.8.0.
The latest Supported version available is ActiViz .NET 9.3.
While VTK itself can run on small to large computers, it is a sophisticated, powerful
system that requires adequate computing resources. We advise using hardware with a
good 3D graphics cards, 2 GB memory and a modern CPU.
● First, you will see the welcome splash screen. Choose “Next>” and proceed to the
next step.
● Next, please review the license agreement and agree to its terms.
● Indicate where on your computer you would like to install the software. For the
purposes of this User’s Guide, the installation location is in C:\Program Files
(x86)\ActiViz.NET 9.3 Supported Edition. (Note that administrative privileges are
required to install ActiViz in the “Program Files” directory. However, you may
install the software anywhere on the system.) Choose “Next” and proceed with the
installation.
● You will also need to indicate where to place the installation on your Start Menu
Folder.
● Once you select “Install” the software installation process begins as illustrated below.
It should take less than a minute.
● That’s it, you have successfully installed ActiViz .NET on your computer.
Activiz Nuget packages of the latest Supported Version targeting .NET Core are provided
with the installer.
To install and use Activiz in .NET Core projects, you must provide nuget with the location
of the packages that come with the installer. This can be achieved by adding the “package”
directory, located in your Activiz installation folder, to the local nuget package feed.
To do so, first install Activiz with the installer, then proceed with the following steps in
Visual Studio:
● Right-click on your project
● Select “Manage NuGet Packages”
● Click the Package Source Settings wheel in the upper right corner of the Nuget
Package Manager
● Add a new package source using the “+” icon, and update the Source path to include
the location of your Activiz nuget packages
● The new package source appears in the list and allows for browsing local packages.
You can now install Kitware.VTK and start using Activiz.
Nuget packages of the Activiz Open Source Version targeting .NET Framework 2.0 are
available on nuget.org, so you can easily install them in your project.
Currently the versions of ActiViz .NET available in the NuGet Gallery are:
● ActiViz .NET 5.6.1 x32
● ActiViz .NET 5.6.1 x64
● ActiViz .NET 5.8.0 x32
● ActiViz .NET 5.8.0 x64
The RenderWindowControl can be used when designing applications, either when using
the .NET Core package or the 32-bit .NET Framework references.
The 64-bit version of ActiViz targeting the .NET Framework cannot be used in the
VisualStudio Designer. Fortunately this step is not required since you can integrate
ActiViz Control manually in your code.
If the RenderWindowControl is not available by default in the Designer ToolBox, you
may need to configure Visual Studio as follows. This step requires a 32bits version of
ActiViz.
You will need to browse for .NET Framework Components by selecting “Browse” to
search in the ActiViz bin directory (e.g., C:\Program Files\ActiViz.NET 9.3 Supported
Edition x86\bin). The following selection will appear:
Select the Kitware.VTK.dll assembly. This will make the ActiViz control available in
your toolbox when designing WindowsForm applications.
4. Using ActiViz .NET
4.1. ActiViz .NET Framework Reference
The first step to use ActiViz in your project is to add a reference to ActiViz libraries. For
this, right click on your project in the Solution Explorer, and choose “Add Reference”. This
will bring up a dialog, at which point you will “Browse” to the ActiViz .NET install
location C:\Program Files\ActiViz.NET 9.3 Supported Edition x86\bin (or appropriate).
Then choose the two assemblies as shown in the figure below:
● “Kitware.mummy.Runtime.dll”
● “Kitware.VTK.dll”.
Note: This step is not required if you installed ActiViz via NuGet.
To start using Activiz in .NET Core applications, follow both the installation instructions of sections
Installation With Installer and Installation With Nuget.
First, VTK is an object-oriented system. The practical realization of this design is that
objects are instantiated and then combined in a variety of patterns to form applications.
Each class represents a focused piece of functionality. The instances (or objects) of these
classes are manipulated by invoking methods upon them.
The graphics subsystem is used to display data of various forms including polygonal data
and volumes (i.e., regularly sampled data). The rendering system consists of the
following key objects that are combined into a scene to produce the final 3D display.
● vtkActor and vtkProp — the objects to be rendered that appear in the scene. In
general, we refer to these objects as “actors” although vtkActor is in fact a subclass
of vtkProp (like the “props” found on stage).
● vtkCamera — the object used to project the actors from 3D space into a 2D image.
● vtkLight — used to illuminate the scene.
● vtkProperty — used to apply material (i.e., lighting) properties to actors.
● vtkRenderer — this is the object where the rendered image is shown.
● vtkRenderWindow — one or more renderers can be combined into a render
window.
This organization of objects is consistent with the “lights, cameras, actors” conceptual
model that is familiar to many of us from the movie/video making business. Note that
many other objects are present behind the scenes such as transformation matrices
(vtkTransform), interactors (process mouse and keyboard events), and texture maps
(vtkTexture). Note that when building Form Applications, ActiViz .NET system
combines the vtkRenderer and vtkRenderWindow into a single class called the
“RenderWindowControl”. This is the form that is created in ActiViz applications and
embedded into the .NET program.
One important note: the vtkRenderWindowInteractor class is the keystone class for
managing mouse and keyboard events in the render window. Through interactor styles
(subclasses of vtkInteractorObserver) it is possible to customize the interaction behavior.
By default, the interactor supports the following bindings:
The examples that follow in this section all implement these mouse and keyboard
bindings.
Besides the basic classes described here, there are hundreds more classes that implement
key functionality for the VTK system. This includes filters for processing data,
interaction widgets for direct manipulation of data, image processing, volume rendering,
information visualization, mathematics, and computational geometry (to name just a
few). The following examples demonstrate a variety of ways in which VTK can be used,
and how to use VTK in the .NET framework.
4.4. Hello VTK - Console Application
In the first example we will create a console application. Create a new Visual Studio
project and choose the Console application template.
Open the created project and add the required references to ActiViz depending on your .NET
version, by following the instruction in Using Activiz .NET.
Now it’s simply a matter of adding in the appropriate references and writing some VTK
code. In this example we will use C#. (Please read the short introduction to VTK to help
clarify some of the concepts.) To add in references, make sure that the line “using
Kitware.VTK;” (highlighted below) is added to your application.
using System;
using System.Collections.Generic;
using System.Text;
using Kitware.VTK;
namespace HelloVTK
{
class Program
{
static void Main(string[] args)
{
// add code here
}
}
}
Next, insert the appropriate VTK code into the Main() function as exemplified by the
following.
shrink = vtkShrinkPolyData.New();
shrink.SetInputConnection(sphere.GetOutputPort());
shrink.SetShrinkFactor(0.9);
mapper = vtkPolyDataMapper.New();
mapper.SetInputConnection(shrink.GetOutputPort());
deleteAllVTKObjects();
}
static vtkSphereSource sphere;
static vtkShrinkPolyData shrink;
static vtkPolyDataMapper mapper;
static vtkActor actor;
static vtkRenderer ren1;
static vtkRenderWindow renWin;
static vtkRenderWindowInteractor iren;
static vtkCamera camera;
///<summary>Deletes all static objects created</summary> public static
void deleteAllVTKObjects()
{
//clean up vtk objects
if (sphere != null) { sphere.Dispose(); }
if (shrink != null) { shrink.Dispose(); }
if (mapper != null) { mapper.Dispose(); }
if (actor != null) { actor.Dispose(); }
if (ren1 != null) { ren1.Dispose(); }
if (renWin != null) { renWin.Dispose(); }
if (iren != null) { iren.Dispose(); }
if (camera != null) { camera.Dispose(); }
}
Compiling and running the C# program yields the red sphere above. (Note that some
interaction with the camera was performed to move the camera into the position shown.)
In this example, a simple pipeline is implemented that generates some polygonal data (the
sphere source); shrinks the polygons towards their center (the shrink filter), and then
maps the data (e.g., polygons) to the graphics library. Since no lights and cameras are
manually created, they are automatically created. Also, the vtkRenderWindowInteractor
is used to control mouse and keyboard events in the window. Note: calling iren.Start() in
the example runs a Windows message loop. To exit the message loop, and hence the
application, simply close the window.
4.5. Hello VTK - Windows Form Application
To create a Windows Form Application (shown here in C#), select “Create a new project”
from the Visual Studio start menu. Select the Windows Forms App template for either the
.NET Framework or .NET Core, and fill the project information.
Open the created project and add the required references to ActiViz depending on your .NET
version, by following the instruction in Using Activiz .NET.
Next, go to the View Menu and make sure the Toolbox is visible.
Under the General category in the toolbox, the RenderWindowControl will appear. To
add the control to your application, select the RenderWindowControl and place it into the
form as shown in the figure below.
Note: The integration of the ActiViz control in your application can be done
programmatically. This can be necessary if the control is not in the ToolBox (see the part
ActiViz Control in Visual Studio for more details).
Next, double click on the RenderWindowControl to bring up the C# code:
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Text;
using System.Windows.Forms;
namespace HelloVTK
{
public partial class Form1 : Form
{
public Form1()
{
InitializeComponent();
}
private void
renderWindowControl1_Load(object sender, EventArgs e)
{
//add code here
}
}
}
As in the Console Application, code can now be inserted into the skeleton application.
Make sure that “using Kitware.VTK;” is added, and add references to the solution.
Finally, note that the control provides some convenience methods for accessing the
renderer and render window, and builds in a render window interactor. Here is what the
code looks like, and the image that results from running the application:
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Text;
using System.Windows.Forms;
using Kitware.VTK;
namespace HelloVTK
{
public partial class Form1 : Form
{
public Form1()
{
InitializeComponent();
}
private void
renderWindowControl1_Load(object sender, EventArgs e)
{
// Create a simple sphere. A pipeline is created.
vtkSphereSource sphere = vtkSphereSource.New();
sphere.SetThetaResolution(8);
sphere.SetPhiResolution(16);
A few limitations to this approach mainly prevent the control from being rotated or causes
air-space issues when having overlapping elements. This has generally no impact in the
application design.
Open the toolbox and add a WindowsFormHost XAML component in your main page:
Add the required references to ActiViz depending on your .NET version by following the
instruction in Using Activiz .NET.
An event handler is added to the Load event of the RenderWindowControl. This will be used
to initialize the VTK scene.
Properties and Events of the selected element can be easily edited in the Properties window by
clicking the xaml line of the element.
Edit the MainWindow.xaml.cs code to initialize the scene in the event callback we just added:
using System;
using System.Windows;
using Kitware.VTK;
namespace HelloVTKWPF
{
public partial class MainWindow : Window
{
public MainWindow()
{
InitializeComponent();
}
Once the solution is loaded, add the required Kitware.AvaloniaControls nuget package to the
list of dependencies by following the instruction in Using Activiz .NET Core Nuget
Package. The Kitware.VTK and Kitware.mummy.Runtime packages are automatically
added to the project as a dependency of Kitware.AvaloniaControls.
using Avalonia.Controls;
using Avalonia.Markup.Xaml;
using Kitware.AvaloniaControls;
using Kitware.VTK;
using System;
namespace HelloVTKAvalonia
{
public partial class MainWindow : Window
{
public MainWindow()
{
InitializeComponent();
}
mainView.RenderWindow.AddRenderer(renderer);
Important Notes: These examples were written to be simple, clear demonstrations of the
potential of ActiViz .NET. In general less than an hour was spent writing these examples,
and even the Wikipedia browser was completed in well under a day. Thus Kitware does
not claim that these are bulletproof applications meant for industrial application. Further,
there are some specific limitations of which you should be aware:
● If you install the software in the “Program Files” directory (or other privileged
location), then you will have to build the software with admin privileges, or
preferably, copy the examples to a non-privileged location and fix the appropriate
reference paths.
● If you are building with 32-bit ActiViz (Win32 x86) on a Win64 installation of
Windows you must change the "Target CPU" of the project to use x86 as the
target CPU type, not "Any CPU" which is typical. This step is necessary because
unmanaged code specific to the given processor in linked in during the build
process. With the setting “Any CPU”, the system runs the managed code as x64
and expects any unmanaged dlls to be in x64 format.
● The two pre-compiled applications, the Wikipedia Browser and the File Browser,
may experience problems when requests lead to processing large amounts of data.
Please refer to the specific examples for further clarification.
Despite these caveats, VTK is commonly used in applications requiring robust, high-
performance code. However, this requires extra programming safeguards omitted from
these examples for the sake of clarity.
6.1. Load Image Files Dialog
This example demonstrates a simple dialog to open and display an image. It supports
several file formats including .png, .jpg, .jpeg, .tif, .slc, .dicom, .minc, .bmp, and .pmn. It
will also support .vtk files, which supports data types including polygonal data, structured
grids, and unstructured grids.
This image viewer is unusual in that it places the image on a quadrilateral polygon using
texture mapping. The polygon exists in 3D space so it is possible to move the camera
around the polygon using the render window interactor. The “Simple Dialog Example”
illustrates what the application looks like after loading a simple image file.
One of the important features of this example is the use of events and associated
callbacks to couple the widget with other VTK objects. In this example, we define a
callback function as follows:
Here the “planes” object is a collection of the six planes retrieved from the widget. In
turn, the planes define a clip function to the vtkClipPolyData filter. Next, the callback
function is connected to the box widget by observing the end interaction event. (Typically
widgets provide three events: start interaction, interaction, and end interaction.)
boxWidget.EndInteractionEvt +=
new vtkObject.vtkObjectEventHandler(SelectPolygons);
Thus, when the widget is manipulated, the event is triggered (at the end of motion) and
the callback function is invoked. Thus widgets are very easy to add and to use in ActiViz.
6.4. Streamline Generation
This example shows some of the
visualization capabilities of VTK. A
structured grid (think of a volume warped in
3D space so that it is topologically regular
but geometrically distorted) is read with
associated scalar and vector data. This 3D
dataset is the result of a computational
simulation of combustion in a segment of an
annular combustor from an aircraft engine.
Once you compile and run the example, aside from using the interactor to position the
camera, it is possible to move the line widget. Do this by selecting the widget end points
(marked as little balls), or grabbing the line and translating it around. It is also possible to
modify the code to increase the line resolution in order to generate more streamlines
emanating from it.
The application consists of two panels: on the left a graph browser indicating the
relationship of Wikipedia articles to one another; on the right, the Wikipedia web page
corresponding to the recently selected graph node (see Figure below).
The application enables the user to type in a search string as a start point for the browser
(make sure to select the “Go” button to initiate the search). In the figure below, the initial
search string is “VTK”. Given this initial string, the search expands out into N links
where N is specified by the user (here the default value is 10). The first N links in the
initial string are followed to other Wikipedia pages, and this process continues H times,
where H is the user specified number of hops to follow. Note that N and H must be
carefully specified. If these numbers are big enough, the graph may grow rapidly (it is
possible to crash the application as currently written in N and H are too large). Further,
since the nodes represent a web page, each page must be accessed over the internet, and
then parsed, which can be very slow depending on network performance.
Once the initial graph is specified, it is possible to expand it iteratively. Simply use the
left mouse button to select a rectangular selection region in the left panel. Any nodes in
the selection region are further expanded in the graph. Note that when expanded, VTK’s
graph layout algorithm will run and can reposition the existing graph nodes. You may also
select a single node by left-mouse clicking on the node. If you select a single node, its
corresponding Wikipedia page is shown in the right panel. If you select a group of nodes
with a rectangular selection, then an arbitrary selection from the group is made and the
corresponding Wikipedia page is shown in the right panel.
The graph layout has some features that facilitate navigation. While the left mouse button
is used for selection, the middle mouse button can be used to translate the graph, and the
right mouse button to zoom in and out (move the mouse “up” to zoom, and “down” to
zoom out). Zooming in and out causes text to appear and disappear dynamically. Finally,
if your mouse has a scrolling wheel, scrolling the wheel also zooms in and out on the
graph.
The source code for this application is included in the ActiViz .NET examples directory;
feel free to extend it. Other VTK classes exist to improve the behavior of this application,
including ways to adjust graph layout, control mouse bindings, change the selection
process, and populate the scene.
6.6. Sphere Puzzle
This is a cute example much like a
Rubik’s cube puzzle except on a
sphere rather than a cube. After the
application initializes itself by
randomizing the panels on the
sphere, the user attempts to restore
the sphere to the proper coloring (to
see the final coloring, hit the
“Reset” button).
6.9. Decimation
Decimation, or polygon reduction, is a technique used in computer graphics to reduce the
complex of geometric models. For example, in the figure below, the original model of Big
Buck Bunny contains over 16,000 polygons; the decimated model contains approximately
8,000 polygons. In computer graphics and visualization, it is common to produce models
with large polygon counts. Such models can be difficult to manipulate due to the delays
in rendering and processing the data. Decimation is used to limit data sizes and thereby
improve interaction rates.
In this example, models from the open-source movie Big Buck Bunny are used to
demonstrate decimation (models copyright the Blender Foundation |
www.bigbuckbunny.org). VTK provides several different decimation algorithms with
varying levels of speed and fidelity. The fastest algorithm is vtkQuadricClustering, the
algorithm that generates models with the best fidelity is vtkQuadricDecimation. In the
example above, vtkDecimatePro is used. (See the included documentation for more
information.) Since the source code is provided, interested readers may want to try
different algorithms.
6.10. File Browser
The next example is a useful application for quickly locating large files and directories in
a directory tree. The application uses VTK’s tree map class and other information
visualization classes. A tree map is a layout scheme that represents the “size” of each
node in a tree (including the node’s children) by a rectangle. In turn, the children are
embedded in the parent’s rectangle in a recursive process. The meaning of size varies
depending on the application. In this example, size means the disk space usage of a file
(if a leaf node) or the disk usage of the files and subdirectories contained within it (if an
intermediate, directory node).
To use the application, simply load the directory you are interested in. Depending on the
size of the directory and the subdirectories
and files contained within it, the program
may take anywhere from one or two seconds
to minutes to execute. Once the image
(shown) is generated, you can interact with
the display. Labels are placed in the center of
each rectangle and dynamically resize based
as the user zooms in and out towards the tree
map. Further, by moving the mouse pointer
over the tree map a label will appear
indicating the current directory or file at
which you are pointing. Selecting (left
mouse button) brings up a file browser. Use
the right mouse button to zoom, and the
center button to pan across the tree map.
* Neither name of Kitware, Inc., Kitware SAS, nor the names of any
contributors
may be used to endorse or promote products derived from this software
without
specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
* Neither name of Kitware, Inc., Kitware SAS, nor the names of any
contributors
may be used to endorse or promote products derived from this software
without
specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.