update SegmentedRoadGenerator to allow user-specified min and max turning angle. Addresses part of issue #7.

fixes #6

README.md

@@ -70,4 +70,6 @@ You can reproduce results by adding a seed with the `--seed` flag.
 
 ## Other
 
-For more info, see `road-gen --help` or `road-gen random --help`.
+For more info, see `road-gen --help` or `road-gen random --help`.
+
+There are some Jupyter notebooks explaining [roads as planar curves](docs/planar_curve.ipynb), as well as the actual implementation of [random segmented roads](docs/prefab_roads.ipynb) and [random roads from noise](docs/random_roads.ipynb).

docs/prefab_roads.ipynb

@@ -0,0 +1,118 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "1a063d05",
+   "metadata": {},
+   "source": [
+    "# Random roads using prefabs\n",
+    "\n",
+    "It is cool to see that a little processed noise can generate something that looks like roads. But of course, roads are not really random. Instead, they are made of a sequence of 'prefabs', for example, a road between A and B may look like\n",
+    "\n",
+    "$$\n",
+    "\\text{straight, turn left, straight, turn right, straight}\n",
+    "$$\n",
+    "\n",
+    "Let's see how we can create a random road of length $L$ from a pre-determined set of prefabs.\n",
+    "\n",
+    "#### Random apportionment of total length\n",
+    "\n",
+    "Suppose we want to build a road of length $L$ out of $K$ segments. The total number of waypoints $N$ depends on the step size $\\Delta s$:\n",
+    "\n",
+    "$$\n",
+    "N = \\frac{L}{\\Delta s}.\n",
+    "$$\n",
+    "\n",
+    "Let $\\left( p_1, p_2, \\dots, p_K \\right)$ represent the proportion of $N$ that each prefab will be assigned, where $\\sum p_i = 1$. One useful distribution here is the [Dirichlet distribution](https://en.wikipedia.org/wiki/Dirichlet_distribution), which is parametrized by a vector $\\mathbf{\\alpha} = \\left(\\alpha_1, \\alpha_2, \\dots, \\alpha_K \\right)$. The special case where all $\\alpha_i$, the scalar parameter $\\alpha$ is called a *concentration parameter*. Setting the same $\\alpha$ across the entire parameter space makes the distribution symmetric, meaning no prior assumptions are made regarding the proportion of $N$ that will be assigned to each segment. $\\alpha = 1$ leads to what is known as a flat Dirichlet distribution, whereas higher values lead to more dense and evenly distributed $\\left( p_1, p_2, \\dots, p_K \\right)$. On the other hand, keeping $\\alpha \\leq 1$ gives a sparser distribution which can lead to larger variance in apportioned number of waypoints to $\\left( p_1, p_2, \\dots, p_K \\right)$.\n",
+    "\n",
+    "#### Expectation value and variance of Dirichlet distribution\n",
+    "\n",
+    "Suppose we draw our samples for proportion of length from the Dirichlet distribution\n",
+    "\n",
+    "$$\n",
+    "(p_1, p_2, \\ldots, p_K) \\sim \\text{Dirichlet}(\\alpha, \\alpha, \\ldots, \\alpha)\n",
+    "$$\n",
+    "\n",
+    "with $\\alpha _{0}=\\sum _{i=1}^{K}\\alpha _{i}$, the mean and variance are then\n",
+    "\n",
+    "$$\n",
+    "\\operatorname {E} [p_{i}]={\\frac {\\alpha _{i}}{\\alpha _{0}}}, \\; \\operatorname {Var} [p_{i}]={\\frac {\\alpha _{i}(\\alpha _{0}-\\alpha _{i})}{\\alpha _{0}^{2}(\\alpha _{0}+1)}}.\n",
+    "$$\n",
+    "\n",
+    "If $\\alpha$ is a scalar, then $\\alpha _{0}= K \\alpha$ and the above simplifies to\n",
+    "\n",
+    "$$\n",
+    "\\operatorname {E} [p_{i}]={\\frac {\\alpha}{K \\alpha}}={\\frac {1}{K}}, \\; \\operatorname {Var} [p_{i}]={\\frac {\\alpha(K \\alpha -\\alpha)}{(K \\alpha)^{2}(K \\alpha +1)}}.\n",
+    "$$\n",
+    "\n",
+    "We see that $\\operatorname {Var} [p_{i}] \\propto \\frac{1}{\\alpha}$ meaning that the variance reduces with increasing $\\alpha$. We can simply scale the proportions\n",
+    "\n",
+    "$$\n",
+    "(N \\cdot p_1, N \\cdot p_2, \\ldots, N \\cdot p_K)\n",
+    "$$\n",
+    "\n",
+    "to get the randomly assigned number of waypoints for each prefab. We now have a distribution which can give randomly assigned lengths to a given list of prefabs, with a parameter to control the degree of randomness. With a large concentration parameter $\\alpha$, the distribution of lengths will be more uniform, with each prefab getting $N \\cdot \\operatorname {E} [p_{i}]={\\frac {N}{K}}$ waypoints assigned to it. Likewise, keeping $\\alpha$ low increases variance and allows for a more random assignment of proportions of waypoints to each prefab segment.\n",
+    "\n",
+    "#### Random angles\n",
+    "\n",
+    "Suppose a turn of a pre-defined arc length $l$ made of $N/K$ waypoints. If one wants to create a random angle, one has to keep in mind that the minimum radius $R_{min}$ depends on the speed of the vehicle and the weather conditions:\n",
+    "\n",
+    "$$\n",
+    "R_{\\text{min,vehicle}} = \\frac{v^2}{g\\mu},\n",
+    "$$\n",
+    "\n",
+    "where\n",
+    "- $v$ is the velocity of the vehicle in $\\text{m/s}$,\n",
+    "- $g$ is the gravitational acceleration (about $9.8$ $\\text{m/s}^{2}$), and\n",
+    "- $\\mu$ is the friction coefficient (about $0.7$ for dry asphalt).\n",
+    "\n",
+    "A regular turn (not a U-turn or roundabout) should also have an lower and upper limit on the angle, say, 30 degrees to 90 degrees for a conservative estimate. In terms of radii, it becomes\n",
+    "\n",
+    "$$\n",
+    "R_{\\text{min}} = \\max\\left(R_{\\text{min,vehicle}}, \\frac{l}{\\pi/2}\\right)\n",
+    "$$\n",
+    "\n",
+    "and\n",
+    "\n",
+    "$$\n",
+    "R_{\\text{max}} = \\frac{l}{\\pi/6}.\n",
+    "$$\n",
+    "\n",
+    "We then sample\n",
+    "\n",
+    "$$\n",
+    "R \\sim \\text{Uniform}\\left(R_{\\text{min}}, R_{\\text{max\\_angle}}\\right)\n",
+    "$$\n",
+    "\n",
+    "and obtain a random radius for a turn of arc length $l$ with limits to ensure the radius is large enough given the velocity of the vehicle. Finally, the curvature profile is related to the radius by\n",
+    "\n",
+    "$$\n",
+    "\\kappa = \\frac{1}{R}\n",
+    "$$\n",
+    "\n",
+    "which means that the curvature profile of a turn is simply a vector $\\mathbf{\\kappa} = (1/R, \\dots, 1/R)$ with a length of $N/K$ waypoints."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

src/road_gen/generators/segmented_road_generator.py

@@ -33,22 +33,26 @@ class SegmentedRoadGenerator(BaseRoadGenerator):
     def generate(
             self,
             segments: list[str],
-            alpha: float = 100
+            alpha: float = 100,
+            min_turn_angle: float = 15.,
+            max_turn_angle: float = 90.
     ) -> Tuple[np.ndarray, np.ndarray]:
         """Generate a curvature profile from a list of segments.
 
         Args:
             segments (list[str]): List of segments.
             alpha (float, optional): Dirichlet concentration parameter. A higher value leads to more uniform apportionment of the length amongst the segments, while a lower value allows more random apportionment. Defaults to 1.0.
-        
+            min_turn_angle (float, optional): Minimum turn angle in degrees for random sampling of turn radius. Does nothing if `angle_list` is provided or no `turn_*` segement is specified in the `segments` list.
+            min_turn_angle (float, optional): Maximum turn angle in degrees for random sampling of turn radius. Does nothing if `angle_list` is provided or no `turn_*` segement is specified in the `segments` list.
         Raises:
             ValueError: "No valid radius for this turn segment" means a turn is too tight given its segment length and the velocity. To fix this, you can try to reduce the amount of segments or increase length. Increasing alpha (Dirichlet concentration parameter) can also help because this reduces the odds of very small lengths being assigned to turn segments. 
         
         Returns:
             Tuple[np.ndarray, np.ndarray]: x and y coordinates of the waypoints describing the random road.
         """
-        if not all(segment in prefabs.PREFABS.keys() for segment in segments):
+        existing_prefabs = prefabs.PREFABS.keys()
-            raise ValueError(f"Invalid segment type provided. Available choices: {prefabs.SEGMENTS.keys()}")
+        if not all(segment in existing_prefabs for segment in segments):
+            raise ValueError(f"Invalid segment type provided. Available choices: {existing_prefabs}")
         
         self.segments = segments
         self.alpha = alpha
@@ -63,7 +67,6 @@ class SegmentedRoadGenerator(BaseRoadGenerator):
         if sum(parts) != num_points:
             parts[0] += num_points - sum(parts)
 
-
         curvature = np.zeros(num_points)
         current_index = 0
 
@@ -73,8 +76,8 @@ class SegmentedRoadGenerator(BaseRoadGenerator):
             if seg_name == 'straight':
                 curvature_s = seg_function(seg_length)
             else:
-                R_min_angle = seg_length / (np.pi / 2)
+                R_min_angle = seg_length / np.deg2rad(max_turn_angle)
-                R_max_angle = seg_length / (np.pi / 6)
+                R_max_angle = seg_length / np.deg2rad(min_turn_angle)
 
                 # physics limit
                 R_min = max(self.min_radius, R_min_angle)