Go to: Synopsis. Return value. Flags. Python examples.
ls(
[object [object...]]
, [absoluteName=boolean], [allPaths=boolean], [assemblies=boolean], [cameras=boolean], [containerType=string], [containers=boolean], [dagObjects=boolean], [defaultNodes=boolean], [dependencyNodes=boolean], [exactType=string], [excludeType=string], [flatten=boolean], [geometry=boolean], [ghost=boolean], [head=int], [hilite=boolean], [intermediateObjects=boolean], [invisible=boolean], [leaf=boolean], [lights=boolean], [live=boolean], [lockedNodes=boolean], [long=boolean], [materials=boolean], [modified=boolean], [noIntermediate=boolean], [nodeTypes=boolean], [objectsOnly=boolean], [orderedSelection=boolean], [partitions=boolean], [persistentNodes=boolean], [planes=boolean], [preSelectHilite=boolean], [readOnly=boolean], [recursive=boolean], [referencedNodes=boolean], [references=boolean], [renderGlobals=boolean], [renderQualities=boolean], [renderResolutions=boolean], [renderSetups=boolean], [selection=boolean], [sets=boolean], [shapes=boolean], [shortNames=boolean], [showNamespace=boolean], [showType=boolean], [tail=int], [templated=boolean], [textures=boolean], [transforms=boolean], [type=string], [undeletable=boolean], [untemplated=boolean], [uuid=boolean], [visible=boolean])
Note: Strings representing object names and arguments must be separated by commas. This is not depicted in the synopsis.
ls is undoable, NOT queryable, and NOT editable.
The ls command returns the names (and
optionally the type names) of objects in the scene.
The most common use of ls is to filter or
match objects based on their name (using wildcards) or based on their
type.
By default ls will match any object in the
scene but it can also be used to filter or list the selected
objects when used in conjunction with the -selection flag.
If type names are requested, using the showType flag, they
will be interleaved with object names so the result will be
pairs of <object, type> values.
Internal nodes (for example itemFilter nodes) are typically filtered
so that only scene objects are returned. However, using a wildcard
will cause all the nodes matching the wild card to show up, including
internal nodes. For example, ls * will list all
nodes whether internal or not.
When Maya is in relativeNames mode, the ls command
will return names relative to the current namespace and
ls * will list from the the current namespace.
For more details, please refer to the -relativeNames
flag of the namespace command.
The command may also be passed node UUIDs instead of names/paths, and
can return UUIDs instead of names via the -uuid flag.
absoluteName, allPaths, assemblies, cameras, containerType, containers, dagObjects, defaultNodes, dependencyNodes, exactType, excludeType, flatten, geometry, ghost, head, hilite, intermediateObjects, invisible, leaf, lights, live, lockedNodes, long, materials, modified, noIntermediate, nodeTypes, objectsOnly, orderedSelection, partitions, persistentNodes, planes, preSelectHilite, readOnly, recursive, referencedNodes, references, renderGlobals, renderQualities, renderResolutions, renderSetups, selection, sets, shapes, shortNames, showNamespace, showType, tail, templated, textures, transforms, type, undeletable, untemplated, uuid, visible
| Long name (short name) |
Argument types |
Properties |
|
absoluteName(an)
|
boolean
|
|
|
This flag can be used in conjunction with the showNamespace flag to specify
that the namespace(s) returned by the command be in absolute namespace format.
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.
The absolute namespace name is invariant and is not affected by the current namespace or
relative namespace modes.
|
|
allPaths(ap)
|
boolean
|
|
|
List all paths to nodes in DAG. This flag only works
if -dag is also specified or if an object name is
supplied.
|
|
assemblies(assemblies)
|
boolean
|
|
|
List top level transform Dag objects
|
|
cameras(ca)
|
boolean
|
|
|
|
containerType(ct)
|
string
|
|
|
List containers with the specified user-defined type.
This flag cannot be used in conjunction with the type or exactType flag.
|
|
containers(con)
|
boolean
|
|
|
List containers. Includes both standard containers as well as other types of
containers such as dagContainers.
|
|
dagObjects(dag)
|
boolean
|
|
|
List Dag objects of any type. If object name arguments are
passed to the command then this flag will list all Dag objects
below the specified object(s).
|
|
defaultNodes(dn)
|
boolean
|
|
|
Returns default nodes.
A default node is one that Maya creates automatically and does not get
saved out with the scene, although some of its attribute values may.
|
|
dependencyNodes(dep)
|
boolean
|
|
|
List dependency nodes. (including Dag objects)
|
|
exactType(et)
|
string
|
|
|
List all objects of the specified type, but not objects that are
descendents of that type. This flag can appear
multiple times on the command line. Note: the type passed to
this flag is the same type name returned from the showType
flag.
This flag cannot be used in conjunction with the type or excludeType flag.
|
|
excludeType(ext)
|
string
|
|
|
List all objects that are not of the specified type.
This flag can appear multiple times on the command line. Note: the type passed to
this flag is the same type name returned from the showType flag.
This flag cannot be used in conjunction with the type or exactType flag.
|
|
flatten(fl)
|
boolean
|
|
|
Flattens the returned list of objects so that each component
is identified individually.
|
|
geometry(g)
|
boolean
|
|
|
List geometric Dag objects.
|
|
ghost(gh)
|
boolean
|
|
|
|
head(hd)
|
int
|
|
|
This flag specifies the maximum number of elements to be
returned from the beginning of the list of items.
Note: each type flag will return at most this many items so
if multiple type flags are specified then the number of items
returned can be greater than this amount.
|
|
hilite(hl)
|
boolean
|
|
|
List objects that are currently hilited for component selection.
|
|
intermediateObjects(io)
|
boolean
|
|
|
List only intermediate dag nodes.
|
|
invisible(iv)
|
boolean
|
|
|
List only invisible dag nodes.
|
|
leaf(lf)
|
boolean
|
|
|
List all leaf nodes in Dag. This flag is a modifier and must
be used in conjunction with the -dag flag.
|
|
lights(lt)
|
boolean
|
|
|
|
live(lv)
|
boolean
|
|
|
List objects that are currently live.
|
|
lockedNodes(ln)
|
boolean
|
|
|
Returns locked nodes, which cannot be deleted or renamed. However, their status may change.
|
|
long(l)
|
boolean
|
|
|
Return full path names for Dag objects. By default the
shortest unique name is returned.
|
|
materials(mat)
|
boolean
|
|
|
List materials or shading groups.
|
|
modified(mod)
|
boolean
|
|
|
When this flag is set, only nodes modified since the last save will be returned.
|
|
noIntermediate(ni)
|
boolean
|
|
|
List only non intermediate dag nodes.
|
|
nodeTypes(nt)
|
boolean
|
|
|
Lists all registered node types.
|
|
objectsOnly(o)
|
boolean
|
|
|
When this flag is set only object names will be returned and
components/attributes will be ignored.
|
|
orderedSelection(os)
|
boolean
|
|
|
List objects and components that are currently selected in their order of selection. This flag depends
on the value of the -tso/trackSelectionOrder flag of the selectPref command. If that flag is not
enabled than this flag will return the same thing as the -sl/selection flag would.
|
|
partitions(pr)
|
boolean
|
|
|
|
persistentNodes(pn)
|
boolean
|
|
|
Returns persistent nodes, which are nodes that stay in the Maya session after a file > new.
These are a special class of default nodes that do not get reset on file > new.
Ex: itemFilter and selectionListOperator nodes.
|
|
planes(pl)
|
boolean
|
|
|
List construction plane shapes.
|
|
preSelectHilite(psh)
|
boolean
|
|
|
List components that are currently hilited for pre-selection.
|
|
readOnly(ro)
|
boolean
|
|
|
Returns referenced nodes. Referenced nodes are read only.
NOTE: Obsolete. Please use "-referencedNodes".
|
|
recursive(r)
|
boolean
|
|
|
When set to true, this command will look for name matches
in all namespaces. When set to false, this command will only look
for matches in namespaces that are requested (e.g. by specifying
a name containing the ':'... "ns1:pSphere1").
|
|
referencedNodes(rn)
|
boolean
|
|
|
Returns referenced nodes. Referenced nodes are read only.
|
|
references(rf)
|
boolean
|
|
|
List references associated with files. Excludes special reference
nodes such as the sharedReferenceNode and unknown reference nodes.
|
|
renderGlobals(rg)
|
boolean
|
|
|
|
renderQualities(rq)
|
boolean
|
|
|
List named render qualities.
|
|
renderResolutions(rr)
|
boolean
|
|
|
|
renderSetups(rs)
|
boolean
|
|
|
Alias for -renderGlobals.
|
|
selection(sl)
|
boolean
|
|
|
List objects that are currently selected.
|
|
sets(set)
|
boolean
|
|
|
|
shapes(s)
|
boolean
|
|
|
|
shortNames(sn)
|
boolean
|
|
|
Return short attribute names. By default long attribute names
are returned.
|
|
showNamespace(sns)
|
boolean
|
|
|
Show the namespace of each object after the object name.
This flag cannot be used in conjunction with the showType flag.
|
|
showType(st)
|
boolean
|
|
|
List the type of each object after its name.
|
|
tail(tl)
|
int
|
|
|
This flag specifies the maximum number of elements to be
returned from the end of the list of items.
Note: each type flag will return at most this many items so
if multiple type flags are specified then the number of items
returned can be greater than this amount
|
|
templated(tm)
|
boolean
|
|
|
List only templated dag nodes.
|
|
textures(tex)
|
boolean
|
|
|
|
transforms(tr)
|
boolean
|
|
|
|
type(typ)
|
string
|
|
|
List all objects of the specified type. This flag can appear
multiple times on the command line. Note: the type passed to
this flag is the same type name returned from the showType
flag. Note: some selection items in Maya do not have a specific
object/data type associated with them and will return "untyped"
when listed with this flag.
This flag cannot be used in conjunction with the exactType or excludeType flag.
|
|
undeletable(ud)
|
boolean
|
|
|
Returns nodes that cannot be deleted (which includes locked nodes). These nodes also cannot be renamed.
|
|
untemplated(ut)
|
boolean
|
|
|
List only un-templated dag nodes.
|
|
uuid(uid)
|
boolean
|
|
|
Return node UUIDs instead of names.
Note that there are no "UUID paths" - combining this
flag with e.g. the -long flag will not result in a path
formed of node UUIDs.
|
|
visible(v)
|
boolean
|
|
|
List only visible dag nodes.
|
|
|
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 some objects to operate on and select them all.
# Note that there are two objects named circle1;
cmds.circle( n='circle1' )
cmds.group()
cmds.circle( n='circle1' )
cmds.sphere( n='sphere1' )
cmds.group()
cmds.instance()
cmds.select( ado=True )
# list all objects
cmds.ls()
# List all selected objects
cmds.ls( selection=True )
# List all hilited objects
cmds.ls( hilite=True )
# List last selected object
cmds.ls( selection=True, tail=1 )
# List all objects named "sphere1". Note that since sphere1 is
# instanced, the command below lists only the first instance.
cmds.ls( 'sphere1' )
# To list all instances of sphere1, use the -ap/allPaths flag.
cmds.ls( 'sphere1', ap=True )
# List all selected objects named "group*"
cmds.ls( 'group*', sl=True )
# List all geometry, lights and cameras in the DAG.
cmds.ls( geometry=True, lights=True, cameras=True )
# List all shapes in the dag.
cmds.ls( shapes=True )
# One thing to note is that it is better to always use the
# -l/long flag when listing nodes without any filter. This is
# because there may be two nodes with the same name (in this
# example, circle1). 'ls' will list the names of all the objects
# in the scene. Objects with the same name need a qualified
# path name which uniquely identifies the object. A command
# to select all objects such as "select `ls`" will fail because
# the object lookup can't resolve which "circle1" object is
# intended. To select all objects, you need the following:
cmds.select(cmds.ls(sl=True))
# When trying to find a list of all objects of a specific
# type, one approach might be to list all objects and then
# use the nodeType command to then filter the list. As in:
allObjects = cmds.ls(l=True)
for obj in allObjects:
if cmds.nodeType(obj) == 'surfaceShape':
print obj
# The problem with this is that 'nodeType' returns the
# most derived type of the node. In this example, "surfaceShape"
# is a base type for nurbsSurface so nothing will be printed.
# To do this properly, the -typ/type flag should be used
# to list objects of a specific type as in:
allObjects = cmds.ls(type='surfaceShape')
for obj in allObjects:
print obj
# List all geometry shapes and their types
cmds.ls( type='geometryShape', showType=True )
# List all paths to all leaf nodes in the DAG
cmds.ls( dag=True, lf=True, ap=True )
# List all nodes below the selected node
cmds.ls( dag=True, ap=True, sl=True )
# List all ghosting objects
cmds.ls( ghost=True )
# List all dag nodes that are read-only (i.e. referenced nodes)
cmds.ls( dag=True, ro=True )
# List reference nodes associated with specific files
cmds.ls( references=True )
# List all reference nodes, including unknown and shared reference nodes
cmds.ls( type='reference' )
# Select some components and then get the list in both selected and numeric order
obj1 = cmds.polySphere( sx=20, sy=20 )
cmds.select( clear=True )
cmds.selectPref( trackSelectionOrder=1 )
cmds.select( obj1[0]+".f[100]" )
cmds.select( (obj1[0]+".f[50:55]"), add=True )
cmds.select( (obj1[0]+".f[0]"), add=True )
cmds.select( (obj1[0]+".f[56:60]"), add=True )
# regular -selection flag returns the components in compacted numeric order.
cmds.ls( selection=True )
# Result:_ [u'pSphere1.f[0]', u'pSphere1.f[50:60]', u'pSphere1.f[100]'] #
# -orderedSelection flag returns the components in the order that we selected them.
cmds.ls( orderedSelection=True )
# Result:_ [u'pSphere1.f[100]', u'pSphere1.f[50:55]', u'pSphere1.f[0]', u'pSphere1.f[56:60]'] #
# turn off tracking when we are done
cmds.selectPref( trackSelectionOrder=0 )
# init some namespace
cmds.namespace( add="A:B:C" )
# add object into namespace
cmds.namespace( set=":A:B" )
cmds.polySphere( name="obj1" )
cmds.namespace( set=":A:B:C" )
cmds.polySphere( name="obj1" )
cmds.polySphere( name="obj2" )
# The current Namespace is ":A:B:C" and relative mode is off
# List all objects and their namespace in the scene
# If the object is in the root namespace, then return root ":"
# Note that the results shown below have been elided (...) for documentation purposes.
cmds.ls( showNamespace=True )
# Result: [u'time1', u':', u'sequenceManager1', u':', u'renderPartition', u':', (...), u'A:B:obj1', u'A:B', u'A:B:C:obj1', u'A:B:C', u'A:B:C:obj2', u'A:B:C'] #
cmds.select( ":A:B:obj1", r=True )
cmds.select( ":A:B:C:obj2", add=True)
# List namespace of all objects named "obj1"
cmds.ls( "obj1", showNamespace=True, recursive=True )
# Result: [u'A:B:obj1', u'A:B', u'A:B:C:obj1', u'A:B:C'] #
# List both name and namespace of each selected object
cmds.ls( showNamespace=True, selection=True )
# Result: [u'A:B:obj1', u'A:B', u'A:B:C:obj2', u'A:B:C'] #
# set current Namespace
cmds.namespace( set=":A:B" )
# enable relative mode
cmds.namespae( relativeNames=True )
# Now the current Namespace is ":A:B" and relative mode is on
# Note that the name of the current namespace is "" in relative mode
# List both name and namespace of each selected objects
cmds.ls( showNamespace=True, selection=True )
# Result: [u'obj1', u'', u'C:obj2', u'C'] #
#make a new scene modify the transform of the camera perspective, play with the timeline and modified the camera's shape
cmds.file(force=True, new=True)
cmds.setAttr('persp.translateX', 10)
cmds.currentTime(8)
cmds.setAttr('perspShape.horizontalFilmAperture', 16)
#list all modified objects of type camera and type time
allObjects=cmds.ls(type=['camera','time'], modified=True)
print allObjects
# Result: [u'perspShape', u'time1']
cmds.ls(modified=True)
# Result: [u'persp', u'perspShape', u'time1']
cmds.ls(modified=True, excludeType='camera')
# Result: [u'persp', u'time1']
# Return a node's UUID
cmds.ls( 'sphere1', uuid=True )
# Result: [u'ECE85CCC-438D-8113-0236-39A6917DE484']
# Find a node by UUID
cmds.ls( 'ECE85CCC-438D-8113-0236-39A6917DE484' )
# Result: [u'group2|sphere1']