[postgis-users] Documentation for PostGIS raster format / binary encoding?

[Felix Schütt]

Hi,

I'm currently working to understand the raster format of PostGIS, 
especially the binary encoding. Let's say that I have a bunch of binary 
data in a file format that raster2pgsql doesn't understand. I have a 
program that reads out the raster data of that file and now I want to 
insert it into postgis. I have the width and height of the image, the 
coordinates of the image corners, the EPSG code and the binary image 
data. My question is, how do I construct an SQL query (INSERT or COPY 
statement) to insert the data into a table. Using a different file 
format, raster2pgsql is able to construct a query like this:

BEGIN;
CREATE TABLE "n00e010.srtmgl3.hgt" ("rid" serial PRIMARY KEY,"rast" 
raster);
INSERT INTO "n00e010.srtmgl3.hgt" ("rast") VALUES ('00100 [... LOTS OF 
NUMBERS ...]'::raster);
END;

However, I don't know how to construct the binary stream in the "LOTS OF 
NUMBERS" part. The public documentation 
(https://postgis.net/docs/manual-2.1/RT_reference.html) is extremely 
sparse on documenting how the binary data is formatted, which is 
probably the most important part. What is "scaleX", "scaleY", "ipX", 
"ipY" and where do I get them from (and why are they set to 0.5 in the 
example)? (Also, if I run the example and try to add the layer in QGIS 
2.18, I somehow can't add the raster layer?) Why is the raster data 
inserted as a second row, but in the output of raster2pgsql it's just a 
single row? Is the header of the binary data always the same or do the 
fields change based on the data type? The official docs basically just 
say "just use raster2pgsql lol", there is no documentation of how the 
binary stream is encoded beyond this single example.

If I had an 3x3 *signed 16-bit integer* array of bytes (just greyscale), 
how would I go about formatting the binary stream so that PostGIS 
accepts them and I can display them in QGIS (using PostGIS 3.0.1 and 
PostgreSQL 12)? Is there a spec? Where should the image data go and how 
is it encoded (especially regarding 16-bit integers instead of 8-bit 
ones like in the example)?

Thanks in advance for any help and thanks for creating PostGIS,

Felix