Scripting and Batch mode

Table of Contents

• Overview
• Running a script
• Writing a script
  • Basic functionalities
  • Accessing model metadata and geometry
• Batch mode
  • Examples
    • Target creation
    • Physics based positioning
• PIPER Python packages

Overview

The scripting capabilities of the PIPER application let the user insert custom operation in his workflow by Writing a script. It is also possible to run complete workflows from scripts, this is the so called Batch mode. The scripts are written in Python 2.7, see PIPER Python packages for a reference of the PIPER specific python API.

Running a script

From the Scripting menu any python script can be run at any time. If the script expects parameters, they can be specified in a space separated list. A list of standard script is provided with the application (they are located in share/python/scripting). Additionnaly the user can set a custom script folder from which the python scripts are listed.

Running a python script with arguments

Writing a script

Using the provided piper python packages, the user can access and modify the current application model, metadata and targets. The following example are available in the share/example/scripting folder.

Basic functionalities

The traditional Hello world ! example (in helloWorld.py):

# Simple hello-world script

# access PIPER application functions
import piper.app

piper.app.logInfo("Hello World !")

A script which manipulates its arguments (in sum.py) :

# Compute the sum a + b
#
# arguments:
#  a b

import sys

# access PIPER application functions
import piper.app

def computeSum(a, b):
    piper.app.logInfo("a+b = {0}".format(a+b))

if (3 != len(sys.argv)):
    raise RuntimeError("Invalid arguments")
else :
    computeSum(float(sys.argv[1]), float(sys.argv[2]))

Accessing model metadata and geometry

The following example shows how to access the current model and metadata, and also query the anatomy database. The script computes the vertebrae centroids and print the result in the application log (in vertebraeCentroid.py) :

# Compute the centroid of each vertebra and print it in the application log

# numpy is a standard package for matrix manipulation
import numpy

# access PIPER human body model functionnalities
import piper.hbm
# access anatomy database functionnalities
import piper.anatomyDB
# access PIPER application functions
import piper.app

model = piper.app.Context.instance().project().model()

# if the model is empty, we can do nothing
if (model.empty()):
    piper.app.logWarning("Model is empty")
else:
    # get metadata and fem from the current project
    metadata = piper.app.Context.instance().project().model().metadata()
    fem = piper.app.Context.instance().project().model().fem()
    for (name,entity) in metadata.entities().iteritems() :
        # check if this entity is a vertebrae
        if piper.anatomyDB.isEntityPartOf(name, "Vertebral_column", True):
            piper.app.logInfo("{0}: {1}".format(name, computeCentroid(entity, fem)))

# compute the centroid of an entity
def computeCentroid(entity, fem):
    c = numpy.zeros((3,1)) # initialize the centroid, notice the (3,1) shape for a vector
    envelopNodesId = entity.getEnvelopNodes(fem)
    for id in envelopNodesId :
         c += fem.getNode(id).get()
    return (c / len(envelopNodesId)).flatten()

The following example shows how to export the currently selected nodes and elements to an external .obj file (in exportSelectedGeometryToObj.py).

# This script exports the current selected geometry (nodes + triangles)
# It also writes a json file which stores correspondances between obj vertices and piper nodes id
# for further update with updateNodesFromObj.py script
# 
# arguments:
#  /path/to/mesh.obj

# author: Thomas Lemaire date: 2017

import sys
import json

import piper.hbm
import piper.app

def writeObj(fem, nodeIds, elem2DIds, objFilePath):
    # gather node ids from nodes and elements
    allNodeIds = set()
    for id in nodeIds:
        allNodeIds.add(id)
    for elemId in elem2DIds:
        elem = fem.getElement2D(elemId)
        if not elem.getType() in {piper.hbm.ELT_TRI, piper.hbm.ELT_QUAD}:
            piper.app.logWarning("Unsupported: elem: {0} type: {1}".format(elemId, elem.getType()))
            continue
        ids = elem.get()
        for id in ids:
            allNodeIds.add(id)
    # in an obj file, vertices are referenced by their index, starting at 1, to describe faces
    nodeIdToObjIndex = dict()
    objIndexToNodeId = dict()
    with open(objFilePath, 'w') as objFile:
        piper.app.logInfo("Writting obj file {0} ...".format(objFilePath))
        objFile.write("# File generated by the PIPER application\n")
        currentIndex = 1 # obj convention starts at 1
        for nodeId in allNodeIds:
            nodeIdToObjIndex[nodeId] = currentIndex
            objIndexToNodeId[currentIndex] = nodeId
            coord = fem.getNode(nodeId).get().flatten()
            objFile.write("v {0} {1} {2}\n".format(coord[0], coord[1], coord[2]))
            currentIndex+=1
        for elemId in elem2DIds:
            elem = fem.getElement2D(elemId)
            ids = elem.get()
            if elem.getType() == piper.hbm.ELT_QUAD:
                idsQuad = elem.get()
                objFile.write("f {0} {1} {2}\n".format(nodeIdToObjIndex[idsQuad[0]], nodeIdToObjIndex[idsQuad[1]], nodeIdToObjIndex[idsQuad[2]]))
                objFile.write("f {0} {1} {2}\n".format(nodeIdToObjIndex[idsQuad[0]], nodeIdToObjIndex[idsQuad[2]], nodeIdToObjIndex[idsQuad[3]]))
                continue
            elif elem.getType() == piper.hbm.ELT_TRI:
                objFile.write("f {0} {1} {2}\n".format(nodeIdToObjIndex[ids[0]], nodeIdToObjIndex[ids[1]], nodeIdToObjIndex[ids[2]]))
            else:
                continue
    objIdFilePath = objFilePath+".json"
    with open(objIdFilePath, 'w') as objIdFile:
        piper.app.logInfo("Writting obj id file {0} ...".format(objIdFilePath))
        json.dump(objIndexToNodeId, objIdFile)

model = piper.app.Context.instance().project().model()

# if the model is empty, we can do nothing
if model.empty():
    piper.app.logWarning("Model is empty")
elif 2 != len(sys.argv) :
    raise RuntimeError("Invalid arguments")
else :
    modelVTK = model.fem().getFEModelVTK()
    nodeIds = modelVTK.getSelectedNodes()
    elem2DIds = modelVTK.getSelectedElements(2)
    piper.app.logInfo("nb selected nodes: {0}".format(len(nodeIds)))
    piper.app.logInfo("nb selected elements: {0}".format(len(elem2DIds)))
    writeObj(model.fem(), nodeIds, elem2DIds, sys.argv[1])
    
    

The following example shows how to export entities nodes id in FE code and coordinate (in exportEntitiesNodesCoordinates.py)

# Export nodes coordinates from a model in history
# 
# arguments: 
#   /path/to/export/directory [history name]

import os
import os.path
import shutil
import exceptions

import piper.hbm
import piper.app

model = piper.app.Context.instance().project().model()

# if the model is empty, we can do nothing
if model.empty():
    piper.app.logWarning("Model is empty")
elif not ( len(sys.argv) in {2,3} ) :
    raise RuntimeError("Invalid arguments")
else :
    exportDirectory = sys.argv[1]
    
    # setup model in history
    originalHistory = None
    if len(sys.argv) == 3:
        originalHistory = model.history().getCurrent()
        model.history().setCurrentModel(sys.argv[2])
        
    shutil.rmtree(exportDirectory, ignore_errors=True)
    os.makedirs(exportDirectory)
    metadata = model.metadata()
    fem = model.fem()
    piperIdToIdKey = fem.computePiperIdToIdKeyMapNode();
    for (name,entity) in metadata.entities().iteritems() :
        ids = entity.getEntityNodesIds(fem)
        datFilePath = os.path.join(exportDirectory, name+".dat")
        piper.app.logInfo("Export {0} nodes from entity {1} to {2}".format(len(ids), name, datFilePath))
        with open(datFilePath, 'w') as datFile:
            datFile.write("# Entity {0}\n".format(name))
            datFile.write("# Id x y z\n")
            for nodeId in ids:
                coord = fem.getNode(nodeId).get().flatten()
                datFile.write("{0} {1} {2} {3}\n".format(piperIdToIdKey[nodeId].id, coord[0], coord[1], coord[2]))
    
    # restore model in history
    if not originalHistory is None:
        model.history().setCurrentModel(originalHistory)

TODO: examples with target creation, TODO: example with data preparation saved to (octave) file, running octave, reading output and preparing targets TODO: doc for piper.app, piper.hbm and piper.anatomydb python packages

Batch mode

The batch mode enable the user to prepare scripts to run at once a sequence of operations. The functions available in batch mode includes Project read/write, import/export, target read/write and modification, module parameters modification and access to PIPER Modules Overview.

The batch mode is started with:

$ piper --batch my_script.py

More options are available, refer to "piper --help" output.

Examples

Target creation

import math

import piper.app
import piper.hbm
import piper.test

target = piper.hbm.TargetList()

target.add(piper.hbm.FixedBoneTarget("Pelvic_skeleton"))

leftASISTarget = piper.hbm.LandmarkTarget()
leftASISTarget.setName("Pelvis_position_1")
leftASISTarget.setUnit(piper.hbm.Length_m)
leftASISTarget.landmark = "Left_ASIS"
leftASISTarget.setValue({0:0.3, 1:1.2, 2:-0.25})
target.add(leftASISTarget)

piper.test.expect_eq(piper.hbm.Length_m, leftASISTarget.unit(), "Error during target creation")

hipTarget = piper.hbm.JointTarget()
hipTarget.setName("Hip_position")
hipTarget.setUnit(piper.hbm.Length_dm)
hipTarget.joint="Left_hip_joint"
hipTarget.setValue({4:math.radians(45)})
target.add(hipTarget)

piper.test.expect_eq(piper.hbm.Length_dm, hipTarget.unit(), "Error during target creation")

headTarget = piper.hbm.FrameToFrameTarget()
headTarget.setName("Head_position")
headTarget.frameSource = "W_Origin"
headTarget.frameTarget = "B_Skull"
headTarget.setUnit(piper.hbm.Length_mm)
headTarget.setValue({0:200})
target.add(headTarget)

piper.test.expect_eq(4, target.size(), "Error during target creation")

Physics based positioning

import os.path
import math

import piper.app
import piper.hbm

project = piper.app.Project()

# save Child
chilpProjectFile = os.path.join(piper.app.tempDirectoryPath(), "child.ppj")
#chilpProjectFile = os.path.join("/local2/build/piper-release/child.ppj")
project.read(chilpProjectFile)

project.moduleParameter().setInt("PhysPosi","autoStopNbIterationMax", 100)
project.moduleParameter().setFloat("PhysPosi", "autoStopVelocity", 1e-7)
project.moduleParameter().setFloat("PhysPosi","voxelSize", 0.01)

target = piper.hbm.TargetList()

target.add(piper.hbm.FixedBoneTarget("Pelvic_skeleton"))

hipTarget = piper.hbm.JointTarget()
hipTarget.setName("Hip_position")
hipTarget.joint="Left_hip_joint"
hipTarget.setValue({4:math.radians(45)})
target.add(hipTarget)

headTarget = piper.hbm.FrameToFrameTarget()
headTarget.setName("Head_position")
headTarget.setUnit(piper.hbm.Length_mm)
headTarget.frameSource = "W_Origin"
headTarget.frameTarget = "B_Skull"
headTarget.setValue({0:200})
target.add(headTarget)

piper.app.physPosiDeform(project, target)

PIPER Python packages

The PIPER specific functions are made available in batch thanks to several Python packages :

• application Context, Project manipulation, logging functions and more: Python package piper.app
• access HBM data, Metadata, Target and more: Python package piper.hbm
• access anatomy database queries and anatomical frames computation: Python package piper.anatomyDB