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']] #
