[postgis-devel] [PostGIS] #1584: [raster] Improve raster documentation terminology and consistency

[PostGIS]

#1584: [raster] Improve raster documentation terminology and consistency
-------------------------+--------------------------------------------------
 Reporter:  pracine      |       Owner:  pracine      
     Type:  enhancement  |      Status:  new          
 Priority:  medium       |   Milestone:  PostGIS 2.0.0
Component:  raster       |     Version:  trunk        
 Keywords:               |  
-------------------------+--------------------------------------------------
 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.

-- 
Ticket URL: <http://trac.osgeo.org/postgis/ticket/1584>
PostGIS <http://trac.osgeo.org/postgis/>
The PostGIS Trac is used for bug, enhancement & task tracking, a user and developer wiki, and a view into the subversion code repository of PostGIS project.