Metadata

In Atoms, users can create and attach custom data to almost every entity available. We call this custom data "Metadata".
Atoms has already some predefined Metadata on most entities such as Agent Types, Animation Clips, etc. 
All the values explained in the previous sections for the Agent type (State Machine, Scale Multiplier) and Animation clip (Loop, Loop Start, Loop End, etc.) are metadata.

This custom data can be accessed and often tweaked at simulation time. 
For instance, you might want to tag a specific skeleton joint and access it via python or C++ or stick some custom metadata on an agent to define a specific behaviour.

The available Metadata types are String, Int, Double, Bool, Euler, Vector3, Vector4, Quaternion, Matrix,  Box3, Curve, Image and Mesh.
There's also an array type for all these metadata.
The most powerful metadata are the MapMetadata (a map container for mixed type of metadata) and the ArrayMetadata (a vector container for mixed type of metadata)

Metadata are most useful when used in conjunction with custom python and C++ Behaviour Modules.



Atoms Metadata

Below you can find a complete list of all metadata used by Atoms Crowd. Users might edit them during the simulation via python, C++ or using the available tools.
All metadata marked as "read only" should not be edited by the users or the editing might lead to unexpected behaviours. 


Clip metadata

nametypedescriptionread only
atomsBlendFramesAfterFootUpintThe number of frames used for blending after the foot leaves the ground.NO
atomsLoopboolTag the clip as loopable.NO
atomsLoopStartintThe start frame of the clip.NO
atomsLoopEndintThe end frame of the clip.NO
atomsNumBlendFramesintThe number of frames used for blending.NO

Agent metadata

nametypedescriptionread only
idintThe global id.YES
groupIdintThe local id (the id relative to this agent group).YES
groupNamestringThe local name.YES
directionvector3The agent target direction in world space.NO
prevDirectionvector3The agent direction before the initFrame stage.YES
frameRatedoubleThe frame rate used for playing the agent animation.NO
localDirectionvector3The agent direction in local space.YES
activeboolWhen false, the agent node graph is not evaluated.NO
positionvector3The agent position in world space.NO
scalevector3The agent scale. Only the x-axis value is used currently.NO
selectedboolThe agent selection state.NO
upvector3The agent up vector.NO
turnAnglevector3The current turn angle of the agent.YES
velocityvector3The current velocity in world space.YES
stateintThe state of the agent to be played by the state machineNO
animatedHfmap(for internal use only)YES
agentTypestringThe agent type nameYES
variationstringThe agent variationNO
cacheIdint(for internal use only)YES
retargetingFactordouble(for internal use only)YES
collectorDirectionsvector4array(for internal use only) YES
clothSetupOverridestringan override metadata for providing a different cloth setup file for an agentNO
disableIkboolDisable the ik and the foot lock during the simulationNO
disableFootLockboolDisable the foot lock during the simulationNO
disableDirectionboolWhen on, the agent the Directional behaviour modules won't affect this agent.NO
targetAgentIdintThe global agent id of the target agent, used by the followAgent module.NO
forceClipTransitionbool  Set to true if you want to trigger an agent out of a state at any time, not have to wait for a transition frameNO 
colorVariationintSets the diffuse color slot used for current variation material as specified in the scene variation tableNO
currentStateintCurrent state being playedYES

maxLegStretch

doubleThe multiplier on the leg length used as the maximum stretch factor by the pelvis operator during the feet adaptationNO
stateMachinestringThe state machine name. This metadata value overrides the state machine defined in the agent type.NO
onGroundbool Defines is the agent is on the ground or not.NO
animFrameRatedoubleThe frame rate used for playing the agent animation without modifying the pelvis velocity.NO
transitionBlendInFramesintIf this metadata is attached on an agent while the state machine is transitioning between two states this value is going to be used for as the number of blend-in frames.NO
transitionBlendOutFramesintIf this metadata is attached on an agent while the state machine is transitioning between two states this value is going to be used for as the number of blend-out frames.NO
locomotionActiveboolTrue when the agent is playing animation with locomotion, False otherwiseYES
targetLinearVelocitydoubleThe target linear velocity for the locomotionNO
targetAngularVelocitydouble The target angular velocity for the locomotionNO
footDownThresholddouble

The threshold used for checking if the foot is in foot down state, if not provided Atoms uses the default value of 0.95.

The foot down state is now stored in Atoms as a double (not a boolean anymore), for this reason when the foot down state is greater than the foot down threshold the foot is considered "down" and the foot locking system is activated.

NO
velocityOverridevector3An override for the velocity metadata. If provided and the useVelocityOverride metadata is set to True, then this velocity is used instead of the velocity coming from the animation
useVelocityOverrideboolWhen set to true, Atoms uses the velocityOverride instead of the velocity coming from the animation. The useVelocityOverride metadata is set to false at each frame after the pose is computed.

Agent type metadata

nametypedescriptioninternal only
lowGeomapThe low geo meshes.YES
skinGeomapThe skin geo meshes.YES
scaleMultiplierdoubleAgent type scale multiplier.NO
stateMachinestringThe state machine name.NO
boundingBoxboxThe agent type bounding box.YES

Joint metadata

nametypedescriptionread only
atoms_bindPoseScalevector3The joint bind pose scale.YES
atoms_bindPoseRotatevector3The joint bind pose rotation (Euler - XYZ order)YES
atoms_bindPoseTranslatevector3The joint bind pose translation.YES
atoms_footHeightdoubleThe foot height.YES
atoms_footIKboolFoot ik joint tag.YES
atoms_footIkHeightdoubleThe foot IK height.YES
atoms_footRootboolFoot root joint tag.YES
atoms_footOnGroundboolFoot down joint state.YES
atoms_frameToFootDownintNumbers of frame to next foot down.YES
atoms_groundNormalvector3The ground normal.YES
jointControlMappingmapParent for joint control mapping metadata. This data is used for the animation rig retargeting feature.YES
jointControlMappingMatrixmatrixThe offset matrix for the given joint.YES
jointControlMappingNamenameThe name of the control to retarget.YES
atoms_origBindPoseRotatevector3The joint original bind pose rotation (Euler - XYZ order)YES
atoms_origBindPoseScalevector3The joint original bind pose scale.YES
atoms_origBindPoseTranslatevector3The joint original bind pose translation.YES
atoms_pelvisHeightdoubleThe pelvis height.YES
atoms_pelvisLocalVelocityvector3The pelvis velocity in local space.YES
atoms_pelvisVelocityvector3The pelvis velocity in world space.YES
atoms_poleVectorvector3The ik pole vector.YES
atoms_propLocalTranslatevector3Prop translation in skeleton root space.YES
atoms_propLocalRotatevector3Prop rotation in skeleton root space.YES
atoms_propLocalScalevector3Prop scale in skeleton root space.YES
atoms_legLengthdoubleThe leg lengthYES
clipDirectionvector3The clip direction. This metadata has to be set on the pelvis root joint.NO
jointPerchingFactordoubleThe perching factor, only valid on the root jointNO
jointGlobalIKdoubleThe retargeting global Ik factor, only valid on the end joints of the limb IK chainsNO

Cloth metadata

nametypedescriptioninternal only
clothHideMeshboolHide cloth mesh at render timeNO
vertexPositionvector3arrayThe positions of a cloth meshYES
vertexNormalvector3arrayThe normals of a cloth meshYES
boundingBoxboxThe cloth bounding boxYES
stackOrderstringThe stack order of a cloth cache.YES

Copyright © 2017, Toolchefs LTD.