workspace

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

Synopsis

workspace( [string] , [active=boolean], [baseWorkspace=string], [create=string], [directory=string], [expandName=string], [fileRule=[string, string]], [fileRuleEntry=string], [fileRuleList=boolean], [filter=boolean], [fullName=boolean], [list=boolean], [listFullWorkspaces=boolean], [listWorkspaces=boolean], [newWorkspace=boolean], [objectType=[string, string]], [objectTypeEntry=string], [objectTypeList=boolean], [openWorkspace=boolean], [projectPath=string], [removeFileRuleEntry=string], [removeVariableEntry=string], [renderType=[string, string]], [renderTypeEntry=string], [renderTypeList=boolean], [rootDirectory=boolean], [saveWorkspace=boolean], [shortName=boolean], [update=boolean], [updateAll=boolean], [variable=[string, string]], [variableEntry=string], [variableList=boolean])

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

workspace is undoable, queryable, and NOT editable.

The string argument represents the workspace. If no workspace is specified then the current workspace is assumed.

A workspace provides the underlying definition of a Maya Project. Each project has an associated workspace file, named workspace.mel, which is stored in the project root directory. The workspace file defines a set of rules that map file types to their storage, either relative to the project root or as an absolute location. These rules are used when resolving file paths at runtime.

The workspace command operates directly on the low-level definition of the workspace to read, change and store the definition to the underlying file. Use of this command is not generally required, for most purposes it is recommended that project definition changes be done via the Project Window in the User Interface. Multiple actions go under the assumption that given paths exist.

Return value

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

Related

Flags

Long name (short name)	Argument types	Properties
active(act)	boolean
This flag is a synonym for -o/openWorkspace.
baseWorkspace(bw)	string
A workspace may be based on another workspace. This means that all the file rules and variables in the base workspace apply to this workspace unless they are explicitly overridden. By default, a new workspace has the workspace "default" as it's base workspace. Note that "duplicated" file rules containing relative paths are not verified nor created when creating a new workspace or when changing the base workspace.
create(cr)	string
Create a new directory. If the directory name is not a full path name, it will be created as a subdirectory of the "current" directory set with the -dir flag. Note that this flag does not create a workspace.
directory(dir)	string
This option will set the current workspace directory to the path specified. When queried it will return the current workspace directory. This directory is used as an initial directory for the fileBrowser and is part of the search path used for locating files. It should not be confused with the current working directory as used by the pwd and chdir commands. When the file browser is used, it will set this value to the last location navigated to.
expandName(en)	string
Query for the full path location of a filename using the current workspace definition. The path may be a project relative file name, a full path name or a variable name. The return value is always a full path name. If the path is an empty string, the return value will be the project root directory. Variable expansion is supported, and will consider both variables defined in the workspace as well as environment variables. There are three formats supported for expanding variable names: %variableName%, $variableName, ${variableName}. Maya will first attempt to find matching variables defined in the current workspace, then search for a matching environment variable. The tilde character ('~') is also supported. If a tilde is located at the beginning of a variable, Maya will only consider and expand environment variables, and will leave the tilde in the expanded result. On linux and mac platforms, a tilde can be used to expand a user's home directory, using the form ~username, ~, or ~/. When specified as ~username, it will be replaced with the corresponding user's home directory. When specified as ~ or ~/, it will be replaced with the value of the HOME environment variable.
fileRule(fr)	[string, string]
Set the default location for a file. The first parameter is the fileRule name(scenes, images, etc) and the second is the location. When queried, it returns a list of strings. The elements of the returned list alternate between fileRule names and the corresponding location. There is typically one file rule for each available translator. Environment variables are supported. You can set multiple path for the file rule by separating them with semicolons (;) on Windows and colons(:) on MacOSX and Linux. Note that whitespace at the beginning and end of each item in the separated sequence is significant and will be included as part of the path name (which is not usually desired unless the pathname does actually start or end with spaces). A valid filerule name cannot contain multiple byte characters. Note that creating a filerule does not create any directories. It is the user's responsibility to ensure that all paths are valid.
fileRuleEntry(fre)	string
Return the location for the given fileRule.
fileRuleList(frl)	boolean
Returns a list of the currently defined file rules.
filter(f)	boolean
This flag is obsolete.
fullName(fn)	boolean
Return the full name of the workspace.
list(l)	boolean
This option will list the current workspace directory. If a path is specified for the "workspaceFile" then the contents of that directory will be listed. Otherwise, the contents of the directory set with the -dir flag will be listed.
listFullWorkspaces(lfw)	boolean
Returns a list of the full path names of all the currently defined workspaces.
listWorkspaces(lw)	boolean
Returns a list of all the currently defined workspace names.
newWorkspace(n)	boolean
This specifies that a new workspace is being created with a given path (full path or relative to "current" directory). If a workspace with this path already exists, the command will fail. Note that the application is creating a virtual workspace without creating any new directories. If given a relative path, it will map the new workspace to the "current" directory set with the -dir flag concatenated with the given path. If the path does not exist, it will default the workspace root directory -rd to the system's root path (e.g. C:\ or '/'). It is the user's responsibility to ensure that all paths exist.
objectType(ot)	[string, string]
This flag is obsolete. All default locations will be added to the fileRules going forward.
objectTypeEntry(ote)	string
This flag is obsolete. This will now return the same as fileRuleEntry.
objectTypeList(otl)	boolean
This flag is obsolete. This will now return the same results as fileRuleList going forward.
openWorkspace(o)	boolean
Open the workspace. The workspace becomes the current workspace.
projectPath(pp)	string
Convert filePath passed as argument to a filename that is relative to the project root directory (if possible) and return it. If the filePath is not under the project root directory, a full path name will be returned.
removeFileRuleEntry(rfr)	string
Remove the given file rule from the specified workspace. If the workspace name is not specified, the given file rule will be removed from the current workspace.
removeVariableEntry(rve)	string
Remove the given variable from the specified workspace. If the workspace name is not specified, the given variable will be removed from the current workspace.
renderType(rt)	[string, string]
This flag is obsolete. All default render types will be added to fileRules going forward.
renderTypeEntry(rte)	string
This flag is obsolete, use fileRuleEntry going forward
renderTypeList(rtl)	boolean
This flag is obsolete, use fileRuleList going forward.
rootDirectory(rd)	boolean
Returns the root directory of the workspace.
saveWorkspace(s)	boolean
Save the workspace. Workspaces are normally saved when Maya exits but this flag will make sure that the data is flushed to disk.
shortName(sn)	boolean
Query the short name of the workspace.
update(u)	boolean
This flag reads all the workspace definitions from the project directory. It is used by Maya at startup time to find the available workspaces.
updateAll(ua)	boolean
This flag is a synonym for -u/update.
variable(v)	[string, string]
Set or query the value of a project variable. Project variables are used when expanding names. See the -en/expandName flag below.
variableEntry(ve)	string
Given a variable name, will return its value.
variableList(vl)	boolean
Return a list of all variables in the workspace.

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

# Set the current workspace to "alphabet".
cmds.workspace( 'alphabet', openWorkspace=True )

# Save the current workspace settings (for "alphabet").
cmds.workspace( saveWorkspace=True )

# Change current directory to project directory
cmds.workspace( directory="/h/userName/maya/projects/" )

# Create a directory for a new workspace
cmds.workspace( create="newWorkspace" )

# Create a new workspace named "newWorkspace".
cmds.workspace( 'newWorkspace', newWorkspace=True )

# The file rules and variables of "newWorkspace" are based on "default" workspace
cmds.workspace( baseWorkspace='default' )

# Return the list of existing workspaces
cmds.workspace( listWorkspaces=True )
# Result: default   newWorkspace

# Add a scriptJob to run on workspaceChanged events
def workspaceChangedCallback():
print 'My workspaceChangedCallback was called'

workspaceChangedID = cmds.scriptJob( event = ["workspaceChanged", workspaceChangedCallback] )

# add a file rule to the current workspace
cmds.workspace(fileRule = ['newFileRuleName', 'newFileRuleValue'])
My workspaceChangedCallback was called            #workspaceChangedCallback was called

# look up the value of the file rule entry
cmds.workspace(fileRuleEntry = 'newFileRuleName')
# Result: newFileRuleValue

# remove specified file rule entry
cmds.workspace(removeFileRuleEntry = 'newFileRuleName')
My workspaceChangedCallback was called            #workspaceChangedCallback is called

# kill the scriptJob with the number
cmds.scriptJob(kill = workspaceChangedID)

# The following example shows how to expand environment and workspace variables

# expand a path value to be a full path relative to the project directory
# relative path example
cmds.workspace( expandName = 'relativePathName')
# Result: /h/userName/maya/projects/newWorkspace/relativePathName
# full path example
cmds.workspace( expandName = '/h/userName/maya/projects/default/')
# Result: /h/userName/maya/projects/default/

# The following examples show various formats for expanding workspace and
# environment variables.

# add a variable to the current workspace
cmds.workspace(variable = ['newVariableName', 'newVariableValue'])
cmds.workspace( expandName = '%newVariableName%')
# Result: /h/userName/maya/projects/newWorkspace/newVariableValue

# add an environment variable
os.environ['newEnvVariableName'] = "newEnvVariableValue"
cmds.workspace( expandName = os.environ['newEnvVariableName'])
# Result: /h/userName/maya/projects/newWorkspace/newEnvVariableValue

# When a tilde is used, maya will only consider the environment variable
# not the workspace variable.
cmds.workspace( expandName = '~%newVariableName%')
# Result: /h/userName/maya/projects/newWorkspace/~newEnvVariableValue

# The following example shows how to set multiple paths into a fileRule value
cmds.workspace(fileRule = ['newMultiPathFileRuleName', '/h/userName/maya/projects/default;newFileRuleValue'])
multipath = cmds.workspace(fileRuleEntry = 'newMultiPathFileRuleName')
# Result : /h/userName/maya/projects/default;newFileRuleValue

# Note that white space at the beginning or end of each path is significant.
# Add a file rule that uses multiple paths with the white space at the beginning and end of each path
cmds.workspace(fileRule = ['newMultiPathFileRuleName', ' /h/userName/maya/projects/default ; newFileRuleValue '])
# Querying and expanding the path value shows that the white space is still included.
multipath = cmds.workspace(fileRuleEntry = 'newMultiPathFileRuleName')
# Result :  /h/userName/maya/projects/default ; newFileRuleValue

# Find the current workspace area.
cmds.workspace( q=True, directory=True )
# Result : /h/userName/maya/projects/

# Note that the "current working directory" as defined by the
# 'pwd' and 'chdir' commands is unrelated to the directories
# used by the workspace command
#
os.getcwd()
# Result : /usr/tmp

os.chdir( '/tmp' )
os.getcwd()
# Result : /tmp
cmds.workspace( q=True, directory=True )
# Result : /h/userName/maya/projects/

cmds.workspace( directory='/h/userName/maya/projects/commercial' )
os.getcwd()
# Result : /tmp