ais-dotnet-bing-maps-geofence.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# AIS.Net Geofence Demo\n",
        "\n",
        "This is a sample using [endjin's](https://endjin.com) open source [AIS.Net libraries](https://github.com/ais-dotnet/) to demonstrate how you can ingest, decode and display Automatic Identification System (AIS) [AIVDM/AIVDO](https://gpsd.gitlab.io/gpsd/AIVDM.html) NMEA messages from the Norwegian Coastal Administration's marine network (available under [Norwegian license for public data (NLOD)](https://data.norge.no/nlod/en/2.0)) to view real-time vessel positions.\n",
        "\n",
        "This sample extends the real-time demo and shows how you can use a GeoJSON shape to define a geofence and apply it as a filter, so that only vessels within that geofence are displayed."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Configure Ais.Net Receiver\n",
        "\n",
        "Pull in the Ais.Net & NetTopologySuite NuGet packages."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "csharp"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "#r \"nuget:Ais.Net.Receiver\"\n",
        "#r \"nuget:Ais.Net.Models\"\n",
        "#r \"nuget:NetTopologySuite.IO.GeoJSON4STJ\""
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Add the namespaces we're going to use:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "csharp"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "using Ais.Net;\n",
        "using Ais.Net.Models;\n",
        "using Ais.Net.Models.Abstractions;\n",
        "using Ais.Net.Receiver.Configuration;\n",
        "using Ais.Net.Receiver.Receiver;\n",
        "\n",
        "using Microsoft.DotNet.Interactive;\n",
        "using Microsoft.DotNet.Interactive.Commands;\n",
        "\n",
        "using NetTopologySuite.Features;\n",
        "using NetTopologySuite.Geometries;\n",
        "using NetTopologySuite.IO.Converters;\n",
        "\n",
        "using System;\n",
        "using System.IO;\n",
        "using System.Reactive; \n",
        "using System.Reactive.Linq;\n",
        "using System.Text.Json;\n",
        "using System.Threading;"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "We want to filter to only those vessels in Skagerrak. You can create your own GeoJson geofences using [geojson.io](https://geojson.io/)"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "csharp"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "var options = new JsonSerializerOptions{ ReadCommentHandling = JsonCommentHandling.Skip };\n",
        "options.Converters.Add(new GeoJsonConverterFactory());\n",
        "\n",
        "FeatureCollection skagerrak = JsonSerializer.Deserialize<FeatureCollection>(File.ReadAllText(\"data/geofence/skagerrak.json\"), options);\n",
        "var geofence = skagerrak[0].Geometry;"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "You can choose to run the notebook from the live Norwegian Costal Administration AIS network:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "csharp"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "INmeaReceiver receiver = new NetworkStreamNmeaReceiver(host: \"153.44.253.27\", port: 5631, retryAttemptLimit: 100, retryPeriodicity: TimeSpan.Parse(\"00:00:00:00.500\"));"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Or from a data file containing a capture from the Norwegian Costal Administration AIS network (using [Ais.Net.Receiver.Storage.Azure.Blob](https://github.com/ais-dotnet/Ais.Net.Receiver/tree/master/Solutions/Ais.Net.Receiver.Storage.Azure.Blob))"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "csharp"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "INmeaReceiver receiver = new FileStreamNmeaReceiver(\"data/nmea-ais/raw/2021/03/01.nm4\", TimeSpan.FromMilliseconds(0.5));"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Create the host with your selected receiver:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "csharp"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "var receiverHost = new ReceiverHost(receiver);"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# Set up Bing Maps"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "We register a client side command handler which will execute the UpdateVesselPosition JavaScript function when invoked."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "javascript"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "kernel.root.findKernelByName(\"javascript\").registerCommandHandler({commandType: 'VesselPositionCommand', handle: c => {\n",
        "    console.log(c.commandEnvelope);\n",
        "    UpdateVesselPosition(c.commandEnvelope.command);\n",
        "}});"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "We create a Bing Map widget with custom functions that add vessels via custom pushpins. You will need to [get your own Bing Maps developer API Key](https://docs.microsoft.com/en-us/bingmaps/getting-started/bing-maps-dev-center-help/getting-a-bing-maps-key) and add that in the credentials below:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "html"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "<!DOCTYPE html>\n",
        "<html>\n",
        "<head>\n",
        "    <title></title>\n",
        "    <meta charset=\"utf-8\" />\n",
        "    <script type='text/javascript'\n",
        "            src='http://www.bing.com/api/maps/mapcontrol?callback=GetMap' \n",
        "            async defer></script>\n",
        "    <script type='text/javascript'>\n",
        "        var map;\n",
        "\n",
        "        function UpdateVesselPosition(position) {\n",
        "\n",
        "            var pin = getPushpinById(position.mmsi);\n",
        "            var loc = new Microsoft.Maps.Location(position.lat, position.lon);\n",
        "\n",
        "            if (pin == null)\n",
        "            {\n",
        "                var pin = new Microsoft.Maps.Pushpin(loc, {\n",
        "                                icon: createArrow(position.courseOverGroundDegrees, position.color),\n",
        "                                title: position.name,\n",
        "                                subTitle: position.mmsi\n",
        "                            });\n",
        "                            \n",
        "                pin.metadata = {\n",
        "                    id: position.mmsi\n",
        "                };\n",
        "\n",
        "                map.entities.push(pin);\n",
        "            }\n",
        "            else\n",
        "            {\n",
        "                pin.setLocation(loc);\n",
        "            }\n",
        "        }\n",
        "\n",
        "        function GetMap()\n",
        "        {\n",
        "            map = new Microsoft.Maps.Map('#myMap', {\n",
        "                credentials: \"ADD YOUR BING MAPS API KEY\"\n",
        "            });\n",
        "\n",
        "            map.setView({ center: map.getCenter(), zoom: 3 });\n",
        "        }\n",
        "\n",
        "        function createArrow(heading, hexColor) {\n",
        "            var c = document.createElement('canvas');\n",
        "            c.width = 24;\n",
        "            c.height = 24;\n",
        "\n",
        "            var ctx = c.getContext('2d');\n",
        "        \n",
        "            //Offset the canvas such that we will rotate around the center of our arrow\n",
        "            ctx.translate(c.width * 0.5, c.height * 0.5);\n",
        "\n",
        "            //Rotate the canvas by the desired heading\n",
        "            ctx.rotate(heading * Math.PI / 180);\n",
        "\n",
        "            //Return the canvas offset back to it's original position\n",
        "            ctx.translate(-c.width * 0.5, -c.height * 0.5);\n",
        "        \n",
        "            ctx.fillStyle = hexColor;\n",
        "\n",
        "            //Draw a path in the shape of an arrow.\n",
        "            ctx.beginPath();\n",
        "            ctx.moveTo(12, 0);\n",
        "            ctx.lineTo(5, 20);\n",
        "            ctx.lineTo(12, 15);\n",
        "            ctx.lineTo(19, 20);\n",
        "            ctx.lineTo(12, 0);\n",
        "            ctx.closePath();\n",
        "            ctx.fill();\n",
        "            ctx.stroke();\n",
        "\n",
        "            //Generate the base64 image URL from the canvas.\n",
        "            return c.toDataURL();\n",
        "        }\n",
        "\n",
        "        function getPushpinById(id) \n",
        "        {\n",
        "            console.log(\"find \" + id);\n",
        "            var pin;\n",
        "            for (i = 0; i < map.entities.getLength(); i++) {\n",
        "                pin = map.entities.get(i);\n",
        "\n",
        "                if(pin.metadata && pin.metadata.id === id){\n",
        "                    return pin;\n",
        "                }\n",
        "            }\n",
        "        }\n",
        "    </script>\n",
        "    <style>\n",
        "        #myMap {\n",
        "            position: relative;\n",
        "            width: 100%;\n",
        "            height: 800px;\n",
        "        }\n",
        "    </style>\n",
        "</head>\n",
        "<body>\n",
        "    <div id=\"myMap\"></div>\n",
        "</body>\n",
        "</html>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "We create a .NET server side Kernel command for passing new vessel positions to the client side Kernel."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "csharp"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "public class VesselPositionCommand : KernelCommand\n",
        "{\n",
        "    public VesselPositionCommand(): base(\"javascript\"){}\n",
        "\n",
        "    public double Lon { get;set; }\n",
        "    public double Lat { get;set; }\n",
        "    public float CourseOverGroundDegrees { get;set; }\n",
        "    public string Mmsi { get;set; }\n",
        "    public string Name { get;set; }\n",
        "    public string Color { get;set; }\n",
        "}"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "csharp"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "var jsKernel = Kernel.Root.FindKernelByName(\"javascript\");\n",
        "jsKernel.RegisterCommandType<VesselPositionCommand>();"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Create the Rx Query\n",
        "\n",
        "Use Rx's operators to multiplex the AIS Message Types 1,2,3,5, 18, 19, 24 containing all the different values we need for visualisation. We use the .NET Interfaces applied to the Record types to expose properties as higher level concepts like `IVesselNavigation` and `IVesselName` for ease of higher order programming constructs. "
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "csharp"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "IObservable<IGroupedObservable<uint, IAisMessage>> byVessel = receiverHost.Messages.GroupBy(m => m.Mmsi);\n",
        "\n",
        "var vesselNavigationWithNameStream =\n",
        "    from perVesselMessages in byVessel\n",
        "    let vesselNavigationUpdates = perVesselMessages.OfType<IVesselNavigation>()\n",
        "    let vesselNames = perVesselMessages.OfType<IVesselName>()\n",
        "    let shipTypes = perVesselMessages.OfType<IShipType>()\n",
        "    let vesselLocationsWithNames = Observable.CombineLatest(vesselNavigationUpdates, vesselNames, shipTypes, (navigation, name, shipType) => (navigation, name, shipType))\n",
        "    from vesselLocationAndName in vesselLocationsWithNames\n",
        "    where geofence.Contains(GeometryFactory.Default.CreatePoint(new Coordinate(vesselLocationAndName.navigation.Position.Longitude, vesselLocationAndName.navigation.Position.Latitude)))\n",
        "    select (mmsi: perVesselMessages.Key, vesselLocationAndName.navigation, vesselLocationAndName.name, vesselLocationAndName.shipType.ShipType);\n",
        "    "
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Add a helper method to colourize different vessel types"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "csharp"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "private static string ToHex(ShipTypeCategory shipTypeCategory)\n",
        "{\n",
        "    return shipTypeCategory switch\n",
        "    {\n",
        "        ShipTypeCategory.NotAvailable => \"#96F9A1\",\n",
        "        ShipTypeCategory.Reserved => \"#1C79F0\",\n",
        "        ShipTypeCategory.WingInGround => \"#F8BA97\",\n",
        "        ShipTypeCategory.SpecialCategory3 => \"#F8B594\",\n",
        "        ShipTypeCategory.HighSpeedCraft => \"#FFFF55\",\n",
        "        ShipTypeCategory.SpecialCategory5 => \"#43FFFF\",\n",
        "        ShipTypeCategory.Passenger => \"#203DB3\",\n",
        "        ShipTypeCategory.Cargo => \"#97F9A1\",\n",
        "        ShipTypeCategory.Tanker => \"#FF464E\",\n",
        "        ShipTypeCategory.Other => \"#56FFFF\",\n",
        "        _ => \"#96F9A1\",\n",
        "    };\n",
        "}"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Create the Rx Subscription\n",
        "We subscribe to the observable stream, deconstruct the incoming position and convert it to a command which can be send via the server side Kernel to the client side Kernel."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "csharp"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "vesselNavigationWithNameStream.Subscribe(navigationWithName =>\n",
        "{\n",
        "    (uint mmsi, IVesselNavigation navigation, IVesselName name, ShipType shipType) = navigationWithName;\n",
        "\n",
        "    jsKernel.SendAsync(new VesselPositionCommand \n",
        "    { \n",
        "        Lat = navigation.Position.Latitude, \n",
        "        Lon = navigation.Position.Longitude,\n",
        "        CourseOverGroundDegrees = navigation.CourseOverGroundDegrees ?? 0,\n",
        "        Mmsi = mmsi.ToString(),\n",
        "        Name = name.VesselName.CleanVesselName(),\n",
        "        Color = ToHex(shipType.ToShipTypeCategory())\n",
        "    }, \n",
        "    System.Threading.CancellationToken.None);\n",
        "});"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Start to ingest the AIS Data\n",
        "\n",
        "To start processing data, start the long running AIS Receiver Host."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "csharp"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "var cts = new CancellationTokenSource();\n",
        "var task = receiverHost.StartAsync(cts.Token);"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "If you want to cancel the long running process, use the CancellationTokenSource."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "csharp"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "cts.Cancel();"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": ".NET (C#)",
      "language": "C#",
      "name": ".net-csharp"
    },
    "language_info": {
      "file_extension": ".cs",
      "mimetype": "text/x-csharp",
      "name": "csharp",
      "pygments_lexer": "csharp",
      "version": "8.0"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 4
}