Class ABREngine

The ABREngine class is the main operational MonoBehaviour Singleton for the ABREngine-UnityPackage. It is in charge of kicking off all startup processes for ABR, including setting up connections with the server, the data listener, VisAssets and Data managers, etc.

Inheritance
object
Object
Component
Behaviour
MonoBehaviour
Singleton<ABREngine>
ABREngine
Namespace: IVLab.ABREngine
Assembly: IVLab.ABREngine.Runtime.dll
Syntax
public class ABREngine : Singleton<ABREngine>
Examples

Usage of ABREngine.Instance

Most methods of the ABREngine can be accessed through its singleton Instance without needing to do a GetComponent:

string mediaPath = ABREngine.Instance.MediaPath;

Example: Getting Started with Unity C# and ABR

This example shows how to create an ABR visualization in code using one data impression.

Note

You can also import this example using the Unity Package Manager. In Unity, go to Window > Package Manager, find the ABREngine package, and import the "Documentation Examples" sample project.

The general process for making an ABR visualization in C# code is:

  1. Import data using LoadData(string)
  2. Import VisAssets using GetVisAsset<T>(Guid).
  3. Create a DataImpression to combine the data and visuals together (using Create<T>(string, Guid, bool)).
  4. Use RegisterDataImpression(DataImpression, DataImpressionGroup, bool) to add the impression to the engine.
  5. Render the data and visuals to the screen using Render().
using UnityEngine;
using IVLab.ABREngine;

// Look in the Resources folder of this example to see the data and VisAssets.
// Before running this example, make sure the ABR Configuration is set to ABRExamplesConfig!
public class ABREngineExample : MonoBehaviour
{
    // Editable in Unity Editor
    [SerializeField, Tooltip("Animated spin rate for the data"), Range(0.0f, 30.0f)]
    private float spinRate = 1.0f;

    // Store the data impression for use in Update()
    private SimpleGlyphDataImpression dataImpression;

    void Start()
    {
        // Load example VisAssets from resources
        // A white to orange colormap
        ColormapVisAsset orange = ABREngine.Instance.VisAssets.GetVisAsset<ColormapVisAsset>(new System.Guid("66b3cde4-034d-11eb-a7e6-005056bae6d8"));

        // A triangular glyph
        GlyphVisAsset triangular = ABREngine.Instance.VisAssets.GetVisAsset<GlyphVisAsset>(new System.Guid("1af02820-f1ed-11e9-a623-8c85900fd4af"));



        // Load an example dataset from resources
        // This Key Data has multiple scalar variables defined at each point in
        // the dataset. We'll use the "XAxis" variable, this increases
        // monotonically from -10 to +10 along the X axis.
        KeyData pointsKd = ABREngine.Instance.Data.LoadData("Demo/Wavelet/KeyData/Points");
        ScalarDataVariable xAxisScalarVar = pointsKd.GetScalarVariable("XAxis");


        // Create a Glyph DataImpression and store it for later use
        dataImpression = DataImpression.Create<SimpleGlyphDataImpression>("Example Points");

        // Assign the key data to the Data Impression. This is the "Geometry"
        // with which the data impression will be drawn.
        dataImpression.keyData = pointsKd;

        // Tell ABR to map the Color visual channel of the Data Impression to
        // the "XAxis" variable.
        dataImpression.colorVariable = xAxisScalarVar;

        // Lastly, apply the colormap and glyph (visual style for this Data
        // Impresssion)
        dataImpression.colormap = orange;
        dataImpression.glyph = triangular;


        // Finally, add the Data Impression to the ABREngine, and re-render.
        // Note, this will automatically look for the DataImpression Group
        // "Demo/Wavelet" in the scene, and put this data impression as a child
        // of that group.
        ABREngine.Instance.RegisterDataImpression(dataImpression);
        ABREngine.Instance.Render();
    }

    void Update()
    {
        // Access the individual data impression that was created earlier and
        // spin it around.
        //
        // Usually we want to do any manipulations like this at the "Group"
        // level rather than individual data impressions so that multiple data
        // impressions in the same dataset remain spatially registered with each
        // other.
        DataImpressionGroup pointsGroup = ABREngine.Instance.GetGroupFromImpression(dataImpression);
        pointsGroup.transform.rotation *= Quaternion.Euler(new Vector3(0, Time.deltaTime * spinRate, 0));
    }
}

Example: Using Custom Data

This example shows how to quickly get up and running with a custom-defined dataset and building your own data impressions. Before the steps in the previous example, you will also need to:

  1. Define your data in some `List`s.
  2. Use the RawDatasetAdapter to convert the `List` into an ABR RawDataset, or import an existing ABR RawDataset using LoadRawDataset(string).
  3. Import that RawDataset into ABR using ImportRawDataset(RawDataset) (optionally, giving the dataset a data path identifier for easier semantic access later).
using System.Collections.Generic;
using UnityEngine;
using IVLab.ABREngine;

/// <summary>
/// Example for the main ABREngine class.
/// </summary>
public class CustomDataABRExample : MonoBehaviour
{
    void Start()
    {
        // STEP 1: Define data
        // 9 points in 3D space
        List<Vector3> vertices = new List<Vector3>
            {
                new Vector3(0.0f, 0.5f, 0.0f),
                new Vector3(0.0f, 0.6f, 0.1f),
                new Vector3(0.0f, 0.4f, 0.2f),
                new Vector3(0.1f, 0.3f, 0.0f),
                new Vector3(0.1f, 0.2f, 0.1f),
                new Vector3(0.1f, 0.3f, 0.2f),
                new Vector3(0.2f, 0.0f, 0.0f),
                new Vector3(0.2f, 0.3f, 0.1f),
                new Vector3(0.2f, 0.1f, 0.2f),
            };

        // Data values for those points
        List<float> data = new List<float>();
        for (int i = 0; i < vertices.Count; i++) data.Add(i);

        // Named scalar variable
        Dictionary<string, List<float>> scalarVars = new Dictionary<string, List<float>> { { "someData", data } };

        // Define some generous bounds
        Bounds b = new Bounds(Vector3.zero, Vector3.one);

        // STEP 2: Convert the point list into ABR Format
        RawDataset abrPoints = RawDatasetAdapter.PointsToPoints(vertices, b, scalarVars, null);

        // STEP 3: Import the point data into ABR so we can use it
        KeyData pointsKD = ABREngine.Instance.Data.ImportRawDataset(abrPoints);

        // STEP 4: Import a colormap visasset
        ColormapVisAsset cmap = ABREngine.Instance.VisAssets.LoadVisAsset<ColormapVisAsset>(new System.Guid("66b3cde4-034d-11eb-a7e6-005056bae6d8"));

        // STEP 5: Create a Data Impression (layer) for the points, and assign some key data and styling
        SimpleGlyphDataImpression di = DataImpression.Create<SimpleGlyphDataImpression>("Simple Points");
        di.keyData = pointsKD;                                 // Assign key data (point geometry)
        di.colorVariable = pointsKD.GetScalarVariables()[0];   // Assign scalar variable "someData"
        di.colormap = cmap;                                    // Apply colormap
        di.glyphSize = 0.002f;                                 // Apply glyph size styling

        // STEP 6: Register impression with the engine
        ABREngine.Instance.RegisterDataImpression(di);

        // STEP 7: Render the visualization
        ABREngine.Instance.Render();
    }
}

Fields

| Improve this Doc View Source

OnStateChanged

Delegate that is called whenever ABRState is updated.

Declaration
public ABREngine.StateChangeDelegate OnStateChanged
Field Value
Type Description
ABREngine.StateChangeDelegate
Examples

Developers may need to use this if they want to know when the state has been updated:

using UnityEngine;
using IVLab.ABREngine;
public class ABRStateExample : MonoBehaviour
{
    void Start()
    {
        ABREngine.Instance.OnStateChanged += ExampleOnStateChanged;
    }
    void ExampleOnStateChanged(JObject state)
    {
        Debug.Log(state["version"]);
    }
}
| Improve this Doc View Source

PackagePath

The package path defined in package.json.

Note

With project builds, the PackagePath assumes that everything is located relative to the built executable. If the current working directory is something besides the directory ABR is located in, there may be problems.

Warning

If the package path changes for any reason, this will need to be updated!

Declaration
public const string PackagePath = "Packages/edu.umn.cs.ivlab.abrengine/"
Field Value
Type Description
string
| Improve this Doc View Source

SchemasFolder

Folder, relative to this package, where the ABR JSON schemas are located.

Declaration
public const string SchemasFolder = "ABRSchemas~"
Field Value
Type Description
string

Properties

| Improve this Doc View Source

ABRTransform

Cached, readonly version of the ABREngine transform so it can be accessed in a non-main thread

Declaration
public Transform ABRTransform { get; }
Property Value
Type Description
Transform
| Improve this Doc View Source

Config

Provides access to all of the ABRConfig options that were loaded in at startup. You can safely change this config at runtime without messing up the ScriptableObject representing the underlying ABRConfig.

Declaration
public ABRConfig Config { get; }
Property Value
Type Description
ABRConfig
| Improve this Doc View Source

ConfigPrototype

Config "Prototype" to use for the current ABR configuration. This is set in edit-mode and should NOT be changed at runtime. Instead, use Config.

Declaration
public static ABRConfig ConfigPrototype { get; set; }
Property Value
Type Description
ABRConfig
| Improve this Doc View Source

Data

System-wide manager for Data (the geometry and variables that make up the visualization)

Declaration
public DataManager Data { get; }
Property Value
Type Description
DataManager
| Improve this Doc View Source

IsInitialized

True if the ABREngine is set up and completely ready to begin rendering. Only returns true once all setup has finished, including:

  • Loading the ABRConfig
  • Connecting to the server (if applicable)
  • Loading any initial state specified by the programmer, or the remote state from the server
Declaration
public bool IsInitialized { get; }
Property Value
Type Description
bool
| Improve this Doc View Source

MediaPath

Media path where all datasets and visassets are located. If the media path is provided in the ABRConfig, use that media path. Otherwise, use Unity's Application.persistentDataPath.

Declaration
public string MediaPath { get; }
Property Value
Type Description
string
| Improve this Doc View Source

SchemasPath

Full path where the ABR JSON schemas are located.

Declaration
public static string SchemasPath { get; }
Property Value
Type Description
string
| Improve this Doc View Source

State

JSON representation of the state that has been previously loaded into ABR

Declaration
public JObject State { get; }
Property Value
Type Description
JObject
| Improve this Doc View Source

VisAssets

System-wide manager for VisAssets (visual elements used in the visualization)

Declaration
public VisAssetManager VisAssets { get; }
Property Value
Type Description
VisAssetManager

Methods

| Improve this Doc View Source

Awake()

The ABREngine class is the main operational MonoBehaviour Singleton for the ABREngine-UnityPackage. It is in charge of kicking off all startup processes for ABR, including setting up connections with the server, the data listener, VisAssets and Data managers, etc.

Declaration
protected override void Awake()
Overrides
IVLab.Utilities.Singleton<IVLab.ABREngine.ABREngine>.Awake()
| Improve this Doc View Source

ClearState()

Remove all data impression groups from the ABR scene (and in turn, remove all data impressions).

Declaration
public void ClearState()
Remarks

This method does remove all data impressions, but it does not clean up other state values like custom colormaps, lighting, and gradients.

| Improve this Doc View Source

CreateDataImpressionGroup(string)

Add a new data impression group with a particular name

Declaration
public DataImpressionGroup CreateDataImpressionGroup(string name)
Parameters
Type Name Description
string name

Name of the new data impression group that will be created
Returns
Type Description
DataImpressionGroup

The group that has been added.
| Improve this Doc View Source

CreateDataImpressionGroup(string, Guid)

Add a new data impression group with a particular UUID

Declaration
public DataImpressionGroup CreateDataImpressionGroup(string name, Guid uuid)
Parameters
Type Name Description
string name

Name of the new data impression group that will be created
Guid uuid

UUID to use for the new data impression group
Returns
Type Description
DataImpressionGroup

The group that has been added.
| Improve this Doc View Source

CreateDataImpressionGroup(string, Guid, Bounds?, Matrix4x4?)

Add a new data impression group with a particular UUID, bounds, and transformation

Declaration
public DataImpressionGroup CreateDataImpressionGroup(string name, Guid uuid, Bounds? containerBounds, Matrix4x4? transformMatrix)
Parameters
Type Name Description
string name

Name of the new data impression group that will be created
Guid uuid

UUID to use for the new data impression group
Bounds? containerBounds

Default bounds to use for this data impression group. Data will be "squished" inside this bounding box.
Matrix4x4? transformMatrix

Default position/rotation/scale (in Unity coordinates) to use for the data impression group.
Returns
Type Description
DataImpressionGroup

The group that has been added.
| Improve this Doc View Source

DuplicateDataImpression(DataImpression)

Create and return a duplicate copy of the given data impression. All inputs in the new data impression are identical to the one being copied. By default duplicate data impressions will be placed in their default groups (grouped by dataset).

Declaration
public DataImpression DuplicateDataImpression(DataImpression impression)
Parameters
Type Name Description
DataImpression impression

The data impression that should be duplicated.
Returns
Type Description
DataImpression

The new data impression.
| Improve this Doc View Source

DuplicateDataImpression(DataImpression, DataImpressionGroup)

Create and return a duplicate copy of the given data impression. The data impression will be placed within the specified DataImpressionGroup group. If group is null, the default group will be used (either conforming to the input dataset that the data impression has, or the default empty group)

Declaration
public DataImpression DuplicateDataImpression(DataImpression dataImpression, DataImpressionGroup group)
Parameters
Type Name Description
DataImpression dataImpression

The data impression that should be duplicated.
DataImpressionGroup group

The DataImpressionGroup that the new data impression should be placed into.
Returns
Type Description
DataImpression

The new data impression.
| Improve this Doc View Source

DuplicateDataImpression(DataImpression, bool)

Create and return a duplicate copy of the given data impression, but ensure that the copy is within the same data impression group as its source.

Declaration
public DataImpression DuplicateDataImpression(DataImpression dataImpression, bool retainGroup = true)
Parameters
Type Name Description
DataImpression dataImpression

The data impression that should be duplicated.
bool retainGroup

Ensure the copy of the data impression will exist within the same group as the original, regardless of whether different data have been applied.
Returns
Type Description
DataImpression

The new data impression.
| Improve this Doc View Source

DuplicateDataImpression(Guid)

Create and return a duplicate copy of the data impression with a given UUID. All inputs in the new data impression are identical to the one being copied. By default duplicate data impressions will be placed in their default groups (grouped by dataset).

Declaration
public DataImpression DuplicateDataImpression(Guid uuid)
Parameters
Type Name Description
Guid uuid

UUID of the data impression that should be duplicated.
Returns
Type Description
DataImpression

The new data impression.
| Improve this Doc View Source

GetABRConfigs()

Get all the configurations available to ABR

Declaration
public static List<ABRConfig> GetABRConfigs()
Returns
Type Description
List<ABRConfig>
| Improve this Doc View Source

GetAllDataImpressions()

Retrieve ALL data impressions that currently exist within the Engine, over ALL data impression groups.

Declaration
public List<DataImpression> GetAllDataImpressions()
Returns
Type Description
List<DataImpression>

All data impressions that exist in the ABREngine
| Improve this Doc View Source

GetDataImpression(Func<DataImpression, bool>)

Retreive the first data impression found with a particular function crieteria (similar to a "filter" or Linq-esque "where" operation).

Declaration
public DataImpression GetDataImpression(Func<DataImpression, bool> criteria)
Parameters
Type Name Description
Func<DataImpression, bool> criteria

Function that takes each data impression of any type and returns a boolean.
Returns
Type Description
DataImpression

The first data impression of any type that matches criteria, null otherwise.
| Improve this Doc View Source

GetDataImpression(Guid)

Retreive a particular data impression from the Engine

Declaration
public DataImpression GetDataImpression(Guid uuid)
Parameters
Type Name Description
Guid uuid

Unique identifier (UUID) of the data impression to be fetched from the engine
Returns
Type Description
DataImpression

A data impression if found, null otherwise.
Remarks

It is often more useful to use the GetDataImpression<T>(string) method since it returns an actual data impression instead of a DataImpression.

| Improve this Doc View Source

GetDataImpression(string)

Returns the first data impression that is associated with the keyDataPath. Although it is often the case that there will be only one data impression per keyDataPath, this is not always the case. GetDataImpressions(string keyDataPath) can be used to get all of the data impressions with the same keyDataPath.

Declaration
public DataImpression GetDataImpression(string keyDataPath)
Parameters
Type Name Description
string keyDataPath
Returns
Type Description
DataImpression
| Improve this Doc View Source

GetDataImpressionGroup(Guid)

Retrieve a particular data impression group from the scene

Declaration
public DataImpressionGroup GetDataImpressionGroup(Guid uuid)
Parameters
Type Name Description
Guid uuid

UUID of the data impression group that should be retrieved.
Returns
Type Description
DataImpressionGroup

A data impression with a given UUID
| Improve this Doc View Source

GetDataImpressionGroup(string)

The ABREngine class is the main operational MonoBehaviour Singleton for the ABREngine-UnityPackage. It is in charge of kicking off all startup processes for ABR, including setting up connections with the server, the data listener, VisAssets and Data managers, etc.

Declaration
public DataImpressionGroup GetDataImpressionGroup(string name)
Parameters
Type Name Description
string name
Returns
Type Description
DataImpressionGroup
Examples

Usage of ABREngine.Instance

Most methods of the ABREngine can be accessed through its singleton Instance without needing to do a GetComponent:

string mediaPath = ABREngine.Instance.MediaPath;

Example: Getting Started with Unity C# and ABR

This example shows how to create an ABR visualization in code using one data impression.

Note

You can also import this example using the Unity Package Manager. In Unity, go to Window > Package Manager, find the ABREngine package, and import the "Documentation Examples" sample project.

The general process for making an ABR visualization in C# code is:

  1. Import data using LoadData(string)
  2. Import VisAssets using GetVisAsset<T>(Guid).
  3. Create a DataImpression to combine the data and visuals together (using Create<T>(string, Guid, bool)).
  4. Use RegisterDataImpression(DataImpression, DataImpressionGroup, bool) to add the impression to the engine.
  5. Render the data and visuals to the screen using Render().
using UnityEngine;
using IVLab.ABREngine;

// Look in the Resources folder of this example to see the data and VisAssets.
// Before running this example, make sure the ABR Configuration is set to ABRExamplesConfig!
public class ABREngineExample : MonoBehaviour
{
    // Editable in Unity Editor
    [SerializeField, Tooltip("Animated spin rate for the data"), Range(0.0f, 30.0f)]
    private float spinRate = 1.0f;

    // Store the data impression for use in Update()
    private SimpleGlyphDataImpression dataImpression;

    void Start()
    {
        // Load example VisAssets from resources
        // A white to orange colormap
        ColormapVisAsset orange = ABREngine.Instance.VisAssets.GetVisAsset<ColormapVisAsset>(new System.Guid("66b3cde4-034d-11eb-a7e6-005056bae6d8"));

        // A triangular glyph
        GlyphVisAsset triangular = ABREngine.Instance.VisAssets.GetVisAsset<GlyphVisAsset>(new System.Guid("1af02820-f1ed-11e9-a623-8c85900fd4af"));



        // Load an example dataset from resources
        // This Key Data has multiple scalar variables defined at each point in
        // the dataset. We'll use the "XAxis" variable, this increases
        // monotonically from -10 to +10 along the X axis.
        KeyData pointsKd = ABREngine.Instance.Data.LoadData("Demo/Wavelet/KeyData/Points");
        ScalarDataVariable xAxisScalarVar = pointsKd.GetScalarVariable("XAxis");


        // Create a Glyph DataImpression and store it for later use
        dataImpression = DataImpression.Create<SimpleGlyphDataImpression>("Example Points");

        // Assign the key data to the Data Impression. This is the "Geometry"
        // with which the data impression will be drawn.
        dataImpression.keyData = pointsKd;

        // Tell ABR to map the Color visual channel of the Data Impression to
        // the "XAxis" variable.
        dataImpression.colorVariable = xAxisScalarVar;

        // Lastly, apply the colormap and glyph (visual style for this Data
        // Impresssion)
        dataImpression.colormap = orange;
        dataImpression.glyph = triangular;


        // Finally, add the Data Impression to the ABREngine, and re-render.
        // Note, this will automatically look for the DataImpression Group
        // "Demo/Wavelet" in the scene, and put this data impression as a child
        // of that group.
        ABREngine.Instance.RegisterDataImpression(dataImpression);
        ABREngine.Instance.Render();
    }

    void Update()
    {
        // Access the individual data impression that was created earlier and
        // spin it around.
        //
        // Usually we want to do any manipulations like this at the "Group"
        // level rather than individual data impressions so that multiple data
        // impressions in the same dataset remain spatially registered with each
        // other.
        DataImpressionGroup pointsGroup = ABREngine.Instance.GetGroupFromImpression(dataImpression);
        pointsGroup.transform.rotation *= Quaternion.Euler(new Vector3(0, Time.deltaTime * spinRate, 0));
    }
}

Example: Using Custom Data

This example shows how to quickly get up and running with a custom-defined dataset and building your own data impressions. Before the steps in the previous example, you will also need to:

  1. Define your data in some `List`s.
  2. Use the RawDatasetAdapter to convert the `List` into an ABR RawDataset, or import an existing ABR RawDataset using LoadRawDataset(string).
  3. Import that RawDataset into ABR using ImportRawDataset(RawDataset) (optionally, giving the dataset a data path identifier for easier semantic access later).
using System.Collections.Generic;
using UnityEngine;
using IVLab.ABREngine;

/// <summary>
/// Example for the main ABREngine class.
/// </summary>
public class CustomDataABRExample : MonoBehaviour
{
    void Start()
    {
        // STEP 1: Define data
        // 9 points in 3D space
        List<Vector3> vertices = new List<Vector3>
            {
                new Vector3(0.0f, 0.5f, 0.0f),
                new Vector3(0.0f, 0.6f, 0.1f),
                new Vector3(0.0f, 0.4f, 0.2f),
                new Vector3(0.1f, 0.3f, 0.0f),
                new Vector3(0.1f, 0.2f, 0.1f),
                new Vector3(0.1f, 0.3f, 0.2f),
                new Vector3(0.2f, 0.0f, 0.0f),
                new Vector3(0.2f, 0.3f, 0.1f),
                new Vector3(0.2f, 0.1f, 0.2f),
            };

        // Data values for those points
        List<float> data = new List<float>();
        for (int i = 0; i < vertices.Count; i++) data.Add(i);

        // Named scalar variable
        Dictionary<string, List<float>> scalarVars = new Dictionary<string, List<float>> { { "someData", data } };

        // Define some generous bounds
        Bounds b = new Bounds(Vector3.zero, Vector3.one);

        // STEP 2: Convert the point list into ABR Format
        RawDataset abrPoints = RawDatasetAdapter.PointsToPoints(vertices, b, scalarVars, null);

        // STEP 3: Import the point data into ABR so we can use it
        KeyData pointsKD = ABREngine.Instance.Data.ImportRawDataset(abrPoints);

        // STEP 4: Import a colormap visasset
        ColormapVisAsset cmap = ABREngine.Instance.VisAssets.LoadVisAsset<ColormapVisAsset>(new System.Guid("66b3cde4-034d-11eb-a7e6-005056bae6d8"));

        // STEP 5: Create a Data Impression (layer) for the points, and assign some key data and styling
        SimpleGlyphDataImpression di = DataImpression.Create<SimpleGlyphDataImpression>("Simple Points");
        di.keyData = pointsKD;                                 // Assign key data (point geometry)
        di.colorVariable = pointsKD.GetScalarVariables()[0];   // Assign scalar variable "someData"
        di.colormap = cmap;                                    // Apply colormap
        di.glyphSize = 0.002f;                                 // Apply glyph size styling

        // STEP 6: Register impression with the engine
        ABREngine.Instance.RegisterDataImpression(di);

        // STEP 7: Render the visualization
        ABREngine.Instance.Render();
    }
}
| Improve this Doc View Source

GetDataImpressionGroupByDataset(Dataset)

Retrieve the first data impression group found that is associated with a particular Dataset.

Declaration
public DataImpressionGroup GetDataImpressionGroupByDataset(Dataset ds)
Parameters
Type Name Description
Dataset ds

Dataset that should be matched with
Returns
Type Description
DataImpressionGroup

A data impression with the given dataset.
| Improve this Doc View Source

GetDataImpressionGroups()

Retrieve all data impression groups that currently exist in the Unity ABR scene.

Declaration
public Dictionary<Guid, DataImpressionGroup> GetDataImpressionGroups()
Returns
Type Description
Dictionary<Guid, DataImpressionGroup>

Dictionary mapping of (uuid => DataImpressionGroup)
| Improve this Doc View Source

GetDataImpression<T>()

Retreive the first data impression found with a particular type

Declaration
public T GetDataImpression<T>() where T : DataImpression
Returns
Type Description
T

The first data impression of matching type T, null otherwise.
Type Parameters
Name Description
T

Any data impression type implementing DataImpression
| Improve this Doc View Source

GetDataImpression<T>(Func<T, bool>)

Retreive the first data impression found with a particular type AND function crieteria (similar to a "filter" or Linq-esque "where" operation).

Declaration
public T GetDataImpression<T>(Func<T, bool> criteria) where T : DataImpression
Parameters
Type Name Description
Func<T, bool> criteria

Function that takes each data impression matching type T and returns a boolean.
Returns
Type Description
T

The first data impression of type T that matches criteria, null otherwise.
Type Parameters
Name Description
T

Any data impression type implementing DataImpression
| Improve this Doc View Source

GetDataImpression<T>(string)

Returns the first data impression within the group that is associated with the keyDataPath. Although it is often the case that there will be only one data impression per keyDataPath, this is not always the case. GetDataImpressions(string keyDataPath) can be used to get all of the data impressions with the same keyDataPath.

Declaration
public T GetDataImpression<T>(string keyDataPath) where T : DataImpression
Parameters
Type Name Description
string keyDataPath
Returns
Type Description
T
Type Parameters
Name Description
T
| Improve this Doc View Source

GetDataImpressions(Func<DataImpression, bool>)

Retreive the all data impressions found of any type matching function crieteria (similar to a "filter" or Linq-esque "where" operation).

Declaration
public List<DataImpression> GetDataImpressions(Func<DataImpression, bool> criteria)
Parameters
Type Name Description
Func<DataImpression, bool> criteria

Function that takes each data impression and returns a boolean.
Returns
Type Description
List<DataImpression>

All data impressions of any type that matches criteria, null otherwise.
| Improve this Doc View Source

GetDataImpressions(string)

Returns all of the data impressions associated with the specified keyDataPath

Declaration
public List<DataImpression> GetDataImpressions(string keyDataPath)
Parameters
Type Name Description
string keyDataPath
Returns
Type Description
List<DataImpression>
| Improve this Doc View Source

GetDataImpressionsOfType<T>()

Retrieve all data impressions in an ABR state of a given impression type (e.g., all SimpleSurfaceDataImpressions)

Declaration
[Obsolete("GetDataImpressionsOfType<T> is obsolete, use GetDataImpressions<T> instead")]
public List<T> GetDataImpressionsOfType<T>() where T : DataImpression
Returns
Type Description
List<T>

A list of data impressions that have a particular type
Type Parameters
Name Description
T
| Improve this Doc View Source

GetDataImpressionsWithTag(string)

Retrieve all data impressions in an ABR scene that have a particular tag. Note that the ABREngine does not do anything with tags; these exist solely for application developers.

Declaration
public List<DataImpression> GetDataImpressionsWithTag(string tag)
Parameters
Type Name Description
string tag

The tag to check for
Returns
Type Description
List<DataImpression>

A list of data impressions with a particular tag
| Improve this Doc View Source

GetDataImpressions<T>()

Retreive the all data impressions found of a particular type

Declaration
public List<T> GetDataImpressions<T>() where T : DataImpression
Returns
Type Description
List<T>

All data impressions of type T.
Type Parameters
Name Description
T

Any data impression type implementing DataImpression
| Improve this Doc View Source

GetDataImpressions<T>(Func<T, bool>)

Retreive the all data impressions found of a particular type matching function crieteria (similar to a "filter" or Linq-esque "where" operation).

Declaration
public List<T> GetDataImpressions<T>(Func<T, bool> criteria) where T : DataImpression
Parameters
Type Name Description
Func<T, bool> criteria

Function that takes each data impression of type T and returns a boolean.
Returns
Type Description
List<T>

All data impressions of type T that match the criteria.
Type Parameters
Name Description
T

Any data impression type implementing DataImpression
| Improve this Doc View Source

GetDataImpressions<T>(string)

Returns all of the data impressions associated with the specified keyDataPath

Declaration
public List<T> GetDataImpressions<T>(string keyDataPath) where T : DataImpression
Parameters
Type Name Description
string keyDataPath
Returns
Type Description
List<T>
Type Parameters
Name Description
T
| Improve this Doc View Source

GetGroupFromImpression(DataImpression)

Get the data impression group a particular data impression

Declaration
public DataImpressionGroup GetGroupFromImpression(DataImpression dataImpression)
Parameters
Type Name Description
DataImpression dataImpression

Data impression to find out the group of
Returns
Type Description
DataImpressionGroup

The data impression group dataImpression belongs to, otherwise null.
| Improve this Doc View Source

GetKeyData(string)

The ABREngine class is the main operational MonoBehaviour Singleton for the ABREngine-UnityPackage. It is in charge of kicking off all startup processes for ABR, including setting up connections with the server, the data listener, VisAssets and Data managers, etc.

Declaration
public KeyData GetKeyData(string keyDataPath)
Parameters
Type Name Description
string keyDataPath
Returns
Type Description
KeyData
Examples

Usage of ABREngine.Instance

Most methods of the ABREngine can be accessed through its singleton Instance without needing to do a GetComponent:

string mediaPath = ABREngine.Instance.MediaPath;

Example: Getting Started with Unity C# and ABR

This example shows how to create an ABR visualization in code using one data impression.

Note

You can also import this example using the Unity Package Manager. In Unity, go to Window > Package Manager, find the ABREngine package, and import the "Documentation Examples" sample project.

The general process for making an ABR visualization in C# code is:

  1. Import data using LoadData(string)
  2. Import VisAssets using GetVisAsset<T>(Guid).
  3. Create a DataImpression to combine the data and visuals together (using Create<T>(string, Guid, bool)).
  4. Use RegisterDataImpression(DataImpression, DataImpressionGroup, bool) to add the impression to the engine.
  5. Render the data and visuals to the screen using Render().
using UnityEngine;
using IVLab.ABREngine;

// Look in the Resources folder of this example to see the data and VisAssets.
// Before running this example, make sure the ABR Configuration is set to ABRExamplesConfig!
public class ABREngineExample : MonoBehaviour
{
    // Editable in Unity Editor
    [SerializeField, Tooltip("Animated spin rate for the data"), Range(0.0f, 30.0f)]
    private float spinRate = 1.0f;

    // Store the data impression for use in Update()
    private SimpleGlyphDataImpression dataImpression;

    void Start()
    {
        // Load example VisAssets from resources
        // A white to orange colormap
        ColormapVisAsset orange = ABREngine.Instance.VisAssets.GetVisAsset<ColormapVisAsset>(new System.Guid("66b3cde4-034d-11eb-a7e6-005056bae6d8"));

        // A triangular glyph
        GlyphVisAsset triangular = ABREngine.Instance.VisAssets.GetVisAsset<GlyphVisAsset>(new System.Guid("1af02820-f1ed-11e9-a623-8c85900fd4af"));



        // Load an example dataset from resources
        // This Key Data has multiple scalar variables defined at each point in
        // the dataset. We'll use the "XAxis" variable, this increases
        // monotonically from -10 to +10 along the X axis.
        KeyData pointsKd = ABREngine.Instance.Data.LoadData("Demo/Wavelet/KeyData/Points");
        ScalarDataVariable xAxisScalarVar = pointsKd.GetScalarVariable("XAxis");


        // Create a Glyph DataImpression and store it for later use
        dataImpression = DataImpression.Create<SimpleGlyphDataImpression>("Example Points");

        // Assign the key data to the Data Impression. This is the "Geometry"
        // with which the data impression will be drawn.
        dataImpression.keyData = pointsKd;

        // Tell ABR to map the Color visual channel of the Data Impression to
        // the "XAxis" variable.
        dataImpression.colorVariable = xAxisScalarVar;

        // Lastly, apply the colormap and glyph (visual style for this Data
        // Impresssion)
        dataImpression.colormap = orange;
        dataImpression.glyph = triangular;


        // Finally, add the Data Impression to the ABREngine, and re-render.
        // Note, this will automatically look for the DataImpression Group
        // "Demo/Wavelet" in the scene, and put this data impression as a child
        // of that group.
        ABREngine.Instance.RegisterDataImpression(dataImpression);
        ABREngine.Instance.Render();
    }

    void Update()
    {
        // Access the individual data impression that was created earlier and
        // spin it around.
        //
        // Usually we want to do any manipulations like this at the "Group"
        // level rather than individual data impressions so that multiple data
        // impressions in the same dataset remain spatially registered with each
        // other.
        DataImpressionGroup pointsGroup = ABREngine.Instance.GetGroupFromImpression(dataImpression);
        pointsGroup.transform.rotation *= Quaternion.Euler(new Vector3(0, Time.deltaTime * spinRate, 0));
    }
}

Example: Using Custom Data

This example shows how to quickly get up and running with a custom-defined dataset and building your own data impressions. Before the steps in the previous example, you will also need to:

  1. Define your data in some `List`s.
  2. Use the RawDatasetAdapter to convert the `List` into an ABR RawDataset, or import an existing ABR RawDataset using LoadRawDataset(string).
  3. Import that RawDataset into ABR using ImportRawDataset(RawDataset) (optionally, giving the dataset a data path identifier for easier semantic access later).
using System.Collections.Generic;
using UnityEngine;
using IVLab.ABREngine;

/// <summary>
/// Example for the main ABREngine class.
/// </summary>
public class CustomDataABRExample : MonoBehaviour
{
    void Start()
    {
        // STEP 1: Define data
        // 9 points in 3D space
        List<Vector3> vertices = new List<Vector3>
            {
                new Vector3(0.0f, 0.5f, 0.0f),
                new Vector3(0.0f, 0.6f, 0.1f),
                new Vector3(0.0f, 0.4f, 0.2f),
                new Vector3(0.1f, 0.3f, 0.0f),
                new Vector3(0.1f, 0.2f, 0.1f),
                new Vector3(0.1f, 0.3f, 0.2f),
                new Vector3(0.2f, 0.0f, 0.0f),
                new Vector3(0.2f, 0.3f, 0.1f),
                new Vector3(0.2f, 0.1f, 0.2f),
            };

        // Data values for those points
        List<float> data = new List<float>();
        for (int i = 0; i < vertices.Count; i++) data.Add(i);

        // Named scalar variable
        Dictionary<string, List<float>> scalarVars = new Dictionary<string, List<float>> { { "someData", data } };

        // Define some generous bounds
        Bounds b = new Bounds(Vector3.zero, Vector3.one);

        // STEP 2: Convert the point list into ABR Format
        RawDataset abrPoints = RawDatasetAdapter.PointsToPoints(vertices, b, scalarVars, null);

        // STEP 3: Import the point data into ABR so we can use it
        KeyData pointsKD = ABREngine.Instance.Data.ImportRawDataset(abrPoints);

        // STEP 4: Import a colormap visasset
        ColormapVisAsset cmap = ABREngine.Instance.VisAssets.LoadVisAsset<ColormapVisAsset>(new System.Guid("66b3cde4-034d-11eb-a7e6-005056bae6d8"));

        // STEP 5: Create a Data Impression (layer) for the points, and assign some key data and styling
        SimpleGlyphDataImpression di = DataImpression.Create<SimpleGlyphDataImpression>("Simple Points");
        di.keyData = pointsKD;                                 // Assign key data (point geometry)
        di.colorVariable = pointsKD.GetScalarVariables()[0];   // Assign scalar variable "someData"
        di.colormap = cmap;                                    // Apply colormap
        di.glyphSize = 0.002f;                                 // Apply glyph size styling

        // STEP 6: Register impression with the engine
        ABREngine.Instance.RegisterDataImpression(di);

        // STEP 7: Render the visualization
        ABREngine.Instance.Render();
    }
}
| Improve this Doc View Source

GetKeyDataStartsWith(string)

The ABREngine class is the main operational MonoBehaviour Singleton for the ABREngine-UnityPackage. It is in charge of kicking off all startup processes for ABR, including setting up connections with the server, the data listener, VisAssets and Data managers, etc.

Declaration
public Dictionary<string, KeyData> GetKeyDataStartsWith(string keyDataPathStartsWith)
Parameters
Type Name Description
string keyDataPathStartsWith
Returns
Type Description
Dictionary<string, KeyData>
Examples

Usage of ABREngine.Instance

Most methods of the ABREngine can be accessed through its singleton Instance without needing to do a GetComponent:

string mediaPath = ABREngine.Instance.MediaPath;

Example: Getting Started with Unity C# and ABR

This example shows how to create an ABR visualization in code using one data impression.

Note

You can also import this example using the Unity Package Manager. In Unity, go to Window > Package Manager, find the ABREngine package, and import the "Documentation Examples" sample project.

The general process for making an ABR visualization in C# code is:

  1. Import data using LoadData(string)
  2. Import VisAssets using GetVisAsset<T>(Guid).
  3. Create a DataImpression to combine the data and visuals together (using Create<T>(string, Guid, bool)).
  4. Use RegisterDataImpression(DataImpression, DataImpressionGroup, bool) to add the impression to the engine.
  5. Render the data and visuals to the screen using Render().
using UnityEngine;
using IVLab.ABREngine;

// Look in the Resources folder of this example to see the data and VisAssets.
// Before running this example, make sure the ABR Configuration is set to ABRExamplesConfig!
public class ABREngineExample : MonoBehaviour
{
    // Editable in Unity Editor
    [SerializeField, Tooltip("Animated spin rate for the data"), Range(0.0f, 30.0f)]
    private float spinRate = 1.0f;

    // Store the data impression for use in Update()
    private SimpleGlyphDataImpression dataImpression;

    void Start()
    {
        // Load example VisAssets from resources
        // A white to orange colormap
        ColormapVisAsset orange = ABREngine.Instance.VisAssets.GetVisAsset<ColormapVisAsset>(new System.Guid("66b3cde4-034d-11eb-a7e6-005056bae6d8"));

        // A triangular glyph
        GlyphVisAsset triangular = ABREngine.Instance.VisAssets.GetVisAsset<GlyphVisAsset>(new System.Guid("1af02820-f1ed-11e9-a623-8c85900fd4af"));



        // Load an example dataset from resources
        // This Key Data has multiple scalar variables defined at each point in
        // the dataset. We'll use the "XAxis" variable, this increases
        // monotonically from -10 to +10 along the X axis.
        KeyData pointsKd = ABREngine.Instance.Data.LoadData("Demo/Wavelet/KeyData/Points");
        ScalarDataVariable xAxisScalarVar = pointsKd.GetScalarVariable("XAxis");


        // Create a Glyph DataImpression and store it for later use
        dataImpression = DataImpression.Create<SimpleGlyphDataImpression>("Example Points");

        // Assign the key data to the Data Impression. This is the "Geometry"
        // with which the data impression will be drawn.
        dataImpression.keyData = pointsKd;

        // Tell ABR to map the Color visual channel of the Data Impression to
        // the "XAxis" variable.
        dataImpression.colorVariable = xAxisScalarVar;

        // Lastly, apply the colormap and glyph (visual style for this Data
        // Impresssion)
        dataImpression.colormap = orange;
        dataImpression.glyph = triangular;


        // Finally, add the Data Impression to the ABREngine, and re-render.
        // Note, this will automatically look for the DataImpression Group
        // "Demo/Wavelet" in the scene, and put this data impression as a child
        // of that group.
        ABREngine.Instance.RegisterDataImpression(dataImpression);
        ABREngine.Instance.Render();
    }

    void Update()
    {
        // Access the individual data impression that was created earlier and
        // spin it around.
        //
        // Usually we want to do any manipulations like this at the "Group"
        // level rather than individual data impressions so that multiple data
        // impressions in the same dataset remain spatially registered with each
        // other.
        DataImpressionGroup pointsGroup = ABREngine.Instance.GetGroupFromImpression(dataImpression);
        pointsGroup.transform.rotation *= Quaternion.Euler(new Vector3(0, Time.deltaTime * spinRate, 0));
    }
}

Example: Using Custom Data

This example shows how to quickly get up and running with a custom-defined dataset and building your own data impressions. Before the steps in the previous example, you will also need to:

  1. Define your data in some `List`s.
  2. Use the RawDatasetAdapter to convert the `List` into an ABR RawDataset, or import an existing ABR RawDataset using LoadRawDataset(string).
  3. Import that RawDataset into ABR using ImportRawDataset(RawDataset) (optionally, giving the dataset a data path identifier for easier semantic access later).
using System.Collections.Generic;
using UnityEngine;
using IVLab.ABREngine;

/// <summary>
/// Example for the main ABREngine class.
/// </summary>
public class CustomDataABRExample : MonoBehaviour
{
    void Start()
    {
        // STEP 1: Define data
        // 9 points in 3D space
        List<Vector3> vertices = new List<Vector3>
            {
                new Vector3(0.0f, 0.5f, 0.0f),
                new Vector3(0.0f, 0.6f, 0.1f),
                new Vector3(0.0f, 0.4f, 0.2f),
                new Vector3(0.1f, 0.3f, 0.0f),
                new Vector3(0.1f, 0.2f, 0.1f),
                new Vector3(0.1f, 0.3f, 0.2f),
                new Vector3(0.2f, 0.0f, 0.0f),
                new Vector3(0.2f, 0.3f, 0.1f),
                new Vector3(0.2f, 0.1f, 0.2f),
            };

        // Data values for those points
        List<float> data = new List<float>();
        for (int i = 0; i < vertices.Count; i++) data.Add(i);

        // Named scalar variable
        Dictionary<string, List<float>> scalarVars = new Dictionary<string, List<float>> { { "someData", data } };

        // Define some generous bounds
        Bounds b = new Bounds(Vector3.zero, Vector3.one);

        // STEP 2: Convert the point list into ABR Format
        RawDataset abrPoints = RawDatasetAdapter.PointsToPoints(vertices, b, scalarVars, null);

        // STEP 3: Import the point data into ABR so we can use it
        KeyData pointsKD = ABREngine.Instance.Data.ImportRawDataset(abrPoints);

        // STEP 4: Import a colormap visasset
        ColormapVisAsset cmap = ABREngine.Instance.VisAssets.LoadVisAsset<ColormapVisAsset>(new System.Guid("66b3cde4-034d-11eb-a7e6-005056bae6d8"));

        // STEP 5: Create a Data Impression (layer) for the points, and assign some key data and styling
        SimpleGlyphDataImpression di = DataImpression.Create<SimpleGlyphDataImpression>("Simple Points");
        di.keyData = pointsKD;                                 // Assign key data (point geometry)
        di.colorVariable = pointsKD.GetScalarVariables()[0];   // Assign scalar variable "someData"
        di.colormap = cmap;                                    // Apply colormap
        di.glyphSize = 0.002f;                                 // Apply glyph size styling

        // STEP 6: Register impression with the engine
        ABREngine.Instance.RegisterDataImpression(di);

        // STEP 7: Render the visualization
        ABREngine.Instance.Render();
    }
}
| Improve this Doc View Source

HasDataImpression(Guid)

Check to see if the data impression with a given uuid exists

Declaration
public bool HasDataImpression(Guid uuid)
Parameters
Type Name Description
Guid uuid

Unique identifier (UUID) of the requisite data impression
Returns
Type Description
bool

A boolean whether or not this data impression is present in this ABR state
| Improve this Doc View Source

HasDataImpressionGroup(Guid)

Check if a particular data impression group exists.

Declaration
public bool HasDataImpressionGroup(Guid uuid)
Parameters
Type Name Description
Guid uuid

UUID to check existence of
Returns
Type Description
bool

Boolean - true if the given group exists in the current ABR state, false otherwise.
| Improve this Doc View Source

LoadState<T>(string)

Load a state into ABR. This includes the following steps:

  1. All Data and VisAssets from the state have been loaded.
  2. The ABR scene has been rendered with all updates (including data impressions, lighting, etc.).
  3. The OnStateChanged callback has been fired.
Declaration
public void LoadState<T>(string stateName) where T : IABRStateLoader, new()
Parameters
Type Name Description
string stateName
Type Parameters
Name Description
T
Remarks

Data impressions that have not changed will not be re-rendered.

Examples

A state may be loaded from any of the following places:

// A Resources folder (in Assets or in a Package)
ABREngine.Instance.LoadState<ResourceStateFileLoader>("exampleState.json");

// A local file
ABREngine.Instance.LoadState<PathStateFileLoader>("C:/Users/VRDemo/Desktop/test.json");

// A JSON string
ABREngine.Instance.LoadState<TextStateFileLoader>("{\"version\": \"0.2.0\", \"name\": \"test\"}");

// A web resource
ABREngine.Instance.LoadState<HttpStateFileLoader>("http://localhost:8000/api/state");
| Improve this Doc View Source

MoveImpressionToGroup(DataImpression, DataImpressionGroup, bool)

Move a data impression from its current group to a new group.

Declaration
public void MoveImpressionToGroup(DataImpression dataImpression, DataImpressionGroup newGroup, bool allowOverwrite = true)
Parameters
Type Name Description
DataImpression dataImpression

The data impression that should be moved.
DataImpressionGroup newGroup

The group to place the data impression into.
bool allowOverwrite

Should we destroy any existing data impressions with this UUID within the newGroup?
| Improve this Doc View Source

RegisterDataImpression(DataImpression, DataImpressionGroup, bool)

Register a new data impression with the ABREngine and add it to a specific DataImpressionGroup.

Declaration
public void RegisterDataImpression(DataImpression dataImpression, DataImpressionGroup newGroup, bool allowOverwrite = true)
Parameters
Type Name Description
DataImpression dataImpression

The data impression to register with the engine
DataImpressionGroup newGroup

Group to add this data impression to
bool allowOverwrite

Should we destroy any existing data impressions that have this UUID already?
| Improve this Doc View Source

RegisterDataImpression(DataImpression, bool)

Register a new data impression, or replace an existing one. If the data impression has a dataset, defaults to placing it inside the existing group with the same dataset, or creating a new DataImpressionGroup with that dataset if no group exists yet.

Declaration
public void RegisterDataImpression(DataImpression dataImpression, bool allowOverwrite = true)
Parameters
Type Name Description
DataImpression dataImpression

The data impression to register with the engine
bool allowOverwrite

Should we destroy any existing data impressions that have this UUID already?
| Improve this Doc View Source

RemoveDataImpressionGroup(Guid)

Remove a given data impression group from the scene, destroying all of the data impressions within the group.

Declaration
public void RemoveDataImpressionGroup(Guid uuid)
Parameters
Type Name Description
Guid uuid

UUID of the data impression group that should be removed.
| Improve this Doc View Source

Render()

Go through every data impression group's impressions and render them. Each impression intelligently decides if the entire geometry needs to be recomputed (slow), or if only the style has changed (fast).

Declaration
public void Render()
| Improve this Doc View Source

SaveState<T>(string)

Save a state from the ABR Unity scene back to a particular JSON destination.

Declaration
public void SaveState<T>(string overrideStateName = null) where T : IABRStateLoader, new()
Parameters
Type Name Description
string overrideStateName
Type Parameters
Name Description
T
Remarks

The SaveState functionality is only implemented in a few IABRStateLoader classes, namely PathStateFileLoader and HttpStateFileLoader.

This method generally takes a long time so should not be called frequently. Also, since this method manually looks through GameObjects in the scene to reverse-engineer a JSON state, so the resulting JSON state may not always be complete.

Examples

ABR states can be saved like this:

// Save the current state to a file on your computer
ABREngine.Instance.SaveState<PathStateFileLoader>("C:/Users/VRDemo/Desktop/exampleState.json");

// Save the current state to a web resource
ABREngine.Instance.SaveState<HttpStateFileLoader>("http://localhost:8000/api/state");
| Improve this Doc View Source

UnregisterDataImpression(Guid)

Remove a data impression from the ABR state.

Declaration
public void UnregisterDataImpression(Guid uuid)
Parameters
Type Name Description
Guid uuid

The UUID data impression to remove (unregister) from the ABREngine
| Improve this Doc View Source

WaitUntilInitialized()

Wait until the Engine is fully initialized before proceeding to use it.

Declaration
public Task WaitUntilInitialized()
Returns
Type Description
Task
Examples

For example, if we want to do some ABREngine-dependant tasks in a MonoBehaviour Start():

using UnityEngine;
using IVLab.ABREngine;

public class ABRInitializerExample : MonoBehaviour
{
    void Start()
    {
        // Wait for the engine to initialize...
        while (!ABREngine.Instance.IsInitialized);

        // ... then print out some very important information that
        // depends on ABR being initialized
        Debug.Log(ABREngine.Instance.Config.defaultBounds);
    }
}