Adding blend shapes

Let's open the man.ma file (you can find this file inside the data folder of your Atoms installation) and duplicate the man body, then edit the mesh to create a facial expression.

Select the mesh and the original body, then create a blend shape deformer.

Exporting meshes

You need to export the blend shapes target. If you use the variation builder, Atoms automatically exports the blend shapes data inside the meshes.

If you want export them manually, open the atoms mesh exporter from the atoms menu: Atoms > Export > Mesh exporter

Set the output path, then turn on the "export skin weight option". Inside the skeleton path file, pick the man.atomsskel from the AtomsMaya/data folder (or the file you exported previously). Then select the Hips joint and press the refresh button. Finally turn on the "export blend shapes" option, select the mesh you want to export and press the "Export" button. This tool automatically writes points, normals, id and name of each target inside the mesh file.

import AtomsCore
mesh_file = "bodyBlendshape.geos"
ark = AtomsCore.Archive()
if ark.readFromFile(mesh_file):
    mesh = AtomsCore.MapMetadata()
    mesh.deserialise(ark)
    for geo in mesh.keys(): #iterate over each geo
        targets_data = mesh[geo]["blendShapes"]
        for i in range(len(targets_data)):
            target = targets_data[i]
            points = target["P"].value()
            normals = target["N"].value()
            id = target["id"].value()
            name = target["name"].value()
            print id, name

Importing meshes

Create a new scene and import the man variation table. From the atoms menu execute Atoms > Variations > Import variation json. Select the variation json file from the folder where you exported it previously. This will load the man variation table into the scene.

Open the variation manager from the atoms menu: Atoms > Variations > Agents Variation Manager. Select "man" from the column on the left and then go inside the Geometry tab. Replace the body_GEO path with the mesh you just exported. Now press ctrl+s or from the widget menu execute File > Register to Atoms to save the changes.

Setting up variations

• Create and agent group node.
• Add a grid layout and set the grid size to 4,0,4
• Add a state machine module
• Add a variation module and set the variationName attribute to "variation1"
• Change the display type to variations

Setting targets weight

The targets weight are controlled by double metadatas. The metadata name should follow this convention:

AgentTypeName_VariationGeometryName_TargetIndex

In our case the following metadata is a valid name:

• man_body_GEO_0

The target index is the order used by the Maya blend shape deformer, so the 0 index is the first blend shape, the 1 index is the second one and so on.

We can add and control these metadatas using the AddMetadata module

• Add an "AddMetadata" behaviour module
• Set the name attribute to man_body_GEO_0
• Set the type attribute to double
• Set the double value attribute to 1.0

If you have more blendshapes, you can add more addMetadata modules on the same agent group to control them. You can also add keyframes on the doubleValue attribute to animate the blend shapes.

Blend shape manager

Blend shapes can be handled more easily with the blend shape manager module.

Remove all your addMetadata modules and add a "blendShapeManager" module to your agent group. In blendShapeManager options click on the "Manage Blend Shapes" button, the UI on the right will be prompted.

From there you will be able to select the blend shapes you want to add to the agent group. 

You can select/deselect blend shapes by double clicking or using the button on the top of the list. 
Please be careful when clicking the "Expand" buttons as it could take some time to populate the entire tree if you have a lot of variation geos.

Click on the tick button on the bottom right corner, the blend shapes will now be visible under the blendShapeManager options where you will be able to animated them.

Adding animation

To add more complex animation or animation cycles to the blend shapes we can use the blendShapesAnim module. Before you can use this module, you have to export some animation curves from your setup scene. Open the man scene where you created the blendshapes and add some keyframes on the target weights of the blend shape deformer.

Now select the man head and open the blend shapes anim exporter from the atoms menu: Atoms > Export > Blend shapes anim exporter.

Set the output path and the frame range, select the head mesh and press the run button.

Go back to the atoms scene and remove the blendShapeManager module.

Add a blendShapesAnim behaviour module and click on the "Manage Animations" button under the blendShapeAnim tab.

Cilck on the "+" button for adding a new animation, select the "body_GEO" in the Geo field and set the path to the animation file we just exported. Leave the property to loop (no property will just play the blend shapes animation once).
You can of course add multiple animations, but we are going to stick with one for this example.

Click on the tick button.

Press play and you will see the blendshapes being animated in a loop inside the viewport.

Click on the "Manage Animations" button again and activate the "Enable Trigger Metadata" checkbox. Type "triggerAnim" as name for your metadata.

Create an addMetadata module and place it before the blendShapesAnim module. Set the name attribute to triggerAnim. change the type to double and set the doubleValue to 1.0.

Now rewind the scene and press play, the result will be exactly as before.

Let's use an area trigger to drive the metadata.

First let's change the agent state to 1 inside the state machine to make them walk. Inside the addMetadata module change the double value to 0 (the area trigger module will drives this value) and activate the "Agent Creation Only" option. Now create an areaTrigger module and create a plane in the scene. Connect the plane to the areaTrigger module and set the metadata name attribute to triggerAnim, the double value to 1.0, the blend in and out to 10 and the random delay in and out to 5. Move the area trigger above the blendShapeAnim module. Rewind the scene and press play.