<para>For most use cases, you will create PostGIS rasters by loading existing raster files using the packaged <varname>raster2pgsql</varname> raster loader.</para>
The <varname>raster2pgsql</varname> is a raster loader executable that loads GDAL supported raster formats into sql suitable for loading into a PostGIS raster table.
by the executable will be the same as those compiled in the GDAL dependency library. To get a list of raster types your particular raster2pgsql supports use the <varname>-G</varname> switch. These should be the same as those provided by your PostGIS install documented here <xreflinkend="RT_ST_GDALDrivers"/> if you are using the same gdal library for both.</para>
<para>The older version of this tool was a python script. The executable has replaced the python script. If you still find the need for the Python script
<listitem><para>Execute each statement individually, do not use a transaction.</para></listitem>
</varlistentry>
<varlistentry>
<term>-E ENDIAN</term>
<listitem><para>Control endianness of generated binary output of raster; specify 0 for XDR and 1 for NDR (default); only NDR output is supported now</para></listitem>
</varlistentry>
<varlistentry>
<term>-V <varname>version</varname></term>
<listitem><para>Specify version of output format. Default is 0. Only 0 is supported at this time.</para></listitem>
</varlistentry>
</variablelist>
<para>An example session using the loader to create an input file and uploading it might look like this:</para>
into a schema called <varname>aerial</varname> and create a full view, 2 and 4 level overview tables, use copy mode for inserting (no intermediary file just straight to db), and -e don't force everything in a transaction (good if you want to see data in tables right away without waiting). Break up the rasters into 128x128 pixel tiles and apply raster constraints. Use copy mode instead of table insert. (-F) Include a field called filename to hold the name of the file the tiles were cut from.</para>
<title>Creating rasters using PostGIS raster functions</title>
<para>On many occasions, you'll want to create rasters and raster tables right in the database. There are a plethora of functions to do that. The general steps to follow.</para>
<orderedlist>
<listitem><para>Create a table with a raster column to hold the new raster records which can be accomplished with:</para>
<programlisting>CREATE TABLE myrasters(rid serial primary key, rast raster);</programlisting>
other functions such as <xreflinkend="RT_ST_Union"/> or <xreflinkend="RT_ST_MapAlgebraFct2"/> or any of the family of other map algebra functions.</para>
<para>There are even many more options for creating new raster tables from existing tables. For example you can create a raster table in a different projection from an existing one using <xreflinkend="RT_ST_Transform"/></para>
<listitem><para>Once you are done populating your table initially, you'll want to create a spatial index on the raster column with something like:</para>
<programlisting>CREATE INDEX myrasters_rast_st_convexhull_idx ON myrasters USING gist( ST_ConvexHull(rast) );</programlisting>
<para>Note the use of <xreflinkend="RT_ST_ConvexHull"/> since most raster operators are based on the convex hull of the rasters.</para>
<note><para>Pre-2.0 versions of PostGIS raster were based on the envelop rather than the convex hull. For teh spatial idnexes to work properly you'll need to drop those and replace with convex hull based index.</para></note></listitem>
<listitem>Apply raster constraints using <xreflinkend="RT_AddRasterConstraints"/></listitem>
<para>There are two raster catalog views that come packaged with PostGIS. Both views utilize information embedded in the constraints of the raster tables. As a result
<para><varname>raster_overviews</varname> this view catalogs all the raster table columns in your database that serve as overviews for a finer grained table. Tables of this type are generated when you use the <varname>-l</varname> switch during load.</para>
<para>The <varname>raster_columns</varname> is a catalog of all raster table columns in your database that are of type raster. It is a view utilizing the constraints on the tables
so the information is always consistent even if you restore one raster table from a backup of another database. The following columns exist in the <varname>raster_columns</varname> catalog.</para>
<para>If you created your tables not with the loader or forgot to specify the <varname>-C</varname> flag during load, you can enforce the constraints after the
fact using <xreflinkend="RT_AddRasterConstraints"/> so that the <varname>raster_columns</varname> catalog registers the common information about your raster tiles.</para>
<para><varname>r_raster_column</varname> the column in the <varname>r_table_name</varname> table that is of type raster. There is nothing in PostGIS preventing you from having multiple raster columns per table so its possible to have a raster table listed multiple times with a different raster column for each.</para>
<para><varname>srid</varname> The spatial reference identifier of the raster. Should be an entry in the <xreflinkend="spatial_ref_sys"/>.</para>
</listitem>
<listitem>
<para><varname>scale_x</varname> The scaling between geometric spatial coordinates and pixel. This is only available if all tiles in the raster column have the same <varname>scale_x</varname> and this constraint is applied. Refer to <xreflinkend="RT_ST_ScaleX"/> for more details.</para>
</listitem>
<listitem>
<para><varname>scale_y</varname> The scaling between geometric spatial coordinates and pixel. This is only available if all tiles in the raster column have the same <varname>scale_y</varname> and the <varname>scale_y</varname> constraint is applied. Refer to <xreflinkend="RT_ST_ScaleY"/> for more details.</para>
</listitem>
<listitem>
<para><varname>blocksize_x</varname> The width (number of pixels across) of each raster tile . Refer to <xreflinkend="RT_ST_Width"/> for more details.</para>
</listitem>
<listitem>
<para><varname>blocksize_y</varname> The width (number of pixels down) of each raster tile . Refer to <xreflinkend="RT_ST_Height"/> for more details.</para>
</listitem>
<listitem>
<para><varname>same_alignment</varname> A boolean that is true if all the raster tiles have the same alignment . Refer to <xreflinkend="RT_ST_SameAlignment"/> for more details.</para>
<para><varname>regular_blocking</varname> This is a true/false constraint flag set on the table to denote that the tiles do not overlap, are of the same alignment, pixel size, srid etc. It is not really validated but just taken as a given so should be used for informational. In the future we plan to properly constrain this so that this inforamtion is guaranteed to be right when it returns <varname>true</varname></para>
<para><varname>num_bands</varname> The number of bands in each tile of your raster set. This is the same information as what is provided by <xreflinkend="RT_ST_NumBands"/></para>
</listitem>
<listitem>
<para><varname>pixel_types</varname> An array defining the pixel type for each band. You will have the same number of elements in this array as you have number of bands. The pixel_types are one of the following defined in <xreflinkend="RT_ST_BandPixelType"/>.</para>
</listitem>
<listitem>
<para><varname>nodata_values</varname> An array of double precision numbers denoting the <varname>nodata_value</varname> for each band. You will have the same number of elements in this array as you have number of bands. These numbers define the pixel value for each band that should be ignored for most operations. This is similar information provided by <xreflinkend="RT_ST_BandNoDataValue"/>.</para>
<para><varname>extent</varname> This is the extent of all the raster rows in your raster set. If you plan to load more data that will change the extent of the set, you'll want to run the <xreflinkend="RT_DropRasterConstraints"/> function before load and then reapply constraints with <xreflinkend="RT_AddRasterConstraints"/> after load. </para>
<para><varname>raster_overviews</varname> catalogs information about raster table columns used for overviews and additional information about them that is useful to know when utilizing overviews. Overview tables are cataloged in both <varname>raster_columns</varname> and <varname>raster_overviews</varname> because they are rasters in their own right but also serve an additional special purpose of being a lower resolution caricature of a higher resolution table. These are generated along-side the main raster table when you use the <varname>-l</varname> switch in raster loading.</para>
<para>Overview tables contain the same constraints as other raster tables as well as additional informational only constraints specific to overviews.</para>
<note><para>The information in <varname>raster_overviews</varname> does not duplicate the information in <varname>raster_columns</varname>. If you need the information about an overview table present in <varname>raster_columns</varname> you can join the <varname>raster_overviews</varname> and <varname>raster_columns</varname> together to get the full set of information you need.</para></note>
<listitem>Computations are generally faster to do on them than their higher resolution parents because there are fewer records and each pixel covers more territory. Though the computations are not as accurate as the high-res tables they support, they can be sufficient in many rule-of-thumb computations.</listitem>
<para><varname>o_raster_column</varname> the raster column in the overview table.</para>
</listitem>
<listitem>
<para><varname>r_table_catalog</varname> The database the raster table that this overview services is in. This will always read the current database.</para>
</listitem>
<listitem>
<para><varname>r_table_schema</varname> The database schema the raster table that this overview services belongs to.</para>
</listitem>
<listitem>
<para><varname>r_table_name</varname> raster table that this overview services.</para>
</listitem>
<listitem>
<para><varname>r_raster_column</varname> the raster column that this overview column services.</para>
<para><varname>overview_factor</varname> - this is the pyramid level of the overview table. The higher the number the lower the resolution of the table.</para>
a particular wgs 84 bounding box and then unions with <xreflinkend="RT_ST_Union"/> the intersecting tiles together returning all bands, transforms to user specified projection using <xreflinkend="RT_ST_Transform"/>,
<para>You would call the below using <programlisting>http://mywebserver/test_raster.php?srid=2249</programlisting> to get the raster image in Massachusetts state plane feet.</para>
<para>You will need the npgsql .NET PostgreSQL driver for this exercise which you can get the latest of from <ulinkurl="http://npgsql.projects.postgresql.org/">http://npgsql.projects.postgresql.org/</ulink>. Just download the latest and drop into your ASP.NET bin folder and you'll be good to go.</para>
<para>The sample query demonstrates how to combine a whole bunch of raster functions together to grab all tiles that intersect
a particular wgs 84 bounding box and then unions with <xreflinkend="RT_ST_Union"/> the intersecting tiles together returning all bands, transforms to user specified projection using <xreflinkend="RT_ST_Transform"/>,
and then outputs the results as a png using <xreflinkend="RT_ST_AsPNG"/>.</para>
<para>This is same example as <xreflinkend="RT_PHP_Output"/> except implemented in C#.</para>
<para>You would call the below using <programlisting>http://mywebserver/TestRaster.ashx?srid=2249</programlisting> to get the raster image in Massachusetts state plane feet.</para>
<para>You can download the latest PostgreSQL JDBC drivers from <ulinkurl="http://jdbc.postgresql.org/download.html">http://jdbc.postgresql.org/download.html</ulink></para>