=======================
Shelf
=======================

.. |small_shelf| image:: ../images/panels/shelf/small_shelf.png

Shelves hold commonly used actions and tools. A shelf can be added with the Shelf Editor or with the Python API. Custom shelves created with Shelf Editor can also be extended with the Script Editor by pressing the |small_shelf| *Add to shelf* button.

.. image:: ../images/panels/shelf/shelf.png
        :align: center

Shelves
-------
Built-in shelves can't be edited with the GUI but can be extended using Python APIs. 

.. |camera| image:: ../images/panels/shelf/camera.png
.. |create_ref| image:: ../images/panels/shelf/create_reference.png

.. |mesh| image:: ../images/panels/shelf/mesh.png
.. |s_mesh| image:: ../images/panels/shelf/sphere_mesh.png

.. |cube| image:: ../images/panels/shelf/cube.png
.. |sphere| image:: ../images/panels/shelf/sphere.png
.. |cylinder| image:: ../images/panels/shelf/cylinder.png
.. |cone| image:: ../images/panels/shelf/cone.png
.. |capsule| image:: ../images/panels/shelf/capsule.png
.. |sculpt| image:: ../images/panels/shelf/sculpt.png
.. |paint| image:: ../images/panels/shelf/paint.png

.. |light_cylinder| image:: ../images/panels/shelf/light_cylinder.png
.. |light_disk| image:: ../images/panels/shelf/light_disk.png
.. |light_distant| image:: ../images/panels/shelf/light_distant.png
.. |light_environment| image:: ../images/panels/shelf/light_environment.png
.. |light_quad| image:: ../images/panels/shelf/light_quad.png
.. |light_sphere| image:: ../images/panels/shelf/light_sphere.png

.. |pointinstancer| image:: ../images/panels/shelf/pointinstancer.png
.. |paint_instance| image:: ../images/panels/shelf/paint_instance.png

General
=======

.. table::
    :align: center

    ============  ============================================================
    Button        Action
    ============  ============================================================
    |create_ref|  Create reference
    |camera|      Create camera
    ============  ============================================================

Geometry
^^^^^^^^
.. table::
    :align: center

    ============  ============================================================
    Button        Action
    ============  ============================================================
    |mesh|        Create polygonal plane with :ref:`settings<docs/menus/create_menu:general>`
    |s_mesh|      Create polygonal sphere with :ref:`settings<docs/menus/create_menu:general>`
    |cube|        Create cube
    |sphere|      Create sphere
    |cylinder|    Create cylinder
    |cone|        Create cone
    |capsule|     Create capsule
    |sculpt|      :ref:`Sculpt Tool<docs/panels/tools/sculpt_tool:sculpt tool>`
    |paint|       :ref:`Paint Primvar Tool<docs/panels/tools/paint_primvar_tool:paint primvar tool>`
    ============  ============================================================

Light
^^^^^
.. table::
    :align: center

    ===================  ============================================================
    Button               Action
    ===================  ============================================================
    |light_cylinder|     Create UsdLuxCylinderLight
    |light_disk|         Create UsdLuxDiskLight
    |light_distant|      Create UsdLuxDistantLight
    |light_environment|  Create UsdLuxDomeLight
    |light_quad|         Create UsdLuxRectLight
    |light_sphere|       Create UsdLuxSphereLight
    ===================  ============================================================

Instancer
^^^^^^^^^

.. note:: Violet color represents instancing.

.. table::
    :align: center

    ===================  ============================================================
    Button               Action
    ===================  ============================================================
    |pointinstancer|     Create PointInstancer
    |paint_instance|     :ref:`Point Instancer Tool<docs/panels/tools/point_instancer_tool:point instancer tool>`
    ===================  ============================================================

Shelf Editor
------------

.. |gear| image:: ../images/panels/shelf/gear.png

.. note:: *Custom shelves* are shelves that are created with the Shelf Editor. Only custom shelves can be edited with the Shelf Editor or the Script Editor.

The Shelf Editor can create and edit custom shelves. It can be accessed by pressing the |gear| *gear* button or right-click on a custom shelf or one of its actions.

.. image:: ../images/panels/shelf/shelf_editor.png
        :align: center

Custom actions can also be separators, have an icon, or be displayed as text if they don't have an icon. 

You can use a built-in icon or type any file path.

Custom shelves are saved as separate JSON files so they can be copied to another machine if needed.