Maya mentalrayTexture Image Sequences - zicher3d-org/domemaster-stereo-shader GitHub Wiki
Table of Contents
Introduction
The new Domemaster3D for Maya Image Sequence add-on makes it possible to create animated file textures using a mental ray native shading network with a mentalrayTexture node and a custom expression.
The reason this technique is so useful is that avoiding stock Maya file texture nodes during a fulldome Maya/mental ray production will reduce the risk of mental ray lens shader induced "blurry grey line streak" artifacts happening in your mental ray fulldome or latlong renderings.
The mentalrayTexture based image sequence feature is available in four of the Domemaster3D shelf tools:
Color Image Sequence Material Button (Covered on this page)
Hybrid MR + Maya Color Material Button
FulldomeIBL Button
HemirectIBL Button
Image Sequence Attributes
Tips: As you configure and set up a new image sequences texture you can check the image name output by the expression by nudging the timeline frame control forwards and then backwards by a frame and the mentalrayTexture node will update the final "Image Name" field contents with the refreshed "sequence name" formatted settings.
To disable the image sequence mode you can set the Frame Animation Ext attribute to "Native Image Name (passthrough)". At this point the image sequence attributes will be ignored and the default mentalrayTexture Image Name field contents will be used.
Let's review each of the available Extra Attribute controls:
File Name Prefix
This control allows you to write in the first "name" part of an image sequence filename.
In Maya 2013 and higher there is a folder icon next to the File Name Prefix attribute that allows you to use a file dialog to select an image file from your hard disk. If you use the file dialog to select an image you will have to shorten the file name manually and transfer the frame number, and image extension information into the Image Format, Frame Animation Ext, and Frame Padding controls.
Usage Example:
If the image sequence was named texture.00001.exr and it was in the sourceimages folder, the correct Extra Attribute settings would be:
The Frame Animation Ext mode would be set to "
name.#.ext".
The File Name Prefix would be set to "sourceimages\texture".
The Image Format would be set to "OpenEXR (exr)".
The Frame Padding attribute would be set to "5". This would enable 5 digit zero padding so the numbered frame sequence would always be 5 digits long. The Frame Offset would be set to "0".
Image Format
The Image Format options menu is used by the image sequence expression to help build up the ".ext" extension part of the image sequence filename.
Supported options are:
- Maya IFF (iff)
- TIFF (tif)
- JPEG (jpg)
- Targa (tga)
- Windows Bitmap (bmp)
- HDR (hdr)
- PSD (psd)
- PNG (png)
- OpenEXR (exr)
- Softimage (pic)
- Portable Pixmap (ppm)
Frame Animation Ext
The Frame Animation Ext options menu is used to tell the expression how to merge the File Name Prefix "name", with the added combination of (the current frame + Frame Offset), and the Image Format ".ext" components into the final image sequence filename.
The available options are:
- name (Single Frame)
- name.ext (Single Frame)
- name.#.ext
- name.ext.#
- name.#
- name#.ext
- name_#.ext
- Native Image Name (Passthrough)
Frame Padding
The Frame Padding control can be used to add leading "zero padded" digits to an image sequence frame number component.
Setting the Frame Padding to "0" turns off the padding. Setting the Frame Padding to 5 would enable 5 digit zero padding so the numbered frame sequence would always be 5 digits long. With the Frame Padding set to "5", frame 1 of the sequence would be translated as "00001" with leading zero characters inserted into the file name.
The most command Frame Padding settings are:
0 (Frame Padding Disabled)
4 (A Short Animation Clip)
5 (A Longer Sequence)
Frame Offset
A positive Frame Offset value advances the current image sequence frame number forward, ahead of the current timeline frame value.
For example, if the timeline playhead control was on frame 14, and there was a Frame Offset value of "220" added, the image sequence frame number would be 234.
Image Sequence Frame Number (234) = Current Frame (14) + Frame Offset (220)
You can also use a negative (-) Frame Offset value if you are starting your render mid way into an animation sequence and want to shift the image sequence starting point to a frame number below the current timeline playhead value.
For example, if the timeline playhead control was on frame 50, and there was a Frame Offset value of "-35" added, the image sequence frame number would be frame 15.
Image Sequence Frame Number (15) = Current Frame (50) + Frame Offset (-35)
Sequence Naming Examples
I've created a list of image name examples to help reduce the confusion of using the mentalrayTexture image sequence tool. Hopefully it will make it easier for users to figure out how to break down a new image sequence file name.
As always, to test a batch of image sequence Extra Attribute settings, you can get the expression to update by nudging the timeline frame control forwards then backwards by a frame and the final "Image Name" field contents will update based upon the current settings.
name (Single Frame)
If you select the "name (Single Frame)" option the only attribute used is the raw value that is in the File Name Prefix field.
This setting assumes the image format three letter ".ext" extension has been written into the File Name Prefix field like "texture.exr". No texture animation is possible with this setting.
Usage Example:
If the file texture was named texture.exr and it was in the sourceimages folder, the correct Extra Attribute settings would be:
The Frame Animation Ext mode would be set to "
name (Single Frame)".
The File Name Prefix would be set to "sourceimages\texture.exr".
The Image Format, Frame Offset, and Frame Padding settings would have no effect.
name.ext (Single Frame)
If you select the "name.ext (Single Frame)" option, the only attributes used are the current settings for the File Name Prefix and the Image Format ".ext" setting. No texture animation is possible with this setting.
Usage Example:
If the file texture was named texture.exr and it was in the sourceimages folder, the correct Extra Attribute settings would be:
The Frame Animation Ext mode would be set to "
name.ext (Single Frame)".
The File Name Prefix would be set to "sourceimages\texture".
The Image Format would be set to "OpenEXR (exr)".
The Frame Offset and Frame Padding settings would have no effect.
name.#.ext
The "name.#.ext" option enables all of the Extra Attribute settings. Animated image sequences are supported.
Usage Example:
If the image sequence was named texture.00001.exr and it was in the sourceimages folder, the correct Extra Attribute settings would be:
The Frame Animation Ext mode would be set to "
name.#.ext".
The File Name Prefix would be set to "sourceimages\texture".
The Image Format would be set to "OpenEXR (exr)".
The Frame Padding would be set to "5". This would enable 5 digit zero padding so the numbered frame sequence would always be 5 digits long. The Frame Offset would be set to "0".
name.ext.#
The "name.ext.#" option enables all of the Extra Attribute settings. Animated image sequences are supported.
Usage Example:
If the image sequence was named texture.exr.00001 and it was in the sourceimages folder, the correct Extra Attribute settings would be:
The Frame Animation Ext mode would be set to "
name.ext.#".
The File Name Prefix would be set to "sourceimages\texture".
The Image Format would be set to "OpenEXR (exr)".
The Frame Padding would be set to "5". This would enable 5 digit zero padding so the numbered frame sequence would always be 5 digits long. The Frame Offset would be set to "0".
name.#
If you select the "name.#" option, most of the Extra Attribute setting are active. Animated image sequences are supported.
This setting assumes mental ray can correctly auto-detect the image format used in the image file since no file extension is specified.
Usage Example:
If the image sequence was named texture.00001 and it was in the sourceimages folder, the correct Extra Attribute settings would be:
The Frame Animation Ext mode would be set to "
name.#".
The File Name Prefix would be set to "sourceimages\texture".
The Image Format setting is ignored and has no effect.
The Frame Padding would be set to "5". This would enable 5 digit zero padding so the numbered frame sequence would always be 5 digits long. The Frame Offset would be set to "0".
name#
If you select the "name#" option, most of the Extra Attribute setting are active and animated image sequences are supported.
There is no separator added between the "name" and the frame number section of the images filename. This setting assumes mental ray can correctly auto-detect the image format used in the image file since there is no file type extension in the filename.
Usage Example:
If the image sequence was named texture00001 and it was in the sourceimages folder, the correct Extra Attribute settings would be:
The Frame Animation Ext mode would be set to "
name#".
The File Name Prefix would be set to "sourceimages\texture".
The Image Format setting is ignored and has no effect.
The Frame Padding would be set to "5". This would enable 5 digit zero padding so the numbered frame sequence would always be 5 digits long. The Frame Offset would be set to "0".
name_#.ext
The "name_#.ext" option enables all of the Extra Attribute settings. Animated image sequences are supported.
This format uses an underscore character _ as the name and frame number separator. The name_#.ext sequence naming system is often used by After Effects when rendering out animations and movies as image sequences.
Usage Example:
If the image sequence was named texture_00001.exr and it was in the sourceimages folder, the correct Extra Attribute settings would be:
The Frame Animation Ext mode would be set to "
name_#.ext".
The File Name Prefix would be set to "sourceimages\texture".
The Image Format would be set to "OpenEXR (exr)".
The Frame Padding would be set to "5". This would enable 5 digit zero padding so the numbered frame sequence would always be 5 digits long. The Frame Offset would be set to "0".
Native Image Name (Passthrough)
If you select the "Native Image Name (Passthrough)" option, no extra attribute settings are used and the native mentalrayTexture node's Image Name field is used. No texture animation is possible with this setting.
Usage Example:
If the image was named texture.exr and it was in the sourceimages folder, the correct Extra Attribute settings would be:
The Image Name attribute would be set to "
sourceimages\texture.exr". All of the file name expression options in the Extra Attributes field are ignored.
How the Texture Animation Works
The process starts with the shelf tool's python script creating a mentalrayTexture based mental ray native shading network.
Image Sequence Shading Network
The 2nd part is where the magic happens with the addition of a custom set of "Extra Attributes" to the mentalrayTexture node and the creation of a new Maya expression node called sequence_mentalrayTexture1_AnimationExpr.
The expression node is linked to the mentalrayTexture node and its responsibility is to build the animated texture's filename based upon the current set of file naming rules that are stored in the Extra Attributes fields. The expression is also has a connection to the time node since it uses the current frame value from the Maya timeline.
A normal mentalrayTexture node comes with a fairly plain interface and it lacks any image sequence controls. Here is an image of the default texture node in the Attribute Editor window:
The Color Image Sequence Material shelf tool adds a new set of controls that are bolted onto a stock mentalrayTexture node. The custom Extra Attributes section has settings for the File Name Prefix, the Image Format, the Frame Animation Ext, Frame Padding, and a Frame Offset control.
When you first run the Color Image Sequence Material shelf tool a default texture named "checker.iff" is linked into the mentalrayTexture node.
A custom note is also added to the node that mentions the need for your render farm software to render the Maya scene using a single frame per render slice rendering mode so the texture will be animated:
The mentalrayTexture based Extra Attribute image sequence feature requires this scene to be rendered with a single frame job distribution mode in your render farm / render queue software. This means the sequence should be rendered with 1 frame per render slice so Maya's Render.exe program will load a new texture for each frame of the animation.
The custom image sequence controls may seem a bit strange at first but they will become invaluable if you want to be able to render animated textures without the headaches caused by the mental ray lens shader induced "blurry grey line streak" artifact.
Render Farm Software Setup
Since the mentalrayTexture based image sequence add-on needs to run the expression on each frame of your animation, you need to set up a custom setting in your render farm software. This will tell Maya that the mental ray render needs to be broken into individual frame sized jobs as it is sent across to the render farm nodes.
When the rendering process is started by the each render node the image name field contents will be regenerated for animated texture maps and a fresh image for each frame of the image sequence will be loaded.
If you have an issue with the animated frames loading during rendering you should check the "mayaRenderLog.txt" file for the image loading line near the top of the jobs output.
Here is an example line from one of my mentalrayTexture based image sequence renders where the texture filename "MOS_dome_video.00435.jpg" shows frame 435 is active:
IMG 0.3 12 MB progr: opening texture
R:/Fulldome/MOS_fulldome_dinosaur_tracking_project/sourceimages/MOS_dome_video.00435.jpg, for reading
JOB 0.n 14 MB progr: 0.7% rendered on 192.168.1.4:7415.14
JOB 0.n 14 MB progr: 1.1% rendered on 192.168.1.4:7415.2
JOB 0.3 14 MB progr: 3.1% rendered on hp.3 JOB 0.4 14 MB progr: 3.9% rendered on hp.4
Mental Ray Standalone Rendering
If you are rendering a Domemaster scene with the mentalrayTexture image sequence add-on using Mental Ray Standalone, you should export your scene from Maya with the "Output file per frame" checkbox enabled in the "Export All" window.
A good starting point for the mental ray output per frame export options would be a Frame extension setting of "name.#.ext", and a frame padding value of "5".
RenderPal Render Farm Software
Let's explore how to use a Domemaster3D for Maya Image Sequence texture with the RenderPal Rendering software.
In the RenderPal render farm software you can specify a Frame List which has an incrementing sequence of frame numbers with one number per line. Each frame number should increment by 1 frame at a time. This will cause RenderPal to break the rendering task into single frame sized rendering operations that are distributed to the render farm nodes.
Render Pal Submitter for Maya
To adjust the frame distribution mode when launching a new RenderPal Render in Maya you would use the following process:
Open the RenderPal Submitter window and scroll down to the Frame Splitting section.
In the Frame Splitting preferences, set the Mode to: "into X frames per Job".
Then set the Count to "1". This will tell each render node to render the animation using a job size of 1 frame per rendering task.
RenderPal Output Logs
If you have issues with the image sequence rendering, you can check in the RenderPal Remote Controller window for more details.
In RenderPal, click on the Job name and then switch to the "Output Logs" tab. You should see each render task as having a single frame size. For example, Frame 1 will be listed as 1.00 - 1.00
Then a few lines beneath the line info: Mayabase version ... you will see an IMG task listed. This will show if the texture was found and if it was loaded correctly. You can use this information to compare the current frame number to the final results of the mentalrayTexture Extra Attribute's "frame offset" command.
Smedge Render Farm Software
Let's explore how to use a Domemaster3D for Maya Image Sequence texture with the Smedge Rendering tool.
Adding a New Job in the Smedge GUI
In the Smedge render farm software you need to open the New Job window.
Set the Type to "Maya" so Smedge knows we want to render the Scene file using Maya's Render.exe program.
Scroll down in the Type Specific Parameters section and change the Packet Size to 1. This will cause Smedge to break the rendering task into single frame sized rendering operations that are distributed to the render farm nodes.
Submitting a Render from Inside Maya
To adjust the Packet Size when launching a new Smedge Render in Maya you would use the following process:
From the Render Menu, select Smedge Render[ ] with options.
In the Smedge Render submission window set the Packet Size to "1" and then click the Submit button.
This will submit the rendering job to Smedge and cause the rendering task to be broken into single frame bundles that are distributed to each of the render nodes. Each time a new frame is rendered on a node, the image sequence expression is updated and the correct frame is loaded for the animated mentalrayTexture.
Other Render Farm Tools
In other render farm programs you would similarity set each rendering job task to be 1 frame in size. This causes the mental ray render to be broken into individual frame sized jobs across the render farm nodes.