Docs - MM ImagePlane - Add attributes descriptions

docs/source/tools_createnode.rst

@@ -185,14 +185,14 @@ Key features:
 Display Attributes
 ~~~~~~~~~~~~~~~~~~
 
+`Display Attributes` control how the `MM ImagePlane` looks in the
+viewport; use these attributes to make the image easier to see.
+
 .. figure:: images/tools_image_plane_attributes_display.png
     :alt: MM ImagePlane Display attributes.
     :align: center
     :width: 80%
 
-`Display Attributes` control how the `MM ImagePlane` looks in the
-viewport; use these attributes to make the image easier to see.
-
 .. list-table:: Display Attributes
    :widths: auto
    :header-rows: 1
@@ -201,47 +201,69 @@ viewport; use these attributes to make the image easier to see.
      - Description
 
    * - Visible To Camera Only
-     - Description
+     - When enabled, this imagePlane node is not visible when viewed
+       by any other camera (including ``persp`` camera).
 
    * - Gain
-     - Description
+     - The color of multiplier of the displayed image.
 
    * - Exposure
-     - Description
+     - Relative exposure brightness (measured in `Stops`) applied to
+       the image. Negative numbers darken the image, positive values
+       increase the brightness.
 
    * - Gamma
-     - Description
+     - Brighten or darken the mid-tones of the image, without
+       affecting the shadows or highlights as much. Do not use this
+       slider to approximate a Color Space of 2.2 - use the `Input
+       Color Space` attribute.
 
    * - Saturation
-     - Description
+     - Adjust the color saturation of the image; 0.0 makes the image
+       black and white, 1.0+ numbers make the image colors very
+       vibrant.
 
    * - SoftClip
-     - Description
+     - Reduce the image highlights to flatten the bright areas of an image.
 
    * - Alpha Gain
-     - Description
+     - Alpha channel multiplier. Controls the opacity/transparency of
+       the image.
 
    * - Input Color Space
-     - Description
+     - The color space saved into the image. Left-click to choose
+       color space from menu.
 
    * - Image Ignore Alpha
-     - Description
+     - If the image contains an alpha channel, you can ignore it here,
+       and treat the image as fully opaque.
 
    * - Display Channel
-     - Description
+     - Which channel the image would you like to display? ``RGBA``
+       (full), ``RGB`` (color only, disables alpha), ``Red`` only,
+       ``Green`` only, ``Blue`` only, ``Alpha`` only, or ``Luminance``
+       only?
 
 .. _imageplane-image-sequence-attributes-ref:
 
 Image Sequence Attributes
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
+`Image Sequence` attributes define the image that is loaded and the
+frame number used for image look-up.
+
+`MM ImagePlane` is designed to contain multiple image sequence
+`Slots`, so that users can easily swap between different images. For
+example, you may have an EXR image sequence, a lower-resolution JPEG
+image sequence and a color adjusted image sequence to better see
+low-contrast image details - you can easily swap between all of these
+image sequences by changing the `Image Sequence Slot` attribute.
+
 .. figure:: images/tools_image_plane_attributes_image_sequence.png
     :alt: MM ImagePlane Image Sequence attributes.
     :align: center
     :width: 80%
 
-*To be written*
-
 .. list-table:: Image Sequence Attributes
    :widths: auto
    :header-rows: 1
@@ -250,62 +272,77 @@ Image Sequence Attributes
      - Description
 
    * - Image Sequence Slot
-     - Description
+     - Change the `Image Sequence Slot`, between the 4 image sequences
+       available; ``Main``, ``Alternate 1``, etc.
 
    * - Image Sequence (Main)
-     - Description
+     - The "Main" image sequence, and the default.
 
    * - Image Sequence (Alt 1)
-     - Description
+     - First alternate image sequence.
 
    * - Image Sequence (Alt 2)
-     - Description
+     - Second alternate image sequence.
 
    * - Image Sequence (Alt 3)
-     - Description
+     - Third alternate image sequence.
 
    * - Image Width
-     - Description
+     - Resolution width of loaded image.
 
    * - Image Height
-     - Description
+     - Resolution height of loaded image.
 
    * - Image Pixel Aspect
-     - Description
+     - Pixel-aspect ratio loaded image. This changes the way the
+       physical image plane size is calculated. For example, when
+       loading raw un-squeezed Anamorphic images, set this value to
+       ``2.0``.
 
    * - Start Frame
-     - Description
+     - The start frame of the loaded image sequence. Will be ``0`` if
+       an image sequence is not loaded.
 
    * - End Frame
-     - Description
+     - The end frame of the loaded image sequence. Will be ``0`` if an
+       image sequence is not loaded.
 
    * - Image Sequence Frame
-     - Description
+     - The current **input** image sequence frame number.
 
    * - First Frame
-     - Description
+     - What frame is the first frame in the image sequence? `MM
+       ImagePlane` Offsets the `Start Frame` of the image sequence so
+       it is displayed when the Maya timeline is at `First Frame`.
 
    * - Frame Output
-     - Description
+     - The current **output** image sequence frame number.
 
    * - Image Flip (Vertical)
-     - Description
+     - Flips the image vertically; does *not* flip any asymmetric lens
+       distortion values.
 
-   * - Image Flip (Horizontal)
-     - Description
+   * - Image Flop (Horizontal)
+     - Flops the image horizontally; does *not* flop any asymmetric
+       lens distortion values.
 
 .. _imageplane-hud-attributes-ref:
 
-HUD Attributes
-~~~~~~~~~~~~~~~~~~~~~~~~~
+HUD (Heads-Up Display) Attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+HUD (Heads-Up Display) attributes control the way text is drawn in the
+viewport when the `MM ImagePlane` is viewed from it's connected
+camera.
+
+The HUD displays useful information intended to help understanding of
+the loaded image and help spot common issues.
 
 .. figure:: images/tools_image_plane_attributes_hud.png
     :alt: MM ImagePlane HUD attributes.
     :align: center
     :width: 80%
 
-*To be written*
-
 .. list-table:: HUD Attributes
    :widths: auto
    :header-rows: 1
@@ -314,29 +351,31 @@ HUD Attributes
      - Description
 
    * - Draw Hud
-     - Description
+     - Enable or disable all HUD features.
 
    * - Draw Camera Size
-     - Description
+     - Enable or disable the camera size display.
 
    * - Draw Image Size
-     - Description
+     - Enable or disable the image size display.
 
 .. _imageplane-image-cache-attributes-ref:
 
 Image Cache Attributes
 ~~~~~~~~~~~~~~~~~~~~~~
 
+Provides quick access to see details and control the `Image Cache`,
+and clear memory resources.
+
+See :ref:`Image Cache Preferences <image-cache-preferences-ref>` for
+details on how to control the `MM Image Plane` hardware resources
+used.
+
 .. figure:: images/tools_image_plane_attributes_image_cache.png
     :alt: MM ImagePlane Image Cache attributes.
     :align: center
     :width: 80%
 
-*To be written*
-
-See :ref:`Image Cache Preferences <image-cache-preferences-ref>` for
-details on how to control the MM Image Plane hardware resources used.
-
 .. list-table:: Image Cache Attributes
    :widths: auto
    :header-rows: 1
@@ -345,38 +384,42 @@ details on how to control the MM Image Plane hardware resources used.
      - Description
 
    * - Refresh Attribute Editor (button)
-     - Description
+     - Update the text fields in the attribute editor.
 
    * - Image Sequence Size
-     - Description
+     - Breaks down the amount of memory required for the full image
+       sequence currently loaded; the size of a single frame
+       multiplied by the image sequence frame count.
 
    * - GPU Cache Used
-     - Description
+     - Amount of GPU cache capacity is currently used.
 
    * - CPU Cache Used
-     - Description
+     - Amount of CPU cache capacity is currently used.
 
    * - Total Memory Available
-     - Description
+     - Amount of memory resources available on the computer.
 
    * - Clear... (button)
-     - Description
+     - Left-click to open a menu; clearing all images, clearing memory
+       from image sequence slots on the current `MM ImagePlane` node.
 
    * - Image Cache Preferences... (button)
-     - Open the :ref:`Image Cache Preferences <image-cache-preferences-ref>`.
+     - Left-click to open the :ref:`Image Cache Preferences <image-cache-preferences-ref>`.
 
 .. _imageplane-misc-attributes-ref:
 
 Miscellaneous Attributes
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
+`Miscellaneous` attributes do not fit into the other categories and
+are not commonly adjusted, but provided for rare use cases.
+
 .. figure:: images/tools_image_plane_attributes_misc.png
     :alt: MM ImagePlane Miscellaneous attributes.
     :align: center
     :width: 80%
 
-*To be written*
-
 .. list-table:: Miscellaneous Attributes
    :widths: auto
    :header-rows: 1
@@ -385,23 +428,33 @@ Miscellaneous Attributes
      - Description
 
    * - Mesh Resolution
-     - Description
+     - Used to adjust the real-time lens distortion quality. You
+       should adjust the resolution with more polygons when lens
+       distortion is so extreme that the lens distortion is displayed
+       is not accurate. Increasing the number also slows-down the
+       real-time performance.
 
    * - Output Color Space
-     - Description
+     - This is the color space that Maya should work with
+       internally. Left-click to choose color space from menu.
 
 .. _imageplane-nodes-attributes-ref:
 
 Nodes Attributes
 ~~~~~~~~~~~~~~~~
 
+These attributes can be used to quickly navigate to the connected
+nodes of this `MM ImagePlane` node.
+
+The node connections cannot be adjusted using this UI. Only adjust
+these attributes if you know what you are doing, or want to
+experiment.
+
 .. figure:: images/tools_image_plane_attributes_nodes.png
     :alt: MM ImagePlane Nodes attributes.
     :align: center
     :width: 80%
 
-*To be written*
-
 .. list-table:: Nodes Attributes
    :widths: auto
    :header-rows: 1
@@ -415,20 +468,21 @@ Nodes Attributes
        screen. This geometry node may be deformed by lens distortion.
 
    * - Camera Node
-     - Description
+     - The image plane is attached to this camera node.
 
 .. _imageplane-extended-image-details-attributes-ref:
 
 Extended Image Details Attributes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+`Extended Image Details` explain the internal and low-level details of
+the loaded images, and they are used to debug and for scripting tools.
+
 .. figure:: images/tools_image_plane_attributes_extended_image_details.png
     :alt: MM ImagePlane Extended Image Details attributes.
     :align: center
     :width: 80%
 
-*To be written*
-
 .. list-table:: Extended Image Details Attributes
    :widths: auto
    :header-rows: 1
@@ -437,19 +491,25 @@ Extended Image Details Attributes
      - Description
 
    * - Padding
-     - Description
+     - Image sequence file path frame number padding; For example
+       ``file.1001.jpg`` (``file.####.jpg``) has a padding of 4.
 
    * - Image Num Channels
-     - Description
+     - The number of channels saved in the loaded image; 3 for RGB, 4
+       for RGBA.
 
    * - Image Bytes Per Channel
-     - Description
+     - The number of bytes that is used for each image channel. 8-bit
+       is 1-byte; 32-bit is 4-bytes.
 
    * - Image Size Bytes
-     - Description
+     - The calculated number of bytes for a single image. This value
+       is used to make calculations for the :ref:`Image Cache
+       Attributes <imageplane-image-cache-attributes-ref>` attributes,
+       and is mostly intended for debugging and scripting.
 
    * - Input Color Space
-     - Description
+     - The string value of the `Input Color Space` of the loaded image. Used for debugging.
 
    * - Output Color Space
-     - Description
+     - The string value of the `Output Color Space` of the loaded image. Used for debugging.