Simplify hand pose definitions. Cache analyzed hand pose data for use across multiple poses in a pose set. (#3)

Author: Malcolmnixon

README.md

@@ -54,22 +54,11 @@ New hand poses can be made by creating new Hand Pose Resource instances.
 Hand Pose Resources consist of:
 * A Pose Name (reported in the pose detector signals)
 * A Threshold (a minimal fitness threshold to report the pose)
-* An array of Hand Pose Rules
+* A set of fitness functions to apply to each pose component
 
-### Hand Pose Rules
+### Pose Components
 
-![Hand Pose Rule](/docs/hand_pose_rule.png)
-
-Hand Pose Rules consist of:
-* A Rule Name (useful for tuning and debugging)
-* A Rule Type [Flexion, Curl, Abduciton, and Tip-Distance]
-* A Finger
-* A second Finger (for Abduction and Tip-Distance)
-* Fitness Function Terms (min, lower, upper, max)
-
-### Rule Types
-
-| Rule | Description |
+| Type | Description |
 | :--- | :---------- |
 | Flexion | The angle (in degrees) of a fingers proximal joint curving into the palm to make a fist. |
 | Curl | The curl (in degrees) of a finger from the proximal to the distal joints. |
@@ -78,10 +67,25 @@ Hand Pose Rules consist of:
 
 ### Fitness Function
 
-Each rule produces a measurement in either degrees or millimeters. This measurement is translated to a fitness value in the range 0..1 using a transform defined by the fitness function terms. Values outside of the min/max range have a fitness of 0. Values inside the lower/upper range have a fitness of 1, and min-lower and upper-max are connected by a smoothstep function:
-![Fitness Transform](/docs/fitness-transform.png)
+The fitness function converts a measurement (degrees or milimeters) into a fitness in the range 0..1 with 0 being a bad match, and 1 being a perfect match. Two types of fitness function are supported:
+* Smoothstep
+* Range
+
+The fitness of a Hand Pose is the product of the fitness of all the components.
+
+#### Smooth-Step Function
+
+The Smooth-Step function transitions from 0 to 1 over the specified range. The paramerters may be reversed to reverse the function.
+
+![SmoothStep Positive](/docs/smootstep_positive.png)
+![SmoothStep Negative](/docs/smootstep_negative.png)
+
+#### Range Function
+
+The Range function provides non-zero values in a finite range.
+
+![Fitness Transform](/docs/range_function.png)
 
-The fitness of a Hand Pose is the product of the fitness of all the rules.
 
 ## Designing and Tuning
 

VERSIONS.md

@@ -1,5 +1,6 @@
 # 1.1.0
 - Moved fitness function to separate resource
+- Simplified hand resource definition
 
 # 1.0.0
 - Initial Revision

addons/hand_pose_detector/hand_info.gd

@@ -15,38 +15,104 @@ extends Resource
 ## Detection threshold
 @export_range(0.0, 1.0) var threshold : float = 0.5
 
-## Array of hand pose rules
-@export var rules : Array[HandPoseRule] = []
+# Flexion group
+@export_group("Flexion", "flexion_")
 
-## Rules validated
-var _validated := false
+## Flexion Thumb Function
+@export var flexion_thumb : FitnessFunction
+
+## Flexion Index Function
+@export var flexion_index : FitnessFunction
+
+## Flexion Middle Function
+@export var flexion_middle : FitnessFunction
+
+## Flexion Ring Function
+@export var flexion_ring : FitnessFunction
+
+## Flexion Pinky Function
+@export var flexion_pinky : FitnessFunction
+
+# Curl group
+@export_group("Curl", "curl_")
+
+## Curl Thumb Function
+@export var curl_thumb : FitnessFunction
+
+## Curl Index Function
+@export var curl_index : FitnessFunction
+
+## Curl Middle Function
+@export var curl_middle : FitnessFunction
+
+## Curl Ring Function
+@export var curl_ring : FitnessFunction
+
+## Curl Pinky Function
+@export var curl_pinky : FitnessFunction
+
+# Abduction group
+@export_group("Abduction", "abduction_")
+
+## Abduction Thumb-Index Function
+@export var abduction_thumb_index : FitnessFunction
+
+## Abduction Index-Middle Function
+@export var abduction_index_middle : FitnessFunction
+
+## Abduction Middle-Ring Function
+@export var abduction_middle_ring : FitnessFunction
+
+## Abduction Ring-Pinky Function
+@export var abduction_ring_pinky : FitnessFunction
+
+# Tip-distance group
+@export_group("Tip-Distance", "distance_")
+
+## Tip-Distance Thumb-Index Function
+@export var distance_thumb_index : FitnessFunction
+
+## Tip-Distance Thumb-Middle Function
+@export var distance_thumb_middle : FitnessFunction
+
+## Tip-Distance Thumb-Ring Function
+@export var distance_thumb_ring : FitnessFunction
+
+## Tip-Distance Thumb-Pinky Function
+@export var distance_thumb_pinky : FitnessFunction
 
 
 ## Returns a fitness value in the range 0..1 as to how well the [param hand]
 ## matches the hand pose rules.
-func get_fitness(hand : XRHandTracker) -> float:
-	# Fail if no rules
-	if rules.size() == 0:
-		return 0
-
-	# Perform rule validation on first use
-	if not _validated:
-		_validated = true
-		if pose_name == "":
-			push_warning("Hand Pose: %s name not specified" % resource_path);
-		if threshold <= 0.0:
-			push_warning("Hand Pose: %s invalid threshold" % pose_name)
-		for r in rules:
-			var warnings = r.get_warnings()
-			if warnings.size() > 0:
-				push_warning("Hand Pose: %s rule issues" % pose_name)
-				for w in warnings.size():
-					push_warning("  Rule %d: %s" % [w, warnings[w]])
-
+func get_fitness(hand : HandPoseData) -> float:
 	# Process the fitness of all rules
 	var fitness := 1.0
-	for r in rules:
-		fitness *= r.get_fitness(hand)
+
+	# Apply flexion rules
+	if flexion_thumb:  fitness *= flexion_thumb.calculate(hand.flx_thumb)
+	if flexion_index:  fitness *= flexion_index.calculate(hand.flx_index)
+	if flexion_middle: fitness *= flexion_middle.calculate(hand.flx_middle)
+	if flexion_ring:   fitness *= flexion_ring.calculate(hand.flx_ring)
+	if flexion_pinky:  fitness *= flexion_pinky.calculate(hand.flx_pinky)
+
+	# Apply curl rules
+	if curl_thumb:  fitness *= curl_thumb.calculate(hand.crl_thumb)
+	if curl_index:  fitness *= curl_index.calculate(hand.crl_index)
+	if curl_middle: fitness *= curl_middle.calculate(hand.crl_middle)
+	if curl_ring:   fitness *= curl_ring.calculate(hand.crl_ring)
+	if curl_pinky:  fitness *= curl_pinky.calculate(hand.crl_pinky)
+
+	# Apply abduction rules
+	if abduction_thumb_index:  fitness *= abduction_thumb_index.calculate(hand.abd_thumb)
+	if abduction_index_middle: fitness *= abduction_index_middle.calculate(hand.abd_index)
+	if abduction_middle_ring:  fitness *= abduction_middle_ring.calculate(hand.abd_middle)
+	if abduction_ring_pinky:   fitness *= abduction_ring_pinky.calculate(hand.abd_ring)
+
+	# Apply tip-distance rules
+	if distance_thumb_index:  fitness *= distance_thumb_index.calculate(hand.dst_index)
+	if distance_thumb_middle: fitness *= distance_thumb_middle.calculate(hand.dst_middle)
+	if distance_thumb_ring:   fitness *= distance_thumb_ring.calculate(hand.dst_ring)
+	if distance_thumb_pinky:  fitness *= distance_thumb_pinky.calculate(hand.dst_pinky)
 
 	# If the fitness is below the threshold then fail
 	if fitness < threshold: