ST_AsPng Function Overview for Pyramid Tile Rendering - PolarDB

Renders a specific tile of a pyramid as a PNG image and returns the result as a bytea value.

Syntax

bytea ST_AsPng(cstring name, cstring key, cstring style);
bytea ST_AsPng(cstring name, int x, int y, int z, cstring style);

Use the first overload to identify the tile by its ID string. Use the second overload to identify the tile by its x, y, and z coordinates.

Parameters

Parameter	Description
`name`	The name of the pyramid.
`key`	The tile ID in `'z_x_y'` format, compatible with the `EPSG:4326` and `EPSG:3857` coordinate systems.
`x`	The x coordinate of the tile.
`y`	The y coordinate of the tile.
`z`	The z coordinate of the tile.
`style`	A JSON string that controls how the PNG is rendered. Pass an empty string (`''`) to use the default style.

Style fields

Field	Type	Default	Description
`background`	string	`#FFFFFFFF`	RGBA color of the background. Default is white.
`line_color`	string	`#000000FF`	RGBA color of dots and edges. Default is black.
`fill_color`	string	`#F4A460FF`	RGBA color of the tile fill. Default is brown.
`line_width`	int	`1`	Line width in pixels.
`point_size`	int	`10`	Dot diameter in pixels. Each dot is rendered as a circle.
`parallel_unit`	int	`50000`	Number of elements each parallel rendering task processes.

All color values use RGBA hexadecimal format, for example #RRGGBBAA.

Example style JSON:

{
  "background": "#FFFFFFFF",
  "line_color": "#000000FF",
  "fill_color": "#F4A460FF",
  "line_width": 1,
  "point_size": 10
}

Usage notes

Tile ID format

The key parameter follows the 'z_x_y' format and is compatible with both the EPSG:4326 and EPSG:3857 coordinate systems.

For EPSG:4326:

The number of chunks on the x axis is twice the number on the y axis.
The z coordinate starts at 1. When z is 1, the only valid tile IDs are 1_0_0 and 1_1_0.

Output image size

The output PNG dimensions match the tileSize value set when the pyramid was created with ST_BuildPyramid.

Examples

The following examples use the roads pyramid and pass an empty style string to use the default rendering style.

-- Render a tile using a tile ID string
SELECT ST_AsPng('roads', '3_1_6', '');
st_aspng
----------
0xFFAABB8D8A6678...

-- Render the same tile using explicit x, y, z coordinates
SELECT ST_AsPng('roads', 1, 6, 3, '');
st_aspng
----------
0xFFAABB8D8A6678...