Context Navigation

Changes between Version 44 and Version 45 of WKTRaster/SpecificationFinal01

Timestamp:: 09/03/10 13:32:21 (3 years ago)
Author:: pracine
Comment:: --

Legend:

: Unmodified
: Added
: Removed
: Modified

WKTRaster/SpecificationFinal01

v44	v45
60	60	== '''Objective 0.1.6d - Being able to get all the properties of a raster (all the “Get” functions).''' ==
61	61
62		'''ST_SRID(raster\|geometry) -> integer'''[[BR]]
63
64		Return the SRID associated with the raster.
65
66		'''ST_Width(raster) -> integer'''[[BR]]
67		Return the width of the raster.
68
69		'''ST_Height(raster) -> integer'''[[BR]]
70		Return the height of the raster.
71
72		'''ST_PixelSizeX(raster) -> float64'''[[BR]]
73		Return the georeference's X pixel size of the raster. [http://www.gdal.org/classGDALDataset.html#f9593cc241e7d140f5f3c4798a43a668 See].
74
75		'''ST_PixelSizeY(raster) -> float64'''[[BR]]
76		Return the georeference's Y pixel size of the raster. [http://www.gdal.org/classGDALDataset.html#f9593cc241e7d140f5f3c4798a43a668 See].
77
78		'''ST_RotationX(raster) -> float64'''[[BR]]
79		Return the georeference's X rotation.
80
81		'''ST_RotationY(raster) -> float64'''[[BR]]
82		Return the georeference's Y rotation. [http://www.gdal.org/classGDALDataset.html#f9593cc241e7d140f5f3c4798a43a668 See].
83
84		'''ST_UpperLeftX(raster) -> float64'''[[BR]]
85		Return the georeference's X-coordinate of the upper left corner of the upper left pixel. [http://www.gdal.org/classGDALDataset.html#f9593cc241e7d140f5f3c4798a43a668 See].
86
87		'''ST_UpperLeftY(raster) -> float64'''[[BR]]
88		Return the georeference's Y-coordinate of the upper left corner of the upper left pixel. [http://www.gdal.org/classGDALDataset.html#f9593cc241e7d140f5f3c4798a43a668 See].
89
90		'''ST_Georeference(raster, text) -> string'''[[BR]]
91		Returns the georeference meta data in GDAL or ESRI format as commonly seen in a world file. For ESRI, [http://en.wikipedia.org/wiki/World_file see] for GDAL, [http://www.gdal.org/classGDALDataset.html#f9593cc241e7d140f5f3c4798a43a668 see].
92
93
94		'''ST_NumBands(raster) -> integer'''[[BR]]
95		Return the number of band included in the raster.
96
97		'''ST_BandPixelType(raster, integer) -> string'''[[BR]]
98		Return the pixel type of the specified 1-based Nth band of raster. Band index is 1-based. The function returns one of the following values:
	62	'''ST_SRID(raster\|geometry) -> integer'''
	63
	64	Returns the SRID associated with the raster.
	65
	66	'''ST_Width(raster) -> integer'''
	67
	68	Returns the width of the raster.
	69
	70	'''ST_Height(raster) -> integer'''
	71
	72	Returns the height of the raster.
	73
	74	'''ST_PixelSizeX(raster) -> float64'''
	75
	76	Returns the georeference's X pixel size of the raster. [http://www.gdal.org/classGDALDataset.html#f9593cc241e7d140f5f3c4798a43a668 See].
	77
	78	'''ST_PixelSizeY(raster) -> float64'''
	79
	80	Returns the georeference's Y pixel size of the raster. [http://www.gdal.org/classGDALDataset.html#f9593cc241e7d140f5f3c4798a43a668 See].
	81
	82	'''ST_RotationX(raster) -> float64'''
	83
	84	Returns the georeference's X rotation.
	85
	86	'''ST_RotationY(raster) -> float64'''
	87
	88	Returns the georeference's Y rotation. [http://www.gdal.org/classGDALDataset.html#f9593cc241e7d140f5f3c4798a43a668 See].
	89
	90	'''ST_UpperLeftX(raster) -> float64'''
	91
	92	Returns the georeference's X-coordinate of the upper left corner of the upper left pixel. [http://www.gdal.org/classGDALDataset.html#f9593cc241e7d140f5f3c4798a43a668 See].
	93
	94	'''ST_UpperLeftY(raster) -> float64'''
	95
	96	Returns the georeference's Y-coordinate of the upper left corner of the upper left pixel. [http://www.gdal.org/classGDALDataset.html#f9593cc241e7d140f5f3c4798a43a668 See].
	97
	98	'''ST_Georeference(raster, text) -> string'''
	99
	100	Returns the georeference meta data in GDAL or ESRI format as commonly seen in a world file. For ESRI, [http://en.wikipedia.org/wiki/World_file see] for GDAL, [http://www.gdal.org/classGDALDataset.html#f9593cc241e7d140f5f3c4798a43a668 see].
	101
	102
	103	'''ST_NumBands(raster) -> integer'''
	104
	105	Returns the number of band included in the raster.
	106
	107	'''ST_BandPixelType(raster, integer) -> string'''
	108
	109	Returns the pixel type of the specified 1-based Nth band of raster. Band index is 1-based. The function returns one of the following values:
99	110	* '''1BB''' - 1-bit boolean
100	111	* '''2BUI''' - 2-bit unsigned integer
…	…
109	120	* '''64BF''' - 64-bit float
110	121
111		'''ST_BandNoDataValue(raster, integer) -> float32'''[[BR]]
112		Return the !NoDataValue of the specified 1-based Nth band of raster. Band index is 1-based. The value is always returned as a float32 even if the pixel type is integer.
	122	'''ST_BandNoDataValue(raster, integer) -> float32'''
	123
	124	Returns the !NoDataValue of the specified 1-based Nth band of raster. Band index is 1-based. The value is always returned as a float32 even if the pixel type is integer.
113	125
114	126	----
…	…
117	129	ST_Raster_to_box2d(raster) should be renamed ST_box2d(raster).
118	130
119		'''ST_Box2D(raster) -> BOX2D''' - Returns a BOX2D representing the extent of the raster.
	131	'''ST_Box2D(raster) -> BOX2D'''
	132
	133	Returns a BOX2D representing the extent of the raster.
120	134
121	135	If the raster is rotated, the result is a box2d enclosing the rotated raster.
…	…
129	143	This function replaces ST_Raster_to_box2d() and should be used for the "raster AS box2d" cast. It should also be used instead of ST_raster_envelope() when creating indexes in gdal2wktraster.py (to be tested).
130	144
131		'''ST_ConvexHull(raster) -> polygon geometry''' - Returns the minimum convex geometry that encloses every pixel from the raster.
	145	'''ST_ConvexHull(raster) -> polygon geometry'''
	146
	147	Returns the minimum convex geometry that encloses every pixel from the raster.
132	148
133	149	The resulting polygon DOES NOT TAKE the NODATA values into account. The resulting polygon enclose every pixel, even those containing NODATA values. The resulting polygon can be rotated or not depending on the rotation of the raster. If the raster is not rotated ST_ConvexHull(geometry) is (almost) equivalent to ST_Envelope(raster) (ST_Envelope floor the coordinates and hence add a little buffer around the raster).
…	…
137	153	This function is actually already implemented by the ST_raster_envelope() function which is wrongly named. There is also a ticket (#348) related to this function: http://trac.osgeo.org/postgis/ticket/348
138	154
139		'''ST_Envelope(raster) -> polygon geometry''' - Returns the minimum bounding box for the supplied raster, as a geometry.
	155	'''ST_Envelope(raster) -> polygon geometry'''
	156
	157	Returns the minimum bounding box for the supplied raster, as a geometry.
140	158
141	159	If the raster is rotated, the envelope is a non-rotated box enclosing the rotated raster.
…	…
153	171
154	172
155		'''ST_Polygon(raster, integer) -> polygon geometry''' - Returns a geometry encomparsing every pixel having a significant value (different than the NODATA value) for the provided band.
	173	'''ST_Polygon(raster, integer) -> polygon geometry'''
	174
	175	Returns a geometry encomparsing every pixel having a significant value (different than the NODATA value) for the provided band.
156	176
157	177	This polygon geometry might contain holes if some internal areas of the raster contain pixels with NODATA values.
…	…
169	189	This function could be roughly implemented as a SQL function looking like 'SELECT ST_Collect((ST_DumpAsPolygons(raster)).geom)'. For sure a more specialised version could be faster than ST_AsPolygon.
170	190
171		'''ST_DumpAsPolygons(raster, integer) -> geomval set''' - Returns a set of "geomval" value, one for each contiguous group of pixel sharing the same value for the provided band.
	191	'''ST_DumpAsPolygons(raster, integer) -> geomval set'''
	192
	193	Returns a set of "geomval" value, one for each contiguous group of pixel sharing the same value for the provided band.
172	194
173	195	This is a set-returning function (SRF). A "geomval" value is a complex type composed of a polygon geometry (one for each contiguous group of pixel sharing the same value) and the value associated with this geometry. These values are always returned as double precision number. The shape of each polygon follow pixels edges.
…	…
200	222	[[Image(WKTRasterAsPolygon.gif)]]
201	223
202		'''DumpAsWKTPolygons(raster, integer) -> wktgeomval set''' - Returns a set of "geomval" value, one for each group of pixel sharing the same value for the provided band.
	224	'''DumpAsWKTPolygons(raster, integer) -> wktgeomval set'''
	225
	226	Returns a set of "geomval" value, one for each group of pixel sharing the same value for the provided band.
203	227
204	228	This is a set-returning function (SRF). A "wktgeomval " value is a complex type composed of a the wkt representation of a geometry (one for each group of pixel sharing the same value) and the value associated with this geometry. These values are always returned as a value of type double precision. The shape of each polygon follow pixels edges. Areas with NODATA values are not included in the resulting set.
…	…
215	239
216	240
217		'''ST_Intersects(raster, integer, geometry) -> boolean''' - Returns TRUE if the geometry and the raster "spatially intersect" - (share any portion of space) and FALSE if they don't (they are disjoint).
	241	'''ST_Intersects(raster, integer, geometry) -> boolean'''
	242
	243	Returns TRUE if the geometry and the raster "spatially intersect" - (share any portion of space) and FALSE if they don't (they are disjoint).
218	244
219	245	'''Variants'''
…	…
247	273	It might be faster to skip test 2) if this test is not signicantly faster than test 3).
248	274
249		'''ST_Intersection(raster, integer, geometry) -> geometry''' - Returns a set of "geomval" value representing the shared portion of the geometry and the raster band areas sharing a common meaningfull values. The integer parameter is the band number of the raster.
	275	'''ST_Intersection(raster, integer, geometry) -> geometry'''
	276
	277	Returns a set of "geomval" value representing the shared portion of the geometry and the raster band areas sharing a common meaningfull values. The integer parameter is the band number of the raster.
250	278
251	279	'''Variants'''
…	…
281	309
282	310	'''ST_SetSRID(raster, integer)'''
283		Set the spatial reference on the specified raster. This is the same as the ST_SetSRID function working on geometries.
	311
	312	Sets the spatial reference on the specified raster. This is the same as the ST_SetSRID function working on geometries.
284	313
285	314	'''ST_SetPixelSize(raster, pixelsize)'''
…	…
291	320	2) ST_SetPixelSize(raster, xsize, ysize)
292	321
293		Set the pixel size (cell size) on the specified raster. The base method sets the X and Y pixel size to the same value. Variant 2 sets the pixel sizes to the individually specified x and y sizes.
	322	Sets the pixel size (cell size) on the specified raster. The base method sets the X and Y pixel size to the same value. Variant 2 sets the pixel sizes to the individually specified x and y sizes.
294	323
295	324	'''ST_SetBandNoDataValue(raster, band, value)'''
296	325
297		Set the value that corresponds to NODATA in the given raster's band.
	326	Sets the value that corresponds to NODATA in the given raster's band.
298	327
299	328	'''ST_SetGeoReference(raster, georef)'''
…	…
305	334	2) ST_SetGeoReference(raster, georef)
306	335
307		Set the georeference fields of the raster (pixel size, skew, upper left location) all in one pass. The 'format' parameter is optional, and defaults to 'GDAL' georeference format if it is not specified.
	336	Sets the georeference fields of the raster (pixel size, skew, upper left location) all in one pass. The 'format' parameter is optional, and defaults to 'GDAL' georeference format if it is not specified.
308	337
309	338	If this function does not receive a georeference string with 6 parameters (or if one of the parameters is not numeric), it raises an exception "st_setgeoreference requires a string with 6 floating point values". If this method receives a NULL raster, it does nothing, and returns a NULL raster.
…	…
311	340	'''ST_SetSkew(raster, skewx, skewy)'''
312	341
313		~~Variants~~
	342	'''Variants'''
314	343
315	344	1) ST_SetSkew(raster, skewx, skewy)
…	…
321	350	'''ST_SetUpperLeft(raster, left, top)'''
322	351
323		Set the location of the upper left pixel (cell). The base method sets the X and Y coordinates to the individually specified left and top coordinates.
	352	Sets the location of the upper left pixel (cell). The base method sets the X and Y coordinates to the individually specified left and top coordinates.
324	353
325	354	----
…	…
328	357
329	358
330		'''Mostly changes to raster2pgsql.exe and ST_RasterFromText().'''[[BR]]
331		'''ST_BandPath(raster, band) -> string'''[[BR]]
332		Return the path of the filesystem raster associated with this band. The band does not contain any pixel value.
	359	'''Changes to raster2pgsql.py'''
	360
	361	'''ST_BandPath(raster, band) -> string'''
	362
	363	Return the path of the filesystem raster associated with this band. The band does not contain any pixel value.
333	364
334	365	----
335	366	== '''Objective 0.1.6h - Being able to quickly get metadata for raster and band.''' ==
336	367
337		'''ST_Metadata(raster) -> record'''[[BR]]
338		Returns all the metadata associated with a raster (upper left x, upper left y, width, height, pixelsize x, pixelsize y, skew x, skew y, srid, numbands in this order). Does not include any band metadata. If you want band metadata, add ST_BandMetadata(raster, integer) to your query.
339
340		It should be used like this: "SELECT (md).* FROM (SELECT ST_Metadata(rast) AS md FROM myrastertable) foo"
341
342		'''ST_BandMetadata(raster, integer) -> record'''[[BR]]
343		Returns all the metadata associated with a raster band (pixeltype, has nodata value, nodata value, is stored out-db, path, in this order). Does not include embedding raster metadata. If you want embedding raster metadata, add ST_Metadata(raster) to your query.
344
345		It should be used like this: "SELECT (bmd).* FROM (SELECT ST_BandMetadata(rast) AS bmd FROM myrastertable) foo"
	368	'''ST_Metadata(raster) -> record'''
	369
	370	Returns all the metadata associated with a raster (upper left x, upper left y, width, height, pixelsize x, pixelsize y, skew x, skew y, srid, numbands in this order). Does not include any band metadata. If you want band metadata, add ST_BandMetadata(raster, integer) to your query.
	371
	372	It should be used like this: "SELECT (md).* FROM (SELECT ST_Metadata(rast) AS md FROM myrastertable) foo"
	373
	374	'''ST_BandMetadata(raster, integer) -> record'''
	375
	376	Returns all the metadata associated with a raster band (pixeltype, has nodata value, nodata value, is stored out-db, path, in this order). Does not include embedding raster metadata. If you want embedding raster metadata, add ST_Metadata(raster) to your query.
	377
	378	It should be used like this: "SELECT (bmd).* FROM (SELECT ST_BandMetadata(rast) AS bmd FROM myrastertable) foo"
346	379
347	380	----
348	381	== '''Objective 0.1.6i - Being able to easily convert world coordinates to raster coordinates.''' ==
349	382
350		'''ST_World2RasterCoordX(rast raster, xw float8, yw float8)'''[[BR]]
351		Returns the column number of the pixel covering the provided X and Y world coordinates.
352		This function works even if the world coordinates are outside the raster extent.
353
354		'''ST_World2RasteCoordX(rast raster, xw float8)'''[[BR]]
355		Returns the column number of the pixels covering the provided world X coordinate for a non-rotated raster.
356		This function works even if the world coordinate is outside the raster extent.
357		This function returns an error if the raster is rotated. In this case you must also provide a Y.
358
359		'''ST_World2RasterCoordX(rast raster, pt geometry)'''[[BR]]
360		Returns the column number of the pixel covering the provided point geometry.
361		This function works even if the point is outside the raster extent.
362
363		'''ST_World2RasterCoordY(rast raster, xw float8, yw float8)'''[[BR]]
364		Returns the row number of the pixel covering the provided X and Y world coordinates.
365		This function works even if the world coordinates are outside the raster extent.
366
367		'''ST_World2RasterCoordY(rast raster, yw float8)'''[[BR]]
368		Returns the row number of the pixels covering the provided world Y coordinate for a non-rotated raster.
369		This function works even if the world coordinate is outside the raster extent.
370		This function returns an error if the raster is rotated. In this case you must also provide an X.
371
372		'''ST_World2RasterCoordY(rast raster, pt geometry)'''[[BR]]
373		Returns the row number of the pixel covering the provided point geometry.
374		This function works even if the point is outside the raster extent.
375
376		'''ST_Raster2WorldCoordX(rast raster, xr int, yr int)'''[[BR]]
377		Returns the X world coordinate of the upper left corner of the pixel located at the provided column and row numbers.
378		This function works even if the provided raster column and row are beyond or below the raster width and height.
379
380
381		'''ST_Raster2WorldCoordX(rast raster, xr int)'''[[BR]]
382		Returns the X world coordinate of the upper left corner of the pixel located at the provided column number for a non-rotated raster.
383		This function works even if the provided raster column is beyond or below the raster width.
384		This function returns an error if the raster is rotated. In this case you must also provide a Y.
385
386		'''ST_Raster2WorldCoordY(rast raster, xr int, yr int)'''[[BR]]
387		Returns the Y world coordinate of the upper left corner of the pixel located at
388		the provided column and row numbers.
389		This function works even if the provided raster column and row are beyond or below the raster width and height.
390
391		'''ST_Raster2WorldCoordY(rast raster, yr int)'''[[BR]]
392		Returns the Y world coordinate of the upper left corner of the pixel located at the provided row number for a non-rotated raster.
393		This function works even if the provided raster row is beyond or below the raster height.
394		This function returns an error if the raster is rotated. In this case you must
395		also provide an X.
	383	'''ST_World2RasterCoordX(rast raster, xw float8, yw float8)'''
	384
	385	Returns the column number of the pixel covering the provided X and Y world coordinates.
	386
	387	This function works even if the world coordinates are outside the raster extent.
	388
	389	'''ST_World2RasteCoordX(rast raster, xw float8)'''
	390
	391	Returns the column number of the pixels covering the provided world X coordinate for a non-rotated raster.
	392
	393	This function works even if the world coordinate is outside the raster extent. It returns an error if the raster is rotated. In this case you must also provide a Y.
	394
	395	'''ST_World2RasterCoordX(rast raster, pt geometry)'''
	396
	397	Returns the column number of the pixel covering the provided point geometry.
	398
	399	This function works even if the point is outside the raster extent.
	400
	401	'''ST_World2RasterCoordY(rast raster, xw float8, yw float8)'''
	402
	403	Returns the row number of the pixel covering the provided X and Y world coordinates.
	404
	405	This function works even if the world coordinates are outside the raster extent.
	406
	407	'''ST_World2RasterCoordY(rast raster, yw float8)'''
	408
	409	Returns the row number of the pixels covering the provided world Y coordinate for a non-rotated raster.
	410
	411	This function works even if the world coordinate is outside the raster extent. It returns an error if the raster is rotated. In this case you must also provide an X.
	412
	413	'''ST_World2RasterCoordY(rast raster, pt geometry)'''
	414
	415	Returns the row number of the pixel covering the provided point geometry.
	416
	417	This function works even if the point is outside the raster extent.
	418
	419	'''ST_Raster2WorldCoordX(rast raster, xr int, yr int)'''
	420
	421	Returns the X world coordinate of the upper left corner of the pixel located at the provided column and row numbers.
	422
	423	This function works even if the provided raster column and row are beyond or below the raster width and height.
	424
	425
	426	'''ST_Raster2WorldCoordX(rast raster, xr int)'''
	427
	428	Returns the X world coordinate of the upper left corner of the pixel located at the provided column number for a non-rotated raster.
	429
	430	This function works even if the provided raster column is beyond or below the raster width. It returns an error if the raster is rotated. In this case you must also provide a Y.
	431
	432	'''ST_Raster2WorldCoordY(rast raster, xr int, yr int)'''
	433
	434	Returns the Y world coordinate of the upper left corner of the pixel located at the provided column and row numbers.
	435
	436	This function works even if the provided raster column and row are beyond or below the raster width and height.
	437
	438	'''ST_Raster2WorldCoordY(rast raster, yr int)'''
	439
	440	Returns the Y world coordinate of the upper left corner of the pixel located at the provided row number for a non-rotated raster.
	441
	442	This function works even if the provided raster row is beyond or below the raster height. It returns an error if the raster is rotated. In this case you must also provide an X.
396	443
397	444	----