Skip to end of metadata
Go to start of metadata

Overview

This API is provided to enable direct operations on internal structure of VDS model.
This API exposes matai functions to achieve the following:
add, edit, remove metadata; set the instances’ closed/hidden/name attributes.

This API can be used within custom scriptable operation as Python script. For more details about scriptable operations please refer to Python Cookbook

New functions have been added as extension methods to "node" objects of VDS model (scene), for example:

node.ChangeMetadataValue(matai, "CADMetadata", "InstanceName", "test value")


Here "matai" is an instance on MataiDirect class, necessary to perform the operation. MataiDirect class defined in SAP.VE.Graphics.Interop library. It has to be used within a with block. A few points need to be
respected for correct usage:

  • there must be only a single MataiDirect object alive for a given scene at
    any point of time
  • during the lifetime of the MataiDirect object, there should be no
    modification done to the Scene object in any way other than via the
    MataiDirect interface. Otherwise the modifications would be lost when
    exiting the with block, as the MataiDirect object rebuilds the scene
    from the matai state.
  • all node references are invalidated after the with block as the scene is
    is rebuilt upon exit of the block. Therefore any node reference needs to be
    reacquired before use.
  • as much as possible, matai direct operations should be grouped together,
    within the same with block, in order to reduce the number of costly
    scene-matai synchronizations


Libraries

Following libraries and extensions are required to get access to the MataiDirect class and extension functions making up the API:

import clr
clr.AddReference('SAP.VE.Graphics.Interop')
clr.AddReference('SAP.VE.Graphics.Interop.Extensions')

import SAP.VE.Graphics.Interop as Interop
import SAP.VE.Graphics.Interop.NodeExtensions as NodeExtensions
import SAP.VE.Graphics.Interop.SceneExtensions as SceneExtensions
clr.ImportExtensions(SAP.VE.Graphics.Interop.SceneExtensions)
clr.ImportExtensions(SAP.VE.Graphics.Interop.NodeExtensions)


Functions

The new functions can operate on the different types of matai objects:
instances, entities and elements. Scene nodes are represented by matai
instances. An instance is a particular instantiation of an entity, which is the
template data for a node — in object-oriented programming, this is akin to a
class, which is a template for objects, and the objects are instances of the
classes. Elements are constituents of an entity and hold the entity’s content;
elements can hold other elements. Therefore metadata attached to the entity or
its elements will be present on all instances of that entity, whereas metadata
attached on the instance will be only present on that particular instance.

The existing node metadata getter functions are returning the metadata with a
given order of precedence (usually instance metadata overrides element’s
which overrides entity’s; however the function
GetExtendedMetadataCategoryKeyValue will give precedence to the entity
metadata over the element’s).

In addition to being assignable to different types of objects, metadata in
matai has other singular properties:

  • metadata values need to be passed either as a binary data, or as strings, in
    which case the metadata type should be set accordingly to the type of the
    original data
  • duplicate metadatum keys are allowed inside a metadata category
  • arrays are implemented by adding duplicate keys, one per array element,
    and assigning to them the type StringArray

The added facilities are as follows:

  • The following convenience functions do as their name suggest. They return
    true on success, false on failure. A reason for failure is that the
    specified metadata was not found on the specified target node. The
    different overloads of AddMetadataValues differ in the type of the value to
    store.
public static bool AddMetadataValue(
            this Node node,
            MataiDirect mataiDirect,
            string categoryName,
            string keyName,
            string value,
            AddAction action = AddAction.AddCategoryIfNotExist,
            Metadata.Type type = Metadata.Type.String,
            Metadata.ObjectType target = Metadata.ObjectType.Instance)
 
public static bool ChangeMetadataValue(
            this Node node,
            MataiDirect mataiDirect,
            string categoryName,
            string keyName,
            string value,
            Metadata.ObjectType target = Metadata.ObjectType.Instance)
 
public static bool RemoveMetadata(
            this Node node,
            MataiDirect mataiDirect,
            string categoryName,
            string keyName,
            RemoveAction action = RemoveAction.RemoveCategoryIfEmpty,
            Metadata.ObjectType target = Metadata.ObjectType.Instance)
             
void Node::SetClosed(MataiDirect^ mataiDirect, bool closed)
 
void Node::SetVisibility(MataiDirect^ mataiDirect, bool visibility)
 
void Node::SetName(MataiDirect^ mataiDirect, System::String^ name)


Enums

Here are the enums that need to be used in some of them, and the respective namespaces where they are defined.

namespace SAP.VE.Graphics.Interop.NodeExtensions
{
	public enum RemoveAction
	{
    	None,
	    RemoveCategoryIfEmpty,
	}
	public enum AddAction
	{
    	None,
	    AddCategoryIfNotExist,
	}
}

namespace SAP.VE.Graphics.Interop.Metadata
{
	public enum class ObjectType
	{
	    Instance,
	    Entity,
	    Element,
	}
    public enum class Type
    {
        String,
        Integer,
        Float,
        Date,
        Blob,
        StringArray,
    }
}


MetadataCategory class

It is a raw wrapper of the corresponding matai class. It is
expected that its main use would be inspecting or reading metadata, and that
for modification operations the above convenience functions would be preferred
to this lower-level interface. Its exposed methods are: AddMetadata,
AddBinaryMetadata, AddStringArrayMetadata, SetMetadata, RemoveMetadata,
HasName, GetName, IsEmpty, IsPrivate, GetCount, GetValue. The below static
members have also been added to enable getting or adding a metadata category on
a given type of target object. Metadata categories can be removed if they are
empty, using the RemoveMetadata function above. All metadata categories of an
object can be obtained with the below function GetAll.

static MetadataCategory Get(
    MataiDirect mataiDirect,
    Node node,
    System::String categoryName,
    ObjectType oType);

static MetadataCategory GetOrAdd(
    MataiDirect mataiDirect,
    Node node,
    System::String categoryName,
    ObjectType oType);

static void Remove(
    MataiDirect mataiDirect,
    Node node,
    System::String categoryName,
    ObjectType oType);

static MetadataCategoryList GetAll(
    MataiDirect mataiDirect,
    Node node,
    ObjectType oType);


Metadatum class

Represents a metadata key-value pair contained in the
MetadataCategory object): raw wrapper of the corresponding matai class. It enables to
get metadatum information read-only (GetName, GetValue, GetType, GetBinary).
If a metadatum information needs to be changed it needs to be either changed
or removed/added via the methods of the MetadataCategory class.


Samples

Sample 1

Below is the sample code to open the scene, access Matai model (MataiDirect), iterate through the nodes and AddMetadata.
Please note which libraries and extensions need to be imported.
Also note that operations on MataiDirect object need to be incapsulated within "with" block to finalize the changes and automatically rebuild the structure before saving.
Function Interop.Scene.LoadFromFile returns "scene" object as the result of opening source file specified by path parameter. If the path is empty, new scene object will be created.
From VEG version 9.13 function Interop.Scene.LoadFromFile will return NULL if the parameter (path) points to non-existing (invalid) location, or to corrupted/unknown format file. Its behavior with empty path will remain unchanged - it will create a new empty scene.

import clr
clr.AddReference('SAP.VE.Graphics.Interop')
clr.AddReference('SAP.VE.Graphics.Interop.Extensions')
 
import SAP.VE.Graphics.Interop as Interop
import SAP.VE.Graphics.Interop.NodeExtensions
import SAP.VE.Graphics.Interop.SceneExtensions
clr.ImportExtensions(SAP.VE.Graphics.Interop.SceneExtensions)
clr.ImportExtensions(SAP.VE.Graphics.Interop.NodeExtensions)
 
clr.ImportExtensions(System.Linq)
 
scene = Interop.Scene.LoadFromFile("C:\\Temp\\SomeSourceFile.vds")
if scene:
	nodes = scene.AllNodes().Where(lambda n: n.Name == "Name of the node that we want to work with");
	with Interop.MataiDirect(scene) as matai:
	    for node in nodes:
	    success = node.AddMetadataValue(matai, "test category", "test key", "test value");
		if success:
		    sap.log.warning("MSG: added metadata to node: '%s'" % (node.Name))
		else:
			sap.log.warning("MSG: Failed to add metadata to node: '%s'" % (node.Name))
	scene.Save("C:\\Temp\\SomeDestinationFile.vds");
	scene.Close()
else:
	sap.log.warning("File not found or corrupted");

Sample 2

Below is the more elaborate sample that demonstrates manipulations on source file

import clr
clr.AddReference('SAP.VE.Graphics.Interop')
clr.AddReference('SAP.VE.Graphics.Interop.Extensions')

import SAP.VE.Graphics.Interop as Interop
import SAP.VE.Graphics.Interop.NodeExtensions as NodeExtensions
import SAP.VE.Graphics.Interop.SceneExtensions as SceneExtensions
import SAP.VE.Generator.Graphics.Wrappers.Metadata

clr.ImportExtensions(SAP.VE.Graphics.Interop.SceneExtensions)
clr.ImportExtensions(SAP.VE.Graphics.Interop.NodeExtensions)

clr.ImportExtensions(System.Linq)


scene = Interop.Scene.LoadFromFile("C:\\SampleFile.vds")
if scene:
	with Interop.MataiDirect(scene) as matai:
    	nodes = scene.AllNodes().Where(lambda n: n.Name == "Truck Deck");
    	for node in nodes:
        	success = node.RemoveMetadata(matai, "CADMetadata", "Part Number", NodeExtensions.RemoveAction.RemoveCategoryIfEmpty, Interop.Metadata.ObjectType.Entity); 
	        node.ChangeMetadataValue(matai, "CADMetadata", "InstanceName", "test value");
    	    node.AddMetadataValue(matai, "CADMetadata", "Part Custom Number", "test value");
        	node.AddMetadataValue(matai, "test category", "test key", "test value");
	        sap.log.warning("MSG: node name:'%s' " % (node.Name))
    	# nodes need to be reacquired because the scene has been rebuilt (all previous node references are invalidated)
	    nodes = scene.AllNodes().Where(lambda n: n.Name == "Truck Deck");
    	# check that the metadata has been added to the GCore scene
	    for node in nodes:
    	   metadata = node.GetExtendedMetadataCategoryKeyValue("test category", "test key");
	       sap.log.warning("MSG: got metadata: '%s' " % (metadata))

    	nodes = scene.AllNodes().Where(lambda n: n.Name == "Remove.1");
	    for node in nodes:
    	    node.RemoveMetadata(matai, "CADMetadata", "Part Number");
        	node.AddMetadataValue(matai, "CADMetadata", "Part Custom Number", "test value", NodeExtensions.AddAction.AddCategoryIfNotExist, Interop.Metadata.Type.String, Interop.Metadata.ObjectType.Element);
	        node.AddMetadataValue(matai, "test category", "test key", "test value", NodeExtensions.AddAction.AddCategoryIfNotExist, Interop.Metadata.Type.String, Interop.Metadata.ObjectType.Element);

    	nodes = scene.AllNodes().Where(lambda n: n.Name == "RectPattern.2");
	    for node in nodes:
    	    node.RemoveMetadata(matai, "CADMetadata", "Part Number");
        	node.AddMetadataValue(matai, "CADMetadata", "Part Custom Number", "test value", NodeExtensions.AddAction.AddCategoryIfNotExist, Interop.Metadata.Type.String, Interop.Metadata.ObjectType.Element);
	        node.AddMetadataValue(matai, "test category", "test key", "test value", NodeExtensions.AddAction.AddCategoryIfNotExist, Interop.Metadata.Type.String, Interop.Metadata.ObjectType.Element);

    	nodes = scene.AllNodes().Where(lambda n: n.Name == "Shock Absorber1");
	    for node in nodes:
    	    node.SetClosed(matai, True);

	    nodes = scene.AllNodes().Where(lambda n: n.Name == "Shock Absorber2");
    	for node in nodes:
        	node.SetVisibility(matai, False);
	        node.SetName(matai, "New Name");


	scene.Save("C:\\SampleFile_modified.vds");
	scene.Close()
else:
	sap.log.warning("File not found or corrupted");












  • No labels