pymel.core.modeling.editMetadata

editMetadata(*args, **kwargs)

This command is used to set metadata elements onto or remove metadata elements from an object. Before using this command you must first attach a metadata stream type to the object using the addMetadatacommand or an API equivalent. The command has four basic variations: Set per-component metadata on meshesRemove per-component metadata on meshesSet generic metadata on any objectRemove generic metadata on any objectThe difference between the setand removevariations (1,3 vs. 2,4) is that setrequires 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 channelNameand indexflags. Note that since indexis 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 channelNameand indexflags. For example the selection “myMesh.vtx[8:10]” corresponds to channelName = vertexand index = 8, 9, 10(as a multi-use flag). Note that the metadata is assigned to an object 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 or scene, 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. Certain nodes have metadata supplied by input attributes. If you edit one of those with an incoming connection on such an attribute then the metadata edit will not be applied directly it will be put into an ‘editMetadata’ node for application during DG evaluation. Since the details of the metadata are not known until the evaluation happens less rigorous compatibility checking is performed. The editMetadata node has its own facilities for verifying and reporting illegal metadata edits. Successive edits to the same metadata in this way appends each edit to the same editMetadata node.

Flags:

Long name (short name)		Argument Types	Properties
channelName (cn)		unicode
	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)		unicode
	Obsolete - use the ‘channelName’ flag instead. In query mode, this flag can accept a value.
endIndex (eix)		unicode
	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 startIndexflag to specify a range of indices from which to retrieve the metadata. It is an error to have the value of startIndexbe greater than that of endIndex. See also the indexflag 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)		unicode
	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 indexflag takes a string, formatted in the way the specified indexTyperequires. All uses of the indexflag 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)		unicode
	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.
memberName (mn)		unicode
	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.
remove (rem)		bool
	If the removeflag 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.
scene (scn)		bool
	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)		unicode
	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 endIndexflag to specify a range of indices from which to retrieve the metadata. It is an error to have the value of startIndexbe greater than that of endIndex. See also the indexflag 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)		unicode
	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 commandFlag can have multiple arguments, passed either as a tuple or a list.
stringValue (sv)		unicode
	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.
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.

Derived from mel command maya.cmds.editMetadata

Example:

import pymel.core as pm

import maya.cmds as cmds
pm.polyPlane( name='smcPlane', constructionHistory=False )
# Result: [nt.Transform(u'smcPlane')] #
pm.pickWalk( d='down' )
# Result: [u'smcPlaneShape'] #
# Create structure
pm.dataStructure( format='raw', asString='name=idStructure:int32=ID' )
# Result: u'idStructure' #
# Apply structure to plane
pm.addMetadata( structure='idStructure', streamName='idStream', channelName='vertex' )
# Result: [u'smcPlaneShape'] #
# Attach a metadata value to three of the components by selection
pm.select( 'smcPlaneShape.vtx[8:10]', replace=True )
pm.editMetadata( streamName='idStream', memberName='ID', value=7 )
# Result: nt.Mesh(u'smcPlaneShape') #
# Attach a metadata value to another component by manual indexing
pm.select( 'smcPlaneShape', replace=True )
pm.editMetadata( streamName='idStream', memberName='ID', channelName='vertex', value=8, index=14 )
# Result: nt.Mesh(u'smcPlaneShape') #
# Remove metadata from the middle of the three vertexes set earlier
pm.select( 'smcPlaneShape.vtx[9]', replace=True )
pm.editMetadata( streamName='idStream', remove=True )
# Result: nt.Mesh(u'smcPlaneShape') #