.. _`improving-performance`:

================================
Improving HoloOcean Performance
================================

HoloOcean is fairly performant by default, but you can also sacrifice
features to increase your frames per second.

.. contents::
   :local:

RGBCamera
---------

By far, the biggest single thing you can do to improve performance is to
disable the ``RGBCamera``. Rendering the camera every frame causes a
context switch deep in the rendering code of the engine, which has a 
significant performance penalty.

This chart shows how much performance you can expect to gain or loose 
adjusting the RGBCamera (left column is frame time in milleseconds). Note
all these tests were done in the original Holodeck, but the results should be
the same.

+------------+----------+---------+-----------+---------+----------+---------+
| Resolution | UrbanCity          | MazeWorld           | AndroidPlayground  |
+============+==========+=========+===========+=========+==========+=========+
| No Camera  | 8.55 ms  | 117 fps | 4.69  ms  | 213 fps | 2.47 ms  | 405 fps |
+------------+----------+---------+-----------+---------+----------+---------+
| 64         | 17   ms  | 59 fps  | 11    ms  | 91 fps  | 4.87 ms  | 205 fps |
+------------+----------+---------+-----------+---------+----------+---------+
| 128        | 20   ms  | 50 fps  | 11.6  ms  | 86 fps  | 5.59 ms  | 179 fps |
+------------+----------+---------+-----------+---------+----------+---------+
| 256        | 22   ms  | 45 fps  | 14.71 ms  | 68 fps  | 9.02 ms  | 111 fps |
+------------+----------+---------+-----------+---------+----------+---------+
| 512        | 35   ms  | 29 fps  | 30.8  ms  | 32 fps  | 24.81 ms | 40 fps  |
+------------+----------+---------+-----------+---------+----------+---------+
| 1024       | 89   ms  | 11 fps  | 84.2  ms  | 12 fps  | 94.55 ms | 11 fps  |
+------------+----------+---------+-----------+---------+----------+---------+
| 2048       | 410  ms  | 2  fps  | 383   ms  | 3  fps  | 366   ms | 3  fps  |
+------------+----------+---------+-----------+---------+----------+---------+

Disabling the ``RGBCamera``
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Remove the ``RGBCamera`` entry from the scenario configuration file you are
using. 

See :ref:`custom-scenarios`.

Lowering the ``RGBCamera`` resolution
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Lowering the resolution of the ``RGBCamera`` can also help speed things up.
Create a :ref:`custom scenario <custom-scenarios>` and in the 
:ref:`configuration block <configuration-block>` for the ``RGBCamera`` set the
``CaptureWidth`` and ``CaptureHeight``.

See :class:`~holoocean.sensors.RGBCamera` for more details.

Changing ticks per capture
~~~~~~~~~~~~~~~~~~~~~~~~~~

The camera sample rate can be reduced to increase the average frames per second.
See :ref:`configure-sensors` and the ``Hz`` parameter for more info.

Sonar Sensors
--------------------------

The sonar sensors can also be taxing on performance. There's a number of things that can be
done to help improve their performance as well.

Lowering Octree Resolution
~~~~~~~~~~~~~~~~~~~~~~~~~~

The Octree resolution has a large impact on sonar performance. The higher ``octree_min``
is, the less leaves there are to search through, and the faster it'll run. This will have an
impact on image quality, especially at close distances. If most objects that are being
inspected are a ways away, this parameter can be safely increased quite a bit.

See :ref:`configure-octree` for info on how to do that.

Changing ticks per capture
~~~~~~~~~~~~~~~~~~~~~~~~~~

The sonar sample rate can be reduced to increase the average frames per second.
See :ref:`configure-sensors` and the ``Hz`` parameter for more info.


Disable Viewport Rendering
--------------------------

Rendering the viewport window can be unnecessary during training. You can 
disable the viewport with the 
:meth:`~holoocean.environments.HoloOceanEnvironment.should_render_viewport` 
method.

At lower ``RGBCamera`` resolutions, you can expect a ~40% frame time reduction.

Change Render Quality
---------------------

You can adjust HoloOcean to render at a lower (or higher) quality to improve
performance. See the 
:meth:`~holoocean.environments.HoloOceanEnvironment.set_render_quality` method

Below is a comparison of render qualities and the frame time in ms

========= =========== =========== ===================
 Quality   MazeWorld   UrbanCity   AndroidPlayground
========= =========== =========== ===================
 ``0``       10.34       12.33       6.63
 ``1``       10.53       15.06       6.84
 ``2``       14.81       19.19       8.66
 ``3``       15.58       21.78       9.2
========= =========== =========== ===================