RS_FromPath

Returns an out-db raster from a path to an image file. Out-db rasters hold references to raster files instead of holding the actual pixel data. Out-db rasters can be used interchangeably with ordinary rasters. The only difference is that out-db rasters will load raster files in a deferred manner. Pixel data won’t be loaded until pixel values are accessed by functions such as RS_Value or RS_BandAsArray. It is more appropriate to load large raster files as out-db rasters. Currently supports loading GeoTiff files (*.tiff or *.tif) and Arc Info Ascii Grid files (*.asc). Additional parameters for configuring the Hadoop file system can be passed in as a ; delimited string. For example, fs.s3a.access.key=xxx;fs.s3a.secret.key=xxx. The same string also carries reader settings such as raster.reader.auto-rescale=false, described in Band values, scale, and offset.

Band values, scale, and offset

RS_FromPath applies the per-band scale and offset stored in a GeoTIFF’s GDAL metadata by default (raster.reader.auto-rescale defaults to true). STAC catalogs expose the same two values as scale and offset in the raster:bands extension. Every SQL function that reads pixels from the raster, such as RS_Value, RS_BandAsArray, RS_MapAlgebra, RS_ZonalStats, and RS_AsInDB, therefore returns values in physical units rather than the raw digital numbers (DNs) stored in the file.

Rescaled bands are returned as doubles: RS_BandPixelType reports REAL_64BITS even when the file stores 16-bit integers.
Nodata pixels are not rescaled. They keep the file’s nodata value, and RS_BandNoDataValue still reports that value.
Files without scale and offset metadata are returned unchanged, in their native pixel type.

For example, Sentinel-2 Collection 1 Level-2A COGs (the sentinel-2-c1-l2a collection on Earth Search) store surface reflectance as 16-bit DNs with scale 0.0001 and offset -0.1. A vegetated near-infrared pixel stored as DN 3345 reads as reflectance 0.2345, because 3345 * 0.0001 - 0.1 = 0.2345:

-- pt is a vegetated pixel of the B8A scene, expressed in the raster's CRS
SELECT RS_Value(RS_FromPath(path), pt) AS reflectance,
       RS_Value(RS_FromPath(path, 'raster.reader.auto-rescale=false'), pt) AS dn
FROM scenes

+-----------+------+
|reflectance|    dn|
+-----------+------+
|     0.2345|3345.0|
+-----------+------+

Because the offset is negative, very dark pixels (DN below 1000) come out slightly below 0, while nodata pixels stay at the file’s nodata value (0 for Sentinel-2). Filter both before computing ratios such as NDVI.

Do not apply a data provider’s DN-to-reflectance formula, such as (DN - 1000) / 10000 for Sentinel-2 processing baseline 04.00 and later, on top of values read from an out-db raster. The reader has already applied the file’s scale and offset. Applying the formula a second time silently turns every reflectance into roughly -0.1: normalized-difference indices such as NDVI, NBR, and NDWI collapse to roughly 0 because the numerator cancels, and any other formula returns a plausible-looking but wrong value. No error is raised.

Disabling rescaling

Pass raster.reader.auto-rescale=false in the params string to keep the raw DNs and the file’s native pixel type:

SELECT RS_FromPath(path, 'raster.reader.auto-rescale=false') AS rast FROM scenes

The same key can be set for a whole Spark session as the Hadoop configuration entry spark.hadoop.raster.reader.auto-rescale=false when the session is created. It then applies to every RS_FromPath call that does not override it in params.

Other loaders

Not every entry point rescales by default:

Loader	Rescales by default	How to change it
`RS_FromPath(path)`	Yes	`RS_FromPath(path, 'raster.reader.auto-rescale=false')`
`RS_FromGeoTiff(content)`	Yes	`RS_FromGeoTiff(content, false)`
Out-db rasters generated by the STAC reader	Yes	`.option("raster.reader.auto-rescale", "false")` on the reader
The `raster` loader	No	`.option("autoRescale", "true")` on the loader

Python raster UDFs read the pixels of an out-db raster directly from the source file through rasterio, which does not apply the scale and offset. raster.as_numpy() and raster.as_rasterio() on an out-db raster return the raw DNs even though SQL functions on the same raster return rescaled values by default. Convert with RS_AsInDB before the UDF, or apply the scale and offset in the UDF yourself, when the two must agree. In-db rasters carry the already rescaled values into the UDF.

Signatures

RS_FromPath(path: String)

RS_FromPath(path: String, params: String)

RS_FromPath(path: String, params: String, eagerLoadMetadata: Boolean)

Parameters

String

required

The path to the raster image file.

String

A ; delimited string of additional parameters for configuring the Hadoop file system and the reader. For example, fs.s3a.access.key=xxx;fs.s3a.secret.key=xxx, or raster.reader.auto-rescale=false to keep raw digital numbers (see Band values, scale, and offset).

Boolean

default:"false"

If set to true, the metadata of the raster file will be loaded immediately and any errors encountered reading the raster file will be reported. If false, only the path to the raster file is kept without loading it, until the metadata is actually needed.

Return type

The resulting out-db raster.

Examples

Load out-db rasters from path

var df = sedona.read.format("binaryFile").load("/some/path/*.tiff")
df = df.selectExpr("path", "RS_FromPath(path) as rast")

Load out-db rasters with custom Hadoop file system parameters

var df = sedona.read.format("binaryFile").load("/some/path/*.tiff")
df = df.selectExpr("path", "RS_FromPath(path, 'fs.s3a.access.key=xxx;fs.s3a.secret.key=xxx') as rast")

Load out-db rasters without rescaling

Keeps the raw digital numbers and the native pixel type instead of applying the GeoTIFF’s scale and offset:

var df = sedona.read.format("binaryFile").load("/some/path/*.tiff")
df = df.selectExpr("path", "RS_FromPath(path, 'raster.reader.auto-rescale=false') as rast")

Wherobots Cloud REST API

WherobotsDB

Vector tiles (PMTiles)

Havasu (Iceberg) table management

GeoStats and Map Matching

Rasterflow

Band values, scale, and offset

Disabling rescaling

Other loaders

Signatures

Parameters

Return type

Examples

Load out-db rasters from path

Load out-db rasters with custom Hadoop file system parameters

Load out-db rasters without rescaling

​Band values, scale, and offset

​Disabling rescaling

​Other loaders

​Signatures

​Parameters

​Return type

​Examples

​Load out-db rasters from path

​Load out-db rasters with custom Hadoop file system parameters

​Load out-db rasters without rescaling

Band values, scale, and offset

Disabling rescaling

Other loaders

Signatures

Parameters

Return type

Examples

Load out-db rasters from path

Load out-db rasters with custom Hadoop file system parameters

Load out-db rasters without rescaling