Issue #213: Project invalid trajectories inside walkable area (#506)

* added preprocessing and trajectory_projector

* edited user guide, added test file

* Fixed Float_Precision Problem and added tests

* new distance calculation function

* errors for false parameters, better structure, method for catching incorrect adjustments

* Added Errors for Exceptions

* Finished documentation

* changed list structure for geo_data into dataframes

* Fixed Docstring Notation

* Updated min_ - / max_distance to user_guide

* Symlinks describtion for Windows User in developeter guide

* Fixed import statements

* added a visualization for the min-/max-distance parameters  

* Improved the plot for showing preprocessing parameters  

* adapted init so tests run through

Author: awestphal1

docs/source/developer_guide.rst

@@ -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 afterwards 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": {},

docs/source/images/parameters_preprocessing.png

@@ -149,6 +149,7 @@
     plot_voronoi_cells,
     plot_walkable_area,
 )
+from .preprocessing.trajectory_projector import correct_invalid_trajectories
 
 __all__ = [  # noqa: RUF022 disable sorting of __all__ for better maintenance
     "AxisAlignedMeasurementArea",
@@ -210,6 +211,7 @@
     "compute_individual_acceleration",
     "compute_mean_acceleration_per_frame",
     "compute_voronoi_acceleration",
+    "correct_invalid_trajectories",
     "PEDPY_BLUE",
     "PEDPY_GREEN",
     "PEDPY_GREY",