Skip to content

RS_MakeEmptyRaster

Creates an in-database raster from a grid definition: a pixel count, a placement (an extent geometry, or an upper-left corner with pixel size or a full affine transform), and a number of zero-filled bands. Use it to define a target grid for RS_AsRaster or as a template for other rasters.

Usage

raster RS_MakeEmptyRaster(num_bands: integer, width: integer, height: integer, extent: geometry)
raster RS_MakeEmptyRaster(num_bands: integer, band_data_type: string, width: integer, height: integer, extent: geometry)
raster RS_MakeEmptyRaster(num_bands: integer, width: integer, height: integer, upper_left_x: double, upper_left_y: double, cell_size: double)
raster RS_MakeEmptyRaster(num_bands: integer, band_data_type: string, width: integer, height: integer, upper_left_x: double, upper_left_y: double, cell_size: double)
raster RS_MakeEmptyRaster(num_bands: integer, width: integer, height: integer, upper_left_x: double, upper_left_y: double, scale_x: double, scale_y: double, skew_x: double, skew_y: double, srid: integer)
raster RS_MakeEmptyRaster(num_bands: integer, band_data_type: string, width: integer, height: integer, upper_left_x: double, upper_left_y: double, scale_x: double, scale_y: double, skew_x: double, skew_y: double, srid: integer)

Arguments

  • num_bands (integer): Number of zero-filled bands; 0 gives a bandless grid template.
  • band_data_type (string): Pixel type of every band: int8, uint8, int16, uint16, int32, uint32, int64, uint64, float32 or float64; Sedona Spark’s letter codes (D, F, I, UI, S, US, B); or an RS_BandPixelType name such as UNSIGNED_8BITS.
  • width (integer): Grid width in pixels.
  • height (integer): Grid height in pixels.
  • upper_left_x (double): X coordinate of the upper-left corner of the upper-left pixel.
  • upper_left_y (double): Y coordinate of the upper-left corner of the upper-left pixel.
  • scale_x (double)
  • scale_y (double): Negative for a north-up raster.
  • skew_x (double)
  • skew_y (double)
  • srid (integer): EPSG code of the raster’s CRS; 0 for no CRS.
  • cell_size (double): Square pixel size; scale_x is cell_size and scale_y is -cell_size.
  • extent (geometry): The grid covers this geometry’s envelope with north-up pixels, in the geometry’s CRS. A geography is accepted too, in which case the envelope follows spherical edges and comes from the session’s geography bounder; a geography crossing the antimeridian gives a grid whose x range runs past 180 (for example, 170 to 190).

Description

RS_MakeEmptyRaster builds a raster from nothing but a grid definition. Every band holds width * height zeros of band_data_type (default float64) and has no nodata value. The grid can be placed three ways:

  • From an extent geometry. The raster covers the envelope of extent with width x height north-up pixels: the upper-left corner is the envelope’s (xmin, ymax), the pixel size is the envelope size divided by the pixel count, and the raster’s CRS is the geometry’s. This is the direct way to describe a grid as “columns, rows, bounding box and CRS”; pair it with ST_MakeEnvelope, ST_Envelope or RS_Envelope. The envelope must span a positive width and height.
  • From an upper-left corner and a square cell size. No skew and no CRS (attach one with RS_SetSRID or RS_SetCRS).
  • From a full affine transform and SRID. The six geotransform parameters and an EPSG code, 0 meaning no CRS.

The last two forms take the same arguments as Sedona Spark’s RS_MakeEmptyRaster; the extent form is a SedonaDB extension. Where Sedona Spark silently falls back to float64 for an unrecognised band_data_type, SedonaDB raises an error. num_bands may be 0, which yields a raster with a grid but no bands: a lightweight template that reference-taking functions can consume without carrying pixel data.

The result is an in-database raster, so each band occupies width * height * bytes-per-pixel in memory (a float64 band of 1000 x 1000 pixels is 8 MB). A single band is limited to 4 GiB.

Null arguments yield a null raster.

Examples

A 400 x 400 uint8 grid over the bounding box (0, 0)-(400, 400) in EPSG:4326:

SELECT RS_GeoReference(r), RS_SRID(r)
FROM (
  SELECT RS_MakeEmptyRaster(
    1, 'uint8', 400, 400,
    ST_MakeEnvelope(0, 0, 400, 400, 4326)
  ) AS r
);

┌────────────────────┬────────────┐
│ rs_georeference(r) ┆ rs_srid(r) │
│        utf8        ┆   uint32   │
╞════════════════════╪════════════╡
│ 1.0000000000…      ┆       4326 │
└────────────────────┴────────────┘

Rasterize a geometry onto that grid:

SELECT RS_AsRaster(
  ST_SetSRID(ST_GeomFromText('POLYGON ((10 10, 50 10, 50 50, 10 50, 10 10))'), 4326),
  RS_MakeEmptyRaster(1, 'uint8', 400, 400, ST_MakeEnvelope(0, 0, 400, 400, 4326)),
  'uint8', false, 1.0, 0.0, false
);

┌──────────────────────────────────────────────────────────────────────────────┐
│ rs_asraster(st_setsrid(st_geomfromtext(Utf8("POLYGON ((10 10, 50 10, 50 50,  │
│ 10 50, 10 10))")),Int64(4326)),rs_makeemptyraster(Int64(1),Utf8("uint8"),In… │
╞══════════════════════════════════════════════════════════════════════════════╡
│ [400x400/1] @ [0 0 400 400] / OGC:CRS84                                      │
└──────────────────────────────────────────────────────────────────────────────┘

A grid matching an existing raster’s extent at a coarser resolution:

SELECT RS_Width(RS_MakeEmptyRaster(1, 16, 8, RS_Envelope(RS_Example())));

┌──────────────────────────────────────────────────────────────────────────────┐
│ rs_width(rs_makeemptyraster(Int64(1),Int64(16),Int64(8),rs_envelope(rs_examp │
│                                   le())))…                                   │
╞══════════════════════════════════════════════════════════════════════════════╡
│                                                                           16 │
└──────────────────────────────────────────────────────────────────────────────┘

The Sedona Spark forms, from an upper-left corner and cell size:

SELECT RS_MakeEmptyRaster(2, 10, 10, 0.0, 0.0, 1.0);

┌──────────────────────────────────────────────────────────────────────────────┐
│ rs_makeemptyraster(Int64(2),Int64(10),Int64(10),Float64(0),Float64(0),Float6 │
│                                    4(1))…                                    │
╞══════════════════════════════════════════════════════════════════════════════╡
│ [10x10/2] @ [0 -10 10 0]                                                     │
└──────────────────────────────────────────────────────────────────────────────┘

and from a full affine transform and SRID:

SELECT RS_MakeEmptyRaster(2, 'I', 10, 10, 0.0, 0.0, 1.0, -1.0, 0.0, 0.0, 4326);

┌──────────────────────────────────────────────────────────────────────────────┐
│ rs_makeemptyraster(Int64(2),Utf8("I"),Int64(10),Int64(10),Float64(0),Float64 │
│        (0),Float64(1),Float64(-1),Float64(0),Float64(0),Int64(4326))…        │
╞══════════════════════════════════════════════════════════════════════════════╡
│ [10x10/2] @ [0 -10 10 0] / OGC:CRS84                                         │
└──────────────────────────────────────────────────────────────────────────────┘

[!NOTE]

The corner-and-pixel-size and affine forms mirror Sedona Spark’s RS_MakeEmptyRaster, including its leading band count and band type argument. This departs from PostGIS, whose ST_MakeEmptyRaster takes no band arguments and returns a bandless raster that ST_AddBand then fills in. Passing num_bands = 0 here gives that same bandless grid template.