DOCUMENT IT

script/calibrator.py

@@ -1,4 +1,6 @@
 #! /usr/bin/env python
+"""The script for calibrating the arm lengths and 'joystick' extents."""
+
 import os
 import json
 
@@ -12,6 +14,7 @@ from teleoperation.msg import RequestSpeechAction, RequestSpeechGoal
 
 
 def calib_field(sentences, src_frames, targ_frames):
+    """Retrieve a relative transform of some marker."""
     ok = False
     t_and_q = []
 
@@ -34,6 +37,7 @@ def calib_field(sentences, src_frames, targ_frames):
 
 
 def calib_center():
+    """Retrieve the coordinates of the 'joystick' zero state."""
     trans, q = calib_field([
         'Stand in front of camera',
         'Far enough to see your arms'
@@ -43,6 +47,7 @@ def calib_center():
 
 
 def calib_arms():
+    """Retrieve the hand positions relative to the chest."""
     ts_and_qs = calib_field(
         ['Now stretch your arms', 'Make sure the markers are detected'],
         ['odom'] * 3,
@@ -58,6 +63,7 @@ def calib_arms():
 
 
 def calib_shoulders():
+    """Retrieve the shoulder positions relative to the chest."""
     ts_and_qs = calib_field(
         ['Now place the markers on the corresponding shoulders',
          'Make sure the markers are detected'],
@@ -74,6 +80,7 @@ def calib_shoulders():
 
 
 def calib_rotation():
+    """Retrieve the limits of the z-axis of the 'joystick'."""
     rots = []
     for side in ('left', 'right'):
         _, q = calib_field(
@@ -86,6 +93,7 @@ def calib_rotation():
 
 
 def calib_extremes():
+    """Retrieve the limits of the x and y axes of the 'joystick'."""
     transs = []
     for direction in ('forward', 'backward', 'to the left', 'to the right'):
          trans, _ = calib_field(
@@ -100,6 +108,7 @@ def calib_extremes():
 
 
 def calibration():
+    """Run full calibration and dump the results to the config file."""
     center = calib_center()
     larm, rarm = calib_arms()
     lsh, rsh = calib_shoulders()