71 task write trails utility functions valid ink trajectory (#87)

* wrote valid_ink_trajectory

* wrote parameterized scenarios for testing valid_ink_trajectory

* update docstring

* copilot changes

* ruff format

* fix imports

* Update trails_utils.py

Not sure where that exception came from?

---------

Co-authored-by: Adam Santorelli <148909356+Asanto32@users.noreply.github.com>

Author: cgmaiorano

src/graphomotor/utils/trails_utils.py

@@ -1,12 +1,54 @@
 """Utility functions for trails management."""
 
-from typing import Dict, List
+from typing import Dict, List, Optional, Tuple
 
 import pandas as pd
 
 from graphomotor.core import models
 
 
+def valid_ink_trajectory(
+    points: pd.DataFrame,
+    start_circle: models.CircleTarget,
+    end_circle: models.CircleTarget,
+) -> Tuple[Optional[int], Optional[int]]:
+    """Determine whether an ink trajectory exists from a start circle to an end circle.
+
+    An "ink trajectory" is defined as the first contiguous sequence of points that:
+      1. Begins **after** the pen leaves the start circle, and
+      2. Ends when the pen first enters the end circle.
+
+    The function scans point-by-point in order. The ink start index is the first point
+    whose (x, y) location is *outside* the start circle. The ink end index is the first
+    subsequent point whose (x, y) location falls *inside* the end circle. If either of
+    these conditions never occurs, the trajectory is considered invalid.
+
+    Args:
+        points: DataFrame of points with 'x' and 'y' columns.
+        start_circle: CircleTarget representing the start circle.
+        end_circle: CircleTarget representing the end circle.
+
+    Returns:
+        Tuple of (ink_start_idx: int, ink_end_idx: int) if valid trajectory exists,
+        else (None, None).
+    """
+    ink_start_idx = None
+    ink_end_idx = None
+
+    for idx, row in points.iterrows():
+        if (
+            not start_circle.contains_point(row["x"], row["y"])
+            and ink_start_idx is None
+        ):
+            ink_start_idx = idx
+
+        if ink_start_idx is not None and end_circle.contains_point(row["x"], row["y"]):
+            ink_end_idx = idx
+            break
+
+    return ink_start_idx, ink_end_idx
+
+
 def segment_lines(
     trail_data: pd.DataFrame,
     trail_id: str,
@@ -30,7 +72,7 @@ def segment_lines(
     Raises:
         KeyError: If trail_id is not found in circles dictionary.
         ValueError: If actual_path values are invalid.
-    """  # noqa: E501
+    """
     if trail_id not in circles:
         raise KeyError("Trail ID not found in circles dictionary.")
 

tests/unit/test_trails_utils.py

@@ -9,6 +9,97 @@
 from graphomotor.utils import trails_utils
 
 
+@pytest.mark.parametrize(
+    "points_data,start_params,end_params,expected_start,expected_end,test_id",
+    [
+        (
+            {"x": [0, 1, 2, 3, 4, 5], "y": [0, 1, 2, 3, 4, 5]},
+            {"order": 1, "label": "A", "center_x": 0, "center_y": 0, "radius": 0.5},
+            {"order": 2, "label": "B", "center_x": 5, "center_y": 5, "radius": 0.5},
+            1,
+            5,
+            "valid_trajectory",
+        ),
+        (
+            {"x": [0.1, 0.2, 0.3], "y": [0.1, 0.2, 0.3]},
+            {"order": 1, "label": "A", "center_x": 0, "center_y": 0, "radius": 1.0},
+            {"order": 2, "label": "B", "center_x": 10, "center_y": 10, "radius": 1.0},
+            None,
+            None,
+            "no_exit_from_start",
+        ),
+        (
+            {"x": [0, 1, 2, 3], "y": [0, 1, 2, 3]},
+            {"order": 1, "label": "A", "center_x": 0, "center_y": 0, "radius": 0.5},
+            {"order": 2, "label": "B", "center_x": 10, "center_y": 10, "radius": 0.5},
+            1,
+            None,
+            "never_reaches_end",
+        ),
+        (
+            {"x": [], "y": []},
+            {"order": 1, "label": "A", "center_x": 0, "center_y": 0, "radius": 1.0},
+            {"order": 2, "label": "B", "center_x": 5, "center_y": 5, "radius": 1.0},
+            None,
+            None,
+            "empty_dataframe",
+        ),
+        (
+            {"x": [0.1], "y": [0.1]},
+            {"order": 1, "label": "A", "center_x": 0, "center_y": 0, "radius": 1.0},
+            {"order": 2, "label": "B", "center_x": 5, "center_y": 5, "radius": 1.0},
+            None,
+            None,
+            "single_point_in_start",
+        ),
+        (
+            {"x": [2], "y": [2]},
+            {"order": 1, "label": "A", "center_x": 0, "center_y": 0, "radius": 0.5},
+            {"order": 2, "label": "B", "center_x": 5, "center_y": 5, "radius": 0.5},
+            0,
+            None,
+            "single_point_outside_start",
+        ),
+        (
+            {"x": [0, 2.5, 5], "y": [0, 2.5, 5]},
+            {"order": 1, "label": "A", "center_x": 0, "center_y": 0, "radius": 0.5},
+            {"order": 2, "label": "B", "center_x": 2.5, "center_y": 2.5, "radius": 1.0},
+            1,
+            1,
+            "immediate_transition",
+        ),
+        (
+            {"x": [3, 4, 5], "y": [3, 4, 5]},
+            {"order": 1, "label": "A", "center_x": 0, "center_y": 0, "radius": 0.5},
+            {"order": 2, "label": "B", "center_x": 5, "center_y": 5, "radius": 0.5},
+            0,
+            2,
+            "first_point_outside_start",
+        ),
+    ],
+    ids=lambda x: x if isinstance(x, str) else "",
+)
+def test_valid_ink_trajectory_scenarios(
+    points_data: Dict[str, list],
+    start_params: Dict,
+    end_params: Dict,
+    expected_start: int,
+    expected_end: int,
+    test_id: str,
+) -> None:
+    """Test various trajectory scenarios between start and end circles."""
+    points = pd.DataFrame(points_data)
+    start_circle = models.CircleTarget(**start_params)
+    end_circle = models.CircleTarget(**end_params)
+
+    ink_start, ink_end = trails_utils.valid_ink_trajectory(
+        points, start_circle, end_circle
+    )
+
+    assert ink_start == expected_start, f"Failed on {test_id}: ink_start"
+    assert ink_end == expected_end, f"Failed on {test_id}: ink_end"
+
+
 @pytest.fixture
 def circles() -> Dict[str, Dict[str, models.CircleTarget]]:
     """Return a minimal set of CircleTarget dictionaries for each trail."""