Go to: Synopsis. Return value. Keywords.
Related. Flags.
Python examples.
getMetadata([channelType=string], [endIndex=int], [index=string], [indexType=string], [memberName=string], [startIndex=int], [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. It has two basic variations:
- Get per-component metadata on meshes
- Get generic metadata on any node
The difference between the two is that the first uses some very
specific knowledge about mesh components, i.e. the legal index
values. For example on a mesh with 14 edges requesting the metadata
corresponding to edge index 15 will generate a warning even if such
metadata exists. For any generic metadata, or even mesh metadata
not associated with known component types, no such warning will
ever be generated since the boundaries of the associated data are
unknown. The typical method of accessing per-component metadata is
to select or specify on the command line the components whose
metadata you wish to retrieve. Only one component type is permitted
per command invocation. In general usage you select specific pieces
of metadata through the channelType and
index/startIndex/endIndex flags. Note that index is a
multi-use flag through which you can select many different elements
from the same Channel, and the setIndex/endIndex pair
specifies an entire range of index values for retrieval. The
index flag works for any type of index. It defaults to a
simple numeric index. Specifying the indexType flag allows
you to use other index types (e.g. "string"). The startIndex
and endIndex flags of course only work with the simple
numeric index type. 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
setting these metadata Channels easier you can simply select or
specify on the command line the corresponding components rather
than using the channelType and
index/startIndex/endIndex flags. For example the selection
"myMesh.vtx[8:10]" corresponds to channelType = vertex and
either index = 8, 9, 10 as a multi-use flag or setIndex =
8, endIndex=10. Only a single node, component type, channel
type, and value type 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 would be an array each so
you would get back three float[3] arrays.
| int[] |
List of integer values from the metadata member |
| float[] |
List of real values from the metadata member |
| string[] |
List of string values from the metadata member |
metadata, component, stream, channel, association
addMetadata, applyMetadata, dataStructure, editMetadata
channelType, endIndex, index,
indexType, memberName, startIndex, streamName
| Long name (short name) |
Argument types |
Properties |
channelType(cht) |
string |
 |
|
Specify the Channel type from which the metadata is to be
retrieved. This is only required when you use this command in the
general form, with a node selected or specified on the command line
rather than components. The Channel type refers to the metadata
Association that will be examined. In general the string is
arbitrary since the channels are named by the user. For the
specific case of mesh components the reserved Channel names
"vertex", "face", "edge", and "vertexFace" are used to look up the
metadata on the similarly named components. |
|
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. |
|
index(idx) |
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 then this flag may be used to specify the index from which the
metadata will be retrieved. If multiple indices are specified then
the values are retrieved from all of them. See also the
startIndex/endIndex flags for an alternate way to specify
multiple indices. It is not necessary to specify every index being
used as the structure will define what happens at unused indices
(i.e. fill with default values or treat as unassigned). So you can
get a value from index 3 regardless of whether there are already
values at indices 0, 1, and 2. |
|
indexType(idt) |
string |
|
|
In the typical case metadata is indexed using a simple
numerical value. Certain types of data may use other index types.
e.g. a "vertexFace" component will use a "pair" index type, which
is two numerical values; one for the face ID of the component and
the second for the vertex ID. The index flag is 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 numeric
value. |
|
startIndex(six) |
int |
|
|
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 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. It is not necessary to specify every index being used as
the structure will define what happens at unused indices (i.e. fill
with default values or treat as unassigned). So you can get a value
from index 3 regardless of whether there are already values at
indices 0, 1, and 2. |
|
endIndex(eix) |
int |
|
|
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 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. It is not necessary to specify every index being used as
the structure will define what happens at unused indices (i.e. fill
with default values or treat as unassigned). So you can get a value
from index 3 regardless of whether there are already values at
indices 0, 1, and 2. |
|
streamName(stn) |
string |
|
|
Name of the metadata Stream being retrieved. It should already
have been created when using this command. See the "addMetadata"
command, the "applyMetadata" command, or the metadata API for
information on how to create a Stream. |
|
| 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
import maya.cmds as cmds
cmds.polyPlane( name='smcPlane', constructionHistory=False )
# Result: smcPlane #
# 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', channelType='vertex' )
cmds.addMetadata( structure='keyValueStructure', streamName='keyValueStream', channelType='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', channelType='vertex', index=['8','9','10'] )
# Result: [[7], [7], [7]] #
# 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:11]', replace=True )
cmds.getMetadata( streamName='idStream', memberName='ID' )
# Result: [[0], [7], [7], [7], [0]] #
# Set metadata values using the complex index type stream
cmds.editMetadata( streamName='keyValueStream', memberName='value', stringValue='Starry Night', index='Title' )
# Result: 1 #
cmds.editMetadata( streamName='keyValueStream', memberName='value', stringValue='Vincent Van Gogh', index='Artist' )
# Result: 1 #
# Retrieve the complex index data
cmds.getMetadata( streamName='keyValueStream', memberName='value', channelType='key', index=['Title', 'Artist'], indexType='string' )
# Result: [['Starry Night'], ['Vincent Van Gogh']] #
