From 278ff0a2daa8784a7d88172776776b64bfb6ee6e Mon Sep 17 00:00:00 2001 From: David Cattermole Date: Sat, 12 Oct 2024 11:46:14 +1030 Subject: [PATCH] Docs - MM ImagePlane - Add attributes descriptions --- docs/source/tools_createnode.rst | 190 ++++++++++++++++++++----------- 1 file changed, 125 insertions(+), 65 deletions(-) diff --git a/docs/source/tools_createnode.rst b/docs/source/tools_createnode.rst index 68f71ba9..515f2b0a 100644 --- a/docs/source/tools_createnode.rst +++ b/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 ` 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 ` 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 `. + - Left-click to open the :ref:`Image Cache Preferences `. .. _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 ` 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.