Cleanup

examples/python/air_traffic_data/README.md

@@ -1,24 +1,46 @@
 <!--[metadata]
 title = "Air Traffic Data"
 tags = ["2d", "3d", "map", "crs"]
-description = "Display aircraft flight trajectories"
-build_args = ["--jpeg-quality=50"]
+description = "Display aircraft traffic data"
 -->
 
 
 Display air traffic data kindly provided by [INVOLI](https://www.involi.com).
 
+<picture>
+  <img src="https://static.rerun.io/air_traffic_data/4a68b46a404c4f9e3c082f57a8a8ed4bf5b9b236/full.png" alt="">
+  <source media="(max-width: 480px)" srcset="https://static.rerun.io/air_traffic_data/4a68b46a404c4f9e3c082f57a8a8ed4bf5b9b236/480w.png">
+  <source media="(max-width: 768px)" srcset="https://static.rerun.io/air_traffic_data/4a68b46a404c4f9e3c082f57a8a8ed4bf5b9b236/768w.png">
+  <source media="(max-width: 1024px)" srcset="https://static.rerun.io/air_traffic_data/4a68b46a404c4f9e3c082f57a8a8ed4bf5b9b236/1024w.png">
+  <source media="(max-width: 1200px)" srcset="https://static.rerun.io/air_traffic_data/4a68b46a404c4f9e3c082f57a8a8ed4bf5b9b236/1200w.png">
+</picture>
 
-```bash
-# install dependencies
-pip install -r examples/python/air_traffic_data/requirements.txt
+This example demonstrates multiple aspects of the Rerun viewer:
+
+- Use of the [map view](https://rerun.io/docs/reference/types/views/map_view).
+- Use of [pyproj](https://pyproj4.github.io/pyproj/stable/) to transform geospatial data from one coordinate system to another.
+- Use [GeoPandas](https://geopandas.org/en/stable/) to load geospatial data into a 3D view.
+- Use [Polars]https://pola.rs) to batch data to be sent via [`rr.send_columns()`](https://rerun.io/docs/howto/logging/send-columns) (use `--batch`).
 
-# run with demo dataset
-python examples/python/air_traffic_data/main.py --dataset 10min
 
-# run with custom dataset
-python examples/python/air_traffic_data/main.py --dir path/to/my/dataset/directory
+## Run the code
 
-# more options
-python examples/python/air_traffic_data/main.py --help
+To run this example, make sure you have Python version at least 3.9, the Rerun repository checked out and the latest SDK installed:
+```bash
+pip install --upgrade rerun-sdk  # install the latest Rerun SDK
+git clone git@github.com:rerun-io/rerun.git  # Clone the repository
+cd rerun
+git checkout latest  # Check out the commit matching the latest SDK release
+```
+Install the necessary libraries specified in the requirements file:
+```bash
+pip install -e examples/python/air_traffic_data
+```
+To experiment with the provided example, simply execute the main Python script:
+```bash
+python -m air_traffic_data
+```
+If you wish to customize it, explore additional features, or save it use the CLI with the `--help` option for guidance:
+```bash
+python -m air_traffic_data --help
 ```

examples/python/air_traffic_data/air_traffic_data.py

@@ -5,6 +5,7 @@
 import itertools
 import json
 import re
+import typing
 import zipfile
 from argparse import ArgumentParser
 from pathlib import Path
@@ -41,11 +42,11 @@ def download_with_progress(url: str, what: str) -> io.BytesIO:
     resp = requests.get(url, stream=True)
     total_size = int(resp.headers.get("content-length", 0))
     with tqdm(
-        desc=f"Downloading {what}…",
-        total=total_size,
-        unit="iB",
-        unit_scale=True,
-        unit_divisor=1024,
+            desc=f"Downloading {what}…",
+            total=total_size,
+            unit="iB",
+            unit_scale=True,
+            unit_divisor=1024,
     ) as progress:
         download_file = io.BytesIO()
         for data in resp.iter_content(chunk_size):
@@ -72,7 +73,7 @@ def shapely_geom_to_numpy(geom: shapely.Geometry) -> list[npt.NDArray[np.float64
 
 
 def log_region_boundaries_for_country(
-    country_code: str, level: int, color: tuple[float, float, float], crs: CRS
+        country_code: str, level: int, color: tuple[float, float, float], crs: CRS
 ) -> None:
     """Log some boundaries for the given country and level."""
 
@@ -202,6 +203,14 @@ def natural_keys(path: Path) -> list[int | str]:
     return sorted(directory.rglob("*.json"), key=natural_keys)
 
 
+class Logger(typing.Protocol):
+    def process_measurement(self, measurement: Measurement) -> None:
+        pass
+
+    def flush(self) -> None:
+        pass
+
+
 # ================================================================================================
 # Simple logger
 
@@ -232,9 +241,9 @@ def process_measurement(self, measurement: Measurement) -> None:
         entity_path = f"aircraft/{measurement.icao_id}"
 
         if (
-            measurement.latitude is not None
-            and measurement.longitude is not None
-            and measurement.barometric_altitude is not None
+                measurement.latitude is not None
+                and measurement.longitude is not None
+                and measurement.barometric_altitude is not None
         ):
             rr.log(
                 entity_path,
@@ -280,7 +289,7 @@ def process_measurement(self, measurement: Measurement) -> None:
         if len(self._measurements) >= 8192:
             self.flush()
 
-    def flush(self):
+    def flush(self) -> None:
         # !!! the raw data is not sorted by timestamp, so we sort it here
         df = polars.DataFrame(self._measurements).sort("timestamp")
         self._measurements = []
@@ -368,14 +377,14 @@ def log_everything(paths: list[Path], raw: bool, batch: bool, batch_size: int) -
     proj = Transformer.from_crs("EPSG:4326", utm_crs, always_xy=True)
 
     rr.set_time_seconds("unix_time", 0)
-    for country_code, (level, color) in itertools.product(["DE", "FR", "CH"], [(0, (1, 0.5, 0.5))]):
+    for country_code, (level, color) in itertools.product(["DE", "CH"], [(0, (1, 0.5, 0.5))]):
         log_region_boundaries_for_country(country_code, level, color, utm_crs)
 
     # Exaggerate altitudes
     rr.log("aircraft", rr.Transform3D(scale=[1, 1, 10]), static=True)
 
     if batch:
-        logger = MeasurementBatchLogger(proj, batch_size)
+        logger: Logger = MeasurementBatchLogger(proj, batch_size)
     else:
         logger = MeasurementLogger(proj, raw)
 
@@ -431,7 +440,12 @@ def main() -> None:
             with zipfile.ZipFile(zip_data) as zip_ref:
                 zip_ref.extractall(dataset_directory)
 
-    blueprint = rrb.Horizontal(rrb.Spatial3DView(origin="/"), rrb.TimeSeriesView(origin="/aircraft"))
+    # TODO(ab): this blueprint would be massively improved by setting the 3D view's orbit point to FRA's coordinates.
+    blueprint = rrb.Vertical(
+        rrb.Horizontal(rrb.Spatial3DView(origin="/"), rrb.MapView(origin="/")),
+        rrb.TimeSeriesView(origin="/aircraft"),
+        row_shares=[3, 1],
+    )
     rr.script_setup(args, "rerun_example_air_traffic_data", default_blueprint=blueprint)
 
     paths = get_paths_for_directory(dataset_directory)