edits to original function and unit tests, added unit test for 180 degrees

Author: cgmaiorano

src/graphomotor/features/trails/drawing_metrics.py

@@ -2,6 +2,7 @@
 
 import numpy as np
 import pandas as pd
+from shapely import points
 
 from graphomotor.core import models
 
@@ -35,11 +36,11 @@ def get_total_errors(drawing: models.Drawing) -> dict[str, float]:
 
 
 def calculate_smoothness(points: pd.DataFrame) -> float:
-    """Calculate path smoothness based on curvature changes.
+    """Calculate path smoothness based on RMS curvature.
 
-    Lower values indicate smoother paths. This function calculates angles between
-    consecutive segments and returns the standard deviation of these angles as a
-    measure of smoothness.
+    Represants the curvature per unit arc length.
+    Lower values indicate smoother drawings. Penalizes sharp corners (e.g., 90° turns)
+    and noisy corrections. Normalized by arc length to reduce sampling-rate dependence.
 
     Args:
         points: DataFrame representing drawing points.
@@ -50,25 +51,29 @@ def calculate_smoothness(points: pd.DataFrame) -> float:
     if len(points) < 3:
         return 0.0
 
-    x = points["x"].values
-    y = points["y"].values
+    xy = points[["x", "y"]].to_numpy()
 
-    angles = []
-    for i in range(1, len(x) - 1):
-        v1 = np.array([x[i] - x[i - 1], y[i] - y[i - 1]])
-        v2 = np.array([x[i + 1] - x[i], y[i + 1] - y[i]])
+    v1 = xy[1:-1] - xy[:-2]
+    v2 = xy[2:] - xy[1:-1]
 
-        if np.linalg.norm(v1) == 0 or np.linalg.norm(v2) == 0:
-            continue
+    l1 = np.linalg.norm(v1, axis=1)
+    l2 = np.linalg.norm(v2, axis=1)
 
-        v1 = v1 / np.linalg.norm(v1)
-        v2 = v2 / np.linalg.norm(v2)
+    valid = (l1 > 0) & (l2 > 0)
+    if not np.any(valid):
+        return 0.0
 
-        cos_angle = np.clip(np.dot(v1, v2), -1.0, 1.0)
-        angle = np.arccos(cos_angle)
-        angles.append(angle)
+    v1 = v1[valid]
+    v2 = v2[valid]
+    l1 = l1[valid]
+    l2 = l2[valid]
 
-    if not angles:
-        return 0.0
+    cos_angle = np.einsum("ij,ij->i", v1, v2) / (l1 * l2)
+    cos_angle = np.clip(cos_angle, -1.0, 1.0)
+
+    angles = np.arccos(cos_angle)
+
+    arc_len = (l1 + l2) / 2.0
+    curvatures = angles / arc_len
 
-    return np.std(np.degrees(angles))
+    return float(np.sqrt(np.mean(curvatures**2)))

tests/unit/test_trails_drawing_metrics.py

@@ -49,31 +49,40 @@ def test_valid_total_errors() -> None:
 
 
 def test_smoothness_less_than_three_points() -> None:
-    """Test smoothness calculation with less than three points."""
+    """Less than 3 points cannot define curvature."""
     points = pd.DataFrame({"x": [0, 1], "y": [0, 1]})
     assert drawing_metrics.calculate_smoothness(points) == 0.0
 
 
 def test_smoothness_straight_line() -> None:
-    """Collinear points should produce zero smoothness."""
+    """Collinear points have zero curvature."""
     points = pd.DataFrame({"x": [0, 1, 2, 3], "y": [0, 0, 0, 0]})
     assert drawing_metrics.calculate_smoothness(points) == 0.0
 
 
 def test_smoothness_single_right_angle() -> None:
-    """A single 90-degree turn should produce an std of 0."""
+    """A single 90-degree corner should produce a large smoothness value.
+
+    (non-zero), since sharp turns are penalized.
+    """
     points = pd.DataFrame({"x": [0, 1, 1], "y": [0, 0, 1]})
+    expected = np.pi / 2
     smoothness = drawing_metrics.calculate_smoothness(points)
-    assert smoothness == 0.0
+    assert np.isclose(smoothness, expected)
 
 
 def test_smoothness_varied_angles() -> None:
-    """Test smoothness with two different angles to ensure std is computed correctly."""
+    """Multiple angles should produce RMS curvature.
+
+    Path has a 90° turn followed by a 45° turn.
+    """
     points = pd.DataFrame({"x": [0, 1, 1, 2], "y": [0, 0, 1, 2]})
+    c1 = np.pi / 2
+    c2 = (np.pi / 4) / ((1 + np.sqrt(2)) / 2)
+    expected = np.sqrt((c1**2 + c2**2) / 2)
 
     smoothness = drawing_metrics.calculate_smoothness(points)
 
-    expected = np.std([90, 45])
     assert np.isclose(smoothness, expected)
 
 
@@ -82,3 +91,17 @@ def test_smoothness_zero_length_segments() -> None:
     points = pd.DataFrame({"x": [0, 1, 1, 2], "y": [0, 0, 0, 0]})
     smoothness = drawing_metrics.calculate_smoothness(points)
     assert smoothness == 0.0
+
+
+def test_smoothness_single_180_degree_turn() -> None:
+    """A single 180-degree turn should produce a very large smoothness value.
+
+    Since it represents maximal curvature.
+    """
+    points = pd.DataFrame({
+        "x": [0, 1, 0],
+        "y": [0, 0, 0],
+    })
+    expected = np.pi
+    smoothness = drawing_metrics.calculate_smoothness(points)
+    assert np.isclose(smoothness, expected)