grapho-user-guide

graphobymod-black

User guide for the Grapho data science + storytelling toolkit

Table of Contents

Introduction

Welcome to the user guide for Grapho - a toolkit for data science + storytelling.

one-pager-grapho_b-tiles

In 2024 data science is having a moment with the explosion in generative AI fuelled by deep learning techniques and vast data collections. But the reality is that for all the technical advances, it comes back to humans. How are we collecting data? Why are we collecting it? What are our motivations for using it? How do we communicate? Getting to grips with modern data still requires that ancient skillset we’ve evolved - storytelling - and how we tell stories is changing.

This toolkit is for anyone anyone working with graph data. It empowers users to create data stories on any platform including spatial computing. It lets you draw connections in real-time within immersive virtual worlds. Explore and query graphs using parameters relevant to you. Grapho productivity tools make taking a deep dive into complex data sets more accessible and engaging. It brings connections to life.

Contact us for more information.

See the Grapho Developers Guide for more information on preparing data and systems for Grapho.

Return to Table of Contents.

Benefits

Why “data science + storytelling”?

Data is about people. Your people must understand the story your data is telling. As data scientists lean further into the astonishing power of Machine Learning, a one-size-fits-all automated approach is inadequate. In the age of AI, coherant storytelling is more valuable than ever.

History

Grapho started life as a spatial knowledge graph interface for a VR documentary A Clever Label released on Steam in 2021 using a Neo4j backend. This was then spun out as a white label tool Grapho XR in 2022 for knowledge graphs. Our first customer was APNIC.

In 2024 ISO 76120 - Graph Query Language (GQL) was published - the first database query language standard in 37 years since SQL. This provides a future-proof way of defining data structures and basic operations on property graphs. GQL is largely based on Neo4j’s CYPHER language.

In 2024 the Grapho service offering was expanded to applied data science including deep learning model creation and training.

Return to Table of Contents.

Roadmap

Grapho is available through Mod’s SaaS and consulting service.

Grapho XR Roadmap

Return to Table of Contents.

Grapho XR

Grapho XR is a spatial graph visualisation tool and a new way to manage and present graph data.

one-pager-grapho-xr-tiles

It’s an interactive experience that feels like Minority Report meets 60 Minutes. Grapho provides flexibility to switch between data sets and between visual themes, ensuring the look is right for your audience. Display and take control of your data. Share knowledge in a hands-on intuitive way. Use it on-set as an interactive in-camera VFX solution.

See also

Return to Table of Contents.

Quickstart for Grapho XR

Installation

PCVR

Mobile VR

Return to Table of Contents.

Induction

Grapho XR is configured by default with a “demo” graph database - a small set of actors & movies in cross-referenced pop culture

Return to Table of Contents.

System Requirements

Grapho XR builds are available for the following platforms.

Return to Table of Contents.

PCVR

NOTE Grapho XR’s “desktop mode” (non-XR) support on Windows is provided for backwards compatibility, accessibility, and testing. We only recommend use of 3D visualisation on 3D displays for professional use given given research findings that 2D visualisation works better on a 2D displays. See Dashboard options for off-the-shelf and custom options.

Mac OS

Mobile VR

Controllers are currently required. Hand tracking support on request.

We don’t currently recommend hand tracking for precise manipulation of graph data for professional use.

Return to Table of Contents.

Development Frameworks

Grapho XR plugins and a separate Grapho Development Guide are provided to licensees for third party development with the following frameworks

Return to Table of Contents.

User Interface

The Grapho UI has the following key components

A Handle is a special type of node that is a convenient handle to a section of a graph that speeds up navigation and helps manage clutter.

Think of it as a pointer or a bookmark to a particular spot in a the graph.

handle

The graph is made up of Nodes

handle

Connections between nodes are relationships (or links)

handle

Nodes properties (anything from multimedia to a simple list of text) appear on an attached surface - the data pad.

datapad-gif

Context menus allow you to perform actions on a particular node.

handle

Return to Table of Contents.

Controls

Meta Quest Touch Controller layout

controls

Passthrough

**Passthrough camera support is available on Quest and Vive mobile headsets but not on Windows.

See Mixed Reality for PCVR camera support for combining greenscreen live action footage and Grapho visualisation**

Toggle FACE BUTTON #2 button to switch between virtual environment and passthrough (see the real world through the onboard cameras). Passthrough (sometimes called Mixed Reality) can be great for new users unfamiliar with VR.

TIP Use this if real world surroundings make it too hard virtual objects.

Teleport

teleport

Push LEFT or RIGHT joystick forward to show reticule and direction arrow on the ground plane. Rotate joystick to change direction of the arrow. This determines what direction you teleport. Release joystick to teleport.

NOTE Users new to VR can get confused if they trigger teleport by mistake. You can change Settings > Teleport delay to adjust how responsive the joysticks are if this is a problem.

Grab

grab

Use GRIP button to grab object (handle, node, relationship).

Force Pull

force-pull-gif

Force pull is a telekinesis-like feature that lets you quickly grab an object regardless of its distance from you.

force-pull

VR mode:

Bump

Use natural hand movements to move objects out of the way

Open Graph

handle-open

Grab Handle. Flip Handle upside down to open graph nodes (run a query).

Flip again to close graph nodes.

handle-close

Open Node

node-open

Press TRIGGER button to toggle opening and closing of a node to reveal its “Datapad” which shows the properties of a node.

Settings > Open Datapad on Grab checkbox controls whether this happens automatically on GRAB. It can get annoying sometimes to have this on but useful as a default for new starters.

Open Context Menu

context-menu

Additional functionality is available while holding a node.

GRAB + <FACE BUTTON #1> opens a floating menu of buttons

While keeping buttons pressed, move hand over the buttons to highlight them

Release <FACE BUTTON #1> to select highlight action.

Move your hand off the menu and release <FACE BUTTON #1> to close menu without doing an action.

Expand

Context Menu > Expand

Any neighbouring node not already visible are spawned

Collapse

Any neighbouring node that was previously expanded (but not part of original query) is hidden

Hide

The node is hidden.

To reveal node again you currently have to Close Graph and Open Graph again using the Handle

Hide Unselected

hide-unselected

Pin

The node is pinned in place - moving neighbouring parts of the graph will have no effect on it

Unpin

The node is unpinned - moving neighbouring parts of the graph will effect its position

Bookmark

Not yet implemented. Sorry about that!

Settings Menu

settings

Press SETTINGS button on Left Controller

NOTE - Changed settings are saved to your local device. There is currently no Reset Settings feature

settings

Return to Table of Contents.

Spectator Mode

Windows

The PCVR build of Grapho XR supports having a separate virtual camera with desktop user controls (separate view to what VR user can see) for collaborations.

CONTROL + S - Toggle Spectator Camera

WASD keys to move camera

Meta Quest

Spectator mode is not yet available for mobile VR.

However using Meta Quest Developer Hub > Casting > Start Forwarding Camera Input you can now remote operate the Quest virtual camera.

WARNING - do not attempt to use this while someone is wearing the HMD as this can make them very sick!

forward-input

Grapho Machine

Grapho Machines (GMs) are re-distributable applications and online services. They are how we build, deploy, distribute and operate services in a standard way. There is no one-size fits-all approach that will work for all use cases so GMs provide an abstraction layer for delivering services across a variety of platforms as required.

GMs include

GMs support a variety of container and virtual machine formats for use on your local device, on-premises hosting or on cloud platforms.

We use packer and terragrunt to maintain Infrastructure as Code definitions of all Grapho components to automated creation of Grapho Machine instances and GM variants for multiple platforms as required.

e.g. a Grapho Machine might be created as

Supported:

Contact us to discuss how we can accomodate any new infrastructure requirements not on this list.

The default Grapho Machine is currently a Linux Debian instance that hosts LXC Containers based on the Academy Software Foundation’s VFX Reference Platform.

See the Grapho Developers Guide for more information on preparing data and systems for Grapho.

Return to Table of Contents.

Online Services

Dashboard

Grapho provides useful screens for managing your data whether these are off-the-shelf integrations or custom built for specific use cases from popular frameworks.

e.g. Neo4j Neodash Dashboard Builder

graphsummitsydney2024-neodash

See our list of Integrations available below and contact us for any new integration requirements you might have.

Return to Table of Contents.

API

grapho-server is a sample python REST API service available to Grapho customers

This provides a thin abstraction layer to help manage vendor lock-in and provide data to Grapho applications in a consistent manner as part of a manageable pipeline.

Features

Public release COMING SOON

demo.grapho.app

Grapho XR default configuration includes this public instance of the Grapho API. It provides access to sample data sets.

See also

Return to Table of Contents.

Integrations

Return to Table of Contents.

Formats

Platforms

Graphics Engines

Return to Table of Contents.

Mixed Reality

LIV

Grapho XR PCVR supports the LIV Mixed Reality for real-time live action video integration.

Use Cases

Grapho has been deployed for a variety of use cases across major projects in different sectors.

Sectors

Case Studies

Asia-Pacific Network Information Centre (APNIC)

APNIC

The APNIC Visualisation Tool was built with Grapho XR to provide internal staff with a resource for network graph exploration and analysis on desktop and in VR.

Parramatta Light Rail

Parramatta-Light-Rail

Grapho tools were used to model and illustrate the complex interplay between people, processes and technology for the Software Management Plan.

Japan Broadcasting Corporation (NHK)

NHK

Grapho was used to design and prototype a digital human agent that communicated in Japanese sign language on broadcast TV.

National Film & Sound Archive (NFSA)

NFSA

Grapho tools are being used to update the service framework for Australia’s national multimedia collection, including a knowledge graph and a topological machine learning pipeline.

Neo4j

Neo4j

Neo4j field engineers and marketing managers use Grapho XR to help visitors to their trade show stand get a handle (literally!) on graph databases.

A Clever Label

ACL

Grapho XR’s first iteration was as the core mechanic behind Mod’s VR investigative documentary, A Clever Label, available on Steam.

Mod

Mod

Property graphs form a core component of Mod’s studio management and production pipeline - tracking physical and digital IP as well as managing storyworlds and productions.

Troubleshooting

We’re here to help.

For general issues on Grapho or this documentation, use https://github.com/modprods/grapho-user-guide/issues or contact your Grapho account manager.

Return to Table of Contents.

Support

Email - support (AT) grapho (DOT) app

Discord - post in channel #grapho on Mod’s Discord server