SpaceNet Building Footprint Outlines on Satellite Scenes

# yaml-language-server: $schema=https://potatoannotator.readthedocs.io/en/latest/schemas/potato-config.schema.json
# SpaceNet building footprints: outline each building on a satellite scene.
#
# Dataset: SpaceNet Challenge 2 (Las Vegas, Paris, Shanghai, Khartoum)
# Dataset URL: https://registry.opendata.aws/spacenet/
# Licence: CC BY-SA 4.0 (https://spacenet-dataset.s3.amazonaws.com/LICENSE.md)
# Paper: Van Etten, Lindenbaum and Bacastow, "SpaceNet: A Remote Sensing
#   Dataset and Challenge Series", arXiv:1807.01232 (2018).
# DOI: 10.48550/arXiv.1807.01232
# BibTeX:
#   @misc{vanetten2018spacenet,
#     doi = {10.48550/ARXIV.1807.01232},
#     url = {https://arxiv.org/abs/1807.01232},
#     author = {Van Etten, Adam and Lindenbaum, Dave and Bacastow, Todd M.},
#     title = {SpaceNet: A Remote Sensing Dataset and Challenge Series},
#     publisher = {arXiv},
#     year = {2018}
#   }
#
# Protocol (paper section 2.4 and Appendix A, "SpaceNet Building Footprint
# Labeling Guide"). Quoted:
#   "A GIS team at DigitalGlobe (now Radiant Solutions) fully annotated each
#   scene to within 5 pixels for building polygon corners."
#   "The labels went through a rigorous QA/QC process, with one expert
#   labeling a specific area and then a second expert performing validation
#   on 100% of the areas."
#   Labeling guide, items used here:
#   "2. Rooflines will first be extracted to best represent the shape of the
#   footprint and for any buildings where the base of the building is
#   partially visible due to off-nadir angle the polygon will be shifted to
#   best fit the base corners."
#   "3. Buildings will have squared corners (assuming they are true to the
#   shape of the building)."
#   "4. Extraction of building corners will be within 5 pixels of the
#   location on the imagery."
#   "5. Building footprints will be closed polygons and will not overlap."
#   "6. No attributes will be populated."
#   "7. Adjoining buildings with different heights shall be captured at one
#   visible roof for the whole block and shifted to that visible roofs
#   baseline."
# The paper leaves annotator disagreement for future work, so no agreement
# figure is claimed here.
#
# Label: one class, a building footprint polygon.
#
# Adaptations:
#   - The ten scenes are ILLUSTRATIVE. They are synthetic 650 x 650 px images
#     drawn for this design (media/LICENSE-media.txt), not SpaceNet
#     imagery, because SpaceNet is CC BY-SA. They are georeferenced to
#     200 m x 200 m extents at an arbitrary location, not the SpaceNet tiles'
#     locations, and use Potato's image-with-extent basemap, so the map
#     needs no network and no tile server.
#   - The original labelers worked in a GIS on 30 cm pan-sharpened GeoTIFFs;
#     here annotators use the polygon tool in the browser.
#   - Scenes 1 and 2 carry deliberately offset suggested polygons
#     (preannotation_field) to show a review-and-correct pass. The original
#     QA/QC was a second expert validating 100% of the areas; that is only
#     imitated by the suggestions.
#   - Guidance items 2 and 7 (off-nadir base shift, adjoining roofs) are
#     reproduced in the instructions, but the synthetic scenes are
#     nadir-view, so they do not exercise them.
#
# Model training (Potato 2.14.0): the `torchvision-segment` trainer
# (kinds geometry and geo, image modality; `pip install
# 'potato-annotation[train-vision]'`) fine-tunes a torchvision Mask R-CNN on
# the polygons drawn over each item's raster, then predicts polygons on
# scenes nobody has outlined. Predictions come back as GeoJSON in EPSG:4326
# and show on the map as suggestions that count as an answer only when an
# annotator edits or accepts them (writeback below). It trains on a raster
# basemap with an extent or a GeoTIFF; a basemap of server tiles has no
# raster and would be left out. It does not serve or deploy a model, and it
# does not export ONNX. Pick the trainer on /admin/training with the admin
# key below.
#
# Run:
#   python potato/flask_server.py start config.yaml -p 8000

annotation_task_name: "SpaceNet building footprints (illustrative scenes)"

task_dir: "."
data_files:
  - sample-data.json
media_directory: media

item_properties:
  id_key: id
  text_key: text

output_annotation_dir: annotation_output
export_annotation_format: jsonl

require_password: false
admin_api_key: "demo-admin-key"

user_config:
  allow_all_users: true
  users: []

annotation_schemes:
  - annotation_type: geo_annotation
    name: building_footprints
    description: "Outline each building footprint as a closed polygon"
    task: draw
    tools: [polygon]
    labels:
      - name: Building
        color: "#D55E00"
    basemap_field: map
    preannotation_field: suggested
    snapping: true
    height: 560
    label_requirement:
      required: false

model_training:
  enabled: true
  writeback:
    schemas: ["building_footprints"]
    include_unlabeled: true
    min_confidence: 0.5

annotation_instructions: |
  Outline every building you can see as one closed polygon with the polygon
  tool, following the SpaceNet building footprint labeling guide.
  Trace the roofline so the polygon fits the footprint, and shift it to the
  base corners where the base of a building is visible because of an
  off-nadir angle. Give buildings squared corners when the building has them,
  and place each corner within 5 pixels of its location on the image.
  Close every polygon and keep polygons from overlapping. Do not add any
  attributes. For adjoining buildings with different heights, capture one
  visible roof for the whole block and shift it to that roof's baseline.
  Where a suggested polygon is already drawn, correct it or delete it.
  The scenes here are synthetic and illustrative.