User Configurable Metrics - PerkTutor/PerkEvaluator GitHub Wiki

To improve the flexibility of the Perk Evaluator, user may define their own metrics, without needing to modify the Perk Evaluator source code. The Perk Evaluator can calculate these user-defined metrics automatically and in real-time. A collection of common user-defined metrics is available: Download metrics (unzip the folder prior to use).

Python Metric Script Interface

Each user-configurable metric must be defined in a single python script and follow the template below. The class must define all of these methods. See http://www.github.com/PerkTutor/PythonMetrics for examples.

# Class name must be "PerkEvaluatorMetric" for all metrics
class PerkEvaluatorMetric:

  def __init__( self ):
    # Constructor
    # Any anatomy-independent initialization should be done here
  
  @staticmethod
  def GetMetricName():
    # Return the name of the metric (string)
    
  @staticmethod
  def GetMetricUnit():
    # Return the unit of the metric (string)
    
  @staticmethod
  def GetAcceptedTransformRoles():
    # Return a list of strings indicating the transform roles accepted by the metric
    # Metric will only be computed for the transform roles which it accepts
    
  @staticmethod
  def GetRequiredAnatomyRoles():
    # Return a dictionary of strings indicating the anatomy roles required by the metric and allowable node types
    # Metric will only be calculated if all of the anatomy roles it requires are fulfilled

  def AddAnatomyRole( self, role, node ):
    # This function should be used to add anatomy nodes to the metric for computation
    # role is a string indicating the role the anatomy node should fulfill
    # node is a vtkMRMLNode which plays the role of an anatomy
    
  def AddTimestamp( self, time, matrix, point ):
    # What to do every time a new time and matrix is added
    # time is the timestamp associated with the matrix
    # matrix is a vtkMatrix4x4 that is the current tool transform
    # point is a four element vector containing the tool position in first three elements (for convenience)
    
  def GetMetric( self ):
    # Return the metric value (double or string)

Initial Discussion

@ungi, @mholden8 on Sep 30, 2013

• Could use a plugin mechanism where the user creates a python script to compute metric: get transform buffer from the Perk Evaluator logic, calculate metric, return result to Perk Evaluator logic (which can output to the metrics table)
• This mechanism is possibly slower than current metric calculation
• Using the Matlab Bridge extension, these scripts could also be written in Matlab
• Short-term: Copy and paste script in python interactor, and produce result there
• Medium-term: Let user select a folder from which scripts for metric calculation can be read
• Long-term: Move "core" metrics to python scripts and include them with the Perk Tutor by default

Pre-Commit Discussion

@ungi, @mholden8 on Dec 10, 2013

• User configurable metrics written in python scripts can now be added (user must select folder storing python script files)
• Default metrics are calculated on their own
• Python metric scripts are not distributed with the PerkTutor - users are responsible for creating/copying scripts on their own (see http://www.github.com/PerkTutor/PythonMetrics for example python metric scripts)