.. _ext_omni_isaac_occupancy_map:

===============================
Occupancy Map Generator
===============================


.. _ext_omni_isaac_occupancy_map_about:

About
=================

The :ref:`ext_omni_isaac_occupancy_map` Extension is used to generate a binary map of whether or not an area in the scene is occupied at a given height.
It uses physics collision geometry in the :ref:`isaac_sim_glossary_stage` to determine if a location is occupied or not.


This extension is enabled by default. If it is ever disabled, it can be re-enabled from the `Extension Manager <../../prod_extensions/prod_extensions/ext_extension-manager.html>`_
by searching for ``omni.isaac.occupancy_map``.

To access this Extension, go to the top menu bar and click `Isaac Utils > Occupancy Map`.

.. _ext_omni_isaac_occupancy_map_conventions:

Conventions
^^^^^^^^^^^^

- All geometry must have `Collisions Enabled` in order to be detected by the Occupancy Map Generator. Otherwise the geometry will not appear in the final map.
- The `Start` location of the map cannot be occupied.

.. note:: If mapping does not work correctly make sure the start location is not occupied. You can view the physics geometry by clicking the Show/Hide (eye icon) in the viewport window and selecting ``Show By Type -> Physics Mesh -> All``

.. _ext_omni_isaac_occupancy_map_api_doc:

API Documentation
=================

See the |link_ext| for usage information.

    .. |link_ext| raw:: html

        <a href="../../py/isaacsim/source/extensions/omni.isaac.occupancy_map/docs/index.html" target="_blank">API Documentation</a>

.. _ext_omni_isaac_occupancy_map_user_interface:

User Interface
=================

.. figure:: /content/images/isaac_occupancy_map_ui_1.png
    :align: center
    :alt: Main Occupancy Map Generator UI Window

* **Origin**: An open location inside of the area you wish to map
* **Lower/Upper Bound**: Areas outside of these bounds will not be mapped. These are maximal bounds, the mapped area may be smaller than these limits
* **Positioning**:

    - **CENTER TO SELECTION**: The origin will be moved to the center of a selected prim or prims
    - **BOUND SELECTION**: The bounds will updated to incorporate the selected prim or prims

- **Cell Size**: the number of centimeters each pixel in the final image represents


.. _ext_omni_isaac_occupancy_map_tutorials:

Tutorials & Examples
=====================

The following tutorials and examples showcase how to best use this extension:

**Tutorials**

- Occupancy Map Generator Tutorial: :ref:`isaac_sim_app_tutorial_advanced_occupancy_map`

**Examples**

- Block World Generator Map: `Isaac Utils -> Block World Generator Map`


Block World Generator Map
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The Block World Generator Map Extension converts a 2d occupancy map into a 3D block world.
In this extension black pixels in the occupancy map are considered occupied and white pixels are considered free space.
The generated 3D world automatically has a collision mesh applied for all the occupied pixels.


To access this Extension, go to the top menu bar and click `Isaac Utils -> Block World Generator Map`.

.. figure:: /content/images/isaac_block_world_ui.png
    :align: center
    :alt: Main Block World Generator UI Window

- **Cell Size**: Real-world units represented by a single pixel in the 2D occupancy image. Note that default unit in Isaac Sim is in centimeters.
- **Load** : Load the desired occupancy image.
- **Generate**: Button to generate the 3D block world.


Block World Usage Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To run the Example:

1. Save the following image to disk:

.. figure:: /content/images/isaac_block_world_example.png
    :align: center
    :alt: Block World Generator Example

2. Go to the top menu bar and click `Isaac Utils -> Block World Generator Map`.
3. Press the ``Load Image`` button and open the saved image. A window titled ``Visualization`` will appear.
4. Press the ``Generate Block World`` button to create geometry corresponding to the input occupancy map in the :ref:`isaac_sim_glossary_stage`.

.. figure:: /content/images/isaac_block_world_viewport.png
    :align: center
    :alt: Block World Generator Example