{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# Visualising Instruments\n\nThis example demonstrates how to use the ``show()`` method on various\ninstrument objects like ``Camera`` and ``Radar`` to create visualisations.\nIt also shows how to annotate plots with geographical positions.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from matplotlib import pyplot as plt\nfrom arguslib.camera.camera import Camera\nimport datetime\n\nfrom arguslib.instruments.instruments import Position\nfrom arguslib.radar.radar import Radar\n\ndt = datetime.datetime(2025, 3, 25, 9)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Plotting camera images\n\nPlotting images on a polar plot, with the axes aligned with the ordinal directions.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "cam = Camera.from_config(\"COBALT\", \"3-7\")\ncam.show(dt)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Annotating positions\n\nWe can annotate a position on the image. Here, we add a red dot at 10km\naltitude above Southampton, a pink dot 10km above Reading, and a dark red\ndot 10km above Chilbolton.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "ax = cam.show(dt)\ncam.annotate_positions(\n    [Position(-1.4419, 51.1553, 10.0)],\n    dt,\n    ax,\n    marker=\"o\",\n    lw=0,\n    color=\"darkred\",\n    label=\"Chilbolton\",\n)\ncam.annotate_positions(\n    [Position(-1.4049, 50.9105, 10.0)],\n    dt,\n    ax,\n    marker=\"o\",\n    lw=0,\n    color=\"red\",\n    label=\"Southampton\",\n)\ncam.annotate_positions(\n    [Position(-0.9783, 51.4550, 10.0)],\n    dt,\n    ax,\n    marker=\"o\",\n    lw=0,\n    color=\"pink\",\n    label=\"Reading\",\n)\n\nax.legend(loc=\"upper left\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Controlling image orientation\n\nWe can also plot the image \"unflipped\", either by setting up the axes to be flipped:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "cam.show(dt, theta_behaviour=\"unflipped_ordinal_aligned\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Or by setting the ``lr_flip`` argument to ``False``.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "cam.show(\n    dt,\n    lr_flip=False,\n)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "We can set the theta behaviour to be \"pixels\", where the theta grid shows\nthe major axes of the pixel grid.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "cam.show(dt, theta_behaviour=\"pixels\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "This lines up with the native image grid, which is seen when we plot on\nnon-polar axes.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "fig, ax = plt.subplots()\ncam.show(dt, ax=ax)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "To still get the rotation, but in place of an existing non-polar set of axes,\nwe can use the ``replace_ax`` argument.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "fig, ax = plt.subplots()\ncam.show(dt, replace_ax=ax)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "The infrastructure can be rigged to plot in a way that doesn't make sense.\nHere, we set up a \"bearing\" axes, but then don't flip the axes, so the angles\ndon't line up with the ordinal directions.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "cam.show(\n    dt,\n    theta_behaviour=\"bearing\",\n    lr_flip=False,\n)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Plotting radar data\n\nRadar objects can also be plotted using the analogous ``show`` function.\nThe axes don't have so much rotating and flipping to do. Following pyart\ndefault behaviour, the positive x direction is towards 0 degrees azimuth\n(i.e. south to north).\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "radar = Radar.from_config(\"COBALT\")\nradar.show(datetime.datetime(2025, 5, 1, 7, 25, 6), var=\"DBZ\")"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.13.5"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}