Visualizing AIXM feature associations
AIXM Graph is a tool that aims at visualizing the various features that can be found in an AIXM dataset along with their associations. The representation is made via an interactive graph where the user can explore the features and how they connect to each other in the specific dataset.
At this link you can have a look at a partial (no upload functionality) demo of the tool and play around with two preloaded AIXM datasets.
The project can get easily up and running in any machine regardless the running OS with the help of Docker.
Before proceeding to the next steps please make sure that you have installed on your machine:
- Linux/Mac users
- Git
- Docker
- Linux users will also need to have a look on some post-installation actions:
- Windows users
Docker Toolbox on Windows (which installs all the required tools and runs the Docker Engine via VirtualBox)
Since Docker runs via VirtualBox, the various app/server sites involved in this demo will not be able to be accessed from your host machine unless you apply some port forwarding rules. You may find instructions about how to do it here. The rule to apply is:
Name Host port Guest Port aixm-graph 3000 3000
Steps:
Get the repository
git clone https://github.com/eurocontrol-swim/aixm-graph.git
cd aixm-graph
Build the image
docker build -t aixm-graph:latest .
Run the container
docker run -d --name aixm_graph -e "PORT=8765" -p 3000:8765 aixm-graph:latest
Make sure that the container is up and running with docker ps
. The output should look like:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
b1c6b3cb3e2b aixm-graph:latest "/bin/sh -c 'gunicor…" 2 seconds ago Up 1 second 80/tcp, 0.0.0.0:3000->8765/tcp aixm_graph
After the steps are successfully completed the project will be available at http://localhost:3000
NOTE for Windows users:
In case the above link does not work, you can use the IP used by Virtual Box. This can be found while starting the docker interactive shell:
In the above case the tool can be accessed by http://192.168.99.100:3000. Needless to mention that you'll need to replace the IP with yours.
In case a new version of the tool is available you can update via the following steps:
Update the git repository (from the roop directory of the project)
git pull --rebase origin master
Stop/remove the relevant container in case AIXM Graph already runs
docker rm -f aixm_graph
Then you can follow the installation steps from Build the image
onward.
The project is divided in two parts: server and client.
The server is the backend where the uploading and processing of the datasets happens. The api is implemented with the miniframework Flask and the dataset processing is made with the library lxml.
The client is the frontend where the datasets are visualized. The interface is implemented with the framework Vue.js while the graphs are created using the library vis-network.
In order to run the project locally on your machine for development reasons you need to start the server and the client separately.
First make sure that python and conda are installed on your system.
Create a dedicated environment using conda
cd server
conda env -create --name aixm-graph -f requirements.yml
activate the environment
source activate aixm-graph
install the server package in your env
pip install .
run the local server
python ./aixm_graph/app.py
The server should now be able to receive calls at http://localhost:5000
Make sure you have npm installed on your system
First install the dependencies
cd client
npm install
and then run the client locally
npm run serve
The client should now be available at http://localhost:8080
Since the project is packaged with docker there are many options of easily deploying it in the cloud. On of them is Heroku and below you can find the steps about how to achieve this with the Container Registry & Runtime method:
Make sure you have the Heroku CLI installed on you system
First create a heroku app
cd aixm-graph
heroku create <app-name>
Login to the Heroku Container Registry:
heroku container:login
Make sure to replace in the below commands with the name of the Heroku app that you just created.
Build the image and tag it with the following format:
docker build -t registry.heroku.com/<app-name>/web
Push the image to the registry:
docker push registry.heroku.com/<app-name>/web
Release the image:
heroku container:release --app <app-name> web
The app should now be available at https://.herokuapp.com
The tool does not require any specific configuration by the user as everything has been pre-configured. However, its
worth looking at the configuration of the AIXM features in case something needs to be changed indeed. It can be found
under aixm-graph/server/aixm_graph/config.yml
.
The config entry for each feature looks like:
AerialRefuelling: # the name of the feature as it is found in the dataset
abbrev: ARF # a pre-selected abbreviation
color: '#f0f8ff' # the color of the graph node that will represent this type of features
shape: square # the shape of the graph node that will represent this type of features
fields: # the elements that will be extracted from the timeSlice elements of that feature
concat: true # determines whether the field values will be displayed concatenated or not
names: # the list of all the element names
- designatorPrefix
- designatorNumber
- designatorSuffix
- designatorDirection
NOTE: if a field name is wrongly configured the parsing of the dataset will fail.
NOTE: The abbreviation has to be unique otherwise it will lead to confusion.
NOTE: the available shapes are limited to:
dot, triangle, triangleDown, box, square, diamond, hexagon. ellipse
.
In the following sub-sections you can find a detailed description of the layout and the available features of the AIXM Graph tool as well as instructions about how to interact with it. If you just want a quick reference of them you can jump directly at the end of this section.
The top bar of the tool offers two different actions. One for uploading/processing an AIXM dataset and one for navigating among already uploaded datasets.
A new dataset can be uploaded to the server by clicking the Upload
button at the top-right corner.
As soon as the dataset is uploaded a pre-processing will take place including:
Each xml
element/feature is parsed and stored along with it's pre-configured key elements in memory.
Typically, a feature holds references (xlink:href
) to other features it's associated with. However, this association
has one direction in a typical AIXM dataset. In order to facilitate the creation of the graph and illustrate better the
associations among the features we generate bi-directional connections on all of them. In other words, a feature will
keep in memory references for all the other features which keep a reference to it. The procedure goes as following:
for each xlink of a feature
for each other target_feature check:
if (
the xlink:href matches the gml:id of the target_feature
or the xlink:href matches the identifier of the target_feature
or the xlink:href matches the gml:id of any of the properties of the target_feature
)
then:
an extension (reverse association) is created in the target_feature
otherwise:
the xlink is marked as broken
Keep in mind that the uploading and the processing of the dataset depends heavily on its size. Although the procedure has been optimized and the whole processing/storing happens in memory, the final memory footprint equals more or less the original size of the dataset. Thus, it has to be taken into consideration when attempting to upload/process a dataset on a machine with limited resources.
As soon as a dataset is uploaded and processed it will be added in the dropdown list at the top-right corner. From there you can opt for it any time and its data will be displayed in the dataset area.
The left side of the tool is the dataset area. This is where details and actions of the currently loaded dataset will be displayed.
As soon as the name of the dataset is clicked, another button will be revealed just under it allowing the user to
download the skeleton file of the currently uploaded dataset. It will have the same structure as the original one but it
will be a subset of it as it will contain only the pre-configured key elements and the xlink
references. Additionally, all the references that were created during the processing phase will be added as extension
elements. Lastly its name will be same as the original dataset's postfixed with _skeleton
, i.e.
<original_filename>_skeleton.xml
.
Next comes the features' area. The total number is reported in the title of the area, i.e. (146) Features
and all the
extracted features are listed below grouped by name, each one reporting the total number of its features. In case one or
more features of a group has broken links then a report icon will be displayed alongside.
Upon mouse hover more details will be revealed about the broken xlinks.
Right below the title there is a switch filter allowing the user to display all the feature groups or only those ones with a report.
Every feature group is clickable and as soon as any of them is clicked the respective graph will be displayed on the graph area.
The main area of the tool belongs to the graph area, where the features and their associations are visualized. It is split in two parts: the top bar which contains manipulation actions as well as reporting of the currently displayed graph and the graph where the actual graph lives.
As soon as a feature group is selected (clicked) from the dataset area a graph of its features and their associations will be displayed. What is displayed though can be manipulated in three ways:
The user can limit the displayed features by filtering them on the values of their key fields. The filter is initiated as
soon as Enter
is pressed.
NOTE: the filter applies only on the features of the selected feature group and not on their associations
In case a feature group contains too many features they will be limited by the selected Features per page
from the top
bar. The current available options are 5, 10, 15, 20
.
The graph is represented by nodes and edges. The nodes represent the features of the selected feature group as well as their associations and the edges indicate their connection in the dataset.
NOTE: when the graph is loaded or expanded, its performance depends heavily on the number of nodes currently being displayed. In large datasets it is common that a feature can be associated with a big number of other features which means that the created graph will be too big rendering the screen unresponsive.
This is a current limitation of the tool but it can be partially handled either by limiting the displayed features per page or by pruning the first level associations of the feature. If none of those options work you can always refresh the page in your browser and explore another feature group.
Each feature group is assigned with a pre-configured color and shape. Thus each feature as well as
its associations are represented as a graph node of a specific shape and color. In case an association is broken
(i.e. does not correspond to any feature in the dataset) it will be represented as a red star
.
Additionally, each node will be labeled by a pre-configured
abbreviation along with the values of of its key fields separated by ,
, unless its configured to keep them concatenated.
For example an Airspace
feature could be labeled asASE: CTA_P,EADD1
where CTA_P
is its type
and EADD1
its designator
.
A Route
feature though, which needs its field values concatenated, will be labeled as RTE: UA4ATS
where U
is the
designatorPrefix
, A
the designatorSecondLetter
, 4
the designatorNumber
and ATS
its type
.
As long as the mouse hovers over a node, then a popup box will appear displaying a table with more information about the
node including its feature name, its UUID
, its key field along with their values as well as how many associations it
is connected with.
TIP: as long as the popup box is displayed the user can copy its UUID into the clipboard by pressing
Ctrl + C
-
Left click: If an association feature node is connected with features other than the currently displayed ones then its label will be prefixed with
[+]
, for example[+] NAV: VOR,LMD
. That means that the association is expandable and it can be expanded just by clicking (left click) on it. Then all its associations will be fetched from the server and will be appended in the graph. -
Right click: A feature can be displayed in a single feature mode by right clicking on an it. A new graph will then be created showing only the selected feature and its associations.
The edges that connect the association features with the selected feature are named by the timeSlice
those
associations were found in and more specifically by its sequenceNumber
and/or its correctionNumber
.
If the association is direct (found under the feature) the edge will be directed from the feature to
its association. Otherwise, if the association is reverse the direction of the edge will be from the association
to the feature. Lastly, if an edge connects a feature with a broken association it will be dashed.
Lastly, in case the are more pages to display (i.e. more features) the user can navigate through them by clicking on the
Next
or Prev
buttons.
For every feature group that is selected, along with its graph there is also displayed a table with all the different associations grouped by name. This table is placed at the top left corner of the graph and every association group has a checkbox in front of it checked by default. As soon as a checkbox is deselected, the corresponding associations will be removed from the graph. In case an association has been expanded their descendants will be removed as well. If the checkbox is selected again, the corresponding associations will re-appear in the graph, however, without their descendants. These actions can also apply in bulk mode by selecting/deselecting the checkbox at the header of the table.
- Upload dataset: at top-right corner button.
- Navigate through datasets: at top-right corner dropdown list.
- Download skeleton: at dataset area (left side) under the name of the dataset.
- Filter feature groups by report: at dataset area (left side) under the Features title.
- Load graph for a specific feature group: click on a feature group at the dataset area.
- Manipulate the graph
- via the top bar of graph area:
- filter the features on their key field values (type filter key and press
Enter
) - select the features per page to display.
- filter the features on their key field values (type filter key and press
- via the graph:
- navigate to next/previous pages, if any.
- click on a feature node whose label starts with
[+]
to expand it with its associations. - right-click on a feature node to display it in single feature mode.
- via the associations table:
- deselect the checkbox of an association to remove all the corresponding nodes from the graph along with its descendants if any.
- select the checkbox of an association to add the corresponding nodes back in the graph.
- via the top bar of graph area:
If you'd like to contribute, please fork the repository and use a feature branch. Pull requests are warmly welcome.
- Repository: https://github.com/eurocontrol-swim/aixm-graph
- Issue tracker: https://github.com/eurocontrol-swim/aixm-graph/issues
- AIXM: http://aixm.aero/
See LICENSE