Changes between Version 26 and Version 27 of frmts_wtkraster.html
- Timestamp:
- Oct 20, 2010, 11:38:31 AM (13 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
frmts_wtkraster.html
v26 v27 5 5 = '''1 - Introduction''' = 6 6 7 PostGIS Raster (previously known as ' WKT Raster') is the project that provides '''raster support on PostGIS'''. Since October 1st, 2010, is an official part of PostGIS project. Further information [http://gis4free.wordpress.com/2010/10/01/wkt-raster-is-now-postgis-raster/ here].7 PostGIS Raster (previously known as '''WKT Raster''') is the project that provides '''raster support on PostGIS'''. Since September 26st, 2010, is an official part of PostGIS project. Further information [http://gis4free.wordpress.com/2010/10/01/wkt-raster-is-now-postgis-raster/ here]. 8 8 9 This driver was developed during the [http://socghop.appspot.com/ Google Summer of Code] 2009 . The driver only supports reading of regularly blocked in-db rasters.9 This driver was developed during the [http://socghop.appspot.com/ Google Summer of Code] 2009, and improved during October 2010. The driver only supports reading of regularly blocked in-db rasters. 10 10 11 The next version of the driver will be released during October 2010, andwill include these features:11 The driver is under development, at same time that PostGIS Raster. The next version of the driver will include these features: 12 12 * Out-db raster support. 13 13 * Reading of non-regular blocked rasters. 14 15 In further versions: create and modify PostGIS rasters. 16 17 This new version will have 3 raster reading working modes: 18 * Browse Mode: If the user only provides dabatase name (and optionally, schema name), the driver searches for raster tables in that database. 19 * ONE_RASTER_PER_ROW mode: The default mode, if the user provides a table name. Each of the raster table rows is considered as a different raster. 20 * ONE_RASTER_PER_TABLE mode: If the user specify a table name and this mode (still not defined the way of doing it. Probably, as an additional parameter in connection string), all the rows of the table will be considered as tiles of the same raster coverage. The whole raster extent will be calculated. The driver will deal with things like rows with different srid, or snapping to different grids. 21 22 The rest of the documentation is referred to the current driver version, and will be updated as soon as the new version of the driver will be released. 14 * Create and modify raster on PostGIS database. 23 15 24 16 == '''1.1 - Credits''' == 25 17 26 18 '''Development ''' 27 * '''Jorge Arévalo''' develops the driver19 * '''Jorge Arévalo''' (jorge.arevalo at deimos-space.com) develops the driver 28 20 29 21 30 22 == '''1.2 - More information''' == 31 * WKTRaster documentation page [http://trac.osgeo.org/postgis/wiki/WKTRaster/Documentation01 here]32 * Introduction to WKTRaster format and description of the work done during the Google Summer of Code 2009 [http://trac.osgeo.org/gdal/wiki/WKTRasterDriver here]23 * PostGIS Raster documentation page [http://trac.osgeo.org/postgis/wiki/WKTRaster/Documentation01 here] 24 * Introduction to PostGIS Raster format and description of the work done during the Google Summer of Code 2009 [http://trac.osgeo.org/gdal/wiki/WKTRasterDriver here] 33 25 * Search for "WKT Raster" in the [http://postgis.refractions.net/pipermail/postgis-users/ PostGIS-users] and [http://postgis.refractions.net/pipermail/postgis-devel/ PostGIS-devel] forums archives or in [http://www.nabble.com/PostGIS-f1221.html Nabble] or write to these forums. 34 26 … … 38 30 = '''2 - Installation''' = 39 31 40 == '''2.1 - Requirements''' ==32 == '''2.1 - Installing prerequisites''' == 41 33 42 For using GDAL WKT Raster driver, you will first need to install: 34 These requisites are for setting up an enviroment with PostgreSQL/PostGIS with raster support. You'll first need some pre-requisites: 35 36 * [http://www.postgresql.org/ PostgreSQL] version 8.3 or higher 37 * [http://trac.osgeo.org/proj Proj4 library] version 4.5.0 or higher 38 * [http://trac.osgeo.org/geos GEOS library] version 3.1.0 or higher 39 * [http://www.python.org Python] version 2.5 or higher 43 40 44 * [http://www.postgresql.org/ PostgreSQL] version 8.3 or higher 45 * [http://trac.osgeo.org/proj Proj4 library] version 4.4 or higher 46 * [http://trac.osgeo.org/geos GEOS library] version 3.2.0 or higher 47 * [http://postgis.refractions.net/ PostGIS] version 1.4.0 or higher 48 * [http://trac.osgeo.org/postgis/wiki/WKTRaster WKTRaster PostGIS extension] version 0.1.6SVN or higher 49 * [http://www.python.org/ Python] version 2.5 or higher and [http://pypi.python.org/pypi/GDAL/ GDAL for Python] version 1.6.0 or higher for the loader (gdal2wktraster.py). 41 Then you'll need to fetch the last PostGIS SVN development snapshot. The PostGIS Raster extension is part of the PostGIS library since September 26th 2010, and there's no stable PostGIS version that includes it yet. The first stable version with PostGIS Raster extension will be '''PostGIS 2.0''', expected for April 2011. 50 42 51 52 == '''2.2 - Installed precompiled binaries''' == 43 The last PostGIS development station can be found [http://postgis.refractions.net/download/postgis-2.0.0SVN.tar.gz here]. Instructions for compiling and installing PostGIS with raster extension are [http://gis4free.wordpress.com/2010/10/01/wkt-raster-is-now-postgis-raster/ here]. 53 44 54 This driver is part of the GDAL library. You can find ready to use binaries [http://trac.osgeo.org/gdal/wiki/DownloadingGdalBinaries here].55 45 56 == '''2. 3 - Compiling and installing from sources''' ==46 == '''2.2 - Installing GDAL''' == 57 47 58 === '''2. 3.1 - Downloading source''' ===48 === '''2.2.1 - From binaries''' === 59 49 60 Follow the instructions to compile the requisites [http://www.gis4free.org/blog/2009/05/30/gsoc-09-weekly-report-1-2305-2905/ here] '''(only the 5 first steps)'''. After this, you can download and install GDAL library as usual. But please, take into account that the driver isn't included in stable version yet. You'll have to checkout the code from SVN: 50 Currently, there's no stable GDAL release that includes the PostGIS Raster driver. The first one will be '''GDAL 1.8.0'''. You can get daily build binaries for Windows mantained by Tamas Szekeres [http://vbkto.dyndns.org/sdk/ here]. In Linux and Mac Os X, you'll need to compile the source code. 51 52 Anyway, there is updated information about general GDAL binaries [http://trac.osgeo.org/gdal/wiki/DownloadingGdalBinaries here] 53 54 === '''2.2.2 - From sources''' === 55 56 You can download daily GDAL snapshots from [http://www.gdal.org/daily/ here], or checkout the code directly from SVN with any subversion client. The examples of this documentation are using Linux console client, but they're easily reproducible with any other client, simply using the same URLs 61 57 62 58 {{{ … … 64 60 }}} 65 61 66 Or, if you prefer it, download one of the [http://download.osgeo.org/gdal/daily/ GDAL daily builds] 62 After that, you have to build GDAL library with Python support: 67 63 64 {{{ 65 >$ ./configure --with-python & make & make install 66 }}} 68 67 69 === '''2.3.2 - Building''' === 70 71 You can find instructions on how to build GDAL library [http://trac.osgeo.org/gdal/wiki/BuildHints here]. 72 68 Further instructions [http://trac.osgeo.org/gdal/wiki/BuildHints here]. 73 69 74 70 [[BR]] 75 71 76 = '''3 - Using GDAL WKTRaster driver''' =72 = '''3 - Using GDAL PostGIS Raster driver''' = 77 73 78 74 == '''3.1 - Loading raster data''' == 79 75 80 The GDAL WKT Raster driver isn't able to load raster data yet. For this proposal, you'll have to use '''gdal2wktraster''' script. This loader script is included with the WKT Raster extension installation, under the ''scripts'' subdirectory. To check the syntax of the script, execute this command from ''$WKT_RASTER/scripts''subdirectory:76 The GDAL PostGIS Raster driver isn't able to load raster data yet. For this proposal, you'll have to use '''gdal2raster''' script. This loader script is included with the PostGIS installation, under the ''raster/scripts/python'' subdirectory. To check the syntax of the script, execute this command from that subdirectory: 81 77 82 78 {{{ 83 >$ python gdal2 wktraster.py --help79 >$ python gdal2raster.py --help 84 80 }}} 85 81 86 '''Important:''' The out-db raster support for WKTRaster is still under development. Please, don't use this option.82 '''Important:''' The out-db raster support for PostGIS Raster is still under development. Please, don't use this option. 87 83 88 84 '''Example 1''': 89 85 90 Load [http:// www.gis4free.org/gdal_wktraster_autotest/autotest/gdrivers/data/utm.tif this one-band grayscale image] (utm.tif) on PostGIS using loader script:86 Load [http://dl.dropbox.com/u/6599273/utm.tif this one-band grayscale image] (utm.tif) on PostGIS using loader script: 91 87 92 88 {{{ 93 >$ python gdal2 wktraster.py -r utm.tif -t utm -l 1 -k 100x100-o utm.sql -s 26711 -I -M89 >$ python gdal2raster.py -r /path/to/utm.tif -t [schema.]utm -l 1 -k 64x64 -o utm.sql -s 26711 -I -M 94 90 }}} 95 91 96 In this example, the script generates a SQL output (redirected to the file ''utm.sql''). This SQL code adds the image ''utm.tif'' to PostGIS, using a regular blocking arrangement with blocks of 100x100px. To execute the code, you must run this command as '''postgres''' user:92 In this example, the script generates a SQL output (redirected to the file ''utm.sql''). This SQL code adds the image ''utm.tif'' to PostGIS, using a regular blocking arrangement with blocks of 64x64px. A new raster table will be created and each image block will be a row of the raster table. To execute the code, you must run this command from a console: 97 93 98 94 {{{ 99 >$ psql -d < wktraster_database> -f utm.sql95 >$ psql -d <raster_database> -f utm.sql -U <user> -W 100 96 }}} 101 97 102 The '' wktraster_database'' must be a PostgreSQL database with PostGIS and WKT Raster extensions enabled.98 The ''raster_database'' must be a PostgreSQL database with PostGIS Raster extension enabled. The user ''user'' must have privileges to create tables and insert values in the database. 103 99 104 100 '''Example 2''': 105 101 106 Load [http:// www.gis4free.org/gdal_wktraster_autotest/autotest/gdrivers/data/small_world.tif this RGB image] (small_world.tif) on PostGIS using loader script:102 Load [http://dl.dropbox.com/u/6599273/katrina.tif this RGB image] (katrina.tif) on PostGIS using loader script: 107 103 108 104 {{{ 109 >$ python gdal2 wktraster.py -r small_world.tif -t utm -l 1 -k 40x20 -o small_world.sql -s 4326 -I -M105 >$ python gdal2raster.py -r /path/to/katrina.tif -t katrina -l 1 -k 64x64 -o katrina.sql -s 4326 -I -M 110 106 }}} 111 107 112 As in ''Example 1'', this code generates a SQL file, called '' small_world.sql'' with the SQL code to add the image ''small_world.tif'' to PostGIS using a regular blocking arrangement with blocks of 40x20px. To execute the code, as '''postgres''' user,run:108 As in ''Example 1'', this code generates a SQL file, called ''katrina.sql'' with the SQL code to add the image ''katrina.tif'' to PostGIS using a regular blocking arrangement with blocks of 64x64px. Again, a new raster table will created and each image block will be a row of the raster table. To execute the code, again run: 113 109 114 110 {{{ 115 >$ psql -d < wktraster_database> -f small_world.sql111 >$ psql -d <raster_database> -f katrina.sql -U <user> -W 116 112 }}} 117 113 … … 119 115 '''Example 3''': 120 116 121 Using the first image (utm.tif), let's create an overview of the image of half size (meaning image dimensions, not file size) in PostGIS.117 Using the second image (katrina.tif), let's create an overview of the image of half size (meaning image dimensions, not file size) in PostGIS. 122 118 123 119 {{{ 124 >$ python gdal2 wktraster.py -r utm.tif -t utm -l 2 -V -k 100x100 -o utm_ov2.sql -s 26711-I -M120 >$ python gdal2raster.py -r /path/to/katrina.tif -t katrina -l 2 -V -k 64x64 -o katrina_ov2.sql -s 4326 -I -M 125 121 }}} 126 122 127 The key concept here is the '''-V''' flag. This flag allows loader script to create a new table to store the overviews' metadata. If you want to load several images with overviews, you'll have to use this flag '''only the first time''' the loader script is called, to create the overviews' metadata table only once. 123 The key concepts here are: 124 * The '''-V''' flag. This flag allows loader script to create a new table to store the overviews' metadata. If you want to load several images with overviews, you'll have to use this flag '''only the first time''' the loader script is called, to create the overviews' metadata table only once. 125 * The '''-l 2''' flag. This flag forces the loader script to create a table with a GDAL-provided overview of the original file, with an overview factor of 2. This is, half size. 128 126 129 The '''-l 2''' flag represents the overview level. 2 means an overview of the 50% of the original image size. 130 131 As usual, to execute the generated SQL code, run as '''postgres''' this command: 127 As usual, to execute the generated SQL code, run this command: 132 128 133 129 {{{ 134 >$ psql -d < wktraster_database> -f utm_ov2.sql130 >$ psql -d <raster_database> -f katrina_ov2.sql -U <user> -W 135 131 }}} 136 132 … … 141 137 142 138 {{{ 143 PG":host='<host>' port:'<port>' dbname='<dbname>' user='<user>' password='<password>' [schema='<schema>'] table='<raster_table>' [where='<sql_where>'mode='<working_mode>']"139 PG":host='<host>' port:'<port>' dbname='<dbname>' user='<user>' password='<password>' [schema='<schema>'] [table='<raster_table>'] [where='<sql_where>' [mode='<working_mode>']" 144 140 }}} 145 141 146 Note that the string, until the part that starts with "table='" is a libpq-style [http://www.gdal.org/ogr/drv_pg.html connection string]. That means that you can change the order of these fields (dbname, user, password, host), or leave out unnecessary ones (like password, in some cases).142 Note that the string, until the part that starts with "table='" is a libpq-style [http://www.gdal.org/ogr/drv_pg.html connection string]. That means that you can leave out unnecessary fields (like password, in some cases). 147 143 148 The "table" option requires the name of a WKT Raster table. This table only can be created by using the script gdal2tiles, from [http://trac.osgeo.org/postgis/wiki/WKTRaster WKTRaster code]144 The "table" option requires the name of a WKT Raster table. This table only can be created by using the script ''gdal2tiles'', by now. 149 145 150 The "where" option is used to filter the results of the raster table. Any SQL-WHERE expression is valid. The "mode" option is used to know the expected arrangement of the raster table. As the driver is currently working with only one table arrangement (regularly blocked tables), you can omit this option, or use it with value "REGULARLY_TILED_MODE". Otherwise, the driver won't work.146 The "where" option is used to filter the results of the raster table. Any SQL-WHERE expression is valid. The "mode" option is used to know the expected arrangement of the raster table. There are 2 possible values: 151 147 152 You must use this dataset's format in all the gdal tools, like gdalinfo, gdal_translate, gdalwarp, etc. 148 * mode = 1. Also called ''ONE_RASTER_PER_ROW'' mode. In this case, a raster table is considered as a bunch of different raster files. This mode is intended for raster tables storing different raster files. It's the default mode if you don't provide this field in connection string. 149 * mode = 2. Also called ''ONE_RASTER_PER_TABLE'' mode. In this case, a raster table is considered as a unique raster file, even if the table has more than one row. This mode is intended for reading tiled rasters from database, just like the rasters created in section 3.1. 150 151 Three important notes here: 152 * If a table stores a tiled raster (like ones created in section 3.1) and you execute the driver with mode = 1, each image tile will be considered as a different image, and will be reported as a subdataset. 153 * There are use cases the driver can't still work with. For example: non-regular blocked rasters. That cases are detected and an error is raised. Anyway, as I've said, the driver is under development, and will work with more raster arrangements ASAP. 154 * There's an additional working mode. If you don't provide a table name, the driver will look for existing raster tables in all allowed database' schemas, and will report each table as a subdataset. 155 156 You must use this connection string's format in all the gdal tools, like gdalinfo, gdal_translate, gdalwarp, etc. 153 157 154 158 '''Example 1:''' … … 157 161 158 162 {{{ 159 >$ gdalinfo -mm -stats -checksum "PG:host='localhost' dbname='< wktraster_database>' user='<wktraster_user>' password='<wktraster_password>' table='utm'"163 >$ gdalinfo -mm -stats -checksum "PG:host='localhost' dbname='<raster_database>' user='<user>' password='<password>' table='utm' mode='2'" 160 164 }}} 161 165 … … 165 169 '''Example 2:''' 166 170 167 To get an overview of the originalimage with half size run this command:171 To get an overview of the ''katrina.tif'' image with half size run this command: 168 172 169 173 {{{ 170 >$ gdal_translate -outsize 50% 50% "PG:host='localhost' dbname='< wktraster_database>' user='<wktraster_user>' password='<wktraster_password>' table='utm'" utm_half_size.tif174 >$ gdal_translate -outsize 50% 50% "PG:host='localhost' dbname='<raster_database>' user='<user>' password='<password>' table='katrina'" katrina_half_size.tif 171 175 }}} 172 176 173 This will create a file called '' utm_half_size.tif'' like the original ''utm.tif'' but half size.177 This will create a file called ''katrina_half_size.tif'' like the original ''katrina.tif'' but half size. 174 178 175 179 176 180 == '''3.3 - Creating and modifying data''' == 177 181 178 The GDAL WKT Raster driver is not able to create and modify rasters yet. You'll have to use '''gdal2wktraster''' loader to create new ones.182 The GDAL PostGIS Raster driver is not able to create and modify rasters yet. You'll have to use '''gdal2raster''' loader to create new ones. 179 183 180 184 181 185 [[BR]] 182 186 183 = '''4 - GDAL WKT Raster driver reference''' =184 187 185 TODO 188 = '''4 - Reporting problems''' = 186 189 187 [[BR]] 188 189 = '''5 - Reporting problems''' = 190 191 If you find any error, want to suggest something or if simply want to say ''hello'' :-), write a mail to ''jorgearevalo at deimos-space dot com'' 192 190 To report errors and suggestions, you can use the [http://www.osgeo.org/mailman/listinfo/gdal-dev/ gdal-dev list] or write me an e-mail: jorge.arevalo at deimos-space.com