getMetadata

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

Synopsis

getMetadata [-channelType string] [-endIndex int] [-index string] [-indexType string] [-memberName string] [-startIndex int] [-streamName string]

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:

1. Get per-component metadata on meshes
2. 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.

Return value

Keywords

Related

Flags

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 be used more than once in a command.

MEL examples

polyPlane -n smcPlane -ch off;
// Result: smcPlane //
// Create structures
dataStructure -format "raw" -asString "name=idStructure:int32=ID";
dataStructure -format "raw" -asString "name=keyValueStructure:string=value";
// Result: idStructure //
// Apply structures to plane
addMetadata -structure "idStructure" -streamName "idStream" -channelType "vertex";
addMetadata -structure "keyValueStructure" -streamName "keyValueStream" -channelType "key" -indexType "string";
// Set the metadata values on three of the components by selection
select -r smcPlaneShape.vtx[8:10];
editMetadata -streamName "idStream" -memberName "ID" -value 7;
// Result: 1 //
// Retrieve the three newly set metadata values
select -r smcPlaneShape;
getMetadata -streamName "idStream" -memberName "ID" -channelType "vertex" -index "8" -index "9" -index "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).
select -r smcPlaneShape.vtx[7:11];
getMetadata -streamName "idStream" -memberName "ID";
// Result: 0 7 7 7 0 //
// Set metadata values using the complex index type "string"
editMetadata -streamName "keyValueStream" -memberName "value" -stringValue "Starry Night" -index "Title";
editMetadata -streamName "keyValueStream" -memberName "value" -stringValue "Vincent Van Gogh" -index "Artist";
// Retrieve the complex index data
getMetadata -streamName "keyValueStream" -memberName "value" -channelType "key" -index "Title" -index "Artist" -indexType "string";
// Result: "Starry Night" "Vincent Van Gogh" //