Using OVE¶
There are several steps that must be performed in order to use OVE to control a display.
Before using OVE, you will need to install OVE Core, any OVE Apps, and any OVE Services that you intend to use. OVE UIs and OVE SDKs may or may not be installed based on your requirements, as all core components provide REST APIs that cover all functionalities provided by these components. Installation guidelines can be found in the OVE Installation Guide. As a part of the installation, you must ensure that the OVE core server, and all OVE apps, are accessible from the computers connected to the monitors that will be used in the display.
Setting up OVE¶
By default, OVE provides two spaces
, that are useful for trying out some of the OVE Apps with sample content. These are:
LocalNine
- Thisspace
contains nineclients
arranged in3 x 3
configuration. Eachclient
has a dimension of1440 x 808
pixels and the totalspace
has a dimension of4320 x 2424
pixels.LocalFour
- Thisspace
contains fourclients
arranged in2 x 2
configuration. Eachclient
has a dimension of1440 x 808
pixels and the totalspace
has a dimension of2880 x 1616
pixels.
You will need to modify the Spaces.json file and introduce a new space
in OVE, before it can be used.
Launching browsers¶
In order to use OVE, you will need to open the URL of each client
in a separate web browser window (or tab). Each URL has the form: http://OVE_CORE_HOST:PORT/view.html?oveViewId={SPACE}-{ID}
. These URLs can also be found on the http://OVE_CORE_HOST:PORT
page. The values for OVE_CORE_HOST
and PORT
must be set as explained in the OVE Installation Guide. The value for SPACE
would be the name of the space
used, such as LocalNine
, LocalFour
, or a name of a new space
that has been defined in the Spaces.json file. The value for ID
is the index of the client
associated with the browser window, in the definition of the space
in Spaces.json file. Not providing the oveViewId
or providing the oveViewId
in an invalid format would result in OVE printing either the Name of space not provided
or the Client id not provided
warning on the browser console.
It is recommended to run each OVE client
in a separate Google Chrome browser launched in full-screen mode. Running Google Chrome in Incognito mode will ensure a smooth operation of OVE. It is also important to set the Google Chrome auto-play policy to No user gesture is required
, which can be accessed by opening the chrome://flags/#autoplay-policy
URL. The Default
auto-play policy prevents the playback of audio and video on OVE. The Console
in Google Chrome DevTools can be used to debug OVE applications when in development.
We recommend using OVE with Google Chrome as this is the web browser used for development and in production at the Data Science Institute. However, OVE should also be compatible with other modern web browsers: if you encounter any browser-specific bugs please report them as an Issue.
To test OVE functionality, you can simply open four web browser windows (or tabs) with the following URLs corresponding to the LocalFour
space:
http://OVE_CORE_HOST:PORT/view.html?oveViewId=LocalFour-0
http://OVE_CORE_HOST:PORT/view.html?oveViewId=LocalFour-1
http://OVE_CORE_HOST:PORT/view.html?oveViewId=LocalFour-2
http://OVE_CORE_HOST:PORT/view.html?oveViewId=LocalFour-3
However, in a much larger OVE installation with many monitors, opening browser windows may be sufficiently time-consuming for automation to be worthwhile.
On Windows, a PowerShell script can be used to launch full-screen browsers with the correct URLs. On Linux, a Bash script can be used. On MacOS, either Bash or AppleScript could be used.
Launching OVE Apps¶
OVE provides three different ways of launching apps into an OVE environment:
The OVE UI is designed to be used by the most basic users of OVE. The OVE Core APIs are intended to be used by the most advanced users of OVE.
Given below are instructions on how to load sample content using the Images App. A complete list of all apps and similar instructions on how to use them can be found in the OVE Apps repository.
Launching OVE Apps using OVE UI¶
The Launcher UI can be used to launch applications into an OVE environment. The step-by-step process involves:
- Choosing the type of application to launch
- Selecting space and providing geometry details
- Configuring initial application state
- Reviewing state configuration and operation details (where you can choose to delete existing sections or show the app-specific controller)
- Launching a new application instance
The confirmation step provides a link to Preview the space as well as a link to the app-specific usage documentation. The Launcher UI can be loaded into a browser window by accessing the URL http://OVE_CORE_HOST:PORT/ui/launcher
. The user interface provides easy-to-follow instructions and validates user input. For those who wish to upload many apps at once, the Launcher UI also provides operating system specific curl commands.
To launch the Images App with a sample image, in the LocalNine
space, somply fill in the form then press launch.
Launching OVE Apps using the Python Client Library¶
The Python Client Library is one of the SDKs provided by OVE, which can be installed separately by following the installation instructions.
To launch the Images App with a sample image, in the LocalNine
space, run:
from ove.config import local_space as space
space.enable_online_mode()
space.delete_sections()
image = space.add_section(w=4320, h=2424, x=0, y=0, app_type='images')
image.set_url("https://farm4.staticflickr.com/3107/2431422903_632ce51b56_o_d.jpg", "shelley")
Launching OVE Apps using OVE Core APIs¶
OVE provides a number of useful APIs that can be used to launch applications and load content. The complete list of APIs provided by OVE Core is documented at: http://OVE_CORE_HOST:PORT/api-docs/
.
The APIs for OVE core, all apps, and all services are documented using Swagger, and it is possible to directly invoke them from within the API documentation page (http://OVE_CORE_HOST:PORT/api-docs/
) using a web browser. Alternatively, a standalone tool such as curl can be used.
An image can be loaded into the LocalFour
space using the OVE APIs, by running the following commands using curl.
Linux/Mac:
curl --header "Content-Type: application/json" --request DELETE http://OVE_CORE_HOST:PORT/sections
curl --header "Content-Type: application/json" --request POST --data '{"app": {"url": "http://OVE_CORE_HOST:PORT/app/images","states": {"load": {"tileSources": "https://openseadragon.github.io/example-images/highsmith/highsmith.dzi"}}}, "space": "LocalFour", "h": 500, "w": 500, "y": 0, "x": 0}' http://OVE_CORE_HOST:PORT/section
Windows:
curl --header "Content-Type: application/json" --request DELETE http://OVE_CORE_HOST:PORT/sections
curl --header "Content-Type: application/json" --request POST --data "{\"app\": {\"url\": \"http://OVE_CORE_HOST:PORT/app/images\", \"states\": {\"load\": {\"tileSources\": \"https://openseadragon.github.io/example-images/highsmith/highsmith.dzi\"}}}, \"space\": \"LocalFour\", \"h\": 500, \"w\": 500, \"y\": 0, \"x\": 0}" http://OVE_CORE_HOST:PORT/section
These commands clear all sections on OVE, and create a new section containing an instance of the Images App. In this example we are loading a Deep Zoom image.
The OVE core APIs can be used for various other purposes such as grouping sections together, transforming section dimensions by translating and scaling, or for moving sections from one space to another. APIs exposed by OVE apps can be used to set, update or flush application state and to obtain differences between states or to transform from one state to another using pan and zoom operations. A catalogue of all available APIs for OVE core and all active apps is available at http://OVE_CORE_HOST:PORT
.
Hosting content¶
Before using most OVE applications, you may need to host the content that you plan to load into them. OVE expects content to be accessible via URLs both locally and also in a distributed deployment. There are multiple options to host your content such that they are accessible via URLs.
- Externally hosted static content: this is a straightforward option, but may expose your content to 3rd parties. Choices include cloud hosting providers such as Amazon AWS and Google Cloud or specialised cloud application platform providers such as Heroku and Netlify.
- Locally hosted static content: this is a convenient choice for local testing and also does not expose your content to third parties. Choices include web servers such as Apache HTTP Server, nginx, and Microsoft IIS, or simpler alternatives such as Node.js HTTP Server or Python Simple HTTP Server.
- Using an object storage: an object storage can be setup either locally or externally and can have open or restricted access. Choices include cloud storage services such as Amazon S3 and locally deployed alternatives (private cloud storage) such as Minio.
- Using the OVE Asset Manager: this internally uses an object storage but is optimised for OVE projects and provides a much better user experience.
Locally hosted static content¶
Once you have stored the desired content in a directory structure, all you need is to start a web-server. This can be done using one of the approaches shown below:
Node.js:
npm install http-server -g
http-server
Python 2:
python -m SimpleHTTPServer 9999
Python 3:
python3 -m http.server 9999
Please note that you may need to specify a port number if you have chosen to use Python and the default of port 8000 is already in use (the examples above specify 9999 as the port to use).
Once the server has started, the content will be available at the any of the URLs printed on the console, if you have chosen to use Node.js or at http://localhost:8000
(or corresponding port number), if you have chosen to use Python.
Using the OVE Asset Manager¶
Please read this short tutorial on the basic functionality of the OVE Asset Manager.
Controlling OVE Apps and designing interactive visualisations¶
Once an App has been launched in an OVE space
it can be controlled using the corresponding controller, which provides app-specific functionality. For example, the controller of the Images App supports panning and zooming of images that have been loaded. The controller can be loaded into a separate browser window by accessing the URL http://OVE_CORE_HOST:PORT/app/images/control.html?oveSectionId=0
. Not providing the oveSectionId
would result in OVE printing the Section id not provided
warning on the browser console.
A common practice when designing projects with interactive visualisations is to create a custom launcher application that is capable of making API calls. Such applications are usually designed to run on web browsers and invoke the OVE Core API using JavaScript code. These applications provide a single-click (or single-touch) experience for launching and controlling OVE apps.
When designing content to be displayed in an OVE environment, please also be aware of the potential pitfalls.