Go to: Synopsis. Return value. Keywords.
Related. Flags.
Python examples.
editMetadata([channelType=string], [endIndex=string], [index=string], [indexType=string], [memberName=string], [remove=boolean], [startIndex=string], [streamName=string], [stringValue=string], [value=float])
Note: Strings representing object names and
arguments must be separated by commas. This is not depicted in the
synopsis.
editMetadata is undoable, NOT queryable, and NOT
editable.
This command is used to set metadata elements onto or remove
metadata elements from a node. Before using this command you must
first attach a metadata stream type to the node using the
addMetadata command or an API equivalent. The command has
four basic variations:
- Set per-component metadata on meshes
- Remove per-component metadata on meshes
- Set generic metadata on any node
- Remove generic metadata on any node
The difference between the set and remove variations
(1,3 vs. 2,4) is that set requires both a member name to be
set and a new value to be set. (The reason removal doesn't use a
member name is that you can only remove an entire metadata
structural element, you cannot remove only a single member from
it.) When metadata values are set or removed the action is
performed on every selected component or index. This provides an
easy method to set or remove a bunch of metadata en masse. The
general usage (variations 3, 4) lets you select specific pieces of
metadata through the channelType and index flags.
Note that since index is a multi-use flag you can select
many different elements from the same Channel and set or remove the
metadata on all of them in one command. 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 flags.
For example the selection "myMesh.vtx[8:10]" corresponds to
channelType = vertex and index = 8, 9, 10 (as a
multi-use flag). Note that the metadata is assigned to a node and
except in the special case of mesh geometry does not flow through
the dependency graph. In meshes the metadata will move from node to
node wherever the geometry is connected, although it will not
adjust itself automatically for changes in topology. Internal data
is arranged to minimize the amount of copying no matter how many
other nodes are connected to it. 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 set more than one structure
member's value.
| boolean |
True if the assignment or removal succeeded |
metadata, component, stream, channel, association
addMetadata, applyMetadata, dataStructure, getMetadata, hasMetadata
channelType, endIndex, index,
indexType, memberName, remove,
startIndex, streamName, stringValue, value
| Long name (short name) |
Argument types |
Properties |
remove(rem) |
boolean |
 |
|
If the remove flag is set then the metadata will be
removed rather than have values set. In this mode the "memberName",
"value", and "stringValue" flags are ignored. "memberName" is
ignored because when deleting metadata all members of a structure
must be removed as a group. The others are ignored since when
deleting you don't need a value to be set. |
|
memberName(mn) |
string |
|
|
Name of the Structure member being edited. 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. |
|
value(v) |
float |
 |
|
Numeric value to be set into the specified metadata locations.
This flag can only be used when the data member is a numeric type.
If the member has N dimensions (e.g. float[3]) then this flag must
appear N times (e.g. 3 times) The same values are applied to the
specified metadata member on all affected components or metadata
indices. All numeric member types should use this type of value
specification, i.e. everything except string and matrix types. Only
one of the value, and stringValue flags can be specified at once
and the type must match the type of the structure member named by
the "member" flag. |
|
stringValue(sv) |
string |
|
|
String value to be set into the specified metadata locations.
This flag can only be used when the data member is a numeric type.
If the member has N dimensions (e.g. string[2]) then this flag must
appear N times (e.g. 2 times) The same values are applied to the
specified metadata member on all affected components or metadata
indices. Only one of the value, and stringValue flags can be
specified at once and the type must match the type of the structure
member named by the "member" flag. |
|
channelType(cht) |
string |
 |
|
Filter the metadata selection to only recognize metadata
belonging to the specified channel type (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.
|
|
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 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.
|
|
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 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. |
import maya.cmds as cmds
import maya.cmds as cmds
cmds.polyPlane( name='smcPlane', constructionHistory=False )
# Result: smcPlane #
# Create structure
cmds.dataStructure( format='raw', asString='name=idStructure:int32=ID' )
# Result: idStructure #
# Apply structure to plane
cmds.addMetadata( structure='idStructure', streamName='idStream', channelType='vertex' )
# Attach a metadata value to three of the components by selection
cmds.select( 'smcPlaneShape.vtx[8:10]', replace=True )
cmds.editMetadata( streamName='idStream', memberName='ID', value=7 )
# Result: 1 #
# Attach a metadata value to another component by manual indexing
cmds.select( 'smcPlaneShape', replace=True )
cmds.editMetadata( streamName='idStream', memberName='ID', channelType='vertex', value=8, index=14 )
# Result: 1 #
# Remove metadata from the middle of the three vertexes set earlier
cmds.select( 'smcPlaneShape.vtx[9]', replace=True )
cmds.editMetadata( streamName='idStream', remove=True )
# Result: 1 #
