Unreal Engine Plugins

Our UE4 plugins are designed to allow easy live data-driven visualisations inside Unreal Engine. Our initial release includes support for native UE (version 4.25 and above) and Ross Video's Voyager platform (version 4 and above).

They comprise the following:

Column Chart Icon

Column Chart

A fully configurable column chart (aka "histogram"). As few or as many columns as you like, capable of showing all positive values or a mixture of positive and negative

Pie Chart Icon

Pie Chart

Colour coded segments with annotations, including the ability to explode them out for emphasis. Loads of animation options

Line Chart Icon

Line Chart

A chart. With lines! Animate lines in one-by-one, or all lines to stop points on the Y axis. Bring lines forward in Z for emphasis

US Map Icon

US Map

COMING SOON! US map, with both State and Congressional District geometry. Optional call-outs for smaller States. Perfect for election coverage!

Where to Get Them

What Next?

Now let's take a look at how to:

Installation

Just as with any other UE4 plugin you can add them to the Engine (in which case they will be globally available in any project), or to a given project. The process is pretty much the same either way:

Pre-Requisites

You need to be running UE 4.25.0 or later. Note that the "Core" plugin is a common dependency of the others.

Install

  • Download and unzip the plugin
  • To make the plugins globally available copy the root "Idonix" folder:
    • For native UE4 to "C:\Program Files\Epic Games\{UE Version}\Engine\Plugins"
    • For Ross Voyager to "C:\Program Files\Voyager\Engine\Plugins"
  • If you only want to use them in the given project copy the root "Idonix" folder to "{Your project name}\plugins"

If you have all the plugins installed your folder should end up looking like this example (installed globally for native EU):

NB The "Core" plugin is a dependency of the others (it contains common library functions), so you'll need to always install this in the same way

Enable

  • Open your project in Unreal Editor, open the Plugins browser, navigate to the Idonix folder and check the "Enabled" boxes (if you're not seeing an Idonix folder here go back and double check you placed them in the correct location in the step above)
  • Restart Unreal Editor and you're good to go!

Configuring in UE Editor

Configure

  • From the Idonix section in the "Place Actors" tab, drag the required chart into your level (you can ignore the "Preview JSON Controllers" for the moment - we'll come onto them shortly)

  • Position and scale the chart as you see fit

  • Use the Details panel to configure the Actor as you like (although the defaults will work "out of the box"). Each plugin will have subtly different options, but they all have a lot in common, for example Plinth shapes and materials, Label sizes and styles, and of course styles and materials for the core items such as pie slices and columns. Note that a great number of these settings can be changed in data (we'll come onto this later)

Preview

  • To preview the plugin with differing data sets, drag the relevant "Preview JSON Controller" Blueprint into your level

  • Set the Controller "...Chart" property to the plugin instance you want to control (the "Immediate Mode" box dictates whether transitions are immediate, or follow configured animations)

  • Hit "Play" on the tool bar to switch the engine to game mode. At this point the plugin actor will disappear (because it will be in it's "animated out" state) - and this is a UE Editor "gotcha" - whilst the Controller will remain in the Details tab, it will lose focus in the Word Outliner tab. Click the Contoller again to give it focus:

  • Now you can start poking data at the plugin - paste some compliant content into the "JSON Data" box and hit Animate. Tweak the data and animate again.

You can find some sample data sets here.

Controlling The Ross Voyager Plugins with UX

Control of Voyager is handled by UX. Here's how:

A UX Controller Blueprint in your Level

  • Add the appropriate UX Controller Blueprint to your level (you'll need one per graphic)
  • You need to give it an "ID" - this how you will reference the graphic from UX
  • As with the Preview Controller, set the "..Chart" property to the graphic instance you want to automate
  • Make sure you have UX running (we're assuming you already have UX hooked up to your Voyager renderer), and hit play to switch to game mode

A UX Layout

  • In UX you'll probably want a new Layout for your chart control, so go ahead and make one. You'll need an Event panel and a Logic panel, so add those to your new layout

UX Events

Now we need an Event for each interaction, so make these: * A "Set Data" event to push new data to the UE Blueprint * An "Animate" event to bring the graphic in, or refresh the data for an existing graphic * A "Animate Out" event to animate the graphic out

UX Logic

  • Now we'll need a Logic Node to hook your data and your events to the UX Controller Blueprint in UE, so make one (you'll need one per graphic instance)

Passing Data

Let's start with passing your data to the plugin

  • Add a text file data source, point it at a suitable JSON file (we'll come to hooking up to DataLinq in a while), and set it to poll every second
  • Now add a Renderer Logic Node. Point it to your Voyager instance, and the "_Data" attribute of the UX Controller Blueprint (based in the "ID" we set earlier)
  • Link the Content of the Text File node to the string input of the Renderer Logic node
  • Now add a UX Event Trigger linked to the "Set Data" event you made earlier, and link it to a new Renderer Logic node that attaches to the graphic's "SetData" action, and set the Index to 1
  • That part's done. The "Set Data" event will now send the JSON in the text file to the UE chart

Animations

  • Add a UX Event Trigger linked to the "Animate" event, and join it to a new Renderer Login node that points to the graphic's "Animate" action. Again set the Index to 1.
  • Add one last UX Event Trigger linked to the "Animate out" event, and join it to a Renderer Login node that points to the graphic's "AnimateOut" action. Don't forget to set the Index to 1.

Datalinq

TODO

In Summary

Here's a quick video that puts all the pieces together:

Data Schemas

Here are the formats of the JSON data you'll need to supply to each plugin: the Column Chart, Pie Chart, Line Chart and US Map

Column Chart

{
    "DataSetID": "fg56dyuU",                                   
    // String, Mandatory
    // Defines the "graphic instance", which dictates the graphic's overall animation behaviour.
    // Sending the same string as in the previous data will cause the graphic to transition to the new state in vision. Sending a different 
    // string will cause it to animate out and then back in. The actual string content has no processing significance in UE.

    "ValueFormat": "Percent1DP",                       
    // Enumeration, Mandatory
    // Formatting to apply to all "Value" elements (see options in "Common")

    "BaselinePosition": "Bottom",      
    // Enumeration, Optional
    // Middle, Bottom. Default is Bottom
    // Using Bottom sets the Baseline at plinth surface level, Middle set the Baseline at the centre of the Y axis

    "ShowPlinthLabel": true,                            
    // Boolean, Optional, Defaults to true
    // Show the label (or not)

    "PlinthLabelText": "CHECK OUT THIS CHART",                             
    // String, Optional
    // Text to show on the label

    "Columns": [                                           
    // Array, Mandatory 
    // Enumerates the columns

        {
            "ColumnValue": "234.54",                         
            // String, Mandatory
            // Formatting will be directed by the ValueFormat (a ColumnValue of 234.54 will be shown as 234.5 if the ValueFormat is Figure1DP
            // If text is entered - the column will be normalized to the minimum setting, the text will not be shown

            "NormalizedHeight": 0.5,             
            // Decimal (0-1), Optional
            // Defaults to 1.0 for the column with the highest ColumnValue, and scales the remaining columns according 
            // to the apportionment of their ColumnValue (1.0 is the full height of the Y axis)
            // Note that the option to specify this allows you to bring columns on one-by-one without them re-scaling

            "ColumnColor": "#FFFF00",           
             // String, Optional, Defaults to the Material colour in the Section Material Settings
             // Hex colour

            "BackdropColor": "#FF00FF",
             // String, Optional, Defaults to the Material colour in the Section Material Settings
             // Hex colour

            "TextColor": "#000000",             
             // String, Optional
             // Hex colour

        }
    ],
    "SeriesLabels": [                                      
    // Array, Mandatory
    // A label for each column
        {
            "Text": "Q1",                                
             // String, Mandatory

            "SeriesIndex": 0,                        
            // Integer, Optional, Default is ordinal index match into the Columns array
            // Which Section this label applies to (the index into the Sections array)

            "TextColor": "#000000",             
            // String, Optional
            // Defaults to the Material colour in the Section Material Settings

            "BackdropColor": "#FF00FF",        
            // String, Optional
            // Hex String

        }
    ]
} 

Pie Chart

{
    "DataSetID": "ajgu7rt",
    // Mandatory, String
    // Defines the "graphic instance", which dictates the graphic's overall animation behaviour.
    // Sending the same string as in the previous data will cause the graphic to transition to the new state in vision. Sending a different 
    // string will cause it to animate out and then back in. The actual string content has no processing significance in UE.

    "ValueFormat": "Percent1DP",
    // Enumeration, Mandatory
    // Formatting to apply to all "Value" elements (see options in "Common")

    "IsRaised": true, 
    // Boolean, Optional, Defaults to true
    // Set this to true if you want the pie to render in a vertical position (according to Settings "Raised Location")

    "InitialRotation": 0,
    // Decimal, Optional, Default: 0
    // Position in degrees at which to start drawing segments

    "ShowPlinthLabel": "true",
    // Boolean, Optional
    // Show the label (or not)

    "PlinthLabelText": "WHAT A NICE PIE",
    // String, Optional
    // Text to show on the label

    "Sections": [                                          
    // Array, Mandatory 
    // Enumerates the pie slices
        {
            "Value": 10,
            // Decimal, Optional
            // You state the slice size here, as an absolute value, in which case the plugin
            // will size all slices based on relative values. Or you can state the size
            // as an "Angle" (in degrees)

            "Color": "#223388",
            // String, Optional, Defaults to the Material colour in the Section Material Settings
            // Colour for section in hex format
            // Although optional, if you don't use this all sections will be the same colour, which kind of defeats the object

            "Angle": 90,
            // Decimal, Optional
            // Size of the section in degrees. Use as an alternative to "Value" above

            "Thickness": 0.5
            // Decimal, Optional, Default 0
            // Depth of the section. Use a value of between 0 and 1, where 0 is the "Minimum Thickess" defined in Section Settings, 
            // and 1 is the "Maximum Thickness"

            "Radius": 0,
            // Decimal, Optional, Default 0
            // Radius of the section. Use a value of between 0 and 1, where 0 is the "Minimum Radius" defined in Section Settings, 
            // and 1 is the "Maximum Radius"

            "RadiusOffset": 1
            // Decimal, Optional, Default 0
            // How far to "pull the segment out" - use a value of between 0 and 1, where 0 is the "Minimum Radius Offset" defined in Section Settings, 
            // and 1 is the "Maximum Radius Offset"
        }
    ],
    "SectionLabels": [
    // Array, Optional 
    // A label for each pie section. Although optional the chart won't make a great deal of sense without it ;)
        {
            "LabelText": "GROUP A",
            // String, Mandatory

            "ValueText": 40.7,
            // Decimal, Mandatory
            // The Value to display. This will be formatted according the "ValueFormat" rule
            // Note that this is supplied as a decimal rather than pre-formatted string in order to allow number animation

            "SectionIndex": 0,
            // Integer, Optional, Default is ordinal index match into the Sections array
            // Which Section this label applies to (the index into the Sections array)

            "RadiusOffset": 0.0,
            // Decimal, Optional, Default: 0

            "BackdropColor": "#660000",
            // String, Optional, Default to grey
            // Hex colour, background for the label

            "LabelColor": "#CCCCCC",
            // String, Mandatory
            // Hex colour, foreground for the LabelText

            "ValueColor": "#CCCCCC",
            // String, Mandatory
            // Hex colour, foreground for the ValueText
        }
    ]
}

Line Chart

{
    "DataSetID": "97gh54R",                                    
    // String, Mandatory
    // Defines the "graphic instance", which dictates the graphic's overall animation behaviour.
    // Sending the same string as in the previous data will cause the graphic to transition to the new state in vision. Sending a different 
    // string will cause it to animate out and then back in. The actual string content has no processing significance in UE.

    "ValueFormat": "Figure1DP",                        
    // Enumeration, Mandatory
    // Formatting to apply to all "Value" elements (see options in "Common")

    "ShowPlinthLabel": true,                            
    // Boolean, Optional, Defaults to true
    // Show the label (or not)

    "PlinthLabelText": "What a nice line graph",                             
    // String, Optional
    // Text to show on the label

    "CategoryLabels": [                                     
    // Array, Mandatory
    // Labels for points along the X axis
        {
            "Text": "Q1",                                 
            // String, Mandatory

            "CategoryIndex": 0,                       
             // Integer, Optional
             // Use 0 for the first line, e.g. a LineChart with three lines could be identified as 2, 1, 0 in the json
             // Changing the CategoryIndex (i.e. reloading json) will then animate (Animate Out needed) as a change of the CategoryLabels only,
             // the lines will remain as they were

            "TextColor": "#FFFFF",             
             // String (Hex String, i.e. #RRGGBB), Optional
             // Defaults to the Material colour in the Section Material Settings

            "BackdropColor": "#00000",             
             // String (Hex String, i.e. #RRGGBB), Optional
             // Defaults to the Material colour in the Section Material Settings

        }
    ],
    "ValueAxis": {                  
    // Decimal,Optional
    // Value Labels for the Y axis

        "MinimumValue": 0.0,    
        // Decimal,Optional

        "MaximumValue": 1.0,    
        // Decimal,Optional

        "MajorUnits": 0.5,      
        // Decimal,Optional

        "MinorUnits": 0.1,       
        // Decimal,Optional

    },
    "Lines": [ 
    // Array, Mandatory
    // Each line can have individual settings

        {
            "BringForward": 0.5,                    
            // Decimal, Optional ( 0.0 -> 1.0 )
            // A value of 1.0 is 100% of the 'Maximum Distance to Bring Forward' (entered in Line Settings)

            "AnimateToPoint": 3,                  
            // Integer, Optional
            // 0 will mean that the line does not animate, or will animate back to the Y axis 
            // If there are three sets of values for  line (i.e. "Points": "Value": 1.0", etc), then an AnimateToPoint figure of '3', will 
            // mean all three sets of values will be shown. 
            // Changing the figure to '2' and re-animating, will reduce the line back to the second set of values (i.e. value, text colour, etc)

            "ShowSeriesLabelOnLine": true,           
            // Boolean, Optional, Defaults to true
            // Show the label (or not)

            "Points": 
            [                                 
            // Array, Mandatory
            // Each point along a line can now be given its value and characteristics (i.e. text colour, etc)
                { 
                    "Value": 1.0,                    
                    // Decimal, Mandatory

                    "PointColor": "#FFFFFF",             
                    // String, Optional, Defaults to the Material colour in the Section Material Settings
                    // Hex colour string

                    "CategoryLabel": {                          
                    // Optional

                    "TextColor": "#FFFFFF",             
                    // String (Hex String, i.e. #RRGGBB), Optional
                    // Defaults to the Material colour in the Section Material Settings

                },
                    "ValueLabel": 
                    // Optional
                    {                             
                        "ShowLabel": true,           
                        // Boolean, Optional, Defaults to true
                        // Show the label (or not)

                        "BackdropColor": "#000000",             
                        // String (Hex String, i.e. #RRGGBB), Optional
                        // Defaults to the Material colour in the Section Material Settings

                        "TextColor": "#FFFFFF",             
                        // String (Hex String, i.e. #RRGGBB), Optional
                        // Defaults to the Material colour in the Section Material Settings

                    }
                }
           ],
           "Series": {                                  
           // Mandatory

                "Text": "Qwerty",                         
                // String, Mandatory

                "LabelColor": "#000000",             
                // String, Optional, Defaults to the Material colour in the Section Material Settings
                // Hex colour string

                "BackdropColor": "#000000",             
                // String, Optional, Defaults to the Material colour in the Section Material Settings
                // Hex colour string

                "LineColor": "#000000",             
                // String, Optional
                // Hex colour string

                "ShapeColor": "#000000",             
                // String, Optional, Defaults to the Material colour in the Section Material Settings
                // Hex colour string

                "Shape": "Square",          
                // Enumeration, Optional, Default is that configured in LegendSettings/ItemStyle/ColourBlockShape
                // Options: "None", "Square", "Circle", "Cross", "Plus"

                "PointShape": "Plus"           
                // Enumeration, Optional, Default is that configured in LineSettings/PointShape
                // Options: "Cross", "None", "Cube", "Cylinder", "Sphere", "Plus"

           }
        }
    ],
    "Legend": 
    // Optional
    {                                 
        "ShowLegend": true,           
        // Boolean, Optional, Defaults to true
        // Show the legend (or not)

        "RevealMode": "VisibleLines",    
        // Enumeration, Optional, Default is VisibleLines
        // Options are "All" and "VisibleLines". , which will only show the information per line as they 
        // are animated (using 'Amnimate Per Line')

        "Title": "Qwerty",                        
        // String, Optional

        "TitleColor": "#000000",             
        // String, Optional, Defaults to the Material colour in the Section Material Settings
        // Hex colour string

    }
}

US Map

{
    // Coming soon!
}