.. |point_instancer_demo| image:: ../../images/tools/point_instancer_tool/point_instancer_demo.gif
.. |point_instancer_tool_settings| image:: ../../images/tools/point_instancer_tool/point_instancer_tool_settings.png

.. |create_instancer| image:: ../../images/tools/point_instancer_tool/create_instancer.png
.. |instancer_tool| image:: ../../images/tools/point_instancer_tool/instancer_tool.png

Point Instancer Tool
====================

The **Point Instancer Tool** provides ability to place assets as point instances over the surface
using a brush. It allows to interact with the 
`UsdGeomPointInstancer <http://openusd.org/dev/api/class_usd_geom_point_instancer.html>`_ objects.

Multiple prototypes are scattered among its "points".
This tool also allows to assign prims to be used as prototypes, which represent the base for the scattered instances.
UsdRelationship prototypes are used to identify and order all of the possible prototypes, by targeting the 
root prim of each prototype.

|point_instancer_demo|

The Point Instancer Tool provides the ability to scatter instances of objects (called "prototypes") onto a 
surface using a brush. 
Its properties allow you to place the instances with a wide range of custom features, e.g., 
using different transforms (such as scale, orientation, and position) for each, and with the defined density. 

Using Point Instancer Tool 
--------------------------

Define the set prim paths in the **prototype** attribute to make them available for scattering 
using the **Point Instancer Tool**:

1. Open the Tool Settings and the Outliner panels in the workspace. 
2. Select the Instancer tab in the Shelf bar and click to the |create_instancer| Create Instancer button. 
   It will add a new Instancer object to serve as a container to the instances created further.
3. Select the Point Instancer object in the Outliner panel and switch to the |instancer_tool| Instancer Tool. 
4. Include the objects you wish to use as prototypes to the selection in the 
   Outliner panel. E.g. by clicking to them holding the **Ctrl** button.

.. tip::
  This tool supports Multi Point Instancing. Thus you can add another instancer object as prototype.

5. Then press the **Add Selected Items as Prototypes** in the Tool Settings panel. 
   These items will be accessible in the **Current Prototype** property. 

.. warning:: For now, when creating a new Point Instancer object, you need to restart the Viewport renderer 
          (**View>Restart Renderer**) to make the instances visible. 

.. warning::
  Currently this tool doesn't support animated instances (Timesampled UsdPointInstancer objects).

Point Instancer Settings 
------------------------

It has the following properties displayed in the **Tool Settings panel**:

|point_instancer_tool_settings|

.. list-table:: 
      :header-rows: 1 
      :align: center

      * - Property 
        - Description
      * - Current Prototype 
        - The prototype selection field, which allows to pick one of the prims defined
          in **Point Instancer's** *prototype* field.
      * - Mode
        - Defines the brush mode: 
            * One
                Places only one instance directly under the cursor.
            * RandomInRadius
                Places a number of instances within the brush field.   
      * - Rotate to Normal 
        - Whether to place the instances according to the surface normal. 
      * - Scale 
        - Allows to modify the prototype's proportions for the resulting instances.
      * - Scale Randomness %
        - Allows to set the limit of randomized proportions applied to each instance.
      * - Rotation, deg 
        - Defines the minimal and maximal random rotation around the normal applied to the instances.
      * - Bend Randomness 
        - Defines the maximal degree to which the instance deviates from prototype's position.
      * - Vertical Offset
        - Defines how high the instances will be placed over the surface. 
      * - Radius 
        - Defines the size of the brush.
      * - Density 
        - The overall count of the instances per unit of area.
      * - Falloff
        - Defines how the instances are distributed in the brush's radius relative to its center and the border.
          The higher values will result in sparse instances closer to the brush borders.