raster2pgsql ملف تنفيذي لتحميل الرستر يحوّل صيغ الرستر التي تدعمها GDAL إلى SQL مناسب للتحميل في جدول رستر PostGIS. وهو قادر على تحميل مجلدات من ملفات الرستر، وكذلك إنشاء عروض مصغّرة (overviews) للرستر.

بما أن raster2pgsql يُترجَم غالبًا كجزء من PostGIS (ما لم تترجم مكتبة GDAL الخاصة بك)، فستكون أنواع الرستر التي يدعمها الملف التنفيذي هي نفسها المترجَمة في مكتبة GDAL التابعة. للحصول على قائمة بأنواع الرستر التي يدعمها raster2pgsql لديك، استخدم الخيار -G.

	عند إنشاء عروض مصغّرة بمُعامل محدد من مجموعة رستر متحاذية، قد لا تتحاذى العروض المصغّرة. زُر http://trac.osgeo.org/postgis/ticket/1764 للاطلاع على مثال لا تتحاذى فيه العروض المصغّرة.

10.1.1.1. مثال على الاستخدام

قد تبدو جلسة نموذجية تستخدم المُحمِّل لإنشاء ملف إدخال ورفعه مقسّمًا إلى بلاطات بحجم 100x100 على النحو الآتي:

# -s use srid 4326
# -I create spatial index
# -C use standard raster constraints
# -M vacuum analyze after load
# *.tif load all these files
# -F include a filename column in the raster table
# -t tile the output 100x100
# public.demelevation load into this table
raster2pgsql -s 4326 -I -C -M -F -t 100x100 *.tif public.demelevation 
> elev.sql

# -d connect to this database
# -f read this file after connecting
psql -d gisdb -f elev.sql

	إذا لم تحدد المخطط (schema) كجزء من اسم الجدول الهدف، فسيُنشأ الجدول في المخطط الافتراضي لقاعدة البيانات أو للمستخدم الذي تتصل به.

يمكن إجراء التحويل والرفع في خطوة واحدة باستخدام أنابيب UNIX:

raster2pgsql -s 4326 -I -C -M *.tif -F -t 100x100 public.demelevation | psql -d gisdb

تحميل بلاطات رستر جوية بالأمتار وفق نظام Massachusetts state plane إلى مخطط يُسمى aerial، وإنشاء عرض كامل وجداول عروض مصغّرة بالمستويين 2 و4، واستخدام وضع النسخ (copy) للإدراج (دون ملف وسيط، مباشرة إلى قاعدة البيانات)، و-e لعدم فرض تنفيذ كل شيء في معاملة (مفيد إذا أردت رؤية البيانات في الجداول فورًا دون انتظار). تقسيم الرستر إلى بلاطات بحجم 128x128 بكسل وتطبيق قيود الرستر. استخدام وضع النسخ بدلًا من الإدراج في الجدول. (-F) تضمين حقل يُسمى filename لحفظ اسم الملف الذي قُطعت منه البلاطات.

raster2pgsql -I -C -e -Y -F -s 26986 -t 128x128  -l 2,4 bostonaerials2008/*.jpg aerials.boston | psql -U postgres -d gisdb -h localhost -p 5432

--get a list of raster types supported:
raster2pgsql -G

يُخرج الأمر -G قائمة تشبه

Available GDAL raster formats:
  Virtual Raster
  GeoTIFF
  National Imagery Transmission Format
  Raster Product Format TOC format
  ECRG TOC format
  Erdas Imagine Images (.img)
  CEOS SAR Image
  CEOS Image
  ...
  Arc/Info Export E00 GRID
  ZMap Plus Grid
  NOAA NGS Geoid Height Grids

في مناسبات كثيرة، ستحتاج إلى إنشاء الرستر وجداول الرستر داخل قاعدة البيانات مباشرة. وتوجد وفرة من الدوال لذلك. الخطوات العامة الواجب اتباعها هي:

تستخدم الأداة raster2pgsql مكتبة GDAL للوصول إلى بيانات الرستر، ويمكنها الاستفادة من ميزة أساسية في GDAL: القدرة على القراءة من رستر مخزّن عن بُعد في "مخازن الكائنات" السحابية (مثل AWS S3 وGoogle Cloud Storage).

يتطلب الاستخدام الفعال للرستر المخزّن سحابيًا استخدام صيغة "مُحسَّنة للسحابة". وأشهرها وأوسعها استخدامًا صيغة "GeoTIFF المُحسَّنة للسحابة". أما استخدام صيغة غير سحابية، مثل JPEG أو TIFF غير مقسّم إلى بلاطات، فسيؤدي إلى أداء ضعيف جدًا، لأن النظام سيضطر إلى تنزيل الرستر بأكمله في كل مرة يحتاج فيها إلى الوصول إلى جزء منه.

أولًا، حمّل الرستر إلى التخزين السحابي الذي تختاره. وبعد تحميله سيكون لديك URI للوصول إليه، إما URI من نوع "http"، أو أحيانًا URI خاص بالخدمة (مثل "s3://bucket/object"). وللوصول إلى الحاويات غير العامة، ستحتاج إلى تقديم خيارات إعداد GDAL لمصادقة اتصالك. لاحظ أن هذا الأمر يقرأ من الرستر السحابي ويكتب إلى قاعدة البيانات.

AWS_ACCESS_KEY_ID=xxxxxxxxxxxxxxxxxxxx \
AWS_SECRET_ACCESS_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
raster2pgsql \
  -s 990000 \
  -t 256x256 \
  -I \
  -R \
  /vsis3/your.bucket.com/your_file.tif \
  your_table \
  | psql your_db

بعد تحميل الجدول، تحتاج إلى منح قاعدة البيانات إذنًا بالقراءة من الرستر البعيد، بضبط إعدادين: postgis.enable_outdb_rasters وpostgis.gdal_enabled_drivers.

SET postgis.enable_outdb_rasters = true;
SET postgis.gdal_enabled_drivers TO 'ENABLE_ALL';
    

لجعل التغييرات دائمة، اضبطها مباشرة على قاعدة بياناتك. ستحتاج إلى إعادة الاتصال حتى تسري الإعدادات الجديدة.

ALTER DATABASE your_db SET postgis.enable_outdb_rasters = true;
ALTER DATABASE your_db SET postgis.gdal_enabled_drivers TO 'ENABLE_ALL';
    

بالنسبة إلى الرستر غير العام، قد تضطر إلى تقديم مفاتيح وصول للقراءة من الرستر السحابي. ويمكن ضبط المفاتيح نفسها التي استخدمتها في استدعاء raster2pgsql لاستخدامها داخل قاعدة البيانات، عبر الإعداد postgis.gdal_vsi_options. لاحظ أنه يمكن ضبط عدة خيارات بفصل أزواج key=value بمسافات.

SET postgis.gdal_vsi_options = 'AWS_ACCESS_KEY_ID=xxxxxxxxxxxxxxxxxxxx
AWS_SECRET_ACCESS_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';

بعد تحميل البيانات وضبط الأذونات، يمكنك التعامل مع جدول الرستر كأي جدول رستر آخر، باستخدام الدوال نفسها. وستتولى قاعدة البيانات جميع آليات الاتصال بالبيانات السحابية عندما تحتاج إلى قراءة بيانات البكسلات.

raster_columns فهرس لجميع أعمدة جداول الرستر في قاعدة بياناتك التي من النوع raster. وهو عرض يستخدم القيود على الجداول، لذا تظل المعلومات متسقة دائمًا حتى لو استعدت جدول رستر من نسخة احتياطية لقاعدة بيانات أخرى. توجد الأعمدة الآتية في الفهرس raster_columns.

إذا لم تُنشئ جداولك باستخدام المُحمِّل أو نسيت تحديد الخيار -C أثناء التحميل، يمكنك فرض القيود لاحقًا باستخدام AddRasterConstraints حتى يسجّل الفهرس raster_columns المعلومات المشتركة عن بلاطات الرستر لديك.

يُفهرس raster_overviews المعلومات عن أعمدة جداول الرستر المستخدمة كعروض مصغّرة، ومعلومات إضافية عنها من المفيد معرفتها عند استخدام العروض المصغّرة. تُفهرس جداول العروض المصغّرة في كل من raster_columns وraster_overviews لأنها رستر قائم بذاته، لكنها تخدم أيضًا غرضًا خاصًا إضافيًا هو كونها صورة تقريبية منخفضة الدقة لجدول عالي الدقة. وتُولَّد بجانب جدول الرستر الرئيسي عند استخدام الخيار -l في تحميل الرستر، أو يمكن توليدها يدويًا باستخدام AddOverviewConstraints.

تحتوي جداول العروض المصغّرة على القيود نفسها الموجودة في جداول الرستر الأخرى، إضافة إلى قيود إعلامية فقط خاصة بالعروض المصغّرة.

	لا تُكرّر المعلومات في raster_overviews المعلومات الموجودة في raster_columns. إذا احتجت إلى المعلومات المتعلقة بجدول عرض مصغّر الموجودة في raster_columns، يمكنك ربط raster_overviews وraster_columns معًا للحصول على المجموعة الكاملة من المعلومات التي تحتاجها.

السببان الرئيسيان للعروض المصغّرة هما:

يحتوي الفهرس raster_overviews على أعمدة المعلومات التالية.

في هذا القسم سنوضح كيفية استخدام مشغّل PHP لـ PostgreSQL وعائلة الدوال ST_AsGDALRaster لإخراج النطاقات 1 و2 و3 من رستر إلى تدفق طلب PHP يمكن بعد ذلك تضمينه في وسم html من نوع img src.

يوضح الاستعلام النموذجي كيفية الجمع بين مجموعة كبيرة من دوال الرستر لجلب جميع البلاطات التي تتقاطع مع مستطيل محيط معيّن بنظام wgs 84، ثم دمج البلاطات المتقاطعة معًا باستخدام ST_Union مع إعادة جميع النطاقات، والتحويل إلى الإسقاط الذي يحدده المستخدم باستخدام ST_Transform، ثم إخراج النتائج بصيغة png باستخدام ST_AsPNG.

يمكنك استدعاء ما يلي باستخدام

http://mywebserver/test_raster.php?srid=2249

للحصول على صورة الرستر بنظام Massachusetts state plane بوحدة القدم.

<?php
/** contents of test_raster.php **/
$conn_str ='dbname=mydb host=localhost port=5432 user=myuser password=mypwd';
$dbconn = pg_connect($conn_str);
header('Content-Type: image/png');
/**If a particular projection was requested use it otherwise use mass state plane meters **/
if (!empty( $_REQUEST['srid'] ) &amp;&amp; is_numeric( $_REQUEST['srid']) ){
                $input_srid = intval($_REQUEST['srid']);
}
else { $input_srid = 26986; }
/** The set bytea_output may be needed for PostgreSQL 9.0+, but not for 8.4 **/
$sql = "set bytea_output='escape';
SELECT ST_AsPNG(ST_Transform(
                        ST_AddBand(ST_Union(rast,1), ARRAY[ST_Union(rast,2),ST_Union(rast,3)])
                                ,$input_srid) ) As new_rast
 FROM aerials.boston
        WHERE
         ST_Intersects(rast, ST_Transform(ST_MakeEnvelope(-71.1217, 42.227, -71.1210, 42.218,4326),26986) )";
$result = pg_query($sql);
$row = pg_fetch_row($result);
pg_free_result($result);
if ($row === false) return;
echo pg_unescape_bytea($row[0]);
?>

في هذا القسم سنوضح كيفية استخدام مشغّل Npgsql لـ PostgreSQL في .NET وعائلة الدوال ST_AsGDALRaster لإخراج النطاقات 1 و2 و3 من رستر إلى تدفق طلب PHP يمكن بعد ذلك تضمينه في وسم html من نوع img src.

ستحتاج في هذا التمرين إلى مشغّل npgsql لـ PostgreSQL في .NET، ويمكنك الحصول على أحدث إصدار منه من http://npgsql.projects.postgresql.org/. ما عليك سوى تنزيل أحدث إصدار ووضعه في مجلد bin الخاص بتطبيق ASP.NET وستكون جاهزًا.

يوضح الاستعلام النموذجي كيفية الجمع بين مجموعة كبيرة من دوال الرستر لجلب جميع البلاطات التي تتقاطع مع مستطيل محيط معيّن بنظام wgs 84، ثم دمج البلاطات المتقاطعة معًا باستخدام ST_Union مع إعادة جميع النطاقات، والتحويل إلى الإسقاط الذي يحدده المستخدم باستخدام ST_Transform، ثم إخراج النتائج بصيغة png باستخدام ST_AsPNG.

هذا هو المثال نفسه الوارد في قسم 10.3.1, “مثال PHP للإخراج باستخدام ST_AsPNG بالاقتران مع دوال رستر أخرى” لكنه مُنفّذ بلغة C#.

يمكنك استدعاء ما يلي باستخدام

http://mywebserver/TestRaster.ashx?srid=2249

للحصول على صورة الرستر بنظام Massachusetts state plane بوحدة القدم.

 -- web.config connection string section --
<connectionStrings>
    <add name="DSN"
        connectionString="server=localhost;database=mydb;Port=5432;User Id=myuser;password=mypwd"/>
</connectionStrings>

// Code for TestRaster.ashx
<%@ WebHandler Language="C#" Class="TestRaster" %>
using System;
using System.Data;
using System.Web;
using Npgsql;

public class TestRaster : IHttpHandler
{
        public void ProcessRequest(HttpContext context)
        {

                context.Response.ContentType = "image/png";
                context.Response.BinaryWrite(GetResults(context));

        }

        public bool IsReusable {
                get { return false; }
        }

        public byte[] GetResults(HttpContext context)
        {
                byte[] result = null;
                NpgsqlCommand command;
                string sql = null;
                int input_srid = 26986;
        try {
                    using (NpgsqlConnection conn = new NpgsqlConnection(System.Configuration.ConfigurationManager.ConnectionStrings["DSN"].ConnectionString)) {
                            conn.Open();

                if (context.Request["srid"] != null)
                {
                    input_srid = Convert.ToInt32(context.Request["srid"]);
                }
                sql = @"SELECT ST_AsPNG(
                            ST_Transform(
                                        ST_AddBand(
                                ST_Union(rast,1), ARRAY[ST_Union(rast,2),ST_Union(rast,3)])
                                                    ,:input_srid) ) As new_rast
                        FROM aerials.boston
                                WHERE
                                    ST_Intersects(rast,
                                    ST_Transform(ST_MakeEnvelope(-71.1217, 42.227, -71.1210, 42.218,4326),26986) )";
                            command = new NpgsqlCommand(sql, conn);
                command.Parameters.Add(new NpgsqlParameter("input_srid", input_srid));


                            result = (byte[]) command.ExecuteScalar();
                conn.Close();
                        }

                }
        catch (Exception ex)
        {
            result = null;
            context.Response.Write(ex.Message.Trim());
        }
                return result;
        }
}

هذا تطبيق Java بسيط للطرفية يأخذ استعلامًا يُعيد صورة واحدة ويُخرجها إلى ملف محدد.

يمكنك تنزيل أحدث مشغّلات JDBC لـ PostgreSQL من http://jdbc.postgresql.org/download.html

يمكنك ترجمة الشيفرة التالية باستخدام أمر مشابه لما يلي:

set env CLASSPATH .:..\postgresql-9.0-801.jdbc4.jar
javac SaveQueryImage.java
jar cfm SaveQueryImage.jar Manifest.txt *.class

واستدعاؤه من سطر الأوامر بأمر مشابه لما يلي

java -jar SaveQueryImage.jar "SELECT ST_AsPNG(ST_AsRaster(ST_Buffer(ST_Point(1,5),10, 'quad_segs=2'),150, 150, '8BUI',100));" "test.png" 

-- Manifest.txt --
Class-Path: postgresql-9.0-801.jdbc4.jar
Main-Class: SaveQueryImage

// Code for SaveQueryImage.java
import java.sql.Connection;
import java.sql.SQLException;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.io.*;

public class SaveQueryImage {
  public static void main(String[] argv) {
      System.out.println("Checking if Driver is registered with DriverManager.");

      try {
        //java.sql.DriverManager.registerDriver (new org.postgresql.Driver());
        Class.forName("org.postgresql.Driver");
      }
      catch (ClassNotFoundException cnfe) {
        System.out.println("Couldn't find the driver!");
        cnfe.printStackTrace();
        System.exit(1);
      }

      Connection conn = null;

      try {
        conn = DriverManager.getConnection("jdbc:postgresql://localhost:5432/mydb","myuser", "mypwd");
        conn.setAutoCommit(false);

        PreparedStatement sGetImg = conn.prepareStatement(argv[0]);

        ResultSet rs = sGetImg.executeQuery();

                FileOutputStream fout;
                try
                {
                        rs.next();
                        /** Output to file name requested by user **/
                        fout = new FileOutputStream(new File(argv[1]) );
                        fout.write(rs.getBytes(1));
                        fout.close();
                }
                catch(Exception e)
                {
                        System.out.println("Can't create file");
                        e.printStackTrace();
                }

        rs.close();
                sGetImg.close();
        conn.close();
      }
      catch (SQLException se) {
        System.out.println("Couldn't connect: print out a stack trace and exit.");
        se.printStackTrace();
        System.exit(1);
      }
  }
}

هذه دالة مخزّنة بلغة plpython تنشئ ملفًا في مجلد الخادم لكل سجل. تتطلب أن يكون plpython مثبتًا لديك. يُفترض أن تعمل جيدًا مع كل من plpythonu وplpython3u.

CREATE OR REPLACE FUNCTION write_file (param_bytes bytea, param_filepath text)
RETURNS text
AS $$
f = open(param_filepath, 'wb+')
f.write(param_bytes)
return param_filepath
$$ LANGUAGE plpythonu;

--write out 5 images to the PostgreSQL server in varying sizes
-- note the postgresql daemon account needs to have write access to folder
-- this echos back the file names created;
 SELECT write_file(ST_AsPNG(
        ST_AsRaster(ST_Buffer(ST_Point(1,5),j*5, 'quad_segs=2'),150*j, 150*j, '8BUI',100)),
         'C:/temp/slices'|| j || '.png')
         FROM generate_series(1,5) As j;

     write_file
---------------------
 C:/temp/slices1.png
 C:/temp/slices2.png
 C:/temp/slices3.png
 C:/temp/slices4.png
 C:/temp/slices5.png

للأسف لا تمتلك PSQL وظيفة مدمجة سهلة الاستخدام لإخراج البيانات الثنائية. هذا حلٌّ التفافي يعتمد على دعم PostgreSQL القديم نسبيًا للكائنات الكبيرة (large objects). للاستخدام، شغّل أولًا سطر أوامر psql متصلًا بقاعدة بياناتك.

على خلاف طريقة python، تنشئ هذه الطريقة الملف على حاسوبك المحلي.

SELECT oid, lowrite(lo_open(oid, 131072), png) As num_bytes
 FROM
 ( VALUES (lo_create(0),
   ST_AsPNG( (SELECT rast FROM aerials.boston WHERE rid=1) )
  ) ) As v(oid,png);
-- you'll get an output something like --
   oid   | num_bytes
---------+-----------
 2630819 |     74860

-- next note the oid and do this replacing the c:/test.png to file path location
-- on your local computer
 \lo_export 2630819 'C:/temp/aerial_samp.png'

-- this deletes the file from large object storage on db
SELECT lo_unlink(2630819);