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

* added seciton of code to calculate ink_points

* move valid_ink_trajectory into lineSegment and update impors for models.py and trails_utils.py

* moved unit test and reformatted

* mypy error

* ruff reformat

Author: cgmaiorano

src/graphomotor/core/models.py

@@ -2,7 +2,7 @@
 
 import dataclasses
 import datetime
-import typing
+from typing import Callable, List, Optional, Tuple
 
 import numpy as np
 import pandas as pd
@@ -95,7 +95,7 @@ def all(cls) -> set[str]:
     @classmethod
     def get_extractors(
         cls, spiral: Drawing, reference_spiral: np.ndarray
-    ) -> dict[str, typing.Callable[[], dict[str, float]]]:
+    ) -> dict[str, Callable[[], dict[str, float]]]:
         """Get all feature extractors with appropriate inputs.
 
         Args:
@@ -189,6 +189,7 @@ class LineSegment:
     points: pd.DataFrame
     is_error: bool
     line_number: int
+    ink_points: np.ndarray = dataclasses.field(default_factory=lambda: np.array([]))
 
     ink_time: float = 0.0
     think_time: float = 0.0
@@ -200,8 +201,62 @@ class LineSegment:
     smoothness: float = 0.0
     hesitation_count: int = 0
     hesitation_duration: float = 0.0
-    velocities: typing.List[float] = dataclasses.field(default_factory=list)
-    accelerations: typing.List[float] = dataclasses.field(default_factory=list)
+    velocities: List[float] = dataclasses.field(default_factory=list)
+    accelerations: List[float] = dataclasses.field(default_factory=list)
+
+    def valid_ink_trajectory(
+        self,
+        start_circle: CircleTarget,
+        end_circle: CircleTarget,
+    ) -> Tuple[Optional[int], Optional[int]]:
+        """Determine whether an ink trajectory exists from a start to 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. If a valid trajectory is found,
+        the ink_points attribute is updated to contain only the points within
+        this trajectory.
+
+        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 self.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
+
+        if (
+            ink_start_idx is not None
+            and ink_end_idx is not None
+            and ink_end_idx > ink_start_idx
+        ):
+            self.ink_points = self.points.iloc[ink_start_idx : ink_end_idx + 1].copy()
+
+        return ink_start_idx, ink_end_idx
 
     def calculate_path_optimality(
         self,

src/graphomotor/utils/trails_utils.py

@@ -1,54 +1,12 @@
 """Utility functions for trails management."""
 
-from typing import Dict, List, Optional, Tuple
+from typing import Dict, List
 
 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,

tests/unit/test_models.py

@@ -1,6 +1,7 @@
 """Test cases for the Spiral model."""
 
 import datetime
+from typing import Dict, cast
 
 import pandas as pd
 import pytest
@@ -135,3 +136,106 @@ def test_path_optimality_non_positive_distance() -> None:
     segment.calculate_path_optimality(start, end)
 
     assert segment.path_optimality == 0.0
+
+
+@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(
+    points_data: Dict[str, list[float]],
+    start_params: dict[str, int | str | float],
+    end_params: dict[str, int | str | float],
+    expected_start: int | None,
+    expected_end: int | None,
+    test_id: str,
+) -> None:
+    """Test valid_ink_trajectory method with various point configurations.
+
+    Tests behavior with different circle boundaries.
+    """
+    points_df = pd.DataFrame(points_data)
+
+    start_circle = models.CircleTarget(**start_params)  # type: ignore[arg-type]
+    end_circle = models.CircleTarget(**end_params)  # type: ignore[arg-type]
+
+    line_segment = models.LineSegment(
+        start_label=cast(str, start_params["label"]),
+        end_label=cast(str, end_params["label"]),
+        points=points_df,
+        is_error=False,
+        line_number=1,
+    )
+
+    result_start, result_end = line_segment.valid_ink_trajectory(
+        start_circle, end_circle
+    )
+
+    assert result_start == expected_start, f"Start index mismatch for {test_id}"
+    assert result_end == expected_end, f"End index mismatch for {test_id}"

tests/unit/test_trails_utils.py

@@ -9,97 +9,6 @@
 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."""