AmeliaMaps

This repository contains the code for creating the map representations used for training our model in:

Amelia: A Large Dataset and Model for Airport Surface Movement Forecasting [paper]

Ingrid Navarro *, Pablo Ortega-Kral *, Jay Patrikar *, Haichuan Wang, Zelin Ye, Jong Hoon Park, Jean Oh and Sebastian Scherer

Overview

AmeliaMaps: Tool for creating vectorized context graphs for intent prediction. It takes the limit of the airport in the form of a .json file and the .osm file of the airport as input and generates a graph in the form of a .osm file and the corresponding .pkl file. The graph is a dictionary with the keys as the node ids and the values as the node attributes. The node attributes contain the coordinates of the node, the type of the node, and the edges connected to the node. The edges are represented as a list of tuples where each tuple contains the id of the connected node and the distance between the two nodes.

Example of the airport processing pipeline.

The main goal is to simplify the graph to contain only the relevant information for the movement areas of the airport. From the raw OSM data to the processed graph.

Example of th KSEA airport map and the processed `.osm`

For visualizing the simplification process you can use the semantic_graph notebook to see the effect of each step in the graph. Currently, the sanitize function only keeps the largest subgraph, so make sure all the relevant movement areas are fully connected.

Pre-requisites

Dataset

To run this repository, you first need to download the amelia dataset. Follow the instructions here to download the dataset.

Once downloaded, create a symbolic link into datasets:

cd datasets
ln -s /path/to/amelia .

Note that the dataset's OSM files are contained in the assets folder:

datasets
├── amelia
│   ├── assets
│       ├── <airport_code>
|            ├── <airport_code>.osm
|            ├── limits.json

Manual pre-processing

When using this tool with airports downloaded from OSM, these need to have certain characteristics to be compatible with the processing script.

• Runways must be grouped in a single edge. There can be multiple nodes on the runway, but these must be grouped in one single way.
• Runway end nodes cannot be connected "laterally" to taxiways or holdlines. This is because the centerlines will be extended. If a ramp connects to the end of the runway, insert a surrogate node below it.
• Edges must contain aeroway keys indicating the type of zone, i.e. aeroway: taxiway. Hold lines nodes must have the equivalent tag aeroway : holding_position.

For the amelia dataset, the airports have been pre-processed to meet these requirements. The limits.json file contains the bounding box of the airport and the <airport_code>.osm file contains the OSM data of the airport.

Installation

Make sure that you have conda installed.

Recommended: Use the install.sh to download and install the Amelia Framework:

chmod +x install.sh
./install.sh amelia

Alternatively, refer to INSTALL.md for manual installation.

Note: AmeliaMaps requires only requires the Amelia dataset to run, only refer to AmeliaMaps installation.

How to use

Graph processing

After simplifying the desired .osm file manually (in the case of amelia it is already done), use the graph_processor.py tool to generate the corresponding pickle file containing the polyline dictionary for the graph. Run the following command: MapProcessor

python amelia_maps/graph_processor.py --airport <airport> \
                                      --base_dir <base_dir> \
                                      --output_dir <output_dir>
                                      --save \
                                      --show \

Where:

• <airport> is the ICAO code of the airport you want to process. It can be one of the following: kbos, kdca, kewr, kjfk, klax, kmdw, kmsy, ksea, ksfo, panc. By default, it is set to KBOS.
• <base_dir> is the base directory where the airport files are located. By default, it is set to ./datasets/amelia.
• <output_dir> is the directory where the processed files will be saved. By default, it is set to ./output.
• --save flag to save the processed airport data. The output files are .pkl .osm and a .png.
• --show flag to show the processed graph. By default it is set to False

Example usage

This command will process the Boston Logan International Airport (KBOS):

python amelia_maps/graph_processor.py --airport kbos \
                                      --base_dir ./datasets/amelia \
                                      --output_dir ./datasets/amelia/graph_data \
                                      --save

And save the processed data to the specified output directory. The resulting files would be:

./datasets/amelia/graph_data
├── kbos
│   ├── semantic_graph.pkl
│   ├── semantic_kbos.osm
│   ├── semantic_graph.png

Get Map Background

In order tho get the map background for the processed graph and its limits, you can use the get_map_background.py script. This script will download the map background from the OpenStreetMap API and save it as a .png file. Run the following command:

python amelia_maps/get_map_background.py --base_dir <base_dir> \
                                         --airport <airport> \
                                         --style <style> \
                                         --zoom <zoom> \
                                         --output <output> \
                                         --update_datasets

Where:

• <base_dir> is the base directory where the airport files are located. By default, it is set to ./datasets/amelia.
• <airport> is the ICAO code of the airport you want to process. It can be one of the following: any airport from the amelia_maps/utils/airports.txt file. By default, it is set to all. It will download the map background for all the airports in the file.
• <style> is the style of the map background. It can be one of the following: positron, darkmatter, voyager, mapnik, humanitarian, cyclosm, stadia_outdoors. By default, it is set to mapnik.
• <zoom> is the zoom level of the map background. By default, it is set to 18.
• <output> is the directory where the map background will be saved. By default, it is set to ./output/<airport>.
• --update_datasets flag to update the datasets with the new map background. By default it is set to False. It will update the limits.json file with the new map background in the <base_dir> dataset.

Map Background Usage

This command will download the map background for the Boston Logan International Airport (KBOS) with the mapnik style and a zoom level of 18:

python amelia_maps/get_map_background.py --airport kbos --style mapnik --zoom 18

Code details

The MapProcessing Class

For processing the OSM files obtained from public sources, use MapFromNet.

Each of the steps in the processing pipeline is separated into methods of the class. All these methods affect the graph attribute of the class.

MapFromNet.preprocess_map(extension_distance = 1609, supersample_value = 80, save = True, show = False, verbose = True)

Contains the predefined routine for simplifying the routing graphs. The method takes the following parameters:

• extension_distance: Distance in meters to extend runway endpoints. The default is 1,609, equivalent to 1 nautical mile.
• supersample_value: Value MapProcessor to supply to the supersampling method. Note that the supersampling threshold and node spacing are the same for consistency in the processed graph.
• save: flag for toggling saving the processed graph in XML format.
• show: flag for toggling plotting the processed graph.
• verbose: If set to true, it displays a statistic summary of the processed graph.

MapFromNet.map_to_polylines()

Once the map has been preprocessed, it can be converted to vectorized form and stored as a pickle file using this method.

MapFromNet.semantify_nodes()

Given the raw graph, search the nodes for relevant aeroway tags and classify important nodes.

MapFromNet.get_routing_graph()

Classifies the relevant centerlines for movement areas and removes unnecessary edges. Runway endpoint nodes are stored in the MapFromNet.runway_pairs attribute. Consecutive elements in this list represent the pair of endpoints for a given runway.

MapFromNet.extend_runways(extension_distance)

Displaces all runway endpoints by the specified amount following the slope of the runway. It takes in the following parameter:

• extension_distance: Distances in meters to extend runway endpoints. The default is 1,609, equivalent to 1 nautical mile

MapFromNet.sanitize()

Removes all nodes with default class (node_type == 0) and keeps only the largest subgraph. This assumes the movement area of the airport is a fully connected graph.

MapFromNet.supersample_graph(thr, node_separation)

Identifies edges below the specified threshold and supersamples them, placing a node every specified meters. The method takes the following parameters:

• thr: Minimum length, in meters, of an edge to be supersampled.
• node_separation: separation in meters between the placed nodes.

MapFromNet.display_and_save(save, show)

Displays the graph found in MapFromNet.graph with the semantic colors. This requires the nodes to have a node_type attribute. The method takes the following parameters:

• save: Flag to save the graph in XML format. The graph is saved under <output_dir>/<airport>/semantic_<airport>.osm

BibTeX

If you find our work useful in your research, please cite us!

@inbook{navarro2024amelia,
  author = {Ingrid Navarro and Pablo Ortega and Jay Patrikar and Haichuan Wang and Zelin Ye and Jong Hoon Park and Jean Oh and Sebastian Scherer},
  title = {AmeliaTF: A Large Model and Dataset for Airport Surface Movement Forecasting},
  booktitle = {AIAA AVIATION FORUM AND ASCEND 2024},
  chapter = {},
  pages = {},
  doi = {10.2514/6.2024-4251},
  URL = {https://arc.aiaa.org/doi/abs/10.2514/6.2024-4251},
  eprint = {https://arc.aiaa.org/doi/pdf/10.2514/6.2024-4251},
}