This PR adds debouncing to poses. (#8)

Author: Malcolmnixon

README.md

@@ -67,6 +67,8 @@ 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)
+* A Hold Time (a debounce time necessary to register the pose)
+* A Release Time (a debounce time necessary to release the pose)
 * A set of fitness functions to apply to each pose component
 
 
@@ -106,7 +108,7 @@ The Range function provides non-zero values in a finite range.
 
 ## Designing and Tuning
 
-The inspect scene provided in the demo project can be used to inspect the flexion, curl, abduction, and tip-distance of a hand, and can also inspect a selected hand pose to diagnose the fitness of the rules.
+The inspect scene provided in the demo project can be used to inspect the flexion, curl, abduction, and tip-distance of a hand, and can also inspect a selected hand pose to diagnose the fitness of each component.
 
 ![Inspect Scene](/docs/inspect_scene.png)
 

VERSIONS.md

@@ -1,5 +1,6 @@
-# 1.2.0
+# 1.2.0 (in progress)
 - Added hand pose controller capable of generating XR input actions
+- Added debounce hold and release times for poses
 
 # 1.1.0
 - Moved fitness function to separate resource

addons/hand_pose_detector/hand_pose.gd

@@ -15,6 +15,12 @@ extends Resource
 ## Detection threshold
 @export_range(0.0, 1.0) var threshold : float = 0.5
 
+## Hold time before pose is detected
+@export_range(0.01, 1.0) var hold_time : float = 0.2
+
+## Release time before pose is lost
+@export_range(0.01, 1.0) var release_time : float = 0.2
+
 # Flexion group
 @export_group("Flexion", "flexion_")
 

addons/hand_pose_detector/hand_pose_controller.gd

@@ -99,7 +99,7 @@ func _get_configuration_warnings() -> PackedStringArray:
 
 
 # Handle start of pose
-func _pose_started(p_name : String, _fitness : float) -> void:
+func _pose_started(p_name : String) -> void:
 	# Skip if no tracker or action set
 	if not tracker or not action_set:
 		return

addons/hand_pose_detector/hand_pose_detector.gd

@@ -9,10 +9,7 @@ extends Node
 
 
 ## Signal reported when a hand pose starts
-signal pose_started(p_name : String, p_fitness : float)
-
-## Signal reported while a hand pose is in effect
-signal pose_update(p_name : String, p_fitness : float)
+signal pose_started(p_name : String)
 
 ## Signal reported when a hand pose ends
 signal pose_ended(p_name : String)
@@ -31,7 +28,16 @@ var tracker : XRHandTracker
 var _current_data : HandPoseData = HandPoseData.new()
 
 # Current hand pose
-var _current_pose : String = ""
+var _current_pose : HandPose
+
+# Current pose hold
+var _current_hold : float = 0.0
+
+# New hand pose
+var _new_pose : HandPose
+
+# New pose hold
+var _new_hold : float = 0.0
 
 
 # Customize the properties
@@ -42,7 +48,7 @@ func _validate_property(property: Dictionary) -> void:
 
 
 # Called every frame. 'delta' is the elapsed time since the previous frame.
-func _process(_delta: float) -> void:
+func _process(delta: float) -> void:
 	# Skip when running in the engine
 	if Engine.is_editor_hint():
 		return
@@ -57,24 +63,52 @@ func _process(_delta: float) -> void:
 		if not tracker:
 			return
 
+	# Save the active pose before updates (to report changes)
+	var active_pos := _current_pose
+
 	# Find the pose
 	_current_data.update(tracker)
 	var pose_match := hand_pose_set.find_pose(_current_data)
-	var pose : String = pose_match.pose
+	var pose : HandPose = pose_match.pose
 	var fitness : float = pose_match.fitness
 
-	# Handle pose changing
-	if pose != _current_pose:
-		# Report end of the current pose
-		if _current_pose != "":
-			pose_ended.emit(_current_pose)
-
-		# Report start of the new pose
-		if pose != "":
-			pose_started.emit(pose, fitness)
-
-		# Save the updated pose
-		_current_pose = pose
-	elif _current_pose != "":
-		# Report update of existing pose
-		pose_update.emit(_current_pose, fitness)
+	# Manage current pose
+	if _current_pose:
+		# Test if we detect the current pose
+		if pose == _current_pose:
+			# Restore hold on current pose
+			_current_hold = 1.0
+		else:
+			# Decay hold on current pose
+			_current_hold -= delta / _current_pose.release_time
+			if _current_hold <= 0.0:
+				# Current pose lost
+				_current_hold = 0.0
+				_current_pose = null
+
+	# Handle ramp of new pose
+	if pose != _new_pose:
+		# New pose detected
+		_new_pose = pose
+		_new_hold = 0.0
+	elif _new_pose:
+		# Ramp hold on new pose
+		_new_hold += delta / _new_pose.hold_time
+		if _new_hold >= 1.0:
+			# New pose "ready"
+			_new_hold = 1.0
+			if not _current_pose:
+				# No current pose, transition to new pose
+				_current_pose = _new_pose
+				_current_hold = 1.0
+
+	# Detect change in active pose
+	if _current_pose != active_pos:
+		# Report loss of old pose
+		if active_pos:
+			pose_ended.emit(active_pos.pose_name)
+
+		# Report start of new pose
+		active_pos = _current_pose
+		if active_pos:
+			pose_started.emit(active_pos.pose_name)

addons/hand_pose_detector/hand_pose_set.gd

@@ -16,13 +16,13 @@ extends Resource
 ## Returns the best pose for the specified [param hand].
 func find_pose(hand : HandPoseData) -> Dictionary:
 	# Search for the best pose
-	var best_pose := ""
-	var best_fitness := 0.0
+	var best_pose : HandPose = null
+	var best_fitness : float = 0.0
 	for p in poses:
 		var f := p.get_fitness(hand)
 		if f > best_fitness:
+			best_pose = p
 			best_fitness = f
-			best_pose = p.pose_name
 
 	# Return the best pose
 	return {

addons/hand_pose_detector/poses/fist.tres

@@ -79,6 +79,8 @@ max = 0.0
 script = ExtResource("2_ykawg")
 pose_name = "Fist"
 threshold = 0.3
+hold_time = 0.2
+release_time = 0.2
 flexion_thumb = SubResource("Resource_nb4va")
 flexion_index = SubResource("Resource_j5qa6")
 flexion_middle = SubResource("Resource_rmm3v")

addons/hand_pose_detector/poses/metal.tres

@@ -63,6 +63,8 @@ max = 0.0
 script = ExtResource("1_xil5d")
 pose_name = "Metal"
 threshold = 0.5
+hold_time = 0.2
+release_time = 0.2
 flexion_thumb = SubResource("Resource_h0roc")
 flexion_index = SubResource("Resource_gw741")
 flexion_middle = SubResource("Resource_pi16g")

addons/hand_pose_detector/poses/peace_sign.tres

@@ -71,6 +71,8 @@ max = 0.0
 script = ExtResource("2_k3pua")
 pose_name = "Peace Sign"
 threshold = 0.3
+hold_time = 0.2
+release_time = 0.2
 flexion_thumb = SubResource("Resource_21fsw")
 flexion_index = SubResource("Resource_0wa5f")
 flexion_middle = SubResource("Resource_dj0e2")

addons/hand_pose_detector/poses/point.tres

@@ -47,6 +47,8 @@ max = 0.0
 script = ExtResource("2_fvjog")
 pose_name = "Point"
 threshold = 0.3
+hold_time = 0.2
+release_time = 0.2
 flexion_index = SubResource("Resource_3xngl")
 curl_index = SubResource("Resource_5lwnk")
 curl_middle = SubResource("Resource_ni4th")

addons/hand_pose_detector/poses/point_thumb_up.tres

@@ -63,6 +63,8 @@ max = 0.0
 script = ExtResource("2_vgihw")
 pose_name = "Point Thumb Up"
 threshold = 0.3
+hold_time = 0.2
+release_time = 0.2
 flexion_thumb = SubResource("Resource_iey1r")
 flexion_index = SubResource("Resource_yunfv")
 curl_index = SubResource("Resource_ja5by")

addons/hand_pose_detector/poses/spock.tres

@@ -111,6 +111,8 @@ max = 0.0
 script = ExtResource("2_agcwt")
 pose_name = "Spock"
 threshold = 0.3
+hold_time = 0.2
+release_time = 0.2
 flexion_thumb = SubResource("Resource_o7ite")
 flexion_index = SubResource("Resource_vih3q")
 flexion_middle = SubResource("Resource_s4kcy")

addons/hand_pose_detector/poses/thumbs_up.tres

@@ -55,6 +55,8 @@ max = 0.0
 script = ExtResource("2_khw5p")
 pose_name = "ThumbsUp"
 threshold = 0.3
+hold_time = 0.2
+release_time = 0.2
 flexion_thumb = SubResource("Resource_p5lrn")
 curl_thumb = SubResource("Resource_tv1jx")
 curl_index = SubResource("Resource_p1kvp")

demo.gd

@@ -8,20 +8,14 @@ func _ready() -> void:
 		get_viewport().use_xr = true
 
 
-func _on_left_hand_pose_started(p_name: String, p_fitness: float) -> void:
-	$LeftHandLabel.text = "Left\n\n%s\n%0.2f" % [p_name, p_fitness]
-
-func _on_left_hand_pose_update(p_name: String, p_fitness: float) -> void:
-	$LeftHandLabel.text = "Left\n\n%s\n%0.2f" % [p_name, p_fitness]
+func _on_left_hand_pose_started(p_name: String) -> void:
+	$LeftHandLabel.text = "Left\n\n%s" % p_name
 
 func _on_left_hand_pose_ended(_p_name: String) -> void:
 	$LeftHandLabel.text = "Left"
 
-func _on_right_hand_pose_started(p_name: String, p_fitness: float) -> void:
-	$RightHandLabel.text = "Right\n\n%s\n%0.2f" % [p_name, p_fitness]
-
-func _on_right_hand_pose_update(p_name: String, p_fitness: float) -> void:
-	$RightHandLabel.text = "Right\n\n%s\n%0.2f" % [p_name, p_fitness]
+func _on_right_hand_pose_started(p_name: String) -> void:
+	$RightHandLabel.text = "Right\n\n%s" % p_name
 
 func _on_right_hand_pose_ended(_p_name: String) -> void:
 	$RightHandLabel.text = "Right"

demo.tscn

@@ -72,10 +72,8 @@ vertical_alignment = 0
 
 [connection signal="pose_ended" from="XROrigin3D/LeftTrackedHand/LeftHandPose" to="." method="_on_left_hand_pose_ended"]
 [connection signal="pose_started" from="XROrigin3D/LeftTrackedHand/LeftHandPose" to="." method="_on_left_hand_pose_started"]
-[connection signal="pose_update" from="XROrigin3D/LeftTrackedHand/LeftHandPose" to="." method="_on_left_hand_pose_update"]
 [connection signal="pose_ended" from="XROrigin3D/RightTrackedHand/RightHandPose" to="." method="_on_right_hand_pose_ended"]
 [connection signal="pose_started" from="XROrigin3D/RightTrackedHand/RightHandPose" to="." method="_on_right_hand_pose_started"]
-[connection signal="pose_update" from="XROrigin3D/RightTrackedHand/RightHandPose" to="." method="_on_right_hand_pose_update"]
 
 [editable path="XROrigin3D/LeftTrackedHand/LeftHandHumanoid"]
 [editable path="XROrigin3D/RightTrackedHand/RightHandHumanoid"]