🚸 Walkthrough on object detection with bounding boxes (#49)

Tutorial on preparing vector bounding box labels for an object detection task. Using Microsoft Building Footprints over Kampong Ayer, Brunei.

* ➕ Add contextily

Context geo-tiles in Python!

* 🚧 Walkthrough on object detection with bounding boxes

Initial draft tutorial on preparing vector bounding box labels for an object detection task. Will be looking at building footprints over Kampong Ayer, Brunei on ESRI World Imagery. Also added intersphinx links for contextily and numpy.

* ➕ Add adlfs

Fsspec-compatible Azure Datalake and Azure Blob Storage access!

* 📝 Writeup section on loading GeoParquet files

Show how to load the Microsoft Building Footprints from GeoParquet files! Using `geopandas.read_parquet` for now (should it become a DataPipe?) to demonstrate things work. Have tried `pyogrio.read_dataframe(asset.href)` but got `DataSourceError: abfs://footprints/global/2022-07-06/ml-buildings.parquet/RegionName=Brunei: No such file or directory`. Might need to figure out https://gdal.org/user/virtual_file_systems.html#vsiadls auth issues somehow.

* 📝 Writeup section on georeferencing numpy.ndarray image

Show how to turn a numpy.ndarray image into an xarray.DataArray grid with coordinates assigned. Had to first change the image from channel-last to channel-first format (Pytorch/Chainer style) and drop the alpha channel (since there's no mask anyway. Afterwards is just setting the coordinates with xarray/rioxarray.

* 📝 Writeup section on pairing sliced chips with clipped vectors

Show how to use small chips (generated with xbatcher) as masks to clip an input vector geometry. Included an important note that GeoPandasRectangleClipper only works with one global vector database, but it will reproject and clip to each chip's crs and bounding box extent. Showed a side by side image and vector polygon visualization, and did a bit of Brunei Tourism marketing 😆 Also had to change `.rio.set_crs` to `.rio.write_crs` to preserve the crs property on xbatcher slicing.

* 📝 Writeup section on converting geo polygons to image coord boxes

Show how to turn things upside down! First step is to derive geographic bounding boxes from the polygons. Second step is to convert the boxes from geographical coordinates to image/pixel coordinates. Also added an intersphinx link for torchvision to reference the `torchvision.ops.box_convert` function.

* 📝 Writeup final section on batching, dataloading and georeferencing

Show how to create a list of bounding box tensors, looping over batches of object detection data, and georeferencing of the 'predicted' output. Metadata is critical to tie everything together! Also added an intersphinx link for mmdetection, shoutout to their fantastic Model Zoo!

docs/_config.yml

@@ -38,12 +38,21 @@ sphinx:
       # https://sphinx-book-theme.readthedocs.io/en/stable/customize/sidebar-secondary.html
       show_toc_level: 3
     intersphinx_mapping:
+      contextily:
+        - 'https://contextily.readthedocs.io/en/latest/'
+        - null
       datashader:
         - 'https://datashader.org/'
         - null
       geopandas:
         - 'https://geopandas.org/en/latest/'
         - null
+      mmdetection:
+        - 'https://mmdetection.readthedocs.io/zh_CN/latest/'
+        - null
+      numpy:
+        - 'https://numpy.org/doc/stable'
+        - null
       pyogrio:
         - 'https://pyogrio.readthedocs.io/en/latest/'
         - null
@@ -63,7 +72,10 @@ sphinx:
         - 'https://pytorch.org/docs/stable/'
         - null
       torchdata:
-        - 'https://pytorch.org/data/main'
+        - 'https://pytorch.org/data/main/'
+        - null
+      torchvision:
+        - 'https://pytorch.org/vision/main/'
         - null
       xarray:
         - 'https://docs.xarray.dev/en/latest/'

docs/_toc.yml

@@ -11,6 +11,8 @@ chapters:
         file: chipping
       - title: 🫧 Vector Segmentation Masks
         file: vector-segmentation-masks
+      - title: 🥡 Object Detection Boxes
+        file: object-detection-boxes
   - title: 📖 API Reference
     file: api
   - title: 📆 Changelog