Go to: Synopsis. Return value. Related.
Flags. Python
examples.
namespace( [string] , [absoluteName=boolean], [addNamespace=string], [collapseAncestors=string],
[deleteNamespaceContent=boolean],
[exists=string], [force=boolean], [isRootNamespace=string],
[mergeNamespaceWithParent=
boolean], [mergeNamespaceWithRoot=boolean],
[moveNamespace=[string,
string]], [parent=string],
[recurse=boolean], [relativeNames=boolean], [removeNamespace=string],
[rename=[string, string]],
[setNamespace=string])
Note: Strings representing object names and
arguments must be separated by commas. This is not depicted in the
synopsis.
namespace is undoable, queryable, and NOT editable.
This command allows a namespace to be created, set or removed. A
namespace is a simple grouping of objects under a given name.
Namespaces are primarily used to resolve name-clash issues in Maya,
where a new object has the same name as an existing object (from
importing a file, for example). Using namespaces, you can have two
objects with the same name, as long as they are contained in
differenct namespaces. Namespaces are reminiscent of hierarchical
structures like file systems where namespaces are analogous to
directories and objects are analogous to files. The colon (':')
character is the separator used to separate the names of namespaces
and nodes instead of the slash ('/') or backslash ('\') character.
Namespaces can contain other namespaces as well as objects. Like
objects, the names of namespaces must be unique within another
namespace. Objects and namespaces can be in only one namespace.
Namespace names and object names don't clash so a namespace and an
object contained in another namespace can have the same name. There
is an unnamed root namespace specified with a leading colon (':').
Any object not in a named namespace is in the root namespace.
Normally, the leading colon is omitted from the name of an object
as it's presence is implied. The presence of a leading colon is
important when moving objects between namespaces using the 'rename'
command. For the 'rename' command, the new name is relative to the
current namespace unless the new name is fully qualified with a
leading colon. Namespaces are created using the 'add/addNamespace'
flag. By default they are created under the current namespace.
Changing the current namespace is done with the 'set/setNamespace'
flag. To reset the current namespace to the root namespace, use
'namespace -set ":";'. Whenever an object is created, it is added
by default to the current namespace. When creating a new namespace
using a qualified name, any intervening namespaces which do not yet
exist will be automatically created. For example, if the name of
the new namespace is specified as "A:B" and the current namespace
already has a child namespace named "A" then a new child namespace
named "B" will be created under "A". But if the current namespace
does not yet have a child named "A" then it will be created
automatically. This applies regardless of the number of levels in
the provided name (e.g. "A:B:C:D"). The 'p/parent' flag can be used
to explicitly specify the parent namespace under which the new one
should be created, rather than just defaulting to the current
namespace. If the name given for the new namespace is absolute
(i.e. it begins with a colon, as in ":A:B") then both the current
namespace and the 'parent' flag will be ignored and the new
namespace will be created under the root namespace. The
relativeNamespace flag can be used to change the way node names are
displayed in the UI and returned by the 'ls' command. Here are some
specific details on how the return from the 'ls' command works in
relativeNamespace mode:
List all mesh objects in the
scene:
ls -type "mesh";
The above command lists all mesh objects in the root and any child
namespaces. In relative name lookup mode, all names will be
displayed relative to the current namespace. When not in relative
name lookup mode (the default behaviour in Maya), results are
printed relative to the root namespace.
Using a "*" wildcard:
namespace -set myNS;
ls -type "mesh "*";
In relative name lookup mode, the "*" will match to the current
namespace and thus the ls command will list only those meshes
defined within the current namespace (i.e. myNs). If relative name
lookup is off (the default behaviour in Maya), names are
root-relative and thus "*" matches the root namespace, with the net
result being that only thoses meshes defined in the root namespace
will be listed.
You can force the root namespace to be listed when in relative name
lookup mode by specifying ":*" as your search pattern (i.e. ls
-type mesh ":*" which lists those meshes defined in the root
namespace only). Note that you can also use ":*" when relative name
lookup mode is off to match the root if you want a consistent way
to list the root.
Listing child namespace contents:
ls -type mesh "*:*";
For an example to list all meshes in immediate child namespaces,
use "*:*". In relative name lookup mode "*:*" lists those meshes in
immediate child namespaces of the current namespaces. When not in
relative name lookup mode, "*:*" lists meshes in namespaces one
level below the root.
Recursive listing of namespace contents:
Example: ls -type mesh -recurse on "*"
The 'recurse' flag is provided on the "ls" command to recursively
traverse any child namespaces. In relative name lookup mode, the
above example command will list all meshes in the current and any
child namespaces of current. When not in relative name lookup mode,
the above example command works from the root downwards and is thus
equivalent to "ls -type mesh".
In query mode, return type is based on queried flag.
namespaceInfo
absoluteName, addNamespace, collapseAncestors, deleteNamespaceContent, exists, force, isRootNamespace, mergeNamespaceWithParent,
mergeNamespaceWithRoot,
moveNamespace, parent, recurse,
relativeNames, removeNamespace, rename, setNamespace
| Long name (short name) |
Argument types |
Properties |
addNamespace(add) |
string |
 |
|
Create a new namespace with the given name. Both qualified
names ("A:B") and unqualified names ("A") are acceptable. If any of
the higher-level namespaces in a qualified name do not yet exist,
they will be created. |
|
deleteNamespaceContent(
dnc) |
boolean |
|
|
Used with the 'rm/removeNamespace' flag to indicate that when
removing a namespace the contents of the namespace will also be
removed. |
|
exists(ex) |
string |
 |
|
Returns true if the specified namespace exists, false if
not. |
|
isRootNamespace(ir) |
string |
|
|
Returns true if the specified namespace is root, false if
not. |
|
force(f) |
boolean |
|
|
Used with 'mv/moveNamespace' to force the move operation to
ignore name clashes. |
|
mergeNamespaceWithRoot(
mnr) |
boolean |
|
|
Used with the 'rm/removeNamespace' flag. When removing a
namespace, move the rest of the namespace content to the root
namespace. |
|
mergeNamespaceWithParent(
mnp) |
boolean |
|
|
Used with the 'rm/removeNamespace' flag. When removing a
namespace, move the rest of the namespace content to the parent
namespace. |
|
moveNamespace(mv) |
[string, string] |
|
|
Move the contents of the first namespace into the second
namespace. Child namespaces will also be moved.
Attempting to move a namespace containing referenced nodes will
result in an error; use the 'file' command ('file -edit
-namespace') to change a reference namespace.
If there are objects in the source namespace with the same name as
objects in the destination namespace, an error will be issued. Use
the 'force' flag to override this error - name clashes will be
resolved by renaming the objects to ensure uniqueness. |
|
parent(p) |
string |
|
|
Used with the 'addNamespace' or 'rename' flags to specifiy the
parent of the new namespace. The full namespace parent path is
required. When using 'addNamespace' with an absolute name, the
'parent' will be ignored and the command will display a
warning |
|
relativeNames(rel) |
boolean |
|
|
Turns on relative name lookup, which causes name lookups within
Maya to be relative to the current namespace. By default this is
off, meaning that name lookups are always relative to the root
namespace. Be careful turning this feature on since commands such
as setAttr will behave differently. It is wise to only turn this
feature on while executing custom procedures that you have written
to be namespace independent and turning relativeNames off when
returning control from your custom procedures. Note that Maya will
turn on relative naming during file I/O. Although it is not
recommended to leave relativeNames turned on, if you try to toggle
the value during file I/O you may notice that the value stays "on"
because Maya has already temporarily enabled it internally.
When relativeNames are enabled, the returns provided by the 'ls'
command will be relative to the current namespace. See the main
description of this command for more details. |
|
removeNamespace(rm) |
string |
|
|
Deletes the given namespace. The namespace must be empty for it
to be deleted. |
|
rename(ren) |
[string, string] |
|
|
Rename the first namespace to second namespace name. Child
namespaces will also be renamed. Both names are relative to the
current namespace. Use the 'parent' flag to specify a parent
namespace for the renamed namespace. An error is issued if the
second namespace name already exists. |
|
setNamespace(set) |
string |
|
|
Sets the current namespace. |
|
recurse(r) |
boolean |
|
|
Can be used with the 'exists' flag to recursively look for the
specified namespace |
|
absoluteName(an) |
boolean |
|
|
This is a general flag which can be used to specify the desired
format for the namespace(s) returned by the command. The absolute
name of the namespace is a full namespace path, starting from the
root namespace ":" and including all parent namespaces. For example
":ns:ball" is an absolute namespace name while "ns:ball" is
not. |
|
collapseAncestors(ch) |
string |
|
|
Delete all empty ancestors of the given namespace. An empty
namespace is a a namespace that does not contain any objects or
other nested namespaces |
|
| 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. |
import maya.cmds as cmds
# Create three namespaces
cmds.namespace( add='FOO' )
cmds.namespace( add='BAR' )
cmds.namespace( add='FRED' )
# Create namespace with qualified name
cmds.namespace( add="A:B" )
# Create namespace with qualified name
cmds.namespace( add="C:D", parent="A:B" )
# Create namespace with qualified name
cmds.namespace( add=":A:B:C:D:E" )
# Set the current namespace to FOO
cmds.namespace( set='FOO' )
# Create the namespace BAR Under FOO. Note there are
# two "BAR" namespaces, :BAR and :FOO:BAR.
cmds.namespace( add='BAR' )
# Check to see that the BAR namespace exists within the current
# namespace (FOO)
cmds.namespace( exists='BAR' )
# Result: 1 #
# Check to see that the FRED namespace exists under the root namespace
cmds.namespace( exists=':FRED' )
# Result: 1 #
# Create two objects. It gets added to the current namespace FOO;
cmds.sphere( n='sphere1' )
cmds.sphere( n='sphere2' )
# Result: FOO:sphere2 #
# Move sphere1 from namespace FOO to FOO:BAR. Note that we
# need to qualify sphere1 with the namespace FOO because
# "sphere1" identifies a non-existent object in the root namespace.
cmds.rename( 'FOO:sphere1', 'BAR:sphere1' )
# Result: FOO:BAR:sphere1 #
# Move sphere2 from namespace FOO to BAR. Note the leading
# colon on the new name.
cmds.rename( 'FOO:sphere2', ':BAR:sphere2' )
# Result: BAR:sphere2 #
# query the current namespace (using the namespaceInfo command)
cmds.namespaceInfo( currentNamespace=True )
# Result: FOO #
# remove the namespace FRED (it must be empty)
cmds.namespace( set=':' )
cmds.namespace( rm='FRED' )
# Check to see that the FRED namespace has been removed
cmds.namespace( query=True, exists=':FRED' )
# Result: 0 #
# Rename namespace BAR to JOE
# Note: this is done by creating JOE, moving the contents of
# BAR into JOE, and then removing the (now empty) BAR.
cmds.namespace( set=':' )
cmds.namespace( add='JOE' )
cmds.namespace( mv=('BAR', 'JOE') )
cmds.namespace( rm='BAR' )
# JOE should now contain a single node: 'sphere2'.
# Move the contents of JOE into FRANK, when FRANK already
# has a 'sphere2' node. The '-force'
# flag is needed.
cmds.namespace( set=':' )
cmds.namespace( add='FRANK' )
cmds.namespace( set='FRANK' )
cmds.sphere( n='sphere2' )
cmds.namespace( force=True, mv=(':JOE', ':FRANK') )
# In moving 'sphere2' from JOE to FRANK it will be renamed to
# 'sphere3' to ensure uniqueness.
# The namespace FRANK should now contain 'sphere2', 'sphere2Shape',
# and 'sphere3'.
# Determine whether the given namespace is root
#
cmds.namespace( query=True, isRootNamespace="FOO" )
#Set return value to be absolute namespace name
#
print(cmds.namespace(add = "testAbsoluteName", absoluteName = True))
#Create a sample hierachy that contains only empty namespaces, then collapse it
#
cmds.namespace( set = ":")
cmds.namespace( add = "emptyLevel1")
cmds.namespace( add = "emptyLevel2", parent = "emptyLevel1")
cmds.namespace( add = "leaf", parent = "emptyLevel1:emptyLevel2")
cmds.namespace( collapseAncestors = "emptyLevel1:emptyLevel2:leaf")
# Create a sample for removing an existed namespace.
# This command can also be used together with three option parameters named
# deleteNamespaceContent/mergeNamespaceWithParent/mergeNamespaceWithRoot.
# The functionality of the three option parameters will also be displayed in the
# following sample.
# Note: The three option parameters are mutually exclusive.
# Without any option parameters specified, the default way it performances that
# it can only remove a namespace that is empty. If you want to remove any namespace
# with contents, please add option parameter deleteNamespaceContent.
#
cmds.namespace( set = ":")
cmds.namespace( add = ":RM_TEST_ROOT:FOO:BAR:JOE")
cmds.sphere( name = ":RM_TEST_ROOT:FOO:obj1")
cmds.sphere( name = ":RM_TEST_ROOT:FOO:BAR:obj2")
# Trying to remove a namespace that is not empty without option parameter,
# user will get an error message show that maya cannot remove a namespace that
# is not empty.
#
#cmds.namespace( removeNamespace = ":RM_TEST_ROOT:FOO") # Run this command you'll get an error.
# Trying to remove an empty namespace.
# Namespace :RM_TEST_ROOT:FOO:BAR:JOE has been removed successfully by the command.
#
cmds.namespace( removeNamespace = ":RM_TEST_ROOT:FOO:BAR:JOE")
cmds.undo()
# Usage of deleteNamespaceContent option parameter:
# Remove all the contents in the target namespace specified in the command and
# remove the namespace
#
cmds.namespace( removeNamespace = ":RM_TEST_ROOT:FOO:BAR", deleteNamespaceContent = True)
cmds.undo()
# Usage of mergeNamespaceWithParent parameter:
# Move the content of the target namespace specified in the command to its parent
# namespace and remove the namespace.
#
cmds.namespace( removeNamespace = ":RM_TEST_ROOT:FOO:BAR", mergeNamespaceWithParent = True)
cmds.undo()
# Usage of mergeNamespaceWithRoot parameter:
# Move the content of the target namespace specified in the command to the root
# namespace and remove the namespace.
#
cmds.namespace( removeNamespace = ":RM_TEST_ROOT:FOO:BAR", mergeNamespaceWithRoot = True)