Why is there no Python documentation about `cmds.shaderfx` command?

Question:

There is no official documentation about the python operations related to the shaderfx. I enter the MAYA python command reference page, and search for keyword "shaderfx". Then, no result in MAYA "python command reference", and no result in MAYA "node and attribute reference". But I find that the MAYA script editor highlights method "cmds.shaderfx" as a regular method. And I find the similar method calls on Google.

So, where can I find the python method detail about the shaderfx? It’s weird.

enter image description here

Asked By: T3-Tan

||

Answers:

You’re right, not all Maya Python commands are documented online.

You’ll get empty documentation page if you type this:

cmds.help('shaderfx', doc=True)

However, if you get rid of a doc flag and then execute our previous command one more time, you’ll get Script Editor’s offline help.

cmds.help('shaderfx')

It’s short but helpful. Here it is:

  -ag -addGroup                   String
 -amt -acquireMTextureFromSwatch  UnsignedInt UnsignedInt Float String
  -an -addNode                    UnsignedInt
 -ang -moveNodeInGroup            UnsignedInt UnsignedInt
   -b -buildInfo                 
  -bc -breakConnection            UnsignedInt UnsignedInt UnsignedInt UnsignedInt
 -cgn -createGroupNode           
 -cgp -changeGroup                UnsignedInt
  -dn -deleteNode                 UnsignedInt
  -ea -edit_action                UnsignedInt String
  -eb -edit_bool                  UnsignedInt String on|off
 -eeg -edit_exposeGrp             UnsignedInt String Int
  -ef -edit_float                 UnsignedInt String Float
 -ef2 -edit_float2                UnsignedInt String Float
 -ef3 -edit_float3                UnsignedInt String Float Float Float
 -ef4 -edit_float4                UnsignedInt String Float Float Float Float
  -ei -edit_int                   UnsignedInt String Int
  -es -edit_string                UnsignedInt String String
 -esl -edit_stringlist            UnsignedInt String Int
 -esp -edit_stringPath            UnsignedInt String String
  -ga -getAttributeNodeID         String
  -gc -getCode                   
 -gcc -getConnectedSocketCount    UnsignedInt UnsignedInt UnsignedInt
 -gci -getConnectedSocketIndex    UnsignedInt UnsignedInt UnsignedInt UnsignedInt on|off
 -gcn -getNodeClassName           UnsignedInt
 -gge -getGroupEndUID             UnsignedInt
 -ggi -getGroupUID                UnsignedInt
 -gid -getConnectedNodeID         UnsignedInt UnsignedInt UnsignedInt UnsignedInt on|off
 -gnc -getNodeCount              
 -gni -getNodeUIDFromIndex        Int
 -gnn -getNodeIDByName            String
 -gpt -getPropertyType            UnsignedInt String
 -gpv -getPropertyValue           UnsignedInt String
  -gs -getSettingNodeID           String
 -gsc -getSocketCount             UnsignedInt UnsignedInt
 -gsi -getSocketIndexByName       UnsignedInt String UnsignedInt UnsignedInt
 -gsn -getSocketName              UnsignedInt UnsignedInt UnsignedInt
 -gst -getSocketType              UnsignedInt UnsignedInt UnsignedInt
 -gtc -getNodeTypeByClassName     String
 -gtr -getTextureResolution       UnsignedInt
   -h -help                      
 -igd -isGroupFromDisk            UnsignedInt
 -ige -isGroupEnd                 UnsignedInt
 -igs -isGroupStart               UnsignedInt
 -isa -initShaderAttributes      
  -lg -loadGraph                  String
  -lp -listProperties             UnsignedInt
 -lsm -loadSjsonMaterial          String
  -mc -makeConnection             UnsignedInt UnsignedInt UnsignedInt UnsignedInt
  -mu -manualUpdate               on|off
   -n -sfxnode                    String
 -nui -nodeUI                    
   -r -redraw                    
 -rhg -getHwShaderNodeRootGrpID  
 -rhw -getHwShaderNodeID         
 -rsd -renderSwatchToDisk         UnsignedInt UnsignedInt Float String
 -rui -replaceUI                 
 -ruv -renderSwatchToDiskUV       UnsignedInt UnsignedInt Float String
   -s -start                     
 -sam -setAdvancedMode            on|off
 -sel -selectNode                 UnsignedInt
 -sgn -saveGroupNode              UnsignedInt
 -sup -setUserPath                String
 -swc -swatchCamera               String
 -swg -swatchGeom                 String
   -u -update                    
  -us -undoStack                 
 -wfx -write_float2_x            
 -wfy -write_float2_y
Answered By: Andy Jazz
shaderfx Options:

-sfxnode                       Specify the dagPath of the ShaderfxShader you are working on 
                               The -sfxnode has to be supplied with (almost) every other flag 
                               Example: shaderfx -sfxnode "ShaderfxShader1" -start; 


-start                         Start ShaderFX and open node graph 

-replaceUI                     (internal) Replace the existing node graph UI with the graph of another dagPath 

-nodeUI                        (internal) Rebuilds the Attribute Editor when a node is selected in the ShaderFX node graph 

-getNodeCount                  Returns the total number of nodes in the graph (includes all nodes inside all groups) 

-getNodeUIDFromIndex           node_index 
                               Returns the unique node ID of a shaderfx graph node with a certain index 
                               This number will not repeat in the same node graph and remains the same for 
                               the life time of the node during a single Maya session 
                               Many node/connection commands need you to supply this ID so ShaderFX knows what node to work on 
                               Example: $nodeUID = `shaderfx -sfxnode "ShaderfxShader1" -getNodeUIDFromIndex [nodex_index]`; 

-listProperties                node_uniqueID 
                               Returns the names of all properties available on the node 
                               Properties are similar to attributes, but they are not directly connection to an input/output socket 
                               Example: string $props[] = `shaderfx -sfxnode "ShaderfxShader1" -listProperties [node_uniqueID]`; 

-getPropertyType               node_uniqueID name_of_property 
                               Returns the value type of a property (e.g. bool, int, float, float4, string, stringlist, action, etc) 

-getPropertyValue              node_uniqueID name_of_property 
                               Returns the value of a property 
                               Note that from type stringlist we return the string items in the list as well as the active-item-index in an array 
                               Example: string $note = `shaderfx -sfxnode "ShaderfxShader1" -getPropertyValue [node_uniqueID] "note"`; 

-edit_bool                     node_uniqueID name_of_property new_value 
                               Sets the value of a boolean property 
                               Example: shaderfx -sfxnode "ShaderfxShader1" -edit_bool [node_uniqueID] [prop_name] true; 

-edit_int                      node_uniqueID name_of_property new_value 
                               Sets the value of a integer property 

-edit_float                    node_uniqueID name_of_property new_value 
                               Sets the value of a float property 

-edit_float2                   node_uniqueID name_of_property X Y 
                               Sets the value of a float2 property 

-edit_float3                   node_uniqueID name_of_property X Y Z 
                               Sets the value of a float3 property 
                               Example: shaderfx -sfxnode "ShaderfxShader1" -edit_float3 [node_uniqueID] [prop_name] 0.0 1.0 0.5; 

-edit_float4                   node_uniqueID name_of_property X Y Z W 
                               Sets the value of a float4 property 
                               Example: shaderfx -sfxnode "ShaderfxShader1" -edit_float4 [node_uniqueID] [prop_name] 0.0 1.0 0.5 1.0; 

-edit_string                   node_uniqueID name_of_property new_value 
                               Sets the value of a string property 

-edit_stringPath               node_uniqueID name_of_property new_value 
                               Sets the value of a string path property 
                               Can be useful for setting texture path properties 
                               This will remove the Maya Project Path from the provided string 

-edit_stringlist               node_uniqueID name_of_property active_index 
                               Sets the active index of a stringlist (optionList) property 
                               Please note that this does not change the contents of the list, only what list item is selected 

-edit_action                   node_uniqueID name_of_property
                               Triggers an action 
                               Actions are usually buttons 
                               Example: shaderfx -sfxnode "ShaderfxShader1" -edit_action [node_uniqueID] "helpaction"; 

-edit_exposeGrp                node_uniqueID name_of_property new_sorting_value 
                               Some properties on embed inside groups can be made visible when the group node is selected 
                               This integer controls the order in which these properties are listed in the group node UI 
                               A value of 0 will hide the property from the group 
                               Example: shaderfx -sfxnode "ShaderfxShader1" -edit_exposeGrp [node_uniqueID] [prop_name] 1002; 

-addNode                       node_type_id 
                               Adds a new node of the supplied type (integer) to the graph 
                               The node_type can be queried by name with: -getNodeTypeByClassName 
                               Returns the unique ID of the newly created node 
                               Example: $colorClassType = `shaderfx -sfxnode "ShaderfxShader1" -getNodeTypeByClassName "color"`; 
                                              $newColorNodeUID = `shaderfx -sfxnode "ShaderfxShader1" -addNode $colorClassType`; 

-deleteNode                    node_uniqueID 
                               Deletes a node or group from the graph 

-addGroup                      name_of_group 
                               Adds a new group node into the graph 
                               Returns the unique ID of the group START node 
                               Example: shaderfx -sfxnode "ShaderfxShader1" -addGroup "Texture Map-Hw Shader Nodes-Textures.grp"; 

-getGroupEndUID                grp_start_node_uniqueID 
                               Returns the unique ID of the group END node when providing the unique ID of a group START node 
                               See -isGroupStart for more information on groups 

-getGroupUID                   node_uniqueID 
                               If a node is embed inside a group, this will return the unique ID of its group START node 
                               Please note that this group START node may itself be embed in other groups 
                               See -isGroupStart for more information on groups 

-isGroupEnd                    node_uniqueID 
                               Returns true if the node is a group END node 
                               See -isGroupStart for more information on groups 

-isGroupStart                  node_uniqueID 
                               Returns true if the node is a group START node 
                               Groups are made up out of two nodes that encapsulate the group: A Group Start and End node 
                               While traversing the graph, you will come across these nodes a lot and you probably want to check for them 
                               For example, if you are only interested in traversing the top level of the graph, you 
                               will want to jump from a group end directly to a group start, instead of traversing the nodes inside the group 
                               When you have a 'isGroupEnd' node, you can call -getGroupUID to find the group start node 
                               When you have a 'isGroupStart' node, you can call -getGroupEndUID to find the group end node 
                               The group START node holds the input sockets for the group 
                               The group END node holds the output sockets for the group 
                               This is important to realize, because you may want to get the inputs for a group and 
                               if you query the inputs via -getSocketIndexByName (etc) on the group END node you may not 
                               get the resuls you expected. You may first have to get the group Start node via -GetGroupUID 
                               Example: 
                               // We try to find the 'Diffuse Color' input socket on the Surface Shader node by starting at the 'Material' group:
                               $matUID = `shaderfx -sfxnode "ShaderfxShader1" -getNodeIDByName "Material"`; 
                               $surfaceIndex = `shaderfx -sfxnode "ShaderfxShader1" -getSocketIndexByName $matUID "Surface Shader" 0 0`; 
                               $surfaceNodeEndUID = `shaderfx -sfxnode "ShaderfxShader1" -getConnectedNodeID $matUID 0 $surfaceIndex 0 false`; 
                               $isGrpEnd = `shaderfx -sfxnode "ShaderfxShader1" -isGroupEnd $surfaceNodeEndUID`; 
                               if ($isGrpEnd == false) {print "ERROR! we were expecting to find a group end node for surface shader grp";} 
                               $surfaceNodeStartUID = `shaderfx -sfxnode "ShaderfxShader1" -getGroupUID $surfaceNodeEndUID`; 
                               $surfaceIndex = `shaderfx -sfxnode "ShaderfxShader1" -getSocketIndexByName $surfaceNodeStartUID "Diffuse Color" 0 0`; 

-isGroupFromDisk               node_uniqueID 
                               Returns 1 (system node) or 2 (user node) if the node is a group node that is loaded from disk 
                               Users may also create group nodes to organize their graph that 
                               are stored only in the scene and not on disk. It will return 0 in those cases 
                               The node_id provided should be of the group START node 

-makeConnection                output_node_uniqueID out_socket_index input_node_uniqueID input_socket_index 
                               Makes a new connection between an output and input socket on two nodes 
                               To make connection inside a group, you must first enter the group via command: -changeGroup 

-breakConnection               output_node_uniqueID out_socket_index input_node_uniqueID input_socket_index 
                               Removes a connection between an output and input socket on two nodes 

-getNodeClassName              node_uniqueID 
                               Returns class name of the supplied node 

-getNodeIDByName               node_name 
                               Returns the unique ID of the first node found with the supplied name 
                               Note: ShaderFX does not enforce unique names per node. This is up to the user to control 
                               Internally ShaderFX relies on the unique ID to distinguish nodes from each other 

-getSettingNodeID              ui_name_of_setting 
                               Returns the unique ID of the first node found that contributed a 'setting parameter' into 
                               the ShaderFX Settings panel in the Attribute Editor 

-getAttributeNodeID            ui_name_of_attribute 
                               Returns the unique ID of the first node found that contributed a 'Attribute parameter' into 
                               the ShaderFX Properties panel in the Attribute Editor 

-getNodeTypeByClassName        name_of_class 
                               Returns the type for a node class 
                               When using '-addNode' ShaderFX expects an integer for the type of node you wish to create 
                               But it is more intuitive to refer to node classes by name. 

-selectNode                    node_uniqueID 
                               Select a node in the node graph (graph UI needs to be open) 

-getSocketIndexByName          node_uniqueID socket_label socket_type name_index 
                               Returns the index of a socket by searching for it by name 
                               Socket_type=0 means search input sockets. Socket_type=1 means output sockets 
                               name_index can be used if you know the node has multiple sockets with the same name and 
                               you know you want the second, third, etc one 
                               For example a Multiply node may have 2 input sockes called 'Value'. 
                               To get the second one, you supply a name_index of 1 

-getSocketCount                node_uniqueID socket_type 
                               Returns number of input sockets (socket_type=0) or number of output sockets (socket_type=1) 

-getSocketName                 node_uniqueID socket_type socket_index 
                               Returns name of an input or output socket 

-getConnectedSocketCount       node_uniqueID socket_type socket_index 
                               Returns the number of sockets connected to an input or output socket 
                               Note that even input sockets can have multiple incoming connections for some sockets 

-getConnectedSocketIndex       node_uniqueID socket_type socket_index connection_index skip_groups 
                               Returns socket index of the socket connected to the supplied node and socket 
                               If there are multiple connections to the socket, you use connection_index for the one you are interested in 
                               connection_index should be 0 for the first connection 
                               If skip_groups is false, we will not automatically jump inside group nodes 
                               Instead, if a socket is connected to a group (end) node, we will return that group end node instead of 
                               returning what is connected inside the group. 
                               If you are interested in traversing the top-level of the graph only, and do not care what happens inside the groups then set this to false 
                               Example: 
                               $socketUID = `shaderfx -sfxnode "ShaderfxShader1" -getConnectedSocketIndex 303 0 3 0 false;`; 

-getSocketType                 node_uniqueID socket_type socket_index 
                               Returns the socket type string of the supplied node and socket 
                               The returned string will be made up out of two parts: connectionType_valueType 
                               Please note that the returned string may contain spaces. You can split the string by underscore 
                               connectionType: This is usually the value you care about. It indicates the value the socket represents. E.g. int, float, float3 etc 
                               valueType: indicates the internal (cached) value of the socket. For hardware shaders this is usually HwShader, but for 'Graph Nodes' this can also return bool, int etc. 
                               'Graph Nodes sockets' are indicated with a 'v' drawn on their socket. They do not directly contribute code into the hardware shader, but instead allow for graph decisions to be made (e.g. what path to traverse) 
                               Example: string $sType = `shaderfx -sfxnode "ShaderfxShader1" -getSocketType [nodeUID] 0 [socketIndex]`; 

-getConnectedNodeID            node_uniqueID socket_type socket_index connection_index skip_groups 
                               Returns unique node ID for the node connected to the supplied node and socket 
                               If skip_groups is false, we will not automatically jump inside group nodes 
                               Instead, if a socket is connected to a group (end) node, we will return that group end node instead of 
                               returning what is connected inside the group. 
                               If you are interested in traversing the top-level of the graph only, and do not care what happens inside the groups then set this to false 
                               Example: $connectedNodeUID = `shaderfx -sfxnode "ShaderfxShader1" -getConnectedNodeID [srcNodeUID] 0 [srcSocketIndex] 0 false`; 

-undoStack                     (internal) adds a shaderfx change to the Maya undo stack 

-loadGraph                     path_to_sfx_file 
                               Loads a .sfx or .material graph. This replaces the current graph 
                               Make sure you use forward slashes in your path 

-loadSjsonMaterial             stingray sjson material string 
                               Loads a .material sjson string. This replaces the current graph 

-swatchGeom                    geo_dagPath 
                               Sets the geometry for the ShaderFX swatches 

-swatchCamera                  cam_dagPath 
                               Sets the camera for the ShaderFX swatches 

-update                        Rebuilds the shaderfx shader 
                               Note that this re-generates the shader code but attempts to keep all attribute values 

-manualUpdate                  bool
                               Sets manual computing of the graph true or false 
                               When set to true, any changes in the graph (set properties, connections, etc) will not trigger the graph to update 

-redraw                        Redraws the node graph. UI must be open 

-help                          Display this help 

-acquireMTextureFromSwatch     node_uniqueID texture_size time textureName 
                               Renders the swatch of the provided node into a Maya MTexture 
                               Caller is responsible for calling release() on the MTexture when done with it 

-renderSwatchToDisk            node_uniqueID texture_size time texturePath 
                               Renders the swatch of the provided node to a PNG texture 
                               Note: Please make sure you have write access to the texturePath. E.g. Windows may block writing to root of C 
                               Example: shaderfx -sfxnode "ShaderfxShader1" -renderSwatchToDisk [uniqueNodeID] 2048 0.0 "d:/MyTexture.png"; 

-renderSwatchToDiskUV          See renderSwatchToDisk except then creates an UV-unwrapped image instead 

-buildInfo                     Display build information 

-getHwShaderNodeID             Returns the unique node ID of the Hardware Shader node that is currently being rendered 
                               Note that ShaderFX itself does not limit the graph to a single (hardware) shader 
                               But this function will return the node that ShaderFX is currently rendering into the 3d view 

-getHwShaderNodeRootGrpID      Returns the unique node ID of the top most group the Hardware Shader node that is currently being rendered is in 

-getCode                       Returns the hardware shader code generated for the viewport 

-getTextureResolution          node_uniqueID 
                               Returns the texture resolution of a shaderfx Texture Component node 

-initShaderAttributes          Triggers the default behavior (such as loading default graph) we see after creating a node via HyperShade or Assign menu 

-setAdvancedMode               Enabled or disables Advanced mode in ShaderFX editor 

-setUserPath                   Set a custom path where shaderfx will look for user created group nodes and scenes (defaults to /HOME or /MyDocuments) 

-createGroupNode               Create a new, empty group node and returns the group start node unique ID 

-moveNodeInGroup               group_startnode_uniqueID node_uniqueID 
                               Moves a node that exists in the graph inside a group (use AddNode to add it into the graph first) 

-saveGroupNode                 group_startnode_uniqueID 
                               Saves a group node to disk (Before saving, use -edit_string command to set the properties: classname categoryname submenuname) 

-changeGroup                   group_startnode_uniqueID 
                               Goes inside a group. This is required for makeConnection to work inside groups. Provide zero (0) for the uniqueID to exit all groups 
Answered By: m3trik
Categories: questions Tags: ,
Answers are sorted by their score. The answer accepted by the question owner as the best is marked with
at the top-right corner.