Add gallery example for plotting an RGB image from an xarray.DataArray (

#2641)

Gallery example using pygmt.Figure.grdimage to plot
an RGB image from a 3-band GeoTIFF loaded into an
xarray.DataArray via rioxarray.open_rasterio. Example
is over Lāhainā, Hawai'i on 9 Aug 2023.

* Add abbreviation for Cloud-Optimized GeoTIFF
* Set title font to Times-Roman

Makes the unequal spacing before and after the ā less obvious.

* Change apostrophe to Okina symbol ʻ

See https://en.wikipedia.org/wiki/%CA%BBOkina.
Using octal code 140 instead of 047 on the plot title
for Hawaiʻi, so that it looks like a 6 instead of a 9, but
unsure if this is still the correct Okina symbol.

* Inline comment on map scale projection

The 1:100000 scale means 1 centimetre on the
map is equivalent to 1 kilometre on the ground.

* Use ¯ and ` instead of \225 and \140
The non-octal code versions are much easier to see.

* Force loading dataarray into memory

---------

Co-authored-by: Michael Grund <[email protected]>
Co-authored-by: Dongdong Tian <[email protected]>
Co-authored-by: Yvonne Fröhlich <[email protected]>

examples/gallery/images/rgb_image.py

@@ -0,0 +1,40 @@
+"""
+RGB Image
+---------
+The :meth:`pygmt.Figure.grdimage` method can be used to plot Red, Green, Blue
+(RGB) images, or any 3-band false color combination. Here, we'll use
+:py:func:`rioxarray.open_rasterio` to read a GeoTIFF file into an
+:class:`xarray.DataArray` format, and plot it on a map.
+
+The example below shows a Worldview 2 satellite image over
+`Lāhainā, Hawaiʻi during the August 2023 wildfires
+<https://en.wikipedia.org/wiki/2023_Hawaii_wildfires#L%C4%81hain%C4%81>`_.
+Data is sourced from a Cloud-Optimized GeoTIFF (COG) file hosted on
+`OpenAerialMap <https://map.openaerialmap.org>`_ under a
+`CC BY-NC 4.0 <https://creativecommons.org/licenses/by-nc/4.0/>`_ license.
+"""
+import pygmt
+import rioxarray
+
+###############################################################################
+# Read 3-band data from GeoTIFF into an xarray.DataArray object:
+with rioxarray.open_rasterio(
+ filename="https://oin-hotosm.s3.us-east-1.amazonaws.com/64d6a49a19cb3a000147a65b/0/64d6a49a19cb3a000147a65c.tif",
+ overview_level=5,
+) as img:
+ # Subset to area of Lāhainā in EPSG:32604 coordinates
+ image = img.rio.clip_box(minx=738000, maxx=755000, miny=2300000, maxy=2318000)
+ image = image.load() # Force loading the DataArray into memory
+image
+
+###############################################################################
+# Plot the RGB imagery:
+fig = pygmt.Figure()
+with pygmt.config(FONT_TITLE="Times-Roman"): # Set title font to Times-Roman
+ fig.grdimage(
+ grid=image,
+ # Use a map scale where 1 cm on the map equals 1 km on the ground
+ projection="x1:100000",
+ frame=[r"WSne+tL@!a¯hain@!a¯, Hawai`i on 9 Aug 2023", "af"],
+ )
+fig.show()