feat: add StoryboardEntry.purpose, make show segments available for r…

…endering, some typing improvements and refactoring

src/modules/sbstudio/api/base.py

@@ -2,6 +2,7 @@
 import re
 
 from base64 import b64encode
+from collections.abc import Iterator, Sequence
 from contextlib import contextmanager
 from gzip import compress
 from http.client import HTTPResponse
@@ -10,7 +11,7 @@
 from pathlib import Path
 from shutil import copyfileobj
 from ssl import create_default_context, CERT_NONE
-from typing import Any, Dict, Iterator, List, Optional, Sequence, Tuple
+from typing import Any, Optional
 from urllib.error import HTTPError
 from urllib.parse import urljoin
 from urllib.request import Request, urlopen
@@ -321,7 +322,7 @@ def decompose_points(
         *,
         min_distance: float,
         method: str = "greedy",
-    ) -> List[int]:
+    ) -> list[int]:
         """Decomposes a set of points into multiple groups while ensuring that
         the minimum distance of points within the same group is at least as
         large as the given threshold.
@@ -342,44 +343,51 @@ def decompose_points(
 
     def export(
         self,
+        *,
         validation: SafetyCheckParams,
-        trajectories: Dict[str, Trajectory],
-        lights: Optional[Dict[str, LightProgram]] = None,
-        yaw_setpoints: Optional[Dict[str, YawSetpointList]] = None,
+        trajectories: dict[str, Trajectory],
+        lights: Optional[dict[str, LightProgram]] = None,
+        yaw_setpoints: Optional[dict[str, YawSetpointList]] = None,
         output: Optional[Path] = None,
         show_title: Optional[str] = None,
         show_type: str = "outdoor",
+        show_segments: Optional[dict[str, tuple[float, float]]] = None,
         ndigits: int = 3,
         timestamp_offset: Optional[float] = None,
         time_markers: Optional[TimeMarkers] = None,
         cameras: Optional[list[Camera]] = None,
         renderer: str = "skyc",
-        renderer_params: Optional[Dict[str, Any]] = None,
+        renderer_params: Optional[dict[str, Any]] = None,
     ) -> Optional[bytes]:
-        """Export drone show data into Skybrush Compiled Format (.skyc).
+        """
+        Export drone show data.
 
         Parameters:
-            validation: safety check parameters
-            trajectories: dictionary of trajectories indexed by drone names
-            lights: dictionary of light programs indexed by drone names
-            yaw_setpoints: dictionary of yaw setpoints indexed by drone names
-            output: the file path where the output should be saved or `None`
-                if the output must be returned instead of saving it to a file
-            show_title: arbitrary show title; `None` if no title is needed
-            show_type: type of the show; must be one of `outdoor` or `indoor`
-            ndigits: round floats to this precision
-            timestamp_offset: when specified, adds this timestamp offset to the
-                metadata of the .skyc file, which is then used later for display
-                purposes in Skybrush Viewer
-            time_markers: when specified, time markers will be exported to the
-                .skyc file as temporal cues
-            cameras: when specified, list of cameras to include in the environment
+            validation: Safety check parameters.
+            trajectories: Dictionary of trajectories indexed by drone names.
+            lights: Dictionary of light programs indexed by drone names.
+            yaw_setpoints: Dictionary of yaw setpoints indexed by drone names.
+            output: The file path where the output should be saved or `None`
+                if the output must be returned instead of saving it to a file.
+            show_title: Arbitrary show title; `None` if no title is needed.
+            show_type: Type of the show; must be one of `outdoor` or `indoor`.
+            show_segments: Dictionary that maps show segment IDs to a start
+                (inclusive) and end (exclusive) timestamp pair.
+            ndigits: Round floats to this precision.
+            timestamp_offset: When specified, adds this timestamp offset to the
+                show metadata, which can later be used for display purposes in
+                Skybrush Viewer.
+            time_markers: When specified, time markers will be exported as
+                temporal cues.
+            cameras: When specified, list of cameras to include in the environment.
+            renderer: The renderer to use to export the show.
+            renderer_params: Extra parameters for the renderer.
 
         Note: drone names must match in trajectories and lights
 
         Returns:
-            the drone show data in .skyc format or `None` if an output filename
-            was specified
+            The exported drone show data or `None` if an `output` filename
+            was specified.
         """
 
         meta = {}
@@ -389,6 +397,9 @@ def export(
         if timestamp_offset is not None:
             meta["timestampOffset"] = timestamp_offset
 
+        if show_segments is not None:
+            meta["segments"] = show_segments
+
         if lights is None:
             lights = {name: LightProgram() for name in trajectories.keys()}
 
@@ -451,7 +462,7 @@ def create_formation_from_svg(
         num_points: int,
         size: float,
         angle: float,
-    ) -> Tuple[List[Point3D], List[Color3D]]:
+    ) -> tuple[list[Point3D], list[Color3D]]:
         """Samples the path objects of an SVG string into a list of coordinates
         and corresponding colors.
 
@@ -490,7 +501,7 @@ def create_formation_from_svg(
 
     def generate_plots(
         self,
-        trajectories: Dict[str, Trajectory],
+        trajectories: dict[str, Trajectory],
         output: Path,
         validation: SafetyCheckParams,
         plots: Sequence[str] = ("pos", "vel", "nn"),
@@ -563,7 +574,7 @@ def match_points(
         target: Sequence[Coordinate3D],
         *,
         radius: Optional[float] = None,
-    ) -> Tuple[Mapping, Optional[float]]:
+    ) -> tuple[Mapping, Optional[float]]:
         """Matches the points of a source point set to the points of a
         target point set in a way that ensures collision-free straight-line
         trajectories between the matched points when neither the source nor the
@@ -594,7 +605,7 @@ def plan_landing(
         velocity: float,
         target_altitude: float = 0,
         spindown_time: float = 5,
-    ) -> Tuple[List[int], List[int]]:
+    ) -> tuple[list[int], list[int]]:
         """Plans the landing trajectories for a set of drones, assuming that
         they should maintain a given minimum distance while the motors are
         running and that they land with constant speed.