[raster] ST_AsRaster

[Bborie Park]

ST_AsRaster provides the ability convert a geometry into a raster. To create the raster, the X and Y scale or the width and height of the raster must be provided.

The output raster will be in the same coordinate system as the source geometry. The only exception is for ST_AsRaster variations with a raster input parameter.

1. ST_AsRaster( geom geometry,
   scalex double precision, scaley double precision,
   pixeltype text[] DEFAULT ARRAY['8BUI']::text[],
   value double precision[] DEFAULT ARRAY[1]::double precision[],
   nodataval double precision[] DEFAULT ARRAY[0]::double precision[],
   upperleftx double precision DEFAULT NULL, upperlefty double precision DEFAULT NULL,
   gridx double precision DEFAULT NULL, gridy double precision DEFAULT NULL,
   skewx double precision DEFAULT 0, skewy double precision DEFAULT 0

) → raster

geom: the geometry to convert to a raster. Can be any valid PostGIS geometry.

scalex: the scale/pixel size in the X axis of the output raster. If scalex and scaley are zero (0), the output raster's scale will be autocomputed.

scaley: the scale/pixel size in the Y axis of the output raster. If scalex and scaley are zero (0), the output raster's scale will be autocomputed.

pixeltype: array of pixel types for each band. Each array element is a band.

value: array of values to burn into the raster for the geometry. Each array element is a band.

nodataval: array of nodata values to burn into the raster. Each array element is a band. If an array element is null, that band will not have a nodata value.

upperleftx: the X value of the upper-left corner of the output raster

upperlefty: the Y value of the upper-left corner of the output raster

gridx: the X coordinate of a point on the grid to which the raster will be aligned. Value is in the raster's world coordinates.

gridy: the Y coordinate of a point on the grid to which the raster will be aligned. Value is in the raster's world coordinates.

skewx: the skew along the X axis of the raster. by default, the skew along the X axis is zero.

skewy: the skew along the Y axis of the raster. by default, the skew along the X axis is zero.

If the number of elements for pixeltype, value and nodataval do not match, the minimum number of elements will be used.

2. ST_AsRaster( geom geometry,
   width integer, height integer,
   pixeltype text[] DEFAULT ARRAY['8BUI']::text[],
   value double precision[] DEFAULT ARRAY[1]::double precision[],
   nodataval double precision[] DEFAULT ARRAY[0]::double precision[],
   upperleftx double precision DEFAULT NULL, upperlefty double precision DEFAULT NULL,
   gridx double precision DEFAULT NULL, gridy double precision DEFAULT NULL,
   skewx double precision DEFAULT 0, skewy double precision DEFAULT 0

) → raster

width: the number of pixels per line in the raster

height: the number of lines in the raster

3. ST_AsRaster( geom geometry,
   scalex double precision, scaley double precision,
   pixeltype text,
   value double precision DEFAULT 1,
   nodataval double precision DEFAULT 0,
   upperleftx double precision DEFAULT NULL, upperlefty double precision DEFAULT NULL,
   gridx double precision DEFAULT NULL, gridy double precision DEFAULT NULL,
   skewx double precision DEFAULT 0, skewy double precision DEFAULT 0

) → raster

Like #1 but pixeltype, value and nodataval are simple values rather than arrays. Therefore, the output raster will only have one band.

4. ST_AsRaster( geom geometry,
   width integer, height integer,
   pixeltype text,
   value double precision DEFAULT 1,
   nodataval double precision DEFAULT 0,
   upperleftx double precision DEFAULT NULL, upperlefty double precision DEFAULT NULL,
   gridx double precision DEFAULT NULL, gridy double precision DEFAULT NULL,
   skewx double precision DEFAULT 0, skewy double precision DEFAULT 0

) → raster

5. ST_AsRaster( geom geometry,
   ref raster,
   pixeltype text[] DEFAULT ARRAY['8BUI']::text[],
   value double precision[] DEFAULT ARRAY[1]::double precision[],
   nodataval double precision[] DEFAULT ARRAY[0]::double precision[]

) → raster

ref: the reference raster whose scalex, scaley, skewx, skewy and srid will be applied to the output raster. The upperleft corner of the reference raster is used to align the output raster to the same grid.

6. ST_AsRaster( geom geometry,
   ref raster,
   pixeltype text,
   value double precision DEFAULT 1,
   nodataval double precision DEFAULT 0

) → raster

Like #5 but pixeltype, value and nodataval are simple values rather than arrays. Therefore, the output raster will only have one band.

[pracine]

Do we agree that the upperleftx and upperlefty couple of parameters are mutually exclusive with the gridx and gridy couple of parameter? In other word, there should be no variant allowing to pass both couple of parameter? Otherwise what happen if I pass a upperleftx and upperlefty couple not aligned on the grid defined by the gridx, gridy couple?

[Bborie Park]

Correct. None of the ST_AsRaster version above provide parameters for both upperleft and grid. Only the underlying _ST_AsRaster function has parameters for upperleft and grid.

If someone were to bypass the functions above and use _ST_AsRaster or the underlying RASTER_asRaster function directly and provide values for upperleft and grid, the upperleft values would take priority as that is explicit rather than the computation required for a grid value. Granted, by bypassing the user-facing functions, a user would be expected to responsible for whatever happens.

[Bborie Park]

Gah! Ignore my last response. For some reason I thought you were talking about scale and width/height.

The correct behavior is that if both upperleft and grid are provided, upperleft is used with a message indicating to that fact.

[pracine]

That means, in every variant, two parameters are useless? Why not making different variant for grid defined by upperleft and grid defined by the grid parameter?

It's true that there is a parameter type conflict in the variants I proposed:

4) fl fl 5) fl fl fl 6) fl fl fl fl 7) fl fl fl fl fl fl

8) fl fl int int 9) fl fl int int fl fl fl fl

but if you remove variant 4) it should fix the conflict…

[pracine]

Double checking: there was no conflict with 4)… Sorry for this incomprehensible list of types… But still why useless parameters?

[Bborie Park]

I agree that having two useless parameters is undesirable. The way I prototyped the function is so that the function can be called as easily as possible, which is to provide the geometry and either the scale or width/height.

I've refactored the functions to those below. I basically moved the gridx and gridy parameters up in the list of parameters as I think that it is easier to specify a grid point to align to rather than deal with the upper-left corner of the raster as the grid point could be gotten from the coverage or raster to align with.

1. ST_AsRaster(
	geom geometry,
	scalex double precision, scaley double precision,
	gridx double precision DEFAULT NULL, gridy double precision DEFAULT NULL,
	pixeltype text[] DEFAULT ARRAY['8BUI']::text[],
	value double precision[] DEFAULT ARRAY[1]::double precision[],
	nodataval double precision[] DEFAULT ARRAY[0]::double precision[],
	skewx double precision DEFAULT 0, skewy double precision DEFAULT 0
) -> raster

2. ST_AsRaster(
	geom geometry,
	scalex double precision, scaley double precision,
	pixeltype text[],
	value double precision[] DEFAULT ARRAY[1]::double precision[],
	nodataval double precision[] DEFAULT ARRAY[0]::double precision[],
	upperleftx double precision DEFAULT NULL, upperlefty double precision DEFAULT NULL,
	skewx double precision DEFAULT 0, skewy double precision DEFAULT 0
) -> raster

3. ST_AsRaster(
	geom geometry,
	width integer, height integer,
	gridx double precision DEFAULT NULL, gridy double precision DEFAULT NULL,
	pixeltype text[] DEFAULT ARRAY['8BUI']::text[],
	value double precision[] DEFAULT ARRAY[1]::double precision[],
	nodataval double precision[] DEFAULT ARRAY[0]::double precision[],
	skewx double precision DEFAULT 0, skewy double precision DEFAULT 0
) -> raster

4. ST_AsRaster(
	geom geometry,
	width integer, height integer,
	pixeltype text[],
	value double precision[] DEFAULT ARRAY[1]::double precision[],
	nodataval double precision[] DEFAULT ARRAY[0]::double precision[],
	upperleftx double precision DEFAULT NULL, upperlefty double precision DEFAULT NULL,
	skewx double precision DEFAULT 0, skewy double precision DEFAULT 0
) -> raster

5. ST_AsRaster(
	geom geometry,
	scalex double precision, scaley double precision,
	gridx double precision, gridy double precision,
	pixeltype text,
	value double precision DEFAULT 1,
	nodataval double precision DEFAULT 0,
	skewx double precision DEFAULT 0, skewy double precision DEFAULT 0
) -> raster

6. ST_AsRaster(
	geom geometry,
	scalex double precision, scaley double precision,
	pixeltype text,
	value double precision DEFAULT 1,
	nodataval double precision DEFAULT 0,
	upperleftx double precision DEFAULT NULL, upperlefty double precision DEFAULT NULL,
	skewx double precision DEFAULT 0, skewy double precision DEFAULT 0
) -> raster

7. ST_AsRaster(
	geom geometry,
	width integer, height integer,
	gridx double precision, gridy double precision,
	pixeltype text,
	value double precision DEFAULT 1,
	nodataval double precision DEFAULT 0,
	skewx double precision DEFAULT 0, skewy double precision DEFAULT 0
) -> raster

8. ST_AsRaster(
	geom geometry,
	width integer, height integer,
	pixeltype text,
	value double precision DEFAULT 1,
	nodataval double precision DEFAULT 0,
	upperleftx double precision DEFAULT NULL, upperlefty double precision DEFAULT NULL,
	skewx double precision DEFAULT 0, skewy double precision DEFAULT 0
) -> raster

9. ST_AsRaster(
	geom geometry,
	ref raster,
	pixeltype text[] DEFAULT ARRAY['8BUI']::text[],
	value double precision[] DEFAULT ARRAY[1]::double precision[],
	nodataval double precision[] DEFAULT ARRAY[0]::double precision[]
) -> raster

10. ST_AsRaster(
	geom geometry,
	ref raster,
	pixeltype text,
	value double precision DEFAULT 1,
	nodataval double precision DEFAULT 0
) -> raster

[pracine]

For consistency of the API, I think it would be a good idea to develop a "parameter order" policy for all the functions that create, modify and return info on a raster georeference and all those that create, modify and return info on a band so that users get used to the order in which to provide the arguments. I also think that when both type of information must be provided or returned, all raster info should precede (or follow) band info.

I think all the function below would greatly benefit from such a policy, but mostly future functions:

Function needing/returning raster georeference info:

-ST_MakeEmptyRaster()

-ST_MetaData()

-ST_SetGeoReference()

Functions needing/returning bands info:

-ST_AddBand()

-ST_BandMetaData()

Functions needing both:

-ST_AsRaster()

Could you write such a policy in the spec and apply it to every functions? Or at least just use it for future functions and create a ticket for past functions?

That would be great. A shame I never did it…

[pracine]

I forgot all the resampling series… That many functions!

[Bborie Park]

I'll see what I can do about writing an "order" spec for input and output function parameters. I expect that the output order is easier to apply everywhere compared to the input parameter order due to default values.

[Bborie Park]

Added in r7675.