Golaem Simulation Cache Python API

Golaem Crowd is shipped with a SWIG generated glm.devkit Python module. It is strongly advised to use the API provided by this file to handle Golaem Simulation Cache data. As the Python module has been generated from the Golaem Simulation Cache C API, all structures listed in this page can be inspected in the C API.

Including Golaem Simulation Cache API file in a project

The Golaem Simulation Cache API can be added to a project, by importing the module:

from glm.devkit import * 

Using the API to load cache files, read and write data

Load an existing cache

Loading is done in 2 steps.

The first step is to load a GlmSimulationData from a gscs file. It will read shared data valid for all the cache frame, such as sizes and types. There is one gscs (simulation) file per CrowdField to load. These files are loaded via the command :

simulationData = createAndReadSimulationData('cacheFilePath/cacheFileName.gscs')
if (simulationData is not None):
    print('Success while opening Simulation Data file')

The command returns None on error.

Once a GlmSimulationData has been loaded, each frame data can be loaded via :

frameData = createFrameData(simulationData)
frameStatus = readFrameData(frameData, simulationData, 'cacheFilePath/cacheFileName.gscf')

The read command returns a status GSC_SUCCESS on success, or an error amongst:

GSC_SUCCESS No Error, everything went fine.
GSC_FILE_OPEN_FAILED File does not exist, or have access rights issues, or is already opened by another process
GSC_FILE_MAGIC_NUMBER_ERROR File header does not begin by 0x65CF or 0x65CF, this is not a Golaem Simulation Cache
GSC_FILE_VERSION_ERROR Incorrect version, could be a newer version of the Golaem Simulation Cache
GSC_FILE_FORMAT_ERROR Incorrect format, could be a newer version of the Golaem Simulation Cache
GSC_SIMULATION_FILE_DOES_NOT_MATCH The GlmSimulationData, used to read that frame file, does not match the one used at the export (the size of some items differ : entity count, etc.)

Accessing/Modifying Cache data

The cache data can be accessed and modified the following way:

getBonePositions(frameData)
getBoneOrientations(frameData)
getSnsValues(frameData)
getGeoBehaviorAnimFrameInfo(frameValue)
getPPFloatAttributeData(frameData)
getPPVectorAttributeData(frameData)

Those accessors return float array pointers which can be cast in a Python array the following way:

bonePos = []
bonePos.append(floatArray_frompointer(getBonePositions(frameData)))

Some accessors are also provided to help dealing with frame data

getEntityBoneCount(entityIndex, simulationData)
getEntityBoneOffsetIndex(entityIndex, simulationData)

Writing a cache 

Once cache data has been modified, it can be written back if required :

writeFrameData('cacheFilePath/cacheFileName.gscf', frameData, simulationData)

The write command returns a status GSC_SUCCESS on success, or an error from the above table

Clean-up allocated memory

Note that GlmFrameData can be kept allocated to edit several frames. Once done with reading./editing, each Simulation and frame data must be destroyed by calling the commands :

destroyFrameData(frameData, simulationData)

then

destroySimulationData(simulationData)

Basic usage sample code

simulationData = createAndReadSimulationData('cacheFilePath/cacheFileName.gscs')
if (simulationData is not None):
    print('Success while opening Simulation Data file')

frameData = createFrameData(simulationData)
if (readFrameData(frameData , simulationData, 'cacheFilePath/cacheFileName.gscf') == GSC_SUCCESS):
    print('Success while opening Frame Data file')
else:
    print('Error while opening Frame Data file')
    destroyFrameData(frameData, simulationData)
    destroySimulationData(simulationData)
    return


# get bone position array
bonePos = floatArray_frompointer(getBonePositions(frameData))

# set root bone height (Y) to 0
entityCount = simulationData._entityCount
for iEntity in xrange(0, entityCount ):
    # root bone is the first bone
    iBone = getEntityBoneOffsetIndex(iEntity, simulationData)
    # each position is made of 3 float (*3), and we access the Y (+1)
    bonePos[iBone * 3 + 1] = 0

# write frame data
if (writeFrameData('cacheFilePath/cacheFileName.gscf', frameData, simulationData) == GSC_SUCCESS):
    print('Success while writing Frame Data file')
 
# clean memory
destroyFrameData(frameData, simulationData)
destroySimulationData(simulationData)