filePathEditor

Go to: Synopsis. Return value. Keywords. Flags. Python examples.

Synopsis

filePathEditor([attributeOnly=boolean], [attributeType=string], [byType=string], [copyAndRepath=[string, string]], [deregisterType=string], [force=boolean], [listDirectories=string], [listFiles=string], [listRegisteredTypes=boolean], [preview=boolean], [recursive=boolean], [refresh=boolean], [registerType=string], [relativeNames=boolean], [repath=string], [replaceAll=boolean], [replaceField=string], [replaceString=[string, string]], [status=boolean], [temporary=boolean], [typeLabel=string], [unresolved=boolean], [withAttribute=boolean])

Note: Strings representing object names and arguments must be separated by commas. This is not depicted in the synopsis.

filePathEditor is undoable, queryable, and NOT editable.

Maya can reference and use external files, such as textures or other Maya scenes. This command is used to get the information about those file paths and modify them in bulk. By default, only the most frequently used types of files are presented to the user:

• Texture
• Scene reference
• Audio
• Image plane

For the command to manage more file types, those must be explicitly requested by the caller using the "registerType" flag. This flag tells the command about attributes or nodes that are to reveal their paths when the command is used.

Currently, the attributes specified through this flag must have the "usedAsFileName" property. Supported nodes are "reference" and plug-in nodes. For example: "brush.flowerImage" or "reference" can be used as value for this flag.

Conversely, the "deregisterType" flag can be used to tell the command to stop handling certain attributes or nodes.

Once the set of attributes and nodes to be searched for external files is selected, the command can be used to obtain a list of plugs that contain file names. Additional information can be obtained, such as each file's name, directory, and report whether the file exists. Additional information about the associated node or plug can also be obtained, such as its name, type and label.

Finally, the command can be used to perform various manipulations such as editing the paths, remapping the files or verifying the presence of identically-named files in target directories. See the "repath", "copyAndRepath" and "replaceField" flags for more information.

The results of these manipulations can be previewed before they are applied using the "preview" flag.

Return value

None

In query mode, return type is based on queried flag.

Keywords

Flags

Long name (short name)	Argument types	Properties
attributeOnly(ao)	boolean
Used with "listFiles" to return the node and attribute name that are using the files.
attributeType(at)	string
Query the attribute type for the specified plug.
byType(bt)	string
Used with "listFiles" to query files that are used by the specified node type or attribute type. In query mode, this flag needs a value.
copyAndRepath(cr)	[string, string]
Copy a source file to the destination path and repath the plug data to the new file. The source file must have the same name as the one in the plug. The command will look for the file at the specified location first. If not found, the command will try to use the original file in the plug. If the file is still not found, nothing is done.
deregisterType(dt)	string
Deregister a file type from the list of registered types so the command stops handling it. Unless the "temporary" flag is used, the type will be removed from the preferences will not reappear on application restart. When the "temporary" flag is specified, the deregistration is only effective for the current session. The deregistration will be rejected if the type has already been unregistered. However, it is valid to deregister permanently (without the "temporary" flag) a type after it has been temporarily deregistered.
force(f)	boolean
Used with flag "repath" to repath all files to the new location, including the resolved files. Otherwise, "repath" will only deal with the missing files. Used with flag "copyAndRepath" to overwrite any colliding file at the destination. Otherwise, "copyAndRepath" will use the existing file at the destination instead of overwriting it. The default value is off.
listDirectories(ld)	string
List all sub directories of the specified directory. Only directories containing at least one file whose type is registered (see "registerType") will be listed. If no directory is provided, all directories applicable to the scene will be returned. In query mode, this flag needs a value.
listFiles(lf)	string
List files in the specified directory. No recursion in subdirectories will be performed. In query mode, this flag needs a value.
listRegisteredTypes(lrt)	boolean
Query the list of registered attribute types. The registered types include the auto-loaded types from the preference file and the types explicitly registered by the user, both with and without the "temporary" flag.
preview(p)	boolean
Used with "repath", "replaceString" or "copyAndRepath" to preview the result of the operation instead of excuting it. When it is used with "repath" or "replaceString", the command returns the new file path and a status flag indicating whether the new file exists (1) or not (0). The path name and the file status are listed in pairs. When it is used with "copyAndRepath", the command returns the files that need copying.
recursive(rc)	boolean
Used with flag "repath" to search the files in the target directory and its subdirectories recursively. If the flag is on, the command will repath the plug to a file that has the same name in the target directory or sub directories. If the flag is off, the command will apply the directory change without verifying that the resulting file exists.
refresh(rf)	boolean
Clear and re-collect the file information in the scene. The command does not automatically track file path modifications in the scene. So it is the users responsibility to cause refreshes in order to get up-to-date information.
registerType(rt)	string
Register a new file type that the command will handle and recognize from now on. Unless the "temporary" flag is used, the registered type is saved in the preferences and reappears on application restart. The new type will be rejected if it collides with an existing type or label. One exception to this is when registering a type without the "temporary" flag after the type has been registered with it. This is considered as modifying the persistent/temporary property of the existing type, rather than registering a new type.
relativeNames(rel)	boolean
Used with "listDirectories" or "listFiles" to return the relative path of each directory or file. Paths are relative to the current project folder. If a file or the directory is not under the current project folder, the returned path will still be a full path.
repath(r)	string
Replace the directory part of a file path with a specified location. The file name will be preserved.
replaceAll(ra)	boolean
Used with flag "replaceString", specifies how many times the matched string will be replaced. When the flag is false, only the first matched string will be replaced. Otherwise, all matched strings will be replaced. The default value is false.
replaceField(rfd)	string
Used with the "replaceString" flag to control the scope of the replacement. Possible values are: "pathOnly" - only replace strings in the directory part. "nameOnly" - only replace strings in the file name, without the directory. "fullPath" - replace strings anywhere in the full name. The default argument is "fullPath".
replaceString(rs)	[string, string]
Replace the target string with the new string in the file paths. The flag needs two arguments: the first one is the target string and the second one is the new string. See the "replaceField" and "replaceAll" flags to control how the replacement is performed.
status(s)	boolean
Used with "listFiles", this will cause the returned list of files to include one status flag per file: 0 if it cannot be resolved and 1 if it can. Used with "listDirectories", this will cause the returned list of directories to include one status flag per directory: 0 if it cannot be resolved, 1 if it can and 2 if the resolution is partial. The status will be interleaved with the file/directory names, with the name appearing first. See the example for "listFiles". See the "withAttribute" flag for another way of getting per-file information. When multiple per-entry items appear in the list (e.g.: plug name), the status is always last.
temporary(tmp)	boolean
Make the effect of the "register"/"deregister" flag only applicable in the current session. Normally, a type registration/deregistration is permanent and is made persistent via a preference file. When the "temporary" flag is specified, the changes will not be saved to the preference file. When the application restarts, any type that has been previously temporarily registered will not appear and any type that was temporarily deregistered will re-appear.
typeLabel(tl)	string
Used with "registerType" to set the label name for the new file type. Used with "query" to return the type label for the specified attribute type. For default types, the type label is the localized string. For other types, the type label is supplied by user. In query mode, this flag needs a value.
unresolved(u)	boolean
Used with "listFiles" to query the unresolved files that are being used in the scene.
withAttribute(wa)	boolean
Used with "listFiles" to return the name of the plug using a given file. For example, if "file.jpg" is used by the plug "node1.fileTextureName", then the returned string will become the pair "file.jpg node1.fileTextureName". See the "status" flag for another way to get per-file information.

Flag can appear in Create mode of command	Flag can appear in Edit mode of command
Flag can appear in Query mode of command	Flag can have multiple arguments, passed either as a tuple or a list.

Python examples

import maya.cmds as cmds


#Return the directories of the external files in the Maya scene.
#
cmds.filePathEditor(query=True, listDirectories="")

#Return the directories of the external files that are saved at the target
#location.
#
cmds.filePathEditor(query=True, listDirectories="c:/textures/", status=True)

#Return the files present in the specified directory, but not including the
#files in the sub directories.If no specified directory, search all external
#files in the scene.
#
#Use "withAttribute" to return the associated plugs.
#
#Use "status" to return whether the file exists.
#
#Use "unresolved" to return the broken files only.
#
#Use "attributeOnly" to return node and attribute name only.
#
#Use "byType" to specify the node and attribute type.
#
#For example, if "stone.jpg" exists and it is used by the plug
#"node1.imageName", then the returned result will be an ordered pair:
#"stone.jpg node1.imageName 1".
#
cmds.filePathEditor(query=True, listFiles="c:/textures/", withAttribute=True, status=True)
#
#If "rock.jpg" does not exists and it is used by the plug
#"node1.imageName", then this broken file and its plug
#can be found by the command.
#
cmds.filePathEditor(query=True, listFiles="", unresolved=True, withAttribute=True)
#Result: [u'rock.jpg', u'node1.imageName']
#
#List files that are used in the specified attribute of imagePlane
#
cmds.filePathEditor(query=True, listFiles="", byType="imagePlane.imageName")
#
#List all files that are used in the imagePlane node
#
cmds.filePathEditor(query=True, listFiles="", byType="imagePlane")
#
#Get all nodes or attributes that are using broken files to repath them
#
cmds.filePathEditor(query=True, listFiles="", unresolved=True, attributeOnly=True)
#
#Get the imagePlane file attributes that are using broken files to repath them
#
cmds.filePathEditor(query=True, listFiles="", unresolved=True, attributeOnly=True, byType="imagePlane.imageName")

#Return the label for the specified type.
#
#Strings are only guaranteed to be localized for the default types. For the
#other types, the strings are user-specified.
#
cmds.filePathEditor(query=True, typeLabel="imagePlane")

#Register and save a new file type and type label.
#
#These are persistent and can be used in future sessions.
#
cmds.filePathEditor(registerType="containerBase.iconName", typeLabel="ContainerIcon")

#Deregister a file type and clean the saved information.
#
cmds.filePathEditor(deregisterType="containerBase.iconName")

#Register a new non-persistent file type and type label.
#
cmds.filePathEditor(registerType="containerBase.iconName", typeLabel="ContainerIcon", temporary=True)

#Deregister a file type without affecting the persistent information.
#
cmds.filePathEditor(deregisterType="containerBase.iconName", temporary=True)

#Return all registered types, including default types.
#
cmds.filePathEditor(query=True, listRegisteredTypes=True)

#Query the attribute type for a plug instance.
#
cmds.filePathEditor("node1.fileTextureName", query=True, attributeType=True)

#Refresh all the file path editor's information for the current scene.
#
cmds.filePathEditor(refresh=True)

#Recursively look for files with the same name in the target directory. Repath
#the plugs value to those files.
#
#Use "force" to edit all the given plugs, even if the original path does not
#exist.
#
#Use "recursive" to find files recursively and to make sure the files do exist.
#
cmds.filePathEditor("node1.fileTextureName", "node2.fileTextureName", repath="e:/textures/",
						force=True, recursive=True)

#Preview the result of an operation without doing it.
#
#Returns the file name and whether the new file exists. This is returned as a
#list of pairs.
#
cmds.filePathEditor("node1.fileTextureName", "node2.fileTextureName", repath="e:/textures/", preview=True)

#Replace strings in file paths.
#
#Here, the string "image" in the directory part will be replaced by "texture".
#
cmds.filePathEditor("node1.fileTextureName", "node2.fileTextureName", replaceField="pathOnly", replaceString=("image", "texture"), replaceAll=True)

#Copy a file from the source to the destination and repath the plug data to the new file.
#
#Use "force" to overwrite the file at the destination if it has a name clash.
#
cmds.filePathEditor("node1.fileTextureName", "node2.fileTextureName",  copyAndRepath=("e:/textures", "g:/image"), force=True)