Other Types
===========

.. contents:: Table of Contents
    :depth: 2
    :local:


``group``
~~~~~~~~~

Groups are the simplest scene graph location type, with no special meaning.
They are typically used to organize the scene and to apply transformations
affecting all descendant locations.


``assembly`` and ``component``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Components are designed to be the building blocks that assets can be made out
of. Assemblies are designed to be structured assets that can be built out of
components or other assemblies.

As a convention for complex hierarchies, a component is a building block that
can contain a hierarchy of geometry and non-geometry locations, but it
shouldn't contain any assemblies or other components. This convention is used
by some tools in Katana to reduce the amount of Scenegraph that needs to be
inspected to do certain things, such as search for LookFiles that are being
used, with the assumption that no LookFile is assigned deeper than any
'component' location.

.. _camera-attrs:

``camera``
~~~~~~~~~~

Location type to declare a camera.

.. list-table::
    :header-rows: 1
    :widths: 5 20 75

    - * Type
      * Attribute
      * Description

    - * :kat:type:`string`
      * :kat:attr:`geometry.projection`
      * The projection mode, such as perspective or orthographic.

    - * :kat:type:`double`
      * :kat:attr:`geometry.fov`
      * The field of view angle in degrees

    - * :kat:type:`double`
      * :kat:attr:`geometry.near`
      * Distance of the near clipping plane

    - * :kat:type:`double`
      * :kat:attr:`geometry.far`
      * Distance of the far clipping plane

    - * :kat:type:`double`
      * :kat:attr:`geometry.left`
        :kat:attr:`geometry.right`
        :kat:attr:`geometry.bottom`
        :kat:attr:`geometry.top`
      * The screen window placement on the imaging plane. The bound of the
        screen window.

    - * :kat:type:`double`
      * :kat:attr:`geometry.centerOfInterest`
      * This is used for tumbling in the viewer; it has no affect on the camera
        matrix.

    - * :kat:type:`double`
      * :kat:attr:`geometry.orthographicWidth`
      * The orthographic projection width.

.. _light-attrs:

``light``
~~~~~~~~~

Location type to declare a light.

.. list-table::
    :header-rows: 1
    :widths: 5 20 75

    - * Type
      * Attribute
      * Description

    - * :kat:type:`group`
      * :kat:attr:`geometry`
      * Shares the same attributes as cameras.

    - * :kat:type:`float`
      * :kat:attr:`geometry.radius`
      * The radius of the light.

    - * :kat:type:`float[3]`
      * :kat:attr:`geometry.previewColor`
      * The color of the light in the Viewer.



``volume`` and ``openvdbasset``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

An openvdbasset location should be nested under a volume location.

.. _volume-attrs:

The volume location has the following attributes, with <fieldName> being the name of the OpenVDB field(s).

.. list-table::
    :header-rows: 1
    :widths: 5 20 75

    - * Type
      * Attribute
      * Description

    - * :kat:type:`string`
      * :kat:attr:`fields.<fieldName>.fieldName`
      * The name of the field from the openVDB asset.

    - * :kat:type:`string`
      * :kat:attr:`fields.<fieldName>.fieldId`
      * The field location this volume is parent to.

.. _openvdbasset-attrs:

The openvdbasset location has the following attributes:

.. list-table::
    :header-rows: 1
    :widths: 5 20 75

    - * Type
      * Attribute
      * Description

    - * :kat:type:`string`
      * :kat:attr:`fieldAttributes.filePath`
      * The file path to the openVDB asset on disk.

    - * :kat:type:`string`
      * :kat:attr:`fieldAttributes.fieldName`
      * The name of the field to use from the OpenVDB asset. This should match the  ``fields.<fieldName>.fieldName`` attribute of the parent volume.

    - * :kat:type:`int`
      * :kat:attr:`fieldAttributes.fieldIndex`
      * The index of the field to use from the OpenVDB asset.

    - * :kat:type:`string`
      * :kat:attr:`fieldAttributes.fieldDataType`
      * The data type of the field (optional attribute).

    - * :kat:type:`string`
      * :kat:attr:`fieldAttributes.fieldClass`
      * The class of the grid (optional attribute).


``material``
~~~~~~~~~~~~

See :doc:`Materials`.

``instance``, ``instance source`` and ``instance array``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

See :doc:`Instancing`.

``level-of-detail group`` and ``level-of-detail``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A ``level-of-detail group`` location should contain child locations of type
``level-of-detail``. Each child corresponds to an LoD, and should have the
following attributes:

.. list-table::
    :header-rows: 1
    :widths: 5 20 75

    - * Type
      * Attribute
      * Description

    - * :kat:type:`float`
      * :kat:attr:`lodRanges.minVisible`
        :kat:attr:`lodRanges.maxVisible`
        :kat:attr:`lodRanges.lowerTransition`
        :kat:attr:`lodRanges.upperTransition`
      * Geometry with a specific level of detail.


.. _procedural-attrs:

``renderer procedural`` and ``renderer procedural args``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. note::
    This section is under construction.

.. list-table::
    :header-rows: 1
    :widths: 5 20 75

    - * Type
      * Attribute
      * Description

    - * :kat:type:`string`
      * :kat:attr:`rendererProcedural.procedural`
      *

    - * :kat:type:`group`
      * :kat:attr:`rendererProcedural.args`
      *

    - * :kat:type:`string`
      * :kat:attr:`rendererProcedural.args.__outputstyle`
      *

    - * :kat:type:`int`
      * :kat:attr:`rendererProcedural.useInfiniteBounds`
      *

    - * :kat:type:`string`
      * :kat:attr:`rendererProcedural.includeCameraInfo`
      *

    - * :kat:type:`string`
      * :kat:attr:`rendererProcedural.cameraInfo.whichCamera`
      *

    - * :kat:type:`string`
      * :kat:attr:`rendererProcedural.cameraInfo.cameraPath`
      *

    - * :kat:type:`group`
      * :kat:attr:`geometry.arbitrary`
      * See :doc:`ArbitraryAttributes`.

``error``
~~~~~~~~~

Renders halt if this type is encountered (fatal error). An error message is
written to the render log and displayed in the console.