Unplugged Viz
High-performance scientific visualization isn't just for the workstation anymore
|
The samples contained within the download reference the included Unplugged Viz DLLs and show the basic functionality.
This topic demonstrates how to add an Unplugged Viz to your Xamarin.Forms app using C#. For more detailed information, see the API documentation here.
Unplugged Viz includes three controls: a ColorMappedImageView
, a ColorMappedPlotView<T>
, and an XYPlotView<T>
. ColorMappedImageView
and ColorMappedPlotView<T>
are used to plot 3-dimensional data in 2D with a user-definable color map; XYPlotView<T>
is used for plotting 2-dimensional data in either line or bar chart form, with a color map applied.
Note: Unplugged Viz depends on the MonoGame Framework. You should add a reference to the relevant MonoGame.Framework
package (available via NuGet) to your each platform-specific project in order to use it. To use the CameraControl
object, a reference to MonoGame.Framework.Portable
is required on your PCL project. This library is available via NuGet but is currently a prerelease version and cannot be installed in Xamarin Studio; you may need to download the package manually.
In order to ensure Unplugged Viz's custom renderers are registered by Xamarin Forms, add a reference to Durwella.Unplugged.Viz.iOS.dll
include the following in the initialization code for your iOS project (for example, in AppDelegate.cs
).
In your Android project, the call is analogous; however, you should pass in a reference to your MainActivity
object.
It is recommended that you place this line immediately before the call LoadApplication(new App ());
.
Durwella.Unplugged.Viz.ColorMappedImageView
inherits from Xamarin.Forms.View
, and therefore can be used anywhere you would use a View
. It can take data either as a 2-dimensional array of byte
, int
, or float
, or as a Durwella.Unplugged.Viz.RawDataArray
. ColorMappedImageView
is intended for cases when the data is in the form of a raw 1-dimensional array of byte
, int
, or float
; it is intended to allow the user to avoid conversion to a 2D array for improved performance.
Durwella.Unplugged.Viz.ColorMappedPlotView<T>
inherits from ColorMappedImageView
and is a generic class where T
is the class of the data to be displayed; T
may be byte
, int
, or float
. For situations where the user data is already stored as a T[,]
, ColorMappedPlotView<T>
allows the user to create a plot view in a type-safe manner.
The following code illustrates creating a simple ContentPage
containing a ColorMappedPlotView<float>
in C#.
The same result can be obtained in XAML.
Full API documentation can be found here; however, a description of some important properties of ColorMappedPlotView<T>
is given below.
Data
: A T[,]
array defining the data to be plotted.ColorMapRange
: A Durwella.Unplugged.Viz.RangeF
defining the Data
values corresponding to the minimum and maximum of the ColorMap
.ColorMap
: A Xamarin.Forms.Color[]
array defining the color map. The full color map is interpolated linearly between values in the array and mapped to the Data
between the two extremes of the ColorMapRange
.DataRange
: A UDurwella.Unplugged.Viz.RectangleF
the defines the numerical scales of the X- and Y-axes of the plot.All properties are exposed as BindingProperties
; for example, a ColorMappedPlotView<float>
might be defined in XAML as follows.
A simple example is illustrated below. In this example, a 100x100 int
array is created which varies diagonally from 0 at (0,0) to 200 at (100,100). It is then plotted using a ROYGBIV color map.
Durwella.Unplugged.Viz.XYPlotView<T>
is used to plot 2-dimensional data with a color map. There are two types of XYPlot<T>
s:
Use of XYPlotView<T>
is very similar to the use of ColorMappedPlotView<T>
; the differences will be discussed below.
Data
: The Data
array is a 1-dimensional T[]
array instead of T[,]
as in ColorMappedPlotView<T>
.DataRange
: DataRange
is a 1-dimensional UDurwella.Unplugged.Viz.RangeF
instead of a 2-dimensional Durwella.Unplugged.Viz.RectangleF
. It defines the numerical scale of the independent axis; the dependent axis is defined by the ColorMapRange
.IsHorizontal
: By default, XYPlot<T>
s are plotted vertically from the top to the bottom of the screen. IsHorizontal
is a boolean property that switches to a horizontal plot when set to true
.IsBarChart
: XYPlot<T>
s are displayed as line graphs by default. IsBarChart
can be set to true
to switch to a bar chart display.A simple example is illustrated below. In this example, a 21-element float[]
corresponding to the normal distribution is plotted as a horizontal bar chart. The x-axis ranges from -10 to 10, and the y-axis is set by the ColorMapRange
, which defaults to [0,1]
for XYPlotView<float>
.
Durwella.Unplugged.Viz.TumbleView
is used to display 3-dimensional models.
The TumbleView
class is quite simple; it contains just two properties. Detailed information about each property will follow.
CameraControl
: Durwella.Unplugged.Viz.CameraControl
object which allows the relative orientation and position of the camera and the view to be controlled.Models
: An ObservableCollection<Durwella.Unplugged.Viz.IGeometry
. The collection of models to be displayed in the TumbleView
.Durwella.Unplugged.Viz.CameraControl
allows the control of the relative positions and orientations of the camera and the view. Using the default implementation, the camera will always point at the origin (0,0,0)
and use the positive y-direction as the up direction. This can be changed by overriding methods (see the documentation); however, use care – the center of rotation when the use interacts with the view will always be the origin, which can result in strange interaction dynamics.
Important properties and methods of CameraControl
are as follows:
Orientation
: A Microsoft.Xna.Framework.Quaternion
describing the orientation of the TumbleView
.Roll
: A Quaternion
describing the orientation of the CameraControl
. The rotation of the scene is calculated by multiplying Roll * Orientation
.Translation
: A Microsoft.Xna.Framework.Vector3
describing the position of the view.CameraPosition
: A Vector3
describing the position of the camera.ZoomScale
: A float
describing the zoom level of the camera; default to 1.0f
.CreateModelMatrix()
, CreateViewProjectionMatrix()
, and CreateModelViewProjectionMatrix()
: virtual methods which may be overridden to alter camera behavior. Default implementations of these methods are given in the documentation.All models to be used with TumbleView
must implement Durwella.Unplugged.Viz.IGeometry
and have certain attributes applies.
Control of model properties is via attributes. Every model to be used must include the following:
DrawWithAttribute
defining how model will be drawn using OpenGL.ShaderAttribute
or one or more each of VertexShaderAttribute
s and FragmentShaderAttribute
s, which define the shaders to be used in displaying the model.The set of properties that may be used in shaders is limited to the following. Each property is defined in an interface; the model must implement the specified interface to use the property in a shader. The requisite interface for each property is given in parentheses.
Array Vertices
(IGeometry
)int[] Indices
(IIndexedGeometry
)Array TextureCoordinates
(ITexturedgGeometry
)Array TextureMap
(ITextureMappedGeometry
)object Image
(IImageMappedGeometry
)Array ColorMap
, float ColorMapMinimum
, float ColorMapMaximum
(IColorMappedGeometry
)float[] Translation
(ITranslatableGeometry
)float[,] Orientation
(IRotatableGeometry
)Array[] Color
, (IColoredGeometry
)float[,] Normals
, float[] LightPosition
(ILitGeometry
)All models automatically get access to a Rotation
and a ModelViewProjection
property, which are the result of the CreateRotationMatrix()
and CreateModelViewProjectionMatrix()
methods, respectivley, on the CameraControl
associated with the TumbleView
. Your shader must include these properties even if they are unused (see below). If you need additional properties, please contact us at unplugged@durwella.com.
The properties are tagged with attributes to indicate their role in the shader. The attributes are listed below; see the API documentation for more information.
VertexAttributeAttribute
VertexIndicesAttribute
UniformAttribute
TextureMapAttribute
ColorMapAttribute
The component ships with base classes which may be useful as starting points for model definition: IndexedGeometryModel
, IndexedGeometryTextureMappedModel
, and IndexedGeometryTextureMappedLitModel
.
Consider definining a simple model for an oil wellbore. The wellbore will be modeled as a connected series of line segments with a specified color. A possible definition of the well model is as follows:
(Note: The model inherits from Xamarin.Forms.BindableObject
, despite the fact that no property changed notifications are raised, and IGeometry
must implement INotifyPropertyChanged
.)
DrawWithAttribute
with the following properties: "line strip" primitives and no backface culling. (See the documentation.)ShaderAttribute
with a ShaderName
of "WellModel". This means that in each platform-specific project should be found two shaders: the fragment shader "WellModel.fsh" and the vertex shader "WellModel.vsh".VertexAttribute
property Vertices
and a Uniform
property Color
.The two shaders are given below:
WellModel.vsh:
(Note the inclusion of Rotation
despite the fact it is unused.)
WellModel.fsh:
For more examples see the API documentation, the included sample app, or the official Durwella Unplugged Viz example app.
To create a simple view of the well model, a TumbleView
can be used as follows:
The standard license received when purchasing Unplugged Viz through the Component Store will work indefinitely with no restrictions. The sample application included with the download is a special restricted license that should not be used for any other application.
The free Trial version of the component has substantially restricted functionality and should not be used in published apps. The restrictions in this version of the component include:
ColorMappedPlotView<byte>
, XYPlotView<byte>
, and TumbleView
can be used.byte[32,32]
and byte[16]
for ColorMappedPlotView<byte>
and XYPlotView<byte>
, respectively.TumbleView
s are limited to 1 model with up to 128 vertices.CameraControl
s cannot be used.TextureMappedModel
shaders can be used.You may request a more full-featured license by requesting one at unplugged@durwella.com. Trial licenses should not be used for published apps. They offer no restrictions on functionality but are limited to 14 days from the time they are issued; any app using the component with an expired trial license will cease to function.
You will receive your license key on purchase.
In your code, before calling the initialization code described above, set the property Durwella.Unplugged.Viz.License.Key
to the string. Sample code is shown below.
If your license is an expired trial license, an Durwella.Unplugged.Viz.ExpiredLicenseException
will be thrown when setting License.Key
. If it's invalid for any other reason (or when accessing functionality not permitted by your licens) an Durwella.Unplugged.Viz.InvalidLicenseException
will be thrown.