Merge pull request #3 from knmlprz/doc/demo_descriptions

Doc/demo descriptions

README.md

@@ -1 +1,5 @@
-# BestWayToSafe
+# BestWayToSafe
+
+An application made with goal of assisting NGOs that deliver humanitarian aid to developing countries with making decisions associated with their actions in these areas.
+
+Technical details are available [here](demos/technical_solutions_main.ipynb)

demos/nearest_well/nearest_well_location.ipynb

@@ -2,7 +2,7 @@
  "cells": [
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 1,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -12,9 +12,22 @@
     "kml = kmz.open('doc.kml', 'r').read()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Badanie dostępu do wody pitnej\n",
+    "\n",
+    "Jednym z najważniejszych obszarów pomocy humaniternej m.in. w Afryce to zapewnianie dostępu do czystej wody pitnej. Niektóre organizacje zajmujące się utrzymywaniem studni słodkowodnych, takie jak [Water For Good](https://waterforgood.org/well-map/) udostępniają mapy zawierające informacje o punktach dostępu do wody, którymi się zajmują. W przypadku braku takich informacji można zastosować algorytmy detekcji obiektów, aby znaleźć studnie na zdjęciach satelitarnych.\n",
+    "\n",
+    "Widok na fragment mapy; pinezkami zaznaczone są lokalizacje studni:\n",
+    "\n",
+    "![Alt text](image.png)"
+   ]
+  },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 2,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -27,17 +40,22 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Znajdowanie dystansu od najbliższej studni"
+    "## Przetwarzanie danych lokalizacyjnych studni"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Plik KMZ zawiera dane w formacie punktów o pewnych współrzędnych geograficznych. W naszym przypadku plik zawiera wyłącznie lokalizacje studni, które zapisujemy do listy."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 15,
+   "execution_count": 3,
    "metadata": {},
    "outputs": [],
    "source": [
-    "from geopy.distance import distance\n",
-    "\n",
     "def parseKMZFile(kmz_file_path: str) -> list:\n",
     "    \"\"\"\n",
     "    Parses Google My Maps KMZ file into a list of pointmarks.\n",
@@ -51,21 +69,37 @@
     "    A list of placemark coordinates in `[latitude, longitude]` format\n",
     "    \"\"\"\n",
     "\n",
-    "    kmz = ZipFile('Functional Pumps.kmz', 'r')\n",
-    "    kml = kmz.open('doc.kml', 'r').read()\n",
-    "    doc = html.fromstring(kml)\n",
+    "    unpacked_kmz = ZipFile('Functional Pumps.kmz', 'r')\n",
+    "    map_point_data = unpacked_kmz.open('doc.kml', 'r').read()\n",
+    "    map_point_data_parsed = html.fromstring(map_point_data)\n",
     "\n",
     "    wells_coordinates = []\n",
     "\n",
-    "    for placemark_coordinate in doc.cssselect(\"Document Placemark Point\"):\n",
-    "        well_coordinates_raw: str = placemark_coordinate.text_content()\n",
+    "    for placemark_coordinate in map_point_data_parsed.cssselect(\"Document Placemark Point\"):\n",
+    "        well_coordinates_raw = placemark_coordinate.text_content()\n",
     "        well_coordinates_split = well_coordinates_raw.split(',')\n",
     "        well_coordinates = (\n",
     "        float(well_coordinates_split[1].strip()),\n",
     "        float(well_coordinates_split[0].strip())\n",
     "    )\n",
     "        wells_coordinates.append(well_coordinates)\n",
-    "    return wells_coordinates\n",
+    "    return wells_coordinates"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Znajdowanie dystansu od najbliższej studni"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from geopy.distance import distance\n",
     "\n",
     "def closestWellFromLocation(origin_coordinates: float, wells_coordinates: list) -> tuple:\n",
     "    \"\"\"\n",
@@ -78,22 +112,23 @@
     "    ]\n",
     "    minimal_distance = min(distances_to_wells)\n",
     "    index_of_the_closest_well = distances_to_wells.index(minimal_distance)\n",
+    "    closest_well_coordinates = wells_coordinates[index_of_the_closest_well]\n",
     "    return(\n",
-    "        wells_coordinates[index_of_the_closest_well],\n",
+    "        closest_well_coordinates,\n",
     "        minimal_distance\n",
     "    )"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 17,
+   "execution_count": 9,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "((5.734811, 19.129088), 1403.9564923898183)\n"
+      "The closest water well is at lat 5.734811, lon 19.129088; the distance to it is approx. 1404m\n"
      ]
     }
    ],
@@ -102,35 +137,12 @@
     "\n",
     "wells_coordinates = parseKMZFile('Functional Pumps.kmz')\n",
     "\n",
-    "print(closestWellFromLocation(random_point_near_wells, wells_coordinates))"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 19,
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "((5.735001, 19.141562), 1280.3611485467688)"
-      ]
-     },
-     "execution_count": 19,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "closestWellFromLocation([5.74472, 19.13528], wells_coordinates)"
+    "closest_well_coordinates, distance_to_well = closestWellFromLocation(random_point_near_wells, wells_coordinates)\n",
+    "closest_well_latitude, closest_well_longitude = closest_well_coordinates\n",
+    "distance_to_well = round(distance_to_well)\n",
+    "\n",
+    "print(f\"The closest water well is at lat {closest_well_latitude}, lon {closest_well_longitude}; the distance to it is approx. {distance_to_well}m\")"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {

demos/people_cluster_detection/people_cluster_detection.ipynb

@@ -12,6 +12,20 @@
     "image_name = 'false_color_city_image.png'"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Estymacja populacji w Mobayi-Mbongo"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Za pomocą filtrowania pikseli ze zdjęcia satelitarnego możemy wyestymować wielkość społeczności uchwyconej przez satelitę. Na tej podstawie możemy wywnioskować przybliżoną populację ludności w danym miejscu."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 13,
@@ -30,11 +44,25 @@
    ],
    "source": [
     "original_image = cv2.imread(image_name)\n",
-    "original_image_rgb = cv2.cvtColor(original_image, cv2.COLOR_BGR2RGB) #apparently OpenCV doesn't like working on RGB stuff (unless it didn't want to work for me ¯\\_(ツ)_/¯)\n",
+    "original_image_rgb = cv2.cvtColor(original_image, cv2.COLOR_BGR2RGB)\n",
     "plt.imshow(original_image_rgb)\n",
     "plt.show()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Filtrowanie pikseli na zdjęciu satelitarnym"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Po tej operacji pozostają głównie piksele odpowiadające zabudowaniom związanym z aktywnością ludzką, takim jak budynki."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 14,
@@ -78,23 +106,52 @@
     "plt.show()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Zliczenie pozostałych pikseli"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Przez zliczenie pozostałych na zdjęciu pikseli możemy wyestymować populację miescowości. Metoda ta działa najlepiej przy założeniu, że nie znajduje się w niej dużo budynków wielopiętrowych.\n",
+    "Nasza aplikacja zakłada użycie  w lokalizacjach słabiej rozwiniętych - spodziewamy się w nich raczej budynków parterowych."
+   ]
+  },
   {
    "cell_type": "code",
-   "execution_count": 20,
+   "execution_count": 21,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "populacja: ~4824\n"
+      "populacja: ok. 4824\n"
      ]
     }
    ],
    "source": [
     "output_greyscale = cv2.cvtColor(output_rgb, cv2.COLOR_BGR2GRAY)\n",
     "print(f\"populacja: ok. {cv2.countNonZero(output_greyscale)}\")"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Inne źródła informacji"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Estymację na podstawie zdjęcia satelitarnego miejsca można wspomóc danymi dostępnymi w platformie [Google Earth](https://developers.google.com/earth-engine/datasets/catalog/projects_sat-io_open-datasets_ORNL_LANDSCAN_GLOBAL)."
+   ]
   }
  ],
  "metadata": {