Using raster functions

Raster functions are server-side operations that can be applied to imagery and raster data to perform analysis, visualization, and data transformation. These functions are made available through ArcGIS ImageServers and allow you to process raster data dynamically without downloading large datasets to your local machine.

In this tutorial, we’ll demonstrate how to discover and apply raster functions using the Forest Service FIA BIGMAP Tree Species Aboveground Biomass dataset, which represents estimates in tons per acre for total aboveground biomass as well as that of 327 individual tree species at a 30 meter pixel spatial resolution within the coterminous United States.

Connecting to an ImageServer

First, we’ll establish a connection to the ImageServer containing our biomass data:

library(arcgis)

# Store the ImageServer URL
tree_species_biomass <- "https://di-usfsdata.img.arcgis.com/arcgis/rest/services/FIA_BIGMAP_2018_Tree_Species_Aboveground_Biomass/ImageServer"

# Create a connection to the ImageServer
srvr <- arc_open(tree_species_biomass)
srvr

#> <ImageServer <1 bands, 27 fields>>
#> Name: FIA_BIGMAP_2018_Tree_Species_Aboveground_Biomass
#> Description: null
#> Extent: -2911620 2933940 164760 3254760 (xmin, xmax, ymin, ymax)
#> Resolution: 30 x 30
#> CRS: 102039
#> Capabilities: Image,Metadata,Catalog,Mensuration

Discovering Available Raster Functions

Once connected, we can explore what raster functions are available on this ImageServer:

# List all raster functions available in the ImageServer
raster_fns <- list_raster_fns(srvr)
raster_fns 

#> # A data frame: 327 × 3
#>    name                       description                                  help 
#>  * <chr>                      <chr>                                        <chr>
#>  1 SPCD_0000_TOTAL            TOTAL                                        <NA> 
#>  2 None                       Make a Raster or Raster Dataset into a Func… <NA> 
#>  3 SPCD_0010_Abies_spp.       fir spp.                                     <NA> 
#>  4 SPCD_0012_Abies_balsamea   balsam fir                                   <NA> 
#>  5 SPCD_0015_Abies_concolor   white fir                                    <NA> 
#>  6 SPCD_0016_Abies_fraseri    Fraser fir                                   <NA> 
#>  7 SPCD_0017_Abies_grandis    grand fir                                    <NA> 
#>  8 SPCD_0018_Abies_lasiocarpa corkbark fir                                 <NA> 
#>  9 SPCD_0019_Abies_lasiocarpa subalpine fir                                <NA> 
#> 10 SPCD_0020_Abies_magnifica  California red fir                           <NA> 
#> # ℹ 317 more rows

The list_raster_fns() function returns a data frame containing all available raster functions. Each function corresponds to a different tree species or analysis type available in the dataset.

Applying Raster Functions

To apply a raster function, specify its name in the raster_fn argument when calling arc_raster(). Here we’ll extract biomass data for Balsam Fir trees in a specific geographic area:

# Fetch data with the Balsam Fir raster function applied
res <- arc_raster(
  srvr,
  xmin = -71,
  xmax = -67,
  ymin = 43,
  ymax = 47.5,
  bbox_crs = 4326,
  width = 1000,
  height = 1000,
  raster_fn = "SPCD_0012_Abies_balsamea"
)

#> Warning in CPL_crs_from_input(x): GDAL Error 1: PROJ:
#> proj_create_from_database: crs not found: EPSG:102039

# Visualize the results
terra::plot(res)

The resulting SpatRaster object contains the processed biomass values for Balsam Fir trees in our specified extent. The raster function has been applied server-side, returning only the processed data we need for analysis.