Issue #213: Project invalid trajectories inside walkable area

notebooks/user_guide.ipynb

@@ -5,6 +5,7 @@
    "execution_count": null,
    "metadata": {
     "jupyter": {
+     "is_executing": true,
      "outputs_hidden": false
     },
     "tags": [
@@ -891,6 +892,67 @@
     "get_invalid_trajectory(traj_data=traj, walkable_area=walkable_area_faulty)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Preprocessing\n",
+    "\n",
+    "\n",
+    "### Trajectory Projector\n",
+    "\n",
+    "When working with head trajectories, participants may occasionally lean over obstacles. As a result, their trajectories can leave the walkable area for some frames, and this data cannot be processed by PedPy.\n",
+    "\n",
+    "To address this, there is a function that moves trajectory points that lay inside a wall or too close to it. The distance that should remain between the point and the wall afterward is calculated by linear interpolation. The new distance lies within the interval between min_distance and max_distance:\n",
+    "\n",
+    "$$\n",
+    "d' = (d-b)*{(e-s) \\over (e-b)}+s\n",
+    "$$\n",
+    "\n",
+    "- d' is the new distance to the wall\n",
+    "- d is the original distance to the wall\n",
+    "- b corresponds to back_distance\n",
+    "- s corresponds to min_distance\n",
+    "- e corresponds to max_distance\n",
+    "\n",
+    "```{eval-rst}\n",
+    ".. figure:: images/parameters_preprocessing.png\n",
+    "    :width: 400px\n",
+    "    :align: center\n",
+    "```\n",
+    "\n",
+    "If a point lies inside the geometry or too close to it, it will be pushed outward. The distance interval for these points starts at back_distance, which must be negative because it represents the maximum depth inside the wall, and ends at max_distance. Points located deeper inside an obstacle are assigned a smaller new distance than points located near the boundary of the interval.\n",
+    "\n",
+    "For example, a point, which lays deep inside an obstacle will receive a new distance close to min_distance, which represents the minimum possible value for new_distance. A point that is already outside the obstacle but needs to be adjusted for smoother results will also receive a new distance, but this value will be only slightly larger than its original distance.\n",
+    "\n",
+    "It is essential that max_distance is larger than min_distance, and that back_distance is negative. Depending on the geometry and the parameter values, it can also be beneficial to buffer the geometry beforehand to create thicker walls. If the walls are too thin, the function may accidentally move a point to the wrong side.\n",
+    "\n",
+    "The function returns a pedpy.TrajectoryData, either the corrected version of the trajectory or the\n",
+    "         original trajectory, if the original trajectory was valid.\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "jupyter": {
+     "is_executing": true
+    }
+   },
+   "outputs": [],
+   "source": [
+    "from pedpy import correct_invalid_trajectories\n",
+    "\n",
+    "valid_trajectory = correct_invalid_trajectories(\n",
+    "    trajectory_data=traj,\n",
+    "    walkable_area=walkable_area,\n",
+    "    min_distance_obst=0.01,\n",
+    "    max_distance_obst=0.05,\n",
+    "    back_distance_obst=-0.5,\n",
+    ")"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},