Key Locations
=============
.. contents:: Table of Contents
:depth: 2
:local:
``/root``
~~~~~~~~~
The ``/root`` group is located at the top of the hierarchy and contains
collections, output settings, and global render settings. Most of these
attributes are not inherited.
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`group`
* :kat:attr:`<renderer>GlobalStatements`
* This defines global renderer-specific settings and has a different
name depending on which renderer is used, for instance
:kat:attr:`prmanGlobalStatements`, :kat:attr:`arnoldGlobalStatements`,
and similar.
- * :kat:type:`string`
* :kat:attr:`collections.<name>.cel`
* The CEL statement for a named collection.
- * :kat:type:`string[]`
* :kat:attr:`collections.<name>.baked`
* A list of scene graph location paths baked from the CEL statement of a
named collection.
Render Settings
'''''''''''''''
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`string`
* :kat:attr:`renderSettings.cameraName`
* The scene graph location of the camera; for example,
:kat:loc:`/root/world/cam/camera`.
- * :kat:type:`string`
* :kat:attr:`renderSettings.renderer`
* The name of the renderer plug-in to use when starting a render; for
example, ``prman``
- * :kat:type:`string`
* :kat:attr:`renderSettings.resolution`
* The render resolution preset, for example, ``512sq``.
- * :kat:type:`float[4]`
* :kat:attr:`renderSettings.overscan`
* Overscan value in pixels, in the order: left, bottom, right, top.
- * :kat:type:`string`
* :kat:attr:`renderSettings.adjustScreenWindow`
* The method for auto-adjusting the pixel ratio.
- * :kat:type:`int`
* :kat:attr:`renderSettings.maxTimeSamples`
* Defines how many times a point is sampled when the shutter is open.
- * :kat:type:`float`
* :kat:attr:`renderSettings.shutterOpen`
:kat:attr:`renderSettings.shutterClose`
* The timing of the opening and closing of the camera shutter. The
shutter begins opening at t=0, and finishes opening at ``shutterOpen``.
The shutter begins closing at ``shutterClose``, and finishes closing at
t=1.
- * :kat:type:`float`
* :kat:attr:`renderSettings.currentTime`
* The time of the frame for which the scene has been cooked,
as set in the timeline of the Katana main window.
- * :kat:type:`float[4]`
* :kat:attr:`renderSettings.cropWindow`
* The render crop window in normalized co-ordinates, in the order: xmin
xmax ymin ymax.
- * :kat:type:`string[]`
* :kat:attr:`renderSettings.interactiveOutputs`
* Indicates which outputs (as defined in
:kat:attr:`renderSettings.outputs`) to use for interactive renders
(Preview and Live Renders).
- * :kat:type:`int`
* :kat:attr:`renderSettings.producerCaching.limitProducerCaching`
* Controls how the Katana procedural caches potentially terminal scene
graph locations.
Pass Settings
'''''''''''''
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`group`
* :kat:attr:`renderSettings.outputs.<passname>`
* Contains a sub group for every render pass. The default pass is named
``primary``.
The :kat:attr:`rendererSettings`/:kat:attr:`locationSettings` are
configurable per output. Output types are customizable by plug-ins. For
instance, a color output has different :kat:attr:`rendererSettings`
than a shadow output.
- * :kat:type:`string`
* :kat:attr:`renderSettings.outputs.<passname>.type`
* The type of output.
- * :kat:type:`string`
* :kat:attr:`renderSettings.outputs.<passname>.includedByDefault`
* When enabled, this render definition is sent to the Render node.
- * :kat:type:`string`
* :kat:attr:`renderSettings.outputs.<passname>.rendererSettings.colorspace`
* The color space.
- * :kat:type:`string`
* :kat:attr:`renderSettings.outputs.<passname>.rendererSettings.fileExtension`
* The file extension of the output file.
- * :kat:type:`string`
* :kat:attr:`renderSettings.outputs.<passname>.rendererSettings.channel`
* The channel of the output file.
- * :kat:type:`group`
* :kat:attr:`renderSettings.outputs.<passname>.rendererSettings.convertSettings`
* Attribute group with file format-dependent conversion settings.
- * :kat:type:`int`
* :kat:attr:`renderSettings.outputs.<passname>.rendererSettings.clampOutput`
* Post-render, clamps negative RGB values to 0 and alpha values to 0-1.
- * :kat:type:`int`
* :kat:attr:`renderSettings.outputs.<passname>.rendererSettings.colorConvert`
* If ``1``, converts the rendered image data from linear to the output
colorspace specified in the filename post-render. The colorspace is
determined by OCIO's ``getColorSpaceFromFilepath()`` function, which
locates the longest, right-most colorspace substring.
- * :kat:type:`string`
* :kat:attr:`renderSettings.outputs.<passname>.rendererSettings.cameraName`
* Scene graph location to render from.
- * :kat:type:`string`
* :kat:attr:`renderSettings.outputs.<passname>.rendererSettings.locationType`
* The type of location.
- * :kat:type:`group`
* :kat:attr:`renderSettings.outputs.<passname>.rendererSettings.exrheaders`
* List of EXR headers to inject.
- * :kat:type:`string`
* :kat:attr:`renderSettings.outputs.<passname>.locationSettings.renderLocation`
* The file path and name of the output.
``/root/world``
~~~~~~~~~~~~~~~
This group defines attributes that are inherited by the whole world, for
instance, geometry, cameras, or lights. Some attributes like the
:kat:attr:`lightList` are inherited further down the hierarchy; others like
:kat:attr:`globals`, however, define universal settings and are not inherited.
Camera and Light Lists
''''''''''''''''''''''
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`string[]`
* :kat:attr:`globals.cameraList`
* The list of scene graph locations of cameras; for example,
:kat:loc:`/root/world/cam/camera` and :kat:loc:`/root/world/cam/camera2`.
- * :kat:type:`group`
* :kat:attr:`lightList.<entry>`
* A sub-group for every light and light filter; for example,
``lightList.root_world_lgt_gaffer_light1``.
- * :kat:type:`string`
* :kat:attr:`lightList.<entry>.path`
* Scene graph location of the light or light filter, for example,
:kat:loc:`/root/world/lgt/gaffer/light1`.
- * :kat:type:`int`
* :kat:attr:`lightList.<entry>.enable`
* Defines whether the light or light filter is enabled.
- * :kat:type:`string`
* :kat:attr:`lightList.<entry>.type`
* Type of light list entry, either ``light filter`` or
``light filter reference``. If this attribute is not set, the entry is
assumed to be for a light.
- * :kat:type:`string`
* :kat:attr:`lightList.<entry>.inherits`
* For light filters only - the scene graph location this light filter should
inherit its attributes from.
- * :kat:type:`string`
* :kat:attr:`lightList.<entry>.referencePath`
* For light filter references only - the scene graph location this light
filter reference should inherit its attributes from.
- * :kat:type:`string`
* :kat:attr:`globals.coordinateSystems.<name>`
* Defines a new co-ordinate system at the specified scene graph location.
- * :kat:type:`string[]`
* :kat:attr:`globals.itemLists.<custom>`
* Defines a custom item list. When node graph subtrees are merged via a
:kat:node:`Merge` node, the contents of item lists are unioned rather
than the left-most input being used.
``/root/world/geo``
~~~~~~~~~~~~~~~~~~~
Top-level group for :doc:`geometry <GeometryTypes>`.
``/root/world/cam``
~~~~~~~~~~~~~~~~~~~
Top-level group for :ref:`cameras <camera-attrs>`.
``/root/world/lgt``
~~~~~~~~~~~~~~~~~~~
Top-level group for :ref:`lights <light-attrs>`.
``/root/materials``
~~~~~~~~~~~~~~~~~~~
Top-level group for :doc:`materials <Materials>`
``/root/materials/proc``
~~~~~~~~~~~~~~~~~~~~~~~~
Top-level group for :ref:`renderer procedurals <procedural-attrs>`.