added 4 use cases

Author: grallewellyn

docs/python-usage.ipynb

@@ -60,6 +60,12 @@
     "import numpy as np\n",
     "from owslib.wms import WebMapService\n",
     "from IPython.display import Image, display\n",
+    "import rasterio\n",
+    "import geopandas as gpd\n",
+    "from shapely.geometry import box\n",
+    "import urllib.request\n",
+    "from rasterio.mask import mask\n",
+    "import fiona\n",
     "%matplotlib inline"
    ]
   },
@@ -367,6 +373,33 @@
     "print('')                         "
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "50cca222",
+   "metadata": {},
+   "source": [
+    "You can also use rasterio to access the properties of a geospatial raster file \n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4dd19a30",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "proj4326 = 'https://gibs.earthdata.nasa.gov/wms/epsg4326/best/wms.cgi?\\\n",
+    "version=1.3.0&service=WMS&request=GetMap&\\\n",
+    "format=image/jpeg&STYLE=default&bbox=-90,-180,90,180&CRS=EPSG:4326&\\\n",
+    "HEIGHT=512&WIDTH=512&TIME=2021-11-25&layers=MODIS_Terra_SurfaceReflectance_Bands143'\n",
+    "with rasterio.open(proj4326) as src:\n",
+    "    print(src.width, src.height)\n",
+    "    print(src.crs)\n",
+    "    print(src.transform)\n",
+    "    print(src.count)\n",
+    "    print(src.indexes)"
+   ]
+  },
   {
    "attachments": {},
    "cell_type": "markdown",
@@ -3229,6 +3262,107 @@
     "plt.setp(axes.get_xticklabels(), rotation=30, horizontalalignment='right');"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "aefa506c",
+   "metadata": {},
+   "source": [
+    "### Overlaying\n",
+    "You can overlay multiple images and change the transparency to get your desired outcome "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "581736a2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "background_image_url = 'https://gibs.earthdata.nasa.gov/wms/epsg4326/best/wms.cgi?\\\n",
+    "version=1.3.0&service=WMS&request=GetMap&\\\n",
+    "format=image/jpeg&STYLE=default&bbox=-45,-90,0,-45&CRS=EPSG:4326&\\\n",
+    "HEIGHT=512&WIDTH=512&TIME=2021-11-25&layers=MODIS_Terra_SurfaceReflectance_Bands143'\n",
+    "\n",
+    "VIIRS_overlay_image_url = 'https://gibs.earthdata.nasa.gov/wms/epsg4326/best/wms.cgi?\\\n",
+    "version=1.3.0&service=WMS&request=GetMap&\\\n",
+    "format=image/jpeg&STYLE=default&bbox=-45,-90,0,-45&CRS=EPSG:4326&\\\n",
+    "HEIGHT=512&WIDTH=512&TIME=2021-11-25&layers=VIIRS_SNPP_DayNightBand_At_Sensor_Radiance'\n",
+    "\n",
+    "background = plimg.open(urllib.request.urlopen(background_image_url))\n",
+    "overlay = plimg.open(urllib.request.urlopen(VIIRS_overlay_image_url))\n",
+    "\n",
+    "background = background.convert(\"RGBA\")\n",
+    "overlay = overlay.convert(\"RGBA\")\n",
+    "\n",
+    "# .75 is the transparency for this example\n",
+    "VIIRS_overlay = plimg.blend(background, overlay, 0.75)\n",
+    "VIIRS_overlay.save(\"VIIRSOverlay.png\",\"PNG\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5604ba18",
+   "metadata": {},
+   "source": [
+    "You can also crop a TIFF file to be just within the bounds of a Shapefile "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e868d1da",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Create a box Shapefile \n",
+    "\n",
+    "# Define the bounding box over the continental US\n",
+    "minx, miny, maxx, maxy = -125, 25, -66, 50 \n",
+    "\n",
+    "# Create a GeoDataFrame with the bounding box\n",
+    "geometry = [box(minx, miny, maxx, maxy)]\n",
+    "gdf = gpd.GeoDataFrame({\"id\": [1]}, geometry=geometry, crs=\"EPSG:4326\")\n",
+    "\n",
+    "gdf.to_file(\"us_box.shp\")\n",
+    "\n",
+    "# Save a global extents tiff file\n",
+    "# Connect to GIBS WMS Service\n",
+    "wms = WebMapService('https://gibs.earthdata.nasa.gov/wms/epsg4326/best/wms.cgi?', version='1.1.1')\n",
+    "\n",
+    "# Configure request for MODIS_Terra_SurfaceReflectance_Bands143\n",
+    "img = wms.getmap(layers=['MODIS_Terra_SurfaceReflectance_Bands143'],  # Layers\n",
+    "                 srs='epsg:4326',  # Map projection\n",
+    "                 bbox=(-180,-90,180,90),  # Bounds\n",
+    "                 size=(1200, 600),  # Image size\n",
+    "                 time='2021-11-25',  # Time of data\n",
+    "                 format='image/tiff',  # Image format\n",
+    "                 transparent=True)  # Nodata transparency\n",
+    "\n",
+    "# Save output TIFF to a file\n",
+    "out = open('global_extents.tiff', 'wb')\n",
+    "out.write(img.read())\n",
+    "out.close()\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "28a84e80",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Crop and plot the global extents TIFF file using the US box Shapefile \n",
+    "with fiona.open(\"us_box.shp\", \"r\") as shapefile:\n",
+    "    shapes = [feature[\"geometry\"] for feature in shapefile]\n",
+    "\n",
+    "with rasterio.open(\"global_extents.tiff\") as src:\n",
+    "    out_image, out_transform = rasterio.mask.mask(src, shapes, crop=True)\n",
+    "    out_meta = src.meta\n",
+    "\n",
+    "plt.imshow(out_image.transpose(1, 2, 0))  # Transpose to (height, width, channels) for plotting\n",
+    "plt.show()"
+   ]
+  },
   {
    "attachments": {},
    "cell_type": "markdown",
@@ -3441,6 +3575,14 @@
     "print(\"Number of images downloaded:\", len(os.listdir(outdir)))"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "b77926e4",
+   "metadata": {},
+   "source": [
+    "**NOTE** The available options for the format parameter are: `image/png`, `image/tiff`, `image/jpeg`"
+   ]
+  },
   {
    "attachments": {},
    "cell_type": "markdown",