example_usage.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Example Usage\n",
    "This notebook covers example use cases of how the `satellite_czml` package can be used.  The images in this notebook are not the direct output of each cell.  They are taken from the Plotly Dash app that runs at the very end of this notebook.\n",
    "\n",
    "More information can be found here: [https://github.com/cassova/satellite-czml](https://github.com/cassova/satellite-czml)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[['ISS (ZARYA)',\n",
       "  '1 25544U 98067A   21016.23305200  .00001366  00000-0  32598-4 0  9992',\n",
       "  '2 25544  51.6457  14.3113 0000235 231.0982 239.8264 15.49297436265049'],\n",
       " ['KESTREL EYE IIM (KE2M)',\n",
       "  '1 42982U 98067NE  21016.10657201  .00026135  00000-0  14287-3 0  9999',\n",
       "  '2 42982  51.6330 269.7313 0003870 174.0454 186.0594 15.79671909184560'],\n",
       " ['DELLINGR (RBLE)',\n",
       "  '1 43021U 98067NJ  21016.08538968  .00031421  00000-0  15505-3 0  9997',\n",
       "  '2 43021  51.6303 266.6367 0003507 141.7069 218.4183 15.81804201180375'],\n",
       " ['TEMPEST-D',\n",
       "  '1 43547U 98067NV  21016.13692563  .00010875  00000-0  87195-4 0  9993',\n",
       "  '2 43547  51.6351 313.7126 0006282 124.9571 235.2018 15.71624838142830']]"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import urllib\n",
    "\n",
    "url = 'https://celestrak.com/NORAD/elements/stations.txt'\n",
    "tles = [l.decode(\"utf-8\").strip() for l in urllib.request.urlopen(url).readlines()]\n",
    "tle_list = [[tles[i],tles[i+1],tles[i+2]] for i,_ in enumerate(tles) if i%3==0]\n",
    "small_tle_list = tle_list[:4]\n",
    "small_tle_list"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Simple Example\n",
    "`tle_list` must be a list of lists even if it only contains one TLE entry."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[['ISS (ZARYA)',\n",
       "  '1 25544U 98067A   21016.23305200  .00001366  00000-0  32598-4 0  9992',\n",
       "  '2 25544  51.6457  14.3113 0000235 231.0982 239.8264 15.49297436265049']]"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "single_tle = [tle_list[0]]\n",
    "single_tle"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "from satellite_czml import satellite_czml\n",
    "\n",
    "single_czml = satellite_czml(tle_list=single_tle).get_czml()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![Simple Example](screenshots/simple_czml.png \"Simple Satellite Example\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Multiple Satellite Example"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "multiple_czml = satellite_czml(tle_list=small_tle_list).get_czml()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![Multiple Example](screenshots/multiple_czml.png \"Multiple Satellite Example\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Specifying Argument Lists\n",
    "`tle_list` can be either contain lists of 3 elements (which include name as the first element) or as 2 elements (only the TLE data).  If using the latter, `name_list` must also be provided.\n",
    "\n",
    "Each list must be the same length."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "from datetime import datetime, timedelta\n",
    "import random\n",
    "\n",
    "name_list = [t[0] for t in small_tle_list] \n",
    "description_list = ['Station: ' + t[0] for t in small_tle_list]\n",
    "color_list = [[random.randrange(256) for x in range(3)] for x in range(len(small_tle_list))]\n",
    "size_list = [7] * len(small_tle_list)\n",
    "\n",
    "czml_obj = satellite_czml(tle_list=small_tle_list, name_list=name_list, description_list=description_list,\n",
    "                          color_list=color_list, speed_multiplier=1, use_default_image=False,\n",
    "                          marker_scale_list=size_list, show_label=False, show_path=False,\n",
    "                          ignore_bad_tles=True)\n",
    "multiple_czml_p = czml_obj.get_czml()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![Specifying Arguments Example](screenshots/multiple_czml_p.png \"Specifying Arguments Example\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Create One-by-One\n",
    "Instead of generating several lists to pass to `satellite_czml`, you can create a single list of `satellite` objects."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "from satellite_czml import satellite\n",
    "\n",
    "multiple_sats=[]\n",
    "for tle in small_tle_list:\n",
    "    sat = satellite(tle,\n",
    "                    description='Station: ' + tle[0],\n",
    "                    color = [random.randrange(256) for x in range(3)],\n",
    "                    marker_scale=12,\n",
    "                    use_default_image=False,\n",
    "                    start_time=datetime.strptime('2020-01-01 00:00:00','%Y-%m-%d %H:%M:%S'),\n",
    "                    end_time=datetime.strptime('2020-01-01 01:00:00','%Y-%m-%d %H:%M:%S'),\n",
    "                    show_label=True,\n",
    "                    show_path=True,\n",
    "                   )\n",
    "    multiple_sats.append(sat)\n",
    "    \n",
    "\n",
    "czml_obj = satellite_czml(satellite_list=multiple_sats)\n",
    "multiple_czml_c = czml_obj.get_czml()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![Create One-by-One Example](screenshots/multiple_czml_c.png \"Create One-by-One Example\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Modifying a Satellite"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "last_sat_key = list(czml_obj.satellites.keys())[-1]\n",
    "last_sat = czml_obj.satellites[last_sat_key]\n",
    "\n",
    "# Change the path to display the orbit path\n",
    "last_sat.build_path(rebuild=True,\n",
    "                    show=True,\n",
    "                    color=[255, 255, 0, 127],\n",
    "                    width=3\n",
    "                   )\n",
    "\n",
    "# Change the label look\n",
    "last_sat.build_label(rebuild=True,\n",
    "                     show=True,\n",
    "                     font='12pt Arial',\n",
    "                     color=[255, 255, 0, 200],\n",
    "                     outlineColor=[0, 0, 0, 127],\n",
    "                     outlineWidth=3,\n",
    "                    )\n",
    "\n",
    "# Change the marker (billboard)\n",
    "last_sat.build_marker(rebuild=True,\n",
    "                      size=18,\n",
    "                      outlineColor=[0, 0, 0, 128],\n",
    "                     )\n",
    "\n",
    "modified_czml = czml_obj.get_czml()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![Modifying Example](screenshots/modified_czml.png \"Modifying Example\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Display in Cesium using Plotly Dash\n",
    "Replace `YOUR_CESIUM_API_KEY` with your API key from [Cesium](https://cesium.com/) or add to a file `cesium.key` in the same folder as the notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#apikey = 'YOUR_CESIUM_API_KEY'\n",
    "apikey = open('cesium.key').read().strip()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import dash\n",
    "import dash_html_components as html\n",
    "import dash_core_components as dcc\n",
    "from dash.dependencies import Input, Output\n",
    "\n",
    "\n",
    "external_css = ['https://cesium.com/downloads/cesiumjs/releases/1.76/Build/Cesium/Widgets/widgets.css']\n",
    "\n",
    "external_scripts = [{'src':'https://cesium.com/downloads/cesiumjs/releases/1.76/Build/Cesium/Cesium.js'}]\n",
    "\n",
    "app = dash.Dash(__name__,\n",
    "                title='satellite_czml',\n",
    "                external_scripts=external_scripts,\n",
    "                external_stylesheets=external_css)\n",
    "\n",
    "app.layout = html.Div(children=[\n",
    "    dcc.Dropdown(id='choose_czml_dd',\n",
    "                 options=[\n",
    "                     {'label': 'Single CZML', 'value': 'single_czml'},\n",
    "                     {'label': 'Multiple CZML', 'value': 'multiple_czml'},\n",
    "                     {'label': 'Specified Arguments CZML', 'value': 'multiple_czml_p'},\n",
    "                     {'label': 'Create One-by-One CZML', 'value': 'multiple_czml_c'},\n",
    "                     {'label': 'Modified CZML', 'value': 'modified_czml'}\n",
    "                 ],\n",
    "                 value='single_czml'\n",
    "                ),\n",
    "    html.Div(id='cesiumContainer'),\n",
    "    html.Div(id='czml', style={'display': 'none'}),\n",
    "    html.Div(id='apikey', style={'display': 'none'}, children=apikey)\n",
    "])\n",
    "\n",
    "@app.callback(\n",
    "    Output('czml', 'children'),\n",
    "    Input('choose_czml_dd', 'value'))\n",
    "def update_satellite_filter(v):\n",
    "    d = {'single_czml':single_czml,\n",
    "         'multiple_czml':multiple_czml,\n",
    "         'multiple_czml_p':multiple_czml_p,\n",
    "         'multiple_czml_c':multiple_czml_c,\n",
    "         'modified_czml':modified_czml\n",
    "        }\n",
    "    return d[v]\n",
    "\n",
    "app.clientside_callback('''\n",
    "function(id, czml, apikey) {\n",
    "    // Create the Cesium Viewer\n",
    "    if (!window.viewer) {\n",
    "        Cesium.Ion.defaultAccessToken = apikey;\n",
    "        window.viewer = new Cesium.Viewer(id,{\n",
    "            shouldAnimate: true,\n",
    "        });\n",
    "        window.viewer.scene.globe.enableLighting = true;\n",
    "    }\n",
    "\n",
    "    // Update the Cesium Viewer\n",
    "    if (czml) {\n",
    "        window.viewer.dataSources.removeAll();\n",
    "        czmlJson = JSON.parse(czml);\n",
    "        window.viewer.dataSources.add(\n",
    "            Cesium.CzmlDataSource.load(czmlJson)\n",
    "        );\n",
    "    }\n",
    "\n",
    "    return true;\n",
    "}''',\n",
    "    Output('cesiumContainer', 'data-done'),\n",
    "    Input('cesiumContainer', 'id'),\n",
    "    Input('czml', 'children'),\n",
    "    Input('apikey', 'children')\n",
    ")\n",
    "\n",
    "if __name__ == '__main__':\n",
    "    app.run_server(debug=True, use_reloader=False)"
   ]
  }
 ],
 "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.8.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}