ApsaraDB RDS: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);

Parameters

Return value

Returns a protobuf-based binary data matrix of type bytea. The proto 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;    // columns of matrix
    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;
    }
}

Field descriptions:

• type: The data type of the matrix values. Determined by the input value parameter type: INT32 for int4 inputs (used for quantity calculations), DOUBLE for float8 inputs (used for metric calculations).

• rows: The number of rows in the matrix.

• columns: The number of columns in the matrix.

• matrix: A one-of field containing either intValues (array of sint32) or doubleValues (array of double). Values are organized in row-major order, with values ascending in the X direction and descending in the Y direction to facilitate image conversion.

To convert the return value into an array representation, use the ST_HMTAsArray function.

Usage notes

If the spatial reference of the input data differs from the spatial reference of the extent parameter, the function uses the spatial reference of extent.

The config parameter accepts a JSON string with the following options:

Examples

The following examples use a test table with 10 rows, each containing a point geometry and associated numeric values:

-- Create the test table
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 points (default aggregation)

SELECT ST_AsHMT(geom,
    ST_MakeEnvelope(0, 0, 10, 10, 4326), -- extent
    1024,                                 -- width, in pixels
    800                                   -- height, in pixels
)
FROM test_table;
---------
\x080010a0061880083284...

Aggregate a numeric column

SELECT ST_AsHMT(geom,
    ST_MakeEnvelope(0, 0, 10, 10, 4326), -- extent
    1024,                                 -- width, in pixels
    800,                                  -- height, in pixels
    weight                                -- value column
)
FROM test_table;
---------
\x080010a0061880...

Aggregate a computed expression

SELECT ST_AsHMT(geom,
    ST_MakeEnvelope(0, 0, 10, 10, 4326), -- extent
    1024,                                 -- width, in pixels
    800,                                  -- height, in pixels
    weight / volume * 1.2                 -- computed value (returns float8)
)
FROM test_table;
---------
\x080110a0061880083a85...

Enable point mode

In point mode, only points that fall within a mesh cell are counted.

SELECT ST_AsHMT(geom,
    ST_MakeEnvelope(0, 0, 10, 10, 4326), -- extent
    1024,                                 -- width, in pixels
    800,                                  -- height, in pixels
    1::integer,                           -- value
    true                                  -- point mode
)
FROM test_table;
---------
\x080010a0061880083...

Filter rows with a WHERE clause

SELECT ST_AsHMT(geom,
    ST_MakeEnvelope(0, 0, 10, 10, 4326), -- extent
    1024,                                 -- width, in pixels
    800                                   -- height, in pixels
)
FROM test_table
WHERE num < 5;
---------
\x080010a00618...

Use the `avg` aggregation type via the `config` parameter

SELECT ST_AsHMT(the_geom,
    ST_MakeEnvelope(0, 0, 10, 10, 4326), -- extent
    256,                                  -- width, in pixels
    256,                                  -- height, in pixels
    weight,
    '{"type":"avg"}'::cstring)
FROM test_table;
---------
\x080010a00618...

Use the `min` aggregation type with point mode

SELECT ST_AsHMT(the_geom,
    ST_MakeEnvelope(0, 0, 10, 10, 4326), -- extent
    256,                                  -- width, in pixels
    256,                                  -- height, in pixels
    weight,
    '{"type":"min", "point_mode":true}'::cstring)
FROM test_table;
---------
\x080010a00618...