editMetadata

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

Synopsis

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:

1. Set per-component metadata on meshes
2. Remove per-component metadata on meshes
3. Set generic metadata on any node
4. 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.

Return value

Keywords

Related

Flags

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.

Python examples

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 #