pymel.core.general.ls

static general.ls(*args, **kwargs)

The lscommand returns the names (and optionally the type names) of objects in the scene. The most common use of lsis to filter or match objects based on their name (using wildcards) or based on their type. By default lswill 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, typevalues. 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 lscommand will return names relativeto the current namespace and ls *will list from the the current namespace. For more details, please refer to the -relativeNamesflag of the namespacecommand.

Modifications:
  • Added new keyword: ‘editable’ - this will return the inverse set of the readOnly flag. i.e. non-read-only nodes

  • Added new keyword: ‘regex’ - pass a valid regular expression string, compiled regex pattern, or list thereof.

    >>> group('top')
    nt.Transform(u'group1')
    >>> duplicate('group1')
    [nt.Transform(u'group2')]
    >>> group('group2')
    nt.Transform(u'group3')
    >>> ls(regex='group\d+\|top') # don't forget to escape pipes `|`
    [nt.Transform(u'group1|top'), nt.Transform(u'group2|top')]
    >>> ls(regex='group\d+\|top.*')
    [nt.Transform(u'group1|top'), nt.Camera(u'group1|top|topShape'), nt.Transform(u'group2|top'), nt.Camera(u'group2|top|topShape')]
    >>> ls(regex='group\d+\|top.*', cameras=1)
    [nt.Camera(u'group2|top|topShape'), nt.Camera(u'group1|top|topShape')]
    >>> ls(regex='\|group\d+\|top.*', cameras=1) # add a leading pipe to search for full path
    [nt.Camera(u'group1|top|topShape')]
    

    The regular expression will be used to search the full DAG path, starting from the right, in a similar fashion to how globs currently work. Technically speaking, your regular expression string is used like this:

    re.search( '(\||^)' + yourRegexStr + '$', fullNodePath )
    
    rtype:PyNode list
Flags:
Long name (short name) Argument Types Properties
allPaths (ap) bool ../../../_images/create.gif
 
List all paths to nodes in DAG. This flag only works if -dagis also specified or if an object name is supplied.
assemblies (assemblies) bool ../../../_images/create.gif
 
List top level transform Dag objects
cameras (ca) bool ../../../_images/create.gif
 
List camera shapes.
containerType (ct) unicode  
   
containers (con) bool ../../../_images/create.gif
 

List containers. Includes both standard containers as well as other types of containers such as dagContainers. Flag can have multiple arguments, passed either as a tuple or a list.

dagObjects (dag) bool ../../../_images/create.gif
 
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).
dependencyNodes (dep) bool ../../../_images/create.gif
 
List dependency nodes. (including Dag objects)
exactType (et) unicode ../../../_images/create.gif
 

List all objects of the specified type, but notobjects 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 flag.

flatten (fl) bool ../../../_images/create.gif
 
Flattens the returned list of objects so that each component is identified individually.
geometry (g) bool ../../../_images/create.gif
 
List geometric Dag objects.
ghost (gh) bool ../../../_images/create.gif
 
List ghosting objects.
head (hd) int ../../../_images/create.gif
 

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) bool ../../../_images/create.gif
 
List objects that are currently hilited for component selection.
intermediateObjects (io) bool ../../../_images/create.gif
 
List only intermediate dag nodes.
invisible (iv) bool ../../../_images/create.gif
 
List only invisible dag nodes.
leaf (lf) bool ../../../_images/create.gif
 
List all leaf nodes in Dag. This flag is a modifier and must be used in conjunction with the -dag flag.
lights (lt) bool ../../../_images/create.gif
 
List light shapes.
live (lv) bool ../../../_images/create.gif
 
List objects that are currently live.
lockedNodes (ln) bool ../../../_images/create.gif
 
Returns locked nodes, which cannot be deleted or renamed. However, their status may change.
long (l) bool ../../../_images/create.gif
 
Return full path names for Dag objects. By default the shortest unique name is returned.
materials (mat) bool ../../../_images/create.gif
 
List materials or shading groups.
noIntermediate (ni) bool ../../../_images/create.gif
 
List only non intermediate dag nodes.
nodeTypes (nt) bool ../../../_images/create.gif
 
Lists all registered node types.
objectsOnly (o) bool ../../../_images/create.gif
 
When this flag is set only object names will be returned and components/attributes will be ignored.
orderedSelection (os) bool  
   
partitions (pr) bool ../../../_images/create.gif
 
List partitions.
persistentNodes (pn) bool ../../../_images/create.gif
 
Returns persistent nodes, which are nodes that stay in the Maya session after a file new.
planes (pl) bool ../../../_images/create.gif
 
List construction plane shapes.
preSelectHilite (psh) bool ../../../_images/create.gif
 
List components that are currently hilited for pre-selection.
readOnly (ro) bool ../../../_images/create.gif
 
Returns referenced nodes. Referenced nodes are read only. NOTE: Obsolete. Please use -referencedNodes.
recursive (r) bool ../../../_images/create.gif
 

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) bool ../../../_images/create.gif
 
Returns referenced nodes. Referenced nodes are read only.
references (rf) bool ../../../_images/create.gif
 
List references associated with files. Excludes special reference nodes such as the sharedReferenceNode and unknown reference nodes.
renderGlobals (rg) bool ../../../_images/create.gif
 
List render globals.
renderQualities (rq) bool ../../../_images/create.gif
 
List named render qualities.
renderResolutions (rr) bool ../../../_images/create.gif
 
List render resolutions.
renderSetups (rs) bool ../../../_images/create.gif
 
Alias for -renderGlobals.
selection (sl) bool ../../../_images/create.gif
 
List objects that are currently selected.
sets (set) bool ../../../_images/create.gif
 
List sets.
shapes (s) bool ../../../_images/create.gif
 
List shape objects.
shortNames (sn) bool ../../../_images/create.gif
 
Return short attribute names. By default long attribute names are returned.
showType (st) bool ../../../_images/create.gif
 
List the type of each object after its name.
tail (tl) int ../../../_images/create.gif
 

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) bool ../../../_images/create.gif
 
List only templated dag nodes.
textures (tex) bool ../../../_images/create.gif
 
List textures.
transforms (tr) bool ../../../_images/create.gif
 
List transform objects.
type (typ) unicode ../../../_images/create.gif
 

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 untypedwhen listed with this flag. This flag cannot be used in conjunction with the -exactType flag.

undeletable (ud) bool ../../../_images/create.gif
 
Returns nodes that cannot be deleted (which includes locked nodes). These nodes also cannot be renamed.
untemplated (ut) bool ../../../_images/create.gif
 
List only un-templated dag nodes.
visible (v) bool ../../../_images/create.gif
 
List only visible dag nodes.

Derived from mel command maya.cmds.ls

Example:

import pymel.core as pm

# create some objects to operate on and select them all.
# Note that there are two objects named circle1;
pm.circle( n='circle1' )
# Result: [nt.Transform(u'circle1'), nt.MakeNurbCircle(u'makeNurbCircle1')] #
pm.group()
# Result: nt.Transform(u'group1') #
pm.circle( n='circle1' )
# Result: [nt.Transform(u'|circle1'), nt.MakeNurbCircle(u'makeNurbCircle2')] #
pm.sphere( n='sphere1' )
# Result: [nt.Transform(u'sphere1'), nt.MakeNurbSphere(u'makeNurbSphere1')] #
pm.group()
# Result: nt.Transform(u'group2') #
pm.instance()
# Result: [nt.Transform(u'group3')] #
pm.select( ado=True )

# list all objects
pm.ls()
# Result: [nt.Time(u'time1'), nt.Partition(u'renderPartition'), nt.RenderGlobalsList(u'renderGlobalsList1'), nt.DefaultLightList(u'defaultLightList1'), nt.DefaultShaderList(u'defaultShaderList1'), nt.PostProcessList(u'postProcessList1'), nt.DefaultRenderUtilityList(u'defaultRenderUtilityList1'), nt.LightList(u'lightList1'), nt.DefaultTextureList(u'defaultTextureList1'), nt.Lambert(u'lambert1'), nt.ParticleCloud(u'particleCloud1'), nt.ShadingEngine(u'initialShadingGroup'), nt.ShadingEngine(u'initialParticleSE'), nt.MaterialInfo(u'initialMaterialInfo'), nt.ShaderGlow(u'shaderGlow1'), nt.Dof(u'dof1'), nt.RenderGlobals(u'defaultRenderGlobals'), nt.RenderQuality(u'defaultRenderQuality'), nt.Resolution(u'defaultResolution'), nt.ObjectSet(u'defaultLightSet'), nt.ObjectSet(u'defaultObjectSet'), nt.ViewColorManager(u'defaultViewColorManager'), nt.HardwareRenderGlobals(u'hardwareRenderGlobals'), nt.Partition(u'characterPartition'), nt.HwRenderGlobals(u'defaultHardwareRenderGlobals'), nt.IkSystem(u'ikSystem'), nt.HyperGraphInfo(u'hyperGraphInfo'), nt.HyperLayout(u'hyperGraphLayout'), nt.GlobalCacheControl(u'globalCacheControl'), nt.DependNode(u'dynController1'), nt.StrokeGlobals(u'strokeGlobals'), nt.Transform(u'persp'), nt.Camera(u'perspShape'), nt.Transform(u'top'), nt.Camera(u'topShape'), nt.Transform(u'front'), nt.Camera(u'frontShape'), nt.Transform(u'side'), nt.Camera(u'sideShape'), nt.LightLinker(u'lightLinker1'), nt.ObjectMultiFilter(u'layersFilter'), nt.ObjectTypeFilter(u'objectTypeFilter74'), nt.ObjectMultiFilter(u'animLayersFilter'), nt.ObjectTypeFilter(u'objectTypeFilter75'), nt.ObjectMultiFilter(u'notAnimLayersFilter'), nt.ObjectTypeFilter(u'objectTypeFilter76'), nt.ObjectMultiFilter(u'defaultRenderLayerFilter'), nt.ObjectNameFilter(u'objectNameFilter4'), nt.ObjectMultiFilter(u'renderLayerFilter'), nt.ObjectTypeFilter(u'objectTypeFilter77'), nt.ObjectScriptFilter(u'objectScriptFilter10'), nt.ObjectMultiFilter(u'renderingSetsFilter'), nt.ObjectTypeFilter(u'objectTypeFilter78'), nt.ObjectMultiFilter(u'relationshipPanel1LeftAttrFilter'), nt.ObjectMultiFilter(u'relationshipPanel1RightAttrFilter'), nt.DisplayLayerManager(u'layerManager'), nt.DisplayLayer(u'defaultLayer'), nt.RenderLayerManager(u'renderLayerManager'), nt.RenderLayer(u'defaultRenderLayer'), nt.MakeNurbCircle(u'makeNurbCircle1'), nt.Transform(u'group1|circle1'), nt.NurbsCurve(u'group1|circle1|circle1Shape'), nt.Transform(u'group1'), nt.MakeNurbCircle(u'makeNurbCircle2'), nt.Transform(u'|circle1'), nt.NurbsCurve(u'|circle1|circle1Shape'), nt.MakeNurbSphere(u'makeNurbSphere1'), nt.Transform(u'group2|sphere1'), nt.NurbsSurface(u'group2|sphere1|sphere1Shape'), nt.Transform(u'group2'), nt.Transform(u'group3')] #

# List all selected objects
pm.ls( selection=True )
# Result: [nt.Transform(u'group1'), nt.Transform(u'|circle1'), nt.Transform(u'group2'), nt.Transform(u'group3')] #

# List all hilited objects
pm.ls( hilite=True )
# Result: [] #

# List last selected object
pm.ls( selection=True, tail=1 )
# Result: [nt.Transform(u'group3')] #

# List all objects named "sphere1". Note that since sphere1 is
# instanced, the command below lists only the first instance.
pm.ls( 'sphere1' )
# Result: [nt.Transform(u'group2|sphere1')] #

# To list all instances of sphere1, use the -ap/allPaths flag.
pm.ls( 'sphere1', ap=True )
# Result: [nt.Transform(u'group2|sphere1'), nt.Transform(u'group3|sphere1')] #

# List all selected objects named "group*"
pm.ls( 'group*', sl=True )
# Result: [nt.Transform(u'group1'), nt.Transform(u'group2'), nt.Transform(u'group3')] #

# List all geometry, lights and cameras in the DAG.
pm.ls( geometry=True, lights=True, cameras=True )
# Result: [nt.NurbsCurve(u'|circle1|circle1Shape'), nt.NurbsCurve(u'group1|circle1|circle1Shape'), nt.NurbsSurface(u'group2|sphere1|sphere1Shape'), nt.Camera(u'frontShape'), nt.Camera(u'perspShape'), nt.Camera(u'sideShape'), nt.Camera(u'topShape')] #

# List all shapes in the dag.
pm.ls( shapes=True )
# Result: [nt.NurbsCurve(u'|circle1|circle1Shape'), nt.NurbsCurve(u'group1|circle1|circle1Shape'), nt.Camera(u'frontShape'), nt.Camera(u'perspShape'), nt.Camera(u'sideShape'), nt.NurbsSurface(u'group2|sphere1|sphere1Shape'), nt.Camera(u'topShape')] #

# 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:
pm.select(pm.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 = pm.ls(l=True)
for obj in allObjects:
   if pm.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 = pm.ls(type='surfaceShape')
for obj in allObjects:
    print obj

# List all geometry shapes and their types
pm.ls( type='geometryShape', showType=True )
# Result: [nt.NurbsCurve(u'|circle1|circle1Shape'), u'nurbsCurve', nt.NurbsCurve(u'group1|circle1|circle1Shape'), u'nurbsCurve', nt.NurbsSurface(u'group2|sphere1|sphere1Shape'), u'nurbsSurface'] #

# List all paths to all leaf nodes in the DAG
pm.ls( dag=True, lf=True, ap=True )
# Result: [nt.Camera(u'perspShape'), nt.Camera(u'topShape'), nt.Camera(u'frontShape'), nt.Camera(u'sideShape'), nt.NurbsCurve(u'group1|circle1|circle1Shape'), nt.NurbsCurve(u'|circle1|circle1Shape'), nt.NurbsSurface(u'group2|sphere1|sphere1Shape'), nt.NurbsSurface(u'group3|sphere1|sphere1Shape')] #

# List all nodes below the selected node
pm.ls( dag=True, ap=True, sl=True )
# Result: [nt.Transform(u'group1'), nt.Transform(u'group1|circle1'), nt.NurbsCurve(u'group1|circle1|circle1Shape'), nt.Transform(u'|circle1'), nt.NurbsCurve(u'|circle1|circle1Shape'), nt.Transform(u'group2'), nt.Transform(u'group2|sphere1'), nt.Transform(u'group3|sphere1'), nt.NurbsSurface(u'group2|sphere1|sphere1Shape'), nt.NurbsSurface(u'group3|sphere1|sphere1Shape'), nt.Transform(u'group3')] #

# List all dag nodes that are read-only (i.e. referenced nodes)
pm.ls( dag=True, ro=True )
# Result: [] #

# List all ghosting objects
pm.ls( ghost=True )
# Result: [] #

# List reference nodes associated with specific files
pm.ls( references=True )
# Result: [] #

# List all reference nodes, including unknown and shared reference nodes
pm.ls( type='reference' )
# Result: [] #

Previous topic

pymel.core.general.lockNode

Next topic

pymel.core.general.makeIdentity

Core

Core Modules

Other Modules

This Page