Update docs and scala function api

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

Author: vpipkt

core/src/main/scala/org/locationtech/rasterframes/RasterFunctions.scala

@@ -337,13 +337,22 @@ trait RasterFunctions {
   def rf_inverse_mask_by_value(sourceTile: Column, maskTile: Column, maskValue: Int): TypedColumn[Any, Tile] =
     Mask.InverseMaskByValue(sourceTile, maskTile, lit(maskValue))
 
+  /** Applies a mask using bit values in the `mask_tile`. Working from the right, extract the bit at `bitPosition` from the `maskTile`. In all locations where these are equal to the `valueToMask`, the returned tile is set to NoData, else the original `dataTile` cell value. */
   def rf_mask_by_bit(dataTile: Column, maskTile: Column, bitPosition: Int, valueToMask: Boolean): Column =
-    rf_mask_by_bit(dataTile, maskTile, lit(bitPosition), lit(bitPosition))
+    rf_mask_by_bit(dataTile, maskTile, lit(bitPosition), lit(valueToMask))
 
-  def rf_mask_by_bit(dataTile: Column, maskTile: Column, bitPosition: Column, valueToMask: Column): Column = ???
+  /** Applies a mask using bit values in the `mask_tile`. Working from the right, extract the bit at `bitPosition` from the `maskTile`. In all locations where these are equal to the `valueToMask`, the returned tile is set to NoData, else the original `dataTile` cell value. */
+  def rf_mask_by_bit(dataTile: Column, maskTile: Column, bitPosition: Column, valueToMask: Column): Column =
+    rf_mask_by_bits(dataTile, maskTile, bitPosition, lit(1), valueToMask)
+
+  /** Applies a mask from blacklisted bit values in the `mask_tile`. Working from the right, the bits from `start_bit` to `start_bit + num_bits` are @ref:[extracted](reference.md#rf_local_extract_bits) from cell values of the `mask_tile`. In all locations where these are in the `mask_values`, the returned tile is set to NoData; otherwise the original `tile` cell value is returned. */
+  def rf_mask_by_bits(dataTile: Column, maskTile: Column, startBit: Column, numBits: Column, valuesToMask: Column): Column = {
+    val bitMask =  rf_local_extract_bits(maskTile, startBit, numBits)
+    rf_mask_by_values(dataTile, bitMask, valuesToMask)
+  }
 
-  def rf_mask_by_bits(dataTile: Column, maskTile: Column, startBit: Column, numBits: Column, valuesToMask: Column): Column = ???
 
+  /** Applies a mask from blacklisted bit values in the `mask_tile`. Working from the right, the bits from `start_bit` to `start_bit + num_bits` are @ref:[extracted](reference.md#rf_local_extract_bits) from cell values of the `mask_tile`. In all locations where these are in the `mask_values`, the returned tile is set to NoData; otherwise the original `tile` cell value is returned. */
   def rf_mask_by_bits(dataTile: Column, maskTile: Column, startBit: Int, numBits: Int, valuesToMask: Int*): Column = {
     import org.apache.spark.sql.functions.array
     val values = array(valuesToMask.map(lit):_*)

core/src/main/scala/org/locationtech/rasterframes/expressions/transformers/ExtractBits.scala

@@ -67,28 +67,29 @@ case class ExtractBits(child1: Expression, child2: Expression, child3: Expressio
     implicit val tileSer = TileUDT.tileSerializer
     val (childTile, childCtx) = tileExtractor(child1.dataType)(row(input1))
 
-    val startBits = intArgExtractor(child2.dataType)(input2).value.toShort
+    val startBits = intArgExtractor(child2.dataType)(input2).value
 
-    val numBits = intArgExtractor(child2.dataType)(input3).value.toShort
+    val numBits = intArgExtractor(child2.dataType)(input3).value
 
     childCtx match {
       case Some(ctx) => ctx.toProjectRasterTile(op(childTile, startBits, numBits)).toInternalRow
       case None => op(childTile, startBits, numBits).toInternalRow
     }
   }
 
-  protected def op(tile: Tile, startBit: Short, numBits: Short): Tile = {
-    // this is the last `numBits` positions of "111111111111111"
-    val widthMask = Short.MaxValue >> (15 - numBits)
-    // map preserving the nodata structure
-    tile.mapIfSet(x ⇒ x >> startBit & widthMask)
-  }
+  protected def op(tile: Tile, startBit: Int, numBits: Int): Tile = ExtractBits(tile, startBit, numBits)
 
 }
 
 object ExtractBits{
   def apply(tile: Column, startBit: Column, numBits: Column): Column =
     new Column(ExtractBits(tile.expr, startBit.expr, numBits.expr))
 
-}
+  def apply(tile: Tile, startBit: Int, numBits: Int): Tile = {
+    // this is the last `numBits` positions of "111111111111111"
+    val widthMask = Int.MaxValue >> (63 - numBits)
+    // map preserving the nodata structure
+    tile.mapIfSet(x ⇒ x >> startBit & widthMask)
+  }
 
+}

docs/src/main/paradox/reference.md

@@ -167,23 +167,20 @@ Tile rf_make_ones_tile(Int tile_columns, Int tile_rows, [CellType cell_type])
 Tile rf_make_ones_tile(Int tile_columns, Int tile_rows, [String cell_type_name])
 ```
 
-
 Create a `tile` of shape `tile_columns` by `tile_rows` full of ones, with the optional cell type; default is float64. See @ref:[this discussion](nodata-handling.md#cell-types) on cell types for info on the `cell_type` argument. All arguments are literal values and not column expressions.
 
 ### rf_make_constant_tile
 
     Tile rf_make_constant_tile(Numeric constant, Int tile_columns, Int tile_rows,  [CellType cell_type])
     Tile rf_make_constant_tile(Numeric constant, Int tile_columns, Int tile_rows,  [String cell_type_name])
 
-
 Create a `tile` of shape `tile_columns` by `tile_rows` full of `constant`, with the optional cell type; default is float64. See @ref:[this discussion](nodata-handling.md#cell-types) on cell types for info on the `cell_type` argument. All arguments are literal values and not column expressions.
 
 
 ### rf_rasterize
 
     Tile rf_rasterize(Geometry geom, Geometry tile_bounds, Int value, Int tile_columns, Int tile_rows)
 
-
 Convert a vector Geometry `geom` into a Tile representation. The `value` will be "burned-in" to the returned `tile` where the `geom` intersects the `tile_bounds`. Returned `tile` will have shape `tile_columns` by `tile_rows`. Values outside the `geom` will be assigned a NoData value. Returned `tile` has cell type `int32`, note that `value` is of type Int.
 
 Parameters `tile_columns` and `tile_rows` are literals, not column expressions. The others are column expressions.
@@ -236,10 +233,35 @@ Generate a `tile` with the values from `data_tile`, with NoData in cells where t
 ### rf_mask_by_values
 
     Tile rf_mask_by_values(Tile data_tile, Tile mask_tile, Array mask_values)
-    Tile rf_mask_by_values(Tile data_tile, Tile mask_tile, seq mask_values)
+    Tile rf_mask_by_values(Tile data_tile, Tile mask_tile, list mask_values)
 
 Generate a `tile` with the values from `data_tile`, with NoData in cells where the `mask_tile` is in the `mask_values` Array or list. `mask_values` can be a [`pyspark.sql.ArrayType`][Array] or a `list`.  
 
+### rf_mask_by_bit
+
+    Tile rf_mask_by_bits(Tile tile, Tile mask_tile, Int bit_position, Bool mask_value) 
+    
+Applies a mask using bit values in the `mask_tile`. Working from the right, the bit at `bit_position` is @ref:[extracted](reference.md#rf_local_extract_bits) from cell values of the `mask_tile`. In all locations where these are equal to the `mask_value`, the returned tile is set to NoData; otherwise the original `tile` cell value is returned.
+
+This is a single-bit version of @ref:[`rf_mask_by_bits`](reference.md#rf-mask-by-bits).
+    
+### rf_mask_by_bits
+
+    Tile rf_mask_by_bits(Tile tile, Tile mask_tile, Int start_bit, Int num_bits, Array mask_values) 
+    Tile rf_mask_by_bits(Tile tile, Tile mask_tile, Int start_bit, Int num_bits, list mask_values) 
+    
+Applies a mask from blacklisted bit values in the `mask_tile`. Working from the right, the bits from `start_bit` to `start_bit + num_bits` are @ref:[extracted](reference.md#rf_local_extract_bits) from cell values of the `mask_tile`. In all locations where these are in the `mask_values`, the returned tile is set to NoData; otherwise the original `tile` cell value is returned.
+
+This function is not available in the SQL API. The below is equivalent:
+
+```sql
+SELECT rf_mask_by_values(
+            tile, 
+            rf_extract_bits(mask_tile, start_bit, num_bits), 
+            mask_values
+            ),
+```
+
 ### rf_inverse_mask
 
     Tile rf_inverse_mask(Tile tile, Tile mask)
@@ -406,6 +428,15 @@ Returns a `tile` column containing the element-wise inequality of `tile1` and `r
 
 Returns a `tile` column with cell values of 1 where the `tile` cell value is in the provided array or list. The `array` is a Spark SQL [Array][Array]. A python `list` of numeric values can also be passed.
 
+### rf_local_extract_bits
+
+    Tile rf_local_extract_bits(Tile tile, Int start_bit, Int num_bits)
+    Tile rf_local_extract_bits(Tile tile, Int start_bit)
+
+Extract value from specified bits of the cells' underlying binary data. Working from the right, the bits from `start_bit` to `start_bit + num_bits` are extracted from cell values of the `tile`. The `start_bit` is zero indexed. If `num_bits` is not provided, a single bit is extracted.
+
+A common use case for this function is covered by @ref:[`rf_mask_by_bits`](reference.md#rf-mask-by-bits).
+
 ### rf_round
 
     Tile rf_round(Tile tile)

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

@@ -2,6 +2,10 @@
 
 ## 0.8.x
 
+### 0.8.5
+
+* Add `rf_mask_by_bit`, `rf_mask_by_bits` and `rf_local_extract_bits` to deal with bit packed quality masks. Updated the masking documentation to demonstrate the use of these functions.
+
 ### 0.8.4
 
 * Upgraded to Spark 2.4.4