Various PR improvements

Signed-off-by: Jason T. Brown <[email protected]>

Author: vpipkt

core/src/main/scala/org/locationtech/rasterframes/functions/TileFunctions.scala

@@ -151,7 +151,7 @@ trait TileFunctions {
     withTypedAlias(s"rf_make_ones_tile($cols, $rows, $cellTypeName)")(constTile)
   }
 
-  /** Construct a `proj_raster` structure from individual CRS, Extent, and Tile columns. */
+  /** Construct a `proj_raster` structure from individual Tile, Extent, and CRS columns. */
   def rf_proj_raster(tile: Column, extent: Column, crs: Column): TypedColumn[Any, ProjectedRasterTile] =
     CreateProjectedRaster(tile, extent, crs)
 

core/src/main/scala/org/locationtech/rasterframes/util/DataFrameRenderers.scala

@@ -25,7 +25,7 @@ import geotrellis.raster.render.ColorRamps
 import org.apache.spark.sql.Dataset
 import org.apache.spark.sql.functions.{base64, concat, concat_ws, length, lit, substring, when}
 import org.apache.spark.sql.jts.JTSTypes
-import org.apache.spark.sql.types.{StringType, StructField}
+import org.apache.spark.sql.types.{StringType, StructField, BinaryType}
 import org.locationtech.rasterframes.expressions.DynamicExtractors
 import org.locationtech.rasterframes.{rfConfig, rf_render_png, rf_resample}
 import org.apache.spark.sql.rf.WithTypeConformity
@@ -48,6 +48,12 @@ trait DataFrameRenderers {
               base64(rf_render_png(rf_resample(resolved, 0.5), ColorRamps.Viridis)), // TODO: how to expose?
               lit("\"></img>")
             )
+          else if (renderTiles && c.dataType == BinaryType)
+            when(
+              substring(resolved, 0, 8) === lit(Array[Byte](137.asInstanceOf[Byte], 80, 78, 71, 13, 10, 26, 10)),
+              concat(lit("<img src=\"data:image/png;base64,"), base64(resolved), lit("\"></img>"))
+            )
+              .otherwise(resolved.cast(StringType))
           else {
             val isGeom = WithTypeConformity(c.dataType).conformsTo(JTSTypes.GeometryTypeInstance)
             val str = resolved.cast(StringType)

docs/src/main/paradox/reference.md

@@ -120,6 +120,12 @@ Fetches the extent (bounding box or envelope) of a `ProjectedRasterTile` or `Ras
 
 Fetch CRS structure representing the coordinate reference system of a `ProjectedRasterTile` or `RasterSource` type tile columns, or from a column of strings in the form supported by @ref:[`rf_mk_crs`](reference.md#rf-mk-crs). 
 
+### rf_proj_raster
+
+    ProjectedRasterTile rf_proj_raster(Tile tile, Extent extent, CRS crs)
+
+Construct a `proj_raster` structure from individual Tile, Extent, and CRS columns.
+
 ### rf_mk_crs
 
     Struct rf_mk_crs(String crsText)   
@@ -628,6 +634,18 @@ Aggregates over the `tile` and returns statistical summaries of cell values: num
 
 Aggregates over all of the rows in DataFrame of `tile` and returns a count of each cell value to create a histogram with values are plotted on the x-axis and counts on the y-axis. Related is the @ref:[`rf_tile_histogram`](reference.md#rf-tile-histogram) function which operates on a single row at a time.
 
+### rf_agg_extent
+
+    Extent rf_agg_extent(Extent extent)
+    
+Compute the naive aggregate extent over a column. Assumes CRS homogeneity. With mixed CRS in the column, or if you are unsure, use @ref:[`rf_agg_reprojected_extent`](reference.md#rf-agg-reprojected-extent).
+
+
+### rf_agg_reprojected_extent
+
+    Extent rf_agg_reprojected_extent(Extent extent, CRS source_crs, String dest_crs)
+    
+Compute the aggregate extent over the `extent` and `source_crs` columns. The `dest_crs` is given as a string. Each row's extent will be reprojected to the `dest_crs` before aggregating. 
 
 ## Tile Local Aggregate Statistics
 
@@ -710,21 +728,13 @@ Pretty print the tile values as plain text.
 
     String rf_render_matrix(Tile tile)
 
-Render Tile cell values as numeric values, for debugging purposes.
-
-
-### rf_rgb_composite
-
-    Tile rf_rgb_composite(Tile red, Tile green, Tile blue)
-    
-Merges three bands into a single byte-packed RGB composite. It first scales each cell to fit into an unsigned byte, in the range 0-255, and then merges all three channels to fit into a 32-bit unsigned integer. This is useful when you want an RGB tile to render or to process with other color imagery tools. 
-
+Render Tile cell values as a string of numeric values, for debugging purposes.
 
 ### rf_render_png
 
     Array rf_render_png(Tile red, Tile green, Tile blue)
 
-Runs [`rf_rgb_composite`](reference.md#rf-rgb-composite) on the given tile columns and then encodes the result as a PNG byte array.
+Converts three tile columns to a three-channel PNG-encoded image `bytearray`. First evaluates [`rf_rgb_composite`](reference.md#rf-rgb-composite) on the given tile columns, and then encodes the result. For more about rendering these in a Jupyter or IPython environment, see @[Writing Raster Data](raster-write.md#rendering-samples-with-color).
 
 ### rf_render_color_ramp_png
 
@@ -755,16 +765,20 @@ Converts given tile into a PNG image, using a color ramp of the given name to co
  * "Greyscale128"
  * "Greyscale256"
 
-Further descriptions of these color ramps can be found in the [Geotrellis Documentation](https://geotrellis.readthedocs.io/en/latest/guide/rasters.html#built-in-color-ramps).
+Further descriptions of these color ramps can be found in the [Geotrellis Documentation](https://geotrellis.readthedocs.io/en/latest/guide/rasters.html#built-in-color-ramps). For more about rendering these in a Jupyter or IPython environment, see @[Writing Raster Data](raster-write.md#rendering-samples-with-color).
 
 ### rf_agg_overview_raster
 
     Tile rf_agg_overview_raster(Tile proj_raster_col, int cols, int rows, Extent aoi)
     Tile rf_agg_overview_raster(Tile tile_col, int cols, int rows, Extent aoi, Extent tile_extent_col, CRS tile_crs_col)
 
-Construct an overview raster of size `cols`x`rows` where data in `proj_raster` intersects the `aoi` bound box in web-mercator. Uses bi-linear sampling method.
+Construct an overview _tile_ of size `cols` by `rows`. Data is filtered to the specified `aoi` which is given in web mercator. Uses bi-linear sampling method. The `tile_extent_col` and `tile_crs_col` arguments are optional if the first argument has its Extent and CRS embedded.
 
+### rf_rgb_composite
 
+    Tile rf_rgb_composite(Tile red, Tile green, Tile blue)
+    
+Merges three bands into a single byte-packed RGB composite. It first scales each cell to fit into an unsigned byte, in the range 0-255, and then merges all three channels to fit into a 32-bit unsigned integer. This is useful when you want an RGB tile to render or to process with other color imagery tools. 
 
 [RasterFunctions]: org.locationtech.rasterframes.RasterFunctions
 [scaladoc]: latest/api/index.html

docs/src/main/paradox/release-notes.md

@@ -11,6 +11,8 @@
 * Added `toDF` extension method to `MultibandGeoTiff`
 * Added `rf_agg_extent` and `rf_agg_reprojected_extent` to compute the aggregate extent of a column
 * Added `rf_proj_raster` for constructing a `proj_raster` structure from individual CRS, Extent, and Tile columns.
+* Added `rf_render_color_ramp_png` to compute PNG byte array for a single tile column, with specified color ramp.
+* In `rf_ipython`, improved rendering of dataframe binary contents with PNG preamble.
 * Throw an `IllegalArgumentException` when attempting to apply a mask to a `Tile` whose `CellType` has no NoData defined. ([#409](https://github.com/locationtech/rasterframes/issues/384))
 
 ### 0.8.4

pyrasterframes/src/main/python/docs/raster-write.pymd

@@ -21,6 +21,8 @@ We have some convenience methods to quickly visualize tiles (see discussion of t
 In an IPython or Jupyter interpreter, a `Tile` object will be displayed as an image with limited metadata.
 
 ```python tile_sample
+import pyrasterframes.rf_ipython
+
 def scene(band):
     b = str(band).zfill(2) # converts int 2 to '02'
     return 'https://modis-pds.s3.amazonaws.com/MCD43A4.006/11/08/2019059/' \
@@ -39,18 +41,61 @@ display(tile) # IPython.display function
 Within an IPython or Jupyter interpreter, a Spark and Pandas DataFrames containing a column of _tiles_ will be rendered as the samples discussed above. Simply import the `rf_ipython` submodule to enable enhanced HTML rendering of these DataFrame types.
 
 ```python to_samples, evaluate=True
-import pyrasterframes.rf_ipython
 
 samples = spark_df \
     .select(
         rf_extent('proj_raster').alias('extent'),
         rf_tile('proj_raster').alias('tile'),
     )\
-    .select('extent.*', 'tile') \
+    .select('tile', 'extent.*') \
     .limit(3)
 samples
 ```
 
+## Rendering Samples with Color
+
+By default the IPython visualizations use the Viridis color map for each single channel tile. There are other options for reasoning about how color should be applied in the results.
+
+
+### Color Composites
+
+Rendering three different bands of imagery together is called a _color composite_. The bands selected are mapped to the red, green, and blue channels of the resulting display. If the bands chosen are red, green, and blue, the composite is called a true-color composite. Otherwise it is a false-color composite.
+
+Using the @ref:[`rf_rgb_composite`](reference.md#rf-rgb-composite) function, we will compute a three band PNG image as a `bytearray`. The resulting `bytearray` will be displayed as an image in either a Spark or pandas DataFrame display if `rf_ipython` has been imported.
+
+```python, color-composite
+# Select red, green, and blue, respectively
+composite_df = spark.read.raster([[scene(1), scene(4), scene(3)]],
+                                 tile_dimensions=(256, 256))
+composite_df = composite_df.withColumn('png',
+                    rf_render_png('proj_raster_0', 'proj_raster_1', 'proj_raster_2'))
+composite_df.select('png').limit(3)
+```
+
+
+Alternatively the `bytearray` result can be displayed with [`pillow`](https://pillow.readthedocs.io/en/stable/).
+
+```python, single_tile_pil
+import io
+from PIL.Image import open as PIL_open
+png_bytearray = composite_df.first()['png']
+pil_image = PIL_open(io.BytesIO(png_bytearray))
+pil_image
+```
+
+```python, display_pil, echo=False
+display(pil_image)
+```
+
+### Custom Color Map
+
+You can also apply a different color map to a single-channel Tile using the @ref[`rf_render_color_ramp_png`](reference.md#rf-render-color-ramp-png) function. See the function documentation for information about the available color maps.
+
+```python, color-map
+samples.select(rf_render_color_ramp_png('tile', 'Magma'))
+```
+
+
 ## GeoTIFFs
 
 GeoTIFF is one of the most common file formats for spatial data, providing flexibility in data encoding, representation, and storage. RasterFrames provides a specialized Spark DataFrame writer for rendering a RasterFrame to a GeoTIFF.
@@ -86,15 +131,28 @@ os.remove(outfile)
 
 ## Overview Rasters
 
-In cases where writing and reading to/from a GeoTIFF isn't convenient, RasterFrames provides the `rf_agg_overview_raster` aggregate function, where you can construct a single raster (rendered as a tile) downsampled from all or a subset of the dataframe. This allows you to effectively construct the same operations the GeoTIFF writer performs, but without the file I/O.
+In cases where writing and reading to/from a GeoTIFF isn't convenient, RasterFrames provides the @ref:[`rf_agg_overview_raster`](reference.md#rf-agg-overview-raster) aggregate function, where you can construct a single raster (rendered as a tile) downsampled from all or a subset of the DataFrame. This allows you to effectively construct the same operations the GeoTIFF writer performs, but without the file I/O. 
 
-Because a Dataframe may contain data with varying CRSs, and the rendered raster needs to have a single CRS, an "Area of Interest" (AOI) is required in a predetermined CRS. In the case of `rf_agg_reprojected_extent`, the AOI needs to be in commonly used ["web mercator"](https://en.wikipedia.org/wiki/Web_Mercator_projection) CRS. 
+The `rf_agg_overview_raster` function will reproject data to the commonly used ["web mercator"](https://en.wikipedia.org/wiki/Web_Mercator_projection) CRS. You must specify an "Area of Interest" (AOI) in web mercator.  You can use @ref:[`rf_agg_reprojected_extent`](reference.md#rf-agg-reprojected-extent) to compute the extent of a DataFrame in any CRS or mix of CRSs.
 
 ```python, overview
 from pyrasterframes.rf_types import Extent
-target = spark_df.withColumn('extent', rf_extent('proj_raster')).withColumn('crs', rf_crs('proj_raster')) 
-aoi = Extent.from_row(target.select(rf_agg_reprojected_extent('extent', 'crs', 'EPSG:3857')).first()[0])
-target.select(rf_agg_overview_raster(rf_tile('proj_raster'), 512, 512, aoi, 'extent', 'crs')).first()[0]
+wm_extent = spark_df.agg(
+                  rf_agg_reprojected_extent(rf_extent('proj_raster'), rf_crs('proj_raster'), 'EPSG:3857')
+                  ).first()[0]
+aoi = Extent.from_row(wm_extent)
+print(aoi)
+aspect = aoi.width / aoi.height
+
+ov = spark_df.agg(
+           rf_agg_overview_raster('proj_raster', int(512 * aspect), 512, aoi)
+           ).first()[0]
+print("`ov` is of type", type(ov))
+ov
+```
+
+```python, echo=False
+display(ov)
 ```
 
 ## GeoTrellis Layers

pyrasterframes/src/main/python/pyrasterframes/rasterfunctions.py

@@ -340,7 +340,7 @@ def rf_agg_extent(extent_col):
 
 def rf_agg_reprojected_extent(extent_col, src_crs_col, dest_crs):
     """Compute the aggregate extent over a column, first projecting from the row CRS to the destination CRS. """
-    return Column(RFContext.call('rf_agg_reprojected_extent', _to_java_column(extent_col), _to_java_column(src_crs_col),CRS(dest_crs).__jvm__))
+    return Column(RFContext.call('rf_agg_reprojected_extent', _to_java_column(extent_col), _to_java_column(src_crs_col), CRS(dest_crs).__jvm__))
 
 
 def rf_agg_overview_raster(tile_col: Column, cols: int, rows: int, aoi: Extent,
@@ -676,6 +676,12 @@ def rf_tile(proj_raster_col):
     return _apply_column_function('rf_tile', proj_raster_col)
 
 
+def rf_proj_raster(tile, extent, crs):
+    """
+    Construct a `proj_raster` structure from individual CRS, Extent, and Tile columns
+    """
+    return _apply_column_function('rf_proj_raster', tile, extent, crs)
+
 def st_geometry(geom_col):
     """Convert the given extent/bbox to a polygon"""
     return _apply_column_function('st_geometry', geom_col)

pyrasterframes/src/main/python/pyrasterframes/rf_ipython.py

@@ -23,6 +23,8 @@
 
 import numpy as np
 
+_png_header = bytearray([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A])
+
 
 def plot_tile(tile, normalize=True, lower_percentile=1, upper_percentile=99, axis=None, **imshow_args):
     """
@@ -115,6 +117,19 @@ def tile_to_html(tile, fig_size=None):
     return b64_img_html.format(b64_png)
 
 
+def binary_to_html(blob):
+    """ When using rf_render_png, the result from the JVM is a byte string with special PNG header
+        Look for this header and return base64 encoded HTML for Jupyter display
+    """
+    import base64
+    if blob[:8] == _png_header:
+        b64_img_html = '<img src="data:image/png;base64,{}" />'
+        b64_png = base64.b64encode(blob).decode('utf-8').replace('\n', '')
+        return b64_img_html.format(b64_png)
+    else:
+        return blob
+
+
 def pandas_df_to_html(df):
     """Provide HTML formatting for pandas.DataFrame with rf_types.Tile in the columns.  """
     import pandas as pd
@@ -129,11 +144,14 @@ def pandas_df_to_html(df):
 
     tile_cols = []
     geom_cols = []
+    bytearray_cols = []
     for c in df.columns:
         if isinstance(df.iloc[0][c], pyrasterframes.rf_types.Tile):  # if the first is a Tile try formatting
             tile_cols.append(c)
         elif isinstance(df.iloc[0][c], BaseGeometry):  # if the first is a Geometry try formatting
             geom_cols.append(c)
+        elif isinstance(df.iloc[0][c], bytearray):
+            bytearray_cols.append(c)
 
     def _safe_tile_to_html(t):
         if isinstance(t, pyrasterframes.rf_types.Tile):
@@ -152,9 +170,16 @@ def _safe_geom_to_html(g):
         else:
             return g.__repr__()
 
+    def _safe_bytearray_to_html(b):
+        if isinstance(b, bytearray):
+            return binary_to_html(b)
+        else:
+            return b.__repr__()
+
     # dict keyed by column with custom rendering function
     formatter = {c: _safe_tile_to_html for c in tile_cols}
     formatter.update({c: _safe_geom_to_html for c in geom_cols})
+    formatter.update({c: _safe_bytearray_to_html for c in bytearray_cols})
 
     # This is needed to avoid our tile being rendered as `<img src="only up to fifty char...`
     pd.set_option('display.max_colwidth', -1)

pyrasterframes/src/main/python/requirements.txt

@@ -10,4 +10,5 @@ geopandas>=0.6.2,<0.7
 descartes>=1.1.0,<1.2
 pytz
 matplotlib
-rtree
+rtree
+Pillow

pyrasterframes/src/main/python/setup.py

@@ -46,7 +46,7 @@ def _divided(msg):
     divider = ('-' * 50)
     return divider + '\n' + msg + '\n' + divider
 
-# Should we move to https://github.com/aaren/notedown? It allows converstion without evaluation...
+
 class PweaveDocs(distutils.cmd.Command):
     """A custom command to run documentation scripts through pweave."""
     description = 'Pweave PyRasterFrames documentation scripts'

pyrasterframes/src/main/python/tests/RasterFunctionsTests.py

@@ -512,5 +512,9 @@ def test_rf_agg_overview_raster(self):
         # with open('/tmp/test_rf_agg_overview_raster.png', 'wb') as f:
         #     f.write(png)
 
-
+    def test_rf_proj_raster(self):
+        df = self.prdf.select(rf_proj_raster(rf_tile('proj_raster'),
+                                             rf_extent('proj_raster'),
+                                             rf_crs('proj_raster')).alias('roll_your_own'))
+        'tile_context' in df.schema['roll_your_own'].dataType.fieldNames()