{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting started with RustGIS in Python\n",
    "\n",
    "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/opengeos/RustGIS/blob/main/apps/rustgis-python/examples/getting-started.ipynb)\n",
    "[![PyPI](https://img.shields.io/pypi/v/rustgis.svg)](https://pypi.org/project/rustgis/)\n",
    "\n",
    "The `rustgis` package runs the [RustGIS](https://rustgis.app) engine inside Python: open data, run any command or geoprocessing tool, style layers and render maps. `rustgis.Map` shows the RustGIS app itself in the notebook, kept in step with Python both ways.\n",
    "\n",
    "The app in the widget runs in your browser, which needs WebGPU or WebGL2."
   ],
   "id": "cell-00"
  },
  {
   "cell_type": "code",
   "metadata": {},
   "execution_count": null,
   "outputs": [],
   "source": [
    "%pip install -q \"rustgis[jupyter,geopandas]\""
   ],
   "id": "cell-01"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## A session\n",
    "\n",
    "A `Session` is a project open in memory. Every action is a command with an id and parameters, the same ids the app's ribbon, the command line and the AI Assistant use."
   ],
   "id": "cell-02"
  },
  {
   "cell_type": "code",
   "metadata": {},
   "execution_count": null,
   "outputs": [],
   "source": [
    "import rustgis\n",
    "\n",
    "s = rustgis.Session(sample=True)  # the World Atlas sample\n",
    "[layer[\"name\"] for layer in s.layers()]"
   ],
   "id": "cell-03"
  },
  {
   "cell_type": "code",
   "metadata": {},
   "execution_count": null,
   "outputs": [],
   "source": [
    "s.run(\"gp.run\", tool=\"buffer\", params={\"input\": \"Cities\", \"distance\": 100})\n",
    "s.run(\"layer.symbology\", layer=\"Countries\", type=\"graduated\", field=\"pop_est\")\n",
    "s  # a session on the last line shows its map"
   ],
   "id": "cell-04"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Layers come out as GeoJSON or GeoDataFrames, and go back in the same way."
   ],
   "id": "cell-05"
  },
  {
   "cell_type": "code",
   "metadata": {},
   "execution_count": null,
   "outputs": [],
   "source": [
    "gdf = s.layer(\"Cities\").to_geopandas()\n",
    "big = gdf[gdf.pop_max > 10_000_000]\n",
    "big[[\"name\", \"pop_max\"]].sort_values(\"pop_max\", ascending=False).head()"
   ],
   "id": "cell-06"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The app in the notebook\n",
    "\n",
    "`rustgis.Map` shows the RustGIS app (ribbon, panes and map) below. What Python adds or styles appears in the app, and what you do in the app (a pan, an edit, a new layer) comes back to Python."
   ],
   "id": "cell-07"
  },
  {
   "cell_type": "code",
   "metadata": {},
   "execution_count": null,
   "outputs": [],
   "source": [
    "m = rustgis.Map(sample=True)\n",
    "m"
   ],
   "id": "cell-08"
  },
  {
   "cell_type": "code",
   "metadata": {},
   "execution_count": null,
   "outputs": [],
   "source": [
    "m.add_geopandas(big, name=\"Megacities\")\n",
    "m.run(\"layer.symbology\", layer=\"Countries\", type=\"graduated\", field=\"pop_est\")\n",
    "m.set_center(110, 25, scale=30_000_000)"
   ],
   "id": "cell-09"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Pan or zoom the map above, or edit a layer, then read the state back:"
   ],
   "id": "cell-10"
  },
  {
   "cell_type": "code",
   "metadata": {},
   "execution_count": null,
   "outputs": [],
   "source": [
    "m.info()[\"center\"], m.info()[\"scale\"], [layer[\"name\"] for layer in m.layers()]"
   ],
   "id": "cell-11"
  },
  {
   "cell_type": "code",
   "metadata": {},
   "execution_count": null,
   "outputs": [],
   "source": [
    "m.run_in_app(\"ui.language\", code=\"de\")  # commands only the app has (ui.*)"
   ],
   "id": "cell-12"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Save\n",
    "\n",
    "The project opens in the RustGIS desktop app and the [web app](https://web.rustgis.app) as it is."
   ],
   "id": "cell-13"
  },
  {
   "cell_type": "code",
   "metadata": {},
   "execution_count": null,
   "outputs": [],
   "source": [
    "m.save(\"atlas.rgis\")\n",
    "m.to_png(\"atlas.png\", width=1600, height=900);"
   ],
   "id": "cell-14"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Learn more in the [Python guide](https://rustgis.app/python/)."
   ],
   "id": "cell-15"
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}