<para>For most use cases, you will create PostGIS rasters by loading existing raster files using the packaged <varname>raster2pgsql</varname> raster loader.</para>
<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.
It is capable of loading folders of raster files as well as creating overviews of rasters. </para>
<para>Since the raster2pgsql is compiled as part of PostGIS most often (unless you compile your own GDAL library), the raster types supported
by the executable will be the same as those compiled in the GDAL dependency library. To get a list of raster types your particular PostGIS install
supports, refer to <xreflinkend="RT_ST_GDALDrivers"/>.</para>
<note>
<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>
<para>Load rasters Massachusetts state plane meters aerial tiles
into a schema called <varname>aerial</varname> and create a full view, 2 and 4 level overview tables and directly insert to database. Break up the rasters into 100x100 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>
<para>There are two raster catalog views that come package with PostGIS. Both views utilize information embedded in the constraints of the raster tables. As a result
the catalog views are always consistent with the raster data in the tables since the constraints are enforced. </para>
<orderedlist>
<listitem>
<para><varname>raster_columns</varname> this view catalogs all the raster tables in your database.</para>
</listitem>
<listitem>
<para><varname>raster_overviews</varname> this view catalogs all the rasters tables in your database that server 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 columns in the table taht 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 specified the <varname>-C</varname> flag during load, you can enforce the constraints after the
fact using <xreflinkend="AddRasterConstraints"/> so that the <varname>raster_columns</varname> catalog registers the common information after your raster tiles.</para>
<orderedlist>
<listitem>
<para><varname>r_table_catalog</varname> The database the table is in. This will always read the current database.</para>
</listitem>
<listitem>
<para><varname>r_table_schema</varname> The database schema the raster table belongs to.</para>
<para><varname>r_raster_column</varname> the 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>
</listitem>
<listitem>
<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>
</listitem>
<listitem>
<para><varname>regular_blocking</varname> This is a true/false constraint flag set on the table to denote if the tiles form a complete rectangle. It is not really validated but just taken as a given.</para>
</listitem>
<listitem>
<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>
</listitem>
<listitem>
<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 drop the <xreflinkend="RT_DropRasterConstraints"/> function before load and then reapply constraints with <xreflinkend="RT_AddRasterConstraints"/> after load. </para>