103 task add Stroke model (#120)

* Add Stroke model and tests

* minor changes to docstring and removing an unnecessary test

Author: kimit0310

src/graphomotor/core/models.py

@@ -144,6 +144,7 @@ class GridCell:
         y_max: Top boundary of the cell.
         index: Position of the cell in the grid (0-based).
         label: Display label for the cell (e.g., 'A', 'B', '1').
+        strokes: List of Stroke objects assigned to this cell.
     """
 
     x_min: float
@@ -152,6 +153,7 @@ class GridCell:
     y_max: float
     index: int = 0
     label: str = ""
+    strokes: List["Stroke"] = dataclasses.field(default_factory=list)
 
     def __post_init__(self) -> None:
         """Validate that min bounds are strictly less than max bounds.
@@ -189,6 +191,41 @@ def contains_points(self, points: pd.DataFrame) -> bool:
         )
 
 
+@dataclasses.dataclass
+class Stroke:
+    """Represents a single stroke in an Alphabet or DSYM task.
+
+    This class holds stroke data and computed features. Features are populated by
+    utility functions after initialization.
+
+    Attributes:
+        points: DataFrame with columns including 'x', 'y', and 'seconds'.
+        line_number: The line number identifying this stroke in the raw data.
+        duration: Total time (s) spent drawing the stroke.
+        distance: Total distance (px) of the stroke path.
+        mean_speed: Mean drawing speed (px/s).
+        speed_variance: Variance of drawing speed.
+        smoothness: Smoothness of the stroke based on curvature changes.
+        hesitation_count: Number of hesitations during the stroke.
+        hesitation_duration: Total duration of hesitations (s).
+        velocities: List of velocities at each point in the stroke (px/s).
+        accelerations: List of accelerations at each point in the stroke (px/s²).
+    """
+
+    points: pd.DataFrame
+    line_number: int
+
+    duration: float = 0.0
+    distance: float = 0.0
+    mean_speed: float = 0.0
+    speed_variance: float = 0.0
+    smoothness: float = 0.0
+    hesitation_count: int = 0
+    hesitation_duration: float = 0.0
+    velocities: List[float] = dataclasses.field(default_factory=list)
+    accelerations: List[float] = dataclasses.field(default_factory=list)
+
+
 @dataclasses.dataclass
 class CircleTarget:
     """Represents a target circle in the drawing task.

tests/unit/test_stroke.py

@@ -0,0 +1,76 @@
+"""Test cases for the Stroke model."""
+
+import pandas as pd
+
+from graphomotor.core import models
+
+
+def _make_points(line_number: int = 0) -> pd.DataFrame:
+    """Create a stroke DataFrame matching real Alphabet CSV structure.
+
+    In the real data each stroke (line_number) contains many rows with the same
+    line_number value, plus x, y, seconds, and timestamp columns.
+    """
+    return pd.DataFrame(
+        {
+            "line_number": [line_number] * 5,
+            "x": [18.35, 18.24, 18.15, 18.12, 17.99],
+            "y": [92.84, 92.85, 92.88, 92.92, 93.01],
+            "seconds": [0.0, 0.02, 0.037, 0.046, 0.062],
+        }
+    )
+
+
+def test_stroke_initialization() -> None:
+    """Stroke should store points and line_number with default feature values."""
+    points = _make_points(line_number=0)
+    stroke = models.Stroke(points=points, line_number=0)
+
+    assert stroke.line_number == 0
+    assert stroke.points.equals(points)
+    assert list(stroke.points.columns) == ["line_number", "x", "y", "seconds"]
+    assert len(stroke.points) == 5
+    assert stroke.duration == 0.0
+    assert stroke.distance == 0.0
+    assert stroke.mean_speed == 0.0
+    assert stroke.speed_variance == 0.0
+    assert stroke.smoothness == 0.0
+    assert stroke.hesitation_count == 0
+    assert stroke.hesitation_duration == 0.0
+    assert stroke.velocities == []
+    assert stroke.accelerations == []
+
+
+def test_stroke_features_are_mutable() -> None:
+    """Computed features should be writable after initialization."""
+    stroke = models.Stroke(points=_make_points(line_number=0), line_number=0)
+
+    stroke.duration = 0.5
+    stroke.distance = 25.0
+    stroke.mean_speed = 50.0
+    stroke.velocities = [40.0, 50.0, 60.0]
+
+    assert stroke.duration == 0.5
+    assert stroke.distance == 25.0
+    assert stroke.mean_speed == 50.0
+    assert stroke.velocities == [40.0, 50.0, 60.0]
+
+
+def test_grid_cell_stores_strokes() -> None:
+    """GridCell should hold Stroke objects in its strokes list."""
+    cell = models.GridCell(x_min=0.0, x_max=30.0, y_min=70.0, y_max=100.0)
+    stroke_a = models.Stroke(points=_make_points(line_number=0), line_number=0)
+    stroke_b = models.Stroke(points=_make_points(line_number=1), line_number=1)
+
+    cell.strokes.append(stroke_a)
+    cell.strokes.append(stroke_b)
+
+    assert len(cell.strokes) == 2
+    assert cell.strokes[0].line_number == 0
+    assert cell.strokes[1].line_number == 1
+
+
+def test_grid_cell_strokes_default_empty() -> None:
+    """GridCell should default to an empty strokes list."""
+    cell = models.GridCell(x_min=0.0, x_max=10.0, y_min=0.0, y_max=10.0)
+    assert cell.strokes == []