getMetadata

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

Synopsis

getMetadata([channelName=string], [channelType=string], [dataType=boolean], [endIndex=string], [index=string], [indexType=string], [listChannelNames=boolean], [listMemberNames=boolean], [listStreamNames=boolean], [memberName=string], [scene=boolean], [startIndex=string], [streamName=string])

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

getMetadata is NOT undoable, NOT queryable, and NOT editable.

This command is used to retrieve the values of metadata elements from a node or scene. It is restricted to returning a single structure member at a time. For convenience the detail required is only enough to find a single Member of a single Structure on a single metadata Channel.

In the simplest case if there is a single Stream on one metadata Channel which uses a Structure with only one Member then all that is required is the name of the object containing the metadata. In the most complex case the 'channelName', 'streamName', and 'memberName' are all required to narrow down the metadata to a single unique Member.

In general for scripting it's a good idea to use all flags anyway since there could be metadata added anywhere. The shortcuts are mainly for quick entry when entering commands directly in the script editor or command line.

When an Index is specified where data is not present the command fails with a message telling you which Index or Indices didn't have values. Use the hasMetadata command first to determine where metadata exists if you need to know in advance where to find valid metadata. Filter Flags

• channelName - Only look for metadata on one particular Channel type
• streamName - Only look for metadata on one particular named Stream. When used in conjunction with channelName then ignore Streams with a matching name but a different Channel type
• index - Only look for metadata on one or more specific Index values of a Stream. Requires use of the streamName flag. Does not require the indexType flag as that will be inferred by the streamName.
• startIndex/endIndex - Same as index but using an entire range of Index values rather than a single one. Not valid for index types not supporting ranges (e.g. strings)
• indexType - Only look for metadata using a particular Index type. Can have its scope narrowed by other filter flags as well.
• memberName - The particular Member in the metadata in a Structure to retrieve. If this is not specified the Structure can only have a single Member.

Metadata on meshes is special in that the Channel types "vertex", "edge", "face", and "vertexFace" are directly connected to the components of the same name. To make getting these metadata Channels easier you can simply select or specify on the command line the corresponding components rather than using the channelName and index/startIndex/endIndex flags. For example the selection "myMesh.vtx[8:10]" corresponds to channelName = vertex and either index = 8, 9, 10 as a multi-use flag or setIndex = 8, endIndex=10.

Only a single node or scene and unique metadata Structure Member are allowed in a single command. This keeps the data simple at the possible cost of requiring multiple calls to the command to get more than one Structure Member's value.

When the data is returned it will be in Index order with an entire Member appearing together. For example if you were retrieving float[3] metadata on three components you would get the nine values back in the order: index[0]-float[0], index[0]-float[1], index[0]-float[2], index[1]-float[0], index[1]-float[1], index[1]-float[2], index[2]-float[0], index[2]-float[1], index[2]-float[2]. In the Python implementation the float[3] values will be an array each so you would get back three float[3] arrays.

Return value

Keywords

Related

Flags

Long name (short name)	Argument types	Properties
dataType(dt)	boolean
Used with the flag 'streamName' and 'memberName' to query the dataType of the specfied member.
listChannelNames(lcn)	boolean
Query the channel names on the shape. This flag can be used with some flags to filter the results. It can be used with the flag 'streamName' to get the channel with the specfied stream and the flag 'memberName' to get the channel in which the stream contains the specified member. It cannot be used with the flag 'channelName'.
listMemberNames(lmn)	boolean
Query the member names on the shape. This flag can be used with some flags to filter the results. It can be used with 'streamName' to get the member which is in the specified stream and the flag 'channelName' to get the member which is used in the specfied channel. It cannot be used with the flag 'memberName'.
listStreamNames(lsn)	boolean
Query the stream names on the shape. This flag can be used with some flags to filter the results. It can be used with the flag 'channelName' to get the stream names on the specified channel and the flag 'memberName' to get the stream names which has the specified member. It cannot be used with the flag 'streamName'.
memberName(mn)	string
Name of the Structure member being retrieved. The names of the members are set up in the Structure definition, either through the description passed in through the "dataStructure" command or via the API used to create that Structure. This flag is only necessary when selected Structures have more than one member.
channelName(cn)	string
Filter the metadata selection to only recognize metadata belonging to the specified named Channel (e.g. "vertex"). This flag is ignored if the components on the selection list are being used to specify the metadata of interest. In query mode, this flag can accept a value.
channelType(cht)	string
Obsolete - use the 'channelName' flag instead. In query mode, this flag can accept a value.
endIndex(eix)	string
The metadata is stored in a Stream, which is an indexed list. If you have mesh components selected then the metadata indices are implicit in the list of selected components. If you select only the node or scene then this flag may be used in conjunction with the startIndex flag to specify a range of indices from which to retrieve the metadata. It is an error to have the value of startIndex be greater than that of endIndex. See also the index flag for an alternate way to specify multiple indices. This flag can only be used on index types that support a range (e.g. integer values - it makes no sense to request a range between two strings) In query mode, this flag can accept a value.
index(idx)	string
In the typical case metadata is indexed using a simple integer value. Certain types of data may use other index types. e.g. a "vertexFace" component will use a "pair" index type, which is two integer values; one for the face ID of the component and the second for the vertex ID. The index flag takes a string, formatted in the way the specified indexType requires. All uses of the index flag have the same indexType. If the type was not specified it is assumed to be a simple integer value. In query mode, this flag can accept a value.
indexType(idt)	string
Name of the index type the new Channel should be using. If not specified this defaults to a simple integer index. Of the native types only a mesh "vertexFace" channel is different, using a "pair" index type. In query mode, this flag can accept a value.
scene(scn)	boolean
Use this flag when you want to add metadata to the scene as a whole rather than to any individual nodes. If you use this flag and have nodes selected the nodes will be ignored and a warning will be displayed.
startIndex(six)	string
The metadata is stored in a Stream, which is an indexed list. If you have mesh components selected then the metadata indices are implicit in the list of selected components. If you select only the node or scene then this flag may be used in conjunction with the endIndex flag to specify a range of indices from which to retrieve the metadata. It is an error to have the value of startIndex be greater than that of endIndex. See also the index flag for an alternate way to specify multiple indices. This flag can only be used on index types that support a range (e.g. integer values - it makes no sense to request a range between two strings) In query mode, this flag can accept a value.
streamName(stn)	string
Name of the metadata Stream. Depending on context it could be the name of a Stream to be created, or the name of the Stream to pass through the filter. In query mode, this flag can accept a value.

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

import maya.cmds as cmds
cmds.polyPlane( name='smcPlane', constructionHistory=False )
# Result: smcPlane #
cmds.pickWalk( d='down' )
# Result: [u'smcPlaneShape'] #

# Create structures
cmds.dataStructure( format='raw', asString='name=idStructure:int32=ID' )
# Result: idStructure #
cmds.dataStructure( format='raw', asString='name=keyValueStructure:string=value' )
# Result: keyValueStructure #

# Apply structures to plane
cmds.addMetadata( structure='idStructure', streamName='idStream', channelName='vertex' )
cmds.addMetadata( structure='keyValueStructure', streamName='keyValueStream', channelName='key', indexType='string' )

# Set the metadata values on three of the components by selection
cmds.select( 'smcPlaneShape.vtx[8:10]', replace=True )
cmds.editMetadata( streamName='idStream', memberName='ID', value=7 )
# Result: 1 #

# Retrieve the three newly set metadata values
cmds.select( 'smcPlaneShape', replace=True )
cmds.getMetadata( streamName='idStream', memberName='ID', channelName='vertex', index=['8','9','10'] )
# Result: [[7], [7], [7]] #

# List stream names of the shape
cmds.select( 'smcPlaneShape', replace=True )
cmds.getMetadata( listStreamNames=True )
# Result: [u'keyValueStream', u'idStream'] #

# List stream names which is in the specified channel
cmds.select( 'smcPlaneShape', replace=True )
cmds.getMetadata( channelName='vertex', listStreamNames=True )
# Result: [u'idStream'] #

# List stream names of the shape which has the specified member
cmds.select( 'smcPlaneShape', replace=True )
cmds.getMetadata( memberName='ID', listStreamNames=True )
# Result: [u'idStream'] #

# List channel names which is used by the specified stream
cmds.select( 'smcPlaneShape', replace=True )
cmds.getMetadata( streamName='idStream', listChannelNames=True )
# Result: [u'vertex'] #

# List channel names which has the specified member
cmds.select( 'smcPlaneShape', replace=True )
cmds.getMetadata( memberName='ID', listChannelNames=True )
# Result: [u'vertex'] #

# List member names which is used by the specified stream
cmds.select( 'smcPlaneShape', replace=True )
cmds.getMetadata( streamName='idStream', listMemberNames=True )
# Result: [u'ID'] #

# Query data type of the listed member
cmds.select( 'smcPlaneShape', replace=True )
cmds.getMetadata( streamName='idStream', listMemberNames=True, dataType=True )
# Result: [u'ID', u'int32'] #

# Query data type of the specified member
cmds.select( 'smcPlaneShape', replace=True )
cmds.getMetadata( streamName='idStream', memberName='ID', dataType=True )
# Result: [u'int32'] #

# Get metadata from a larger group of indices all at once.
# Note that unassigned metadata values assume the default (0 for numbers).
cmds.select( 'smcPlaneShape.vtx[7:10]', replace=True )
cmds.getMetadata( streamName='idStream', memberName='ID' )
# Result: [[0], [7], [7], [7]] #

# Set metadata values using the complex index type stream
cmds.editMetadata( streamName='keyValueStream', memberName='value', stringValue='Starry Night', index='Title' )
# Result: True #
cmds.editMetadata( streamName='keyValueStream', memberName='value', stringValue='Vincent Van Gogh', index='Artist' )
# Result: True #

# Retrieve the complex index data (note return is in alphabetical order of index)
cmds.getMetadata( streamName='keyValueStream', memberName='value', channelName='key', index=['Title', 'Artist'], indexType='string' )
# Result: [['Vincent Van Gogh'], ['Starry Night']] #