Installation

Note

In accordance with the Unreal Engine EULA, we cannot offer HoloOcean through pypi. Before installing HoloOcean, you must make an Epic Games account, link it to your GitHub account, and accept the Unreal Engine EULA. Follow the steps here. After linking the accounts, you can proceed to install HoloOcean. Please remember to accept the email invitation from Unreal Engine.

Note

HoloOcean has updated from using Unreal Engine 4.27 to 5.3. If you are developing worlds, agents, sensors, etc. using Unreal, you will need to download Unreal Engine 5.3 to develop from the current release and develop branches. Unreal Engine 4.27 usage is still available using previous releases of HoloOcean.

HoloOcean is installed in two portions: a client python library (holoocean) is installed first, which then downloads world packages. The python portion is very small, while the world packages (“binaries”) can be several gigabytes.

Requirements

  • Python >= 3.7

  • Several gigabytes of storage

  • pip3

  • Linux or Windows 64bit

  • Preferably a competent GPU

  • For Linux: OpenGL 3+, gcc (minimum build-essential package)

For the build-essential package for Linux, you can run the following console command:

sudo apt install build-essential

Installation

Python Library

To install the most recent stable release of the HoloOcean library, download or clone our repo at: https://github.com/byu-holoocean/HoloOcean. We suggest cloning it with lowercase naming, as our example code uses, like so:

git clone git@github.com:byu-holoocean/HoloOcean.git holoocean

Note

If you get a Page Not Found Error when trying to access the repository, it means you have not linked your GitHub account to your Epic Games account. Please refer to the instructions above.

From the cloned repo, install the package by doing to following:

cd holoocean/client
pip install .

Worlds Packages

Note

The Ocean package is the only package currently available. Users can create custom worlds and packages if desired.

To install the most recent version of the Ocean worlds package, open a python shell by typing the following and hit enter:

python

Install the package by running the following python commands:

import holoocean
holoocean.install("Ocean")

To do these steps in a single console command, use:

python -c `import holoocean; holoocean.install("Ocean")`

Installation for Development

Both the python library and the available worlds of HoloOcean are actively being developed. These instructions describe how to access the most recent development updates.

For more detailed instructions on installation for development, see Developing HoloOcean.

Python Library

The “release” branch of the GitHub repository contains the latest stable release of the client library, while the “develop” branch contains the latest features and bug fixes but may not be stable. To install the develop branch, clone the repository as described above, then check out the develop branch and rebuild the package:

git checkout develop
cd holoocean/client
pip install .

World Packages

Note

Development versions of the HoloOcean worlds are auto-generated for Linux machines, but not for Windows. Windows binaries are currently compiled manually and may not be up-to-date with the latest changes. To get development versions of the Windows worlds, please reach out to the HoloOcean team.

It is advised that you use the development versions of the Ocean package when on the develop branch of the library. These will contain the latest updates to the worlds that may be necessary to use some features on the develop branch. Using the develop branch with the release version of the worlds may result in unexpected behavior.

To install the development version of the Ocean package, open a python shell and remove any previous versions of the binaries by running the following command:

import holoocean
holoocean.remove("Ocean")

Then install the development version:

holoocean.install("Ocean", branch="develop")