[raster] Documentation: Improve raster documentation terminology and consistency

[pracine]

If you have any opinion any of the 9 items below, please comment.

In the doc we often speak about the same concept in very different and confounding terminology. I think it's about time we agree on some definitions and terms and stick with them in the future. I could identify many concepts with fuzzy definitions or terminology:

1) "scale", "skew", "rotation", "pixel width", "pixel height", "pixel size" and "alignment"

Some sentences examples that seems misleading to me since "skew" is not necessarily synonymous with "rotation":

-"Returns basic meta data about a raster object such as pixel size, rotation (skew), upper, lower left, etc." -"Returns the georeference X skew (or rotation parameter). "

Some examples of sentences that I have to scratch my head to understand:

-"In the common case where there is no skew, the pixel width is just the scale ratio between geometric coordinates and raster pixels... "

-"Returns the uniform rotation of the raster" What is the meaning of uniform?

Let me suggest some definitions for those terms so we can use them or short version of them when appropriate in the doc. Let me know if you think there are wrong or if you have a better set. they are all very much linked together.

• "scalex": X component of the pixel width

• "scaley": Y component of the pixel height

• "skewx": X component of the pixel height

• "skewy": Y component of the pixel width

• "rotation": angle formed by the combination of scalex, scaley, skewx and skewy when they do not twist the squared shape of the pixel

• "pixel width": horizontal length of a pixel formed by the scalex and the skewy of the pixel

• "pixel height": vertical length of a pixel formed by the scaley and the skewx of the pixel

• "pixel size": pixel width and pixel height of a pixel

• "uniform rotation": same as "rotation"

In ST_AsRaster we also introduce the "gridx" and "gridy" parameters which are different from "upperleftx" and "upperlefty". I suggest we define them like this:

-"upperleftx": X world coordinate of the upper left corner of a raster.

-"upperlefty": Y world coordinate of the upper left corner of a raster.

• gridx: X world coordinate of an arbitrary corner of an infinite grid defining its location in space. Used with scale and skew to define a general and infinite grid on which to align a raster.

• gridy: Y world coordinate of an arbitrary corner of an infinite grid defining its location in space. Used with scale and skew to define a general and infinite grid on which to align a raster.

That allows me to define alignment:

• "alignment": combination of gridx, gridy, scalex, scaley, skex and skewy defining a general and infinite grid on which the borders of all the pixel of a raster are aligned.

and

• "georeference": combinaison of upperleftx, upperlefty, scalex, scaley, skex and skewy defining the position of the upper left corner of a raster and the shape of the pixels constituting it.

2) "raster coordinates", "row" and "column" vs "world coordinates"

In the ST_World2RasterCoord() and ST_Raster2WorldCoord() series of function we speak about "geometric X coordinate" and "rows" and "columns". I personally find "world coordinates" and "raster coordinates" are more clear and more in link with the name of the functions. I think also that "raster column" is confusing with a "raster table column".

I would define:

-"raster coordinates": X and Y coordinates (or index) of a pixel in the raster world.

-"world coordinates": X and Y coordinates of a point in a system referencing points in the real world.

3) "tile" vs "block"

Both terms are used very often, sometimes in the same context.

"regular_blocking" for example is used in the context of the loader. raster2pgsql help speaks about tiles but the doc about blocksize. I know "blocksize" and "regular_blocking" came from Mateusz and "gdal".

The ArcGIS doc seems to use "block" and "tile" invariably.

Seems to me that "block" stick more with the idea of a "block" of memory and "tile" more with the idea of a subdivided raster coverage, this is why I prefer "tile".

Should we stick to one term in the doc? Which one do you prefer? Should we change "regular_blocking" to "regular_tiling"?

4) "geometric units" vs "measurement unit"

What is the meaning of "geometric units"? Why not just "units" or "measurement units"?

5) "nodata value" and "withdata value"

I think I invented the term "withdata value" in opposition to "nodata value". Can we or not use it?

6) "variant" & "version"

Both term are used to describe an overload of a function. I think we should stick with only one. Which one? I prefer "variant"...

7) "meta data" & "metadata"

I used to write "metadata" without space. Any opinion on that?

8) "PostgreSQL algebraic operation" vs "PostgreSQL SQL expression"

Seems to me that "PostgreSQL SQL expression" is more explicit?

9) Another thing is that rtpostgis.sql contains documentation, in form of comments, for some function. Shall we remove them all or shall we add commented documentation for every functions (at the risk of being desynchronized with the official documentation)?

I volunteer to make changes to the documentation once we come to definite definitions and terminology.

Thanks for your inputs.

[robe]

You can move this back if you plan to get it done before a day or so.

[pramsey]

Been good enough for the last 6 years....