ST_AsHMT

Syntax

bytea ST_AsHMT(geometry geometry_set, geometry extent, int4 width, int4 height, int4 value default 1, boolean point_mode default false);
bytea ST_AsHMT(geometry geometry_set, geometry extent, int4 width, int4 height, int4 value);
bytea ST_AsHMT(geometry geometry_set, geometry extent, int4 width, int4 height, int4 value, boolean point_mode);
bytea ST_AsHMT(geometry geometry_set, geometry extent, int4 width, int4 height, float8 value);
bytea ST_AsHMT(geometry geometry_set, geometry extent, int4 width, int4 height, float8 value, boolean point_mode);
bytea ST_AsHMT(geometry geometry_set, geometry extent, int4 width, int4 height, int4 value, cstring config);
bytea ST_AsHMT(geometry geometry_set, geometry extent, int4 width, int4 height, float8 value, cstring config);

Return value

Returns a Protocol Buffers (Protobuf)-based binary data structure representing the aggregated value for each grid cell. The schema is as follows:

syntax = "proto2";
option optimize_for = LITE_RUNTIME;

message HMT {
    required Type type = 1; // data value type
    required uint32 rows = 2;   // rows of matrix
    required uint32 columns = 3; // columns of matrix
    required uint32 srid = 4; // spatial reference identifier
    required float  xmin = 5; // xmin
    required float  ymin = 6; // ymin
    required float  xmax = 7; // xmax
    required float  ymax = 8; // ymax

    oneof matrix {
        intMatrix intValues = 10;
        doubleMatrix doubleValues = 11;
    }

    message intMatrix {
        repeated sint32 values = 12 [packed = true];
    }

    message doubleMatrix {
        repeated double values = 13 [packed = true];
    }

    enum Type {
        INT32 = 0;
        DOUBLE = 1;
    }
}

Parameters

Description

This function converts a set of geometry objects into a heat map tile (HMT) based on a specified geographic range and resolution.

The function automatically transforms input geometries to match the spatial reference of the extent parameter if they differ.

The config parameter is a JSON string specifying the calculation method. The following table describes the available options.

Examples

-- The following examples use a sample table named test_table, which is created with this statement.
CREATE TABLE test_table AS
SELECT i num,
    ST_SetSrid(st_makepoint((i-0.5)::numeric, (i-0.5)::numeric), 4326) geom,
    i*100::int4 weight,
    i*i*i::float8 volume
FROM generate_series(1, 10) i;

-- Count the number of geometries in each grid cell.
-- This is the simplest use case and does not require a `value` parameter.
SELECT ST_AsHMT(geom, -- geometry column
    ST_MakeEnvelope(0, 0, 10, 10, 4326), -- Extent
    1024,        -- Width, in pixels
    800        -- height
)
FROM test_table;

---------
\x080010a0061880083284...

-- Sum the values in the `weight` column for each grid cell.
SELECT ST_AsHMT(geom, -- geometry column
    ST_MakeEnvelope(0, 0, 10, 10, 4326), -- Extent
    1024,        -- Width
    800,       -- height
    weight     -- value column
)
FROM test_table;
---------
\x080010a0061880...

-- Sum the result of a computed expression for each grid cell.
-- The function returns a DOUBLE type matrix because the expression returns a float8 value.
SELECT ST_AsHMT(geom, -- geometry column
    ST_MakeEnvelope(0, 0, 10, 10, 4326), -- Extent
    1024,        -- Width
    800,        -- height
    weight / volume * 1.2     -- complex value
)
FROM test_table;
---------
\x080110a0061880083a85...

-- Use point mode to count only geometries whose centers are in a grid cell.
SELECT ST_AsHMT(geom, -- geometry column
    ST_MakeEnvelope(0, 0, 10, 10, 4326), -- Extent
    1024,        -- Width, in pixels
    800,        -- height
    1::integer,  -- value
    true        -- point mode
)
FROM test_table;
---------
\x080010a0061880083...

-- Filter the input data before aggregation by using a WHERE clause.
SELECT ST_AsHMT(geom, -- geometry column
    ST_MakeEnvelope(0, 0, 10, 10, 4326), -- Extent
    1024,        -- Width, in pixels
    800        -- height
)
FROM test_table
WHERE num <5;
---------
\x080010a00618...

-- Calculate the average weight by using the `config` parameter.
SELECT ST_AsHMT(geom,
    ST_MakeEnvelope(0, 0, 10, 10, 4326), -- Extent
    256,        -- Width, in pixels
    256,        -- height
    weight, 
    '{"type":"avg"}'::cstring)
FROM test_table;
---------
\x080010a00618...

-- Find the minimum weight in point mode by using the `config` parameter.
SELECT ST_AsHMT(geom,
    ST_MakeEnvelope(0, 0, 10, 10, 4326), -- Extent
    256,        -- Width, in pixels
    256,        -- height
    weight, 
    '{"type":"min", "point_mod":true}'::cstring)
FROM test_table;
---------
\x080010a00618...