Add design diagram and update text in plot-api and plotting-libraries…

… NBs

notebooks/02-methods/01-plotting-libraries.ipynb

@@ -5,7 +5,41 @@
    "metadata": {},
    "source": [
     "# Plotting Libraries\n",
-    "---"
+    "---\n",
+    "\n",
+    "We will introduce functionality from two visualization libraries and how they are being utilized by UXarray for unstructured grids visualization purposes. \n",
+    "\n",
+    "Before diving deep into these, looking into the current snapshot of the UXarray visualization design through a simple Unified Modelling Language (UML)-like diagram could be helpful to better understand UXarray's relation with such libraries. "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    ":::{note}\n",
+    "The following design diagram is actually provided in the [Plotting API](../03-uxarray-vis/01-plot-api.ipynb) section along with key takeaways about it. We highly recommend to check them out as well.\n",
+    ":::"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## UXarray Plotting API Design"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<img src=\"../images/plotting_api/uxarray-plot-api-design.png\" alt=\"UXarray Plotting API Design\" width=\"800\"/>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "No, let us look into the visulization libraries that UXarray relies upon or provides some interface with."
    ]
   },
   {
@@ -117,14 +151,16 @@
     }
    },
    "source": [
-    "### TODO: SpatialPandas"
+    "### Spatialpandas"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Coming soon!"
+    "Spatialpandas is a package that provides Pandas extension arrays for spatial/geometric operations. This package has an element called `GeoDataFrame`, which can be used directly by packages from the HoloViz stack such as hvPlot, Datashader, Holoviews, and Geoviews. Therefore, UXarray provides Grid conversions to `GeoDataFrame` to allow the user to perform visualizations direclty in HoloViz packages rather than needing to use our UXarray plotting functions. \n",
+    "\n",
+    "Because this cookbook's main goal is to showcase UXarray's own visulization capabilities, we will not detail this conversion here but provide a link to a [UXarray usage example](https://uxarray.readthedocs.io/en/latest/examples/005-to-geodataframe-for-holoviz.html) that demonstrates this."
    ]
   },
   {
@@ -151,7 +187,7 @@
     "\n",
     "We still support Matplotlib as a backend option in our visualization functionality, which will be covered in the next chapter. \n",
     "\n",
-    "We also provide conversion functions from UXarray to Matplotlib data structures such as collections, which can be utilized for visualization directly in Matplotlib after the conversion."
+    "Moreover, just like conversion to `Spatialpandas.GeoDataFrame`, we provide conversion functions from UXarray to Matplotlib data structures such as collections, which can be utilized for visualizations directly in Matplotlib after the conversion."
    ]
   },
   {
@@ -163,8 +199,17 @@
     }
    },
    "source": [
-    "### TODO: Collections \n",
-    "Coming soon! TODO: https://matplotlib.org/stable/api/collections_api.html"
+    "### Collections \n",
+    "Detailed information about Matplotlib's Collections API can be found [here](https://matplotlib.org/stable/api/collections_api.html). In Uxarray, conversions to `LineCollection` and `PolyCollection` are provided for visualizing Grid Geometries and data variables, respectively. "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    ":::{warning}\n",
+    "While these conversion functions have already been released, we have observed some issues with the resulting Matplotlib plots after the exceution of these functions, and the bug-fixing of that is WIP. Hence, we don't have an officially released documentation/example about these functions yet.\n",
+    ":::"
    ]
   },
   {
@@ -176,7 +221,7 @@
     }
    },
    "source": [
-    "### TODO: Cartopy"
+    "### Cartopy"
    ]
   },
   {
@@ -188,7 +233,9 @@
     }
    },
    "source": [
-    "Coming soon!"
+    "Cartopy is originally a Python library for cartographic visualizations with Matplotlib; however, they provide a number of features such as `crs`, i.e. Coordinate Reference Systems (a.k.a. projections), that are significant for cartographic visualizations.\n",
+    "\n",
+    "While UXarray does not rely upon Cartopy, we support projections through our visualization functions with the help of `Cartopy.crs`. The use of such projections in the UXarray functions will be showcased in the next chapter; thus, let us stop at this point."
    ]
   }
  ],