Spatial Data is stored in columns with the Geometry data type. The Geometry data type itself is an abstract (non-instantiable) class. It is the root class of the Geometry Type Hierarchy.

The geometry hierarchy is defined by the OGC document "OpenGIS Simple Features Specification for SQL". The following figure shows the hierarchy of the Geometry data type and its subtypes.

Figure 5.1. Geometry Type Hierarchy Diagram

Not instantiable types in JASPA are highlighted in blue, these include Geometry, Curve, Surface, MultiSurface and MultiCurve. No constructor functions are defined for these types.

Seven members of the hierarchy are instantiable (Point, LineString, Polygon, GeometryCollection, MultiPoint, MultiLineString, and MultiPolygon). So, it is possible to create objects in these instantiable types.

The standard SQL-MM adds CircularString, CompoundCurve and CurvePolygon types. The new types extend the OGC geometry class hierarchy with circular arcs as curves and surfaces that have circular arcs as their boundary. JASPA doesn't support these new types, nonetheless PostGIS does in some functions.

A summary of the instantiable geometry subtypes and their descriptions is listed in the table below.

The Well-known Binary Representation for Geometry provides a portable representation of a geometric object as a contiguous stream of bytes.

You can use the ST_AsBinary function to convert geometries to their WKB representation. Inversely, ST_GeomFromWKB takes a WKB representation of a geometry and, optionally, a SRID as input parameters and returns the corresponding geometry.

binary WKB = ST_AsBinary(geometry);
geometry = ST_GeometryFromWKB(binary WKB, SRID);
geometry = ST_GeometryFromWKB(binary WKB);

The stream of bytes must be represented in a numeral system. PostgreSQL uses binary numeral system, whereas H2 uses hexadecimal representation.

SELECT ST_GeomfromText('POINT(0 0)');

--Result PostgreSQL:
\011 \000\001\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000

--Result H2:
0920000100000000000000000000000000000000

Alternatively, you can use the function ST_AsHEXEWKB to obtain a geometry WKB representation in hexadecimal in both databases.

SELECT ST_AsHEXEWKB(ST_GeomFromText('POINT(1 1 1)',25830));
--Result PostgreSQL & H2:
01010000A0E6640000000000000000F03F000000000000F03F000000000000F03F

SELECT ST_AsText('01010000A0E6640000000000000000F03F000000000000F03F000000000000F03F');
--Result
POINT (1 1 1)

The Well-known Text Representation of Spatial Reference Systems provides a standard textual representation for spatial reference system information.

POINT (0 0 10)

LINESTRING (1 1 2 5, 2 1 4 8, 2 2 6 10)

POLYGON ((1 1, 1 3, 3 3, 3 1, 1 1))

MULTIPOINT ((0 0), (1 1)) 

MULTIPOINT (0 0, 1 1)

MULTILINESTRING ((1 1, 2 1, 2 2), (2 3, 3 3, 3 2))

MULTIPOLYGON (((1 1, 1 3, 3 3, 3 1, 1 1),  
  (1.5 2, 2 2.5, 2.5 2, 1.5 2)), 
  ((4 3, 4 5, 6 5, 6 3, 4 3)))

GEOMETRYCOLLECTION (POINT (1 1), LINESTRING (1 3, 2 2, 2 1))

You can use the ST_AsText function to convert geometries to their WKT representation. Inversely, ST_GeomFromText takes a WKT representation of a geometry and, optionally, a SRID as input parameters and returns the corresponding geometry.

text WKT = ST_AsText(geometry);
geometry = ST_GeomFromText(text WKT);
geometry = ST_GeomFromText(text WKT, SRID);

Extended Well-known Binary. This format embeds the SRID to the geometry.

You can use the ST_AsEWKB function to convert geometries to their EWKB representation. Inversely, ST_GeomFromEWKB takes a EWKB representation of a geometry and returns the corresponding geometry.

binary EWKB = ST_AsEWKB(geometry);
geometry = ST_GeomFromEWKB(binary EWKB);

Extended Well-known Text Representation. This format embeds the SRID to the geometry.

You can use the ST_AsEWKT function to convert geometries to their EWKT representation. Inversely, ST_GeomFromEWKT takes a EWKT representation of a geometry and returns the corresponding geometry.

text EWKT = ST_AsEWKT(geometry);
geometry = ST_GeomFromEWKT(text EWKT);

Example

SRID=25830;POINT(719626 4369131 56.2)

The Geography Markup Language (GML) is the XML grammar defined by the OGC to express geographical features. GML serves as a modeling language for geographic systems as well as an open interchange format for geographic transactions on the Internet. JASPA supports OGC GML standard 2.1.2.

OGC GML standards can be found in http://www.opengeospatial.org/standards/gml

You can use the ST_AsGML function to convert geometries to their GML representation. Inversely, ST_GeomFromGML takes a GML representation of a geometry and returns the corresponding geometry.

text GML = ST_AsGML(geometry);
geometry = ST_GeomFromGML(text GML);

Example

<gml:Point>
<gml:coordinates> 1.0,1.0,1.0 </gml:coordinates>
</gml:Point>

Keyhole Markup Language (KML) is an XML language focused on geographic visualization. KML was developed for use with Google Earth. In 2008 KML Version 2.2 has been adopted as an OGC implementation standard, which can be found in http://www.opengeospatial.org/standards/kml/

KML uses 3D geographic coordinates: longitude, latitude and altitude. The longitude, latitude components are defined in WGS84.

You can use the ST_AsKML function to convert geometries to their KML representation. Inversely, ST_GeomFromKML takes a KML representation of a geometry and returns the corresponding geometry.

text KML = ST_AsKML(geometry);
geometry = ST_GeomFromKML(text KML);

Example

<kml:Polygon xmlns:kml="http://earth.google.com/kml/2.1">
 <kml:outerBoundaryIs>
  <kml:LinearRing>
   <kml:coordinates>
   -5.850379847879675,43.35970362178223
   -5.848336797975651,43.36161117272741
   -5.850411866073801,43.36311451294508
   -5.853216861450062,43.36175621008758
   -5.850379847879675,43.35970362178223
   </kml:coordinates>
  </kml:LinearRing>
 </kml:outerBoundaryIs>
</kml:Polygon>

The GEOMETRY_COLUMNS table consists of a row for each geometry column in the database. The columns of this table are:

F_TABLE_CATALOG, F_TABLE_SCHEMA, F_TABLE_NAME

The fully qualified name of the feature table containing the geometry column. F_Table_Catalog field is unused in JASPA.

F_GEOMETRY_COLUMN

The name of the column in the feature table that is the geometry column.

COORD_DIMENSION

Code for the coordinate dimension. The coordinate_dimension must be an integer (2 for XY coordinates, 3 for XYZ or 4 for XYZM).

SRID

The ID of the spatial reference system used for the coordinate geometry in this table. It is a foreign key reference to the SPATIAL_REF_SYS table.

TYPE

The type must be an uppercase string corresponding to the geometry type (e.g, MULTIPOLYGON,LINESTRING).

The SPATIAL_REF_SYS view stores information on each Spatial Reference System (SRS) in the database. It is pre-populated with SRS and EPSG values. The columns of this table are:

SRID

Spatial Reference System Identifier. It constitutes a unique integer key for a Spatial Reference System within a database.

AUTH_NAME

Spatial Reference System Authority Name

AUTH_SRID

Authority Specific Spatial Reference System Identifier

SRTEXT

Well-known Text description of the Spatial Reference System

The well-known text representation of spatial reference systems provides a standard textual representation for spatial reference system information. The definition for the string representation of a coordinate system is as follows:

<coordinate system> = <projected cs> | <geographic cs> | <geocentric cs>
<projected cs> = PROJCS[‘<name>‘, <geographic cs>, <projection>, {<parameter>,}* <linear unit>]
<projection> = PROJECTION[‘<name>‘]
<parameter> = PARAMETER[‘<name>‘, <value>]
<value> = <number>

This WKT representation of an Spatial Reference System can be found in the SRTEXT column of the SPATIAL_REF_SYS view. As an example, geographic WGS84 is defined as:

EPSG codes and their WKT representation can be found in http://spatialreference.org/

The function ST_Transform is used to transform a Geometry to a specified spatial reference system. This reprojection is done by means of the GeoTools library.

The GeoTools library is used to provide coordinate reprojection support within JASPA. It is done by the EPSG WKT Plugin which stores the SRS definitions in a Java properties file. The EPSG Geodetic Parameter Dataset is a structured dataset of Coordinate Reference Systems and transformations.

Transformation between coordinate systems can be carried out by equation-based methods or by grid-based methods:

National Transformation version 2 (NTv2)

The NTv2 method uses a binary distortion Grid File to transform coordinates from one spatial reference system to another. This method is used for accurate datum shifts, instead of using coordinate transformations by parameters. GeoTools does not support NTv2, for this reason JASPA doesn't support it either.

GeoTools is also used for the JASPA shp loader in order to read .prj files from shapefiles. For further information about GeoTools, refer to http://www.geotools.org/

An Spheroid is defined by its Name, Semi-major axis, and Flattening.

SPHEROID["GRS_1980",6378137,298.257222101]

The following functions can use the WKT representation of an Spheroid as input parameter.

To create an index use the CREATE INDEX command.

CREATE INDEX <index_name> ON <table_name> USING GIST (ST_PGBOX(<geometry_column_name>));

To remove an index, use the DROP INDEX command.

DROP INDEX <index_name>;

Indexes can be added to and removed from tables at any time. Once an index is created, it is advisable running VACCUM ANALIZE command to rebuild table statistics and calculate the maximum and minimum values. After this, no further intervention is required: the system will update the index when the table is modified.

VACUUM ANALYZE [table_name] ([geometry_column_name]);

The following is an example of creating an index, updating statistics and dropping the index.

CREATE TABLE myspatialtable (id serial);
SELECT AddGeometryColumn ('myspatialtable','geom',4326,'POINT',3);

Table myspatialtable

 Column |  Type   |                         
--------+---------|
 id     | integer | 
 geom   | bytea   |

CREATE INDEX myspatialtable_geom_idx ON myspatialtable USING GIST (ST_PGBOX(geom));
VACUUM ANALYZE myspatialtable(geom);
DROP INDEX myspatialtable_geom_idx;

	If the name of the geometry column is in upper-case you must call that column with double quotation marks, as shown in the following example: CREATE TABLE myspatialtable (id serial); SELECT AddGeometryColumn ('myspatialtable','Geom',4326,'POINT',3); CREATE INDEX myspatialtable_geom_idx ON myspatialtable USING GIST (ST_PGBOX("Geom"));

Spatial indexes are used in spatial relationships queries. Once the index is built, the system uses it automatically. To avoid index use, call the functions using the prefix _. In particular JASPA use spatial indexes in the following functions:

PostgreSQL includes automatically GiST indexes for these spatial operators:

The following query would use a spatial index (if it had been created before)

--Find all restaurants within 1 kilometer of the hotels 
SELECT r.name,h.name FROM restaurant as r,hotel as h WHERE ST_DWithin(r.geom,h.geom,1000);

To avoid the index usage:

SELECT r.name,h.name FROM restaurant as r,hotel as h WHERE _ST_DWithin(r.geom,h.geom,1000);

Libpq is the C application programmer's interface to PostgreSQL. It is a set of library functions that allow client programs to pass queries to the PostgreSQL backend server and to receive the results of these queries.

Mapserver accesses to JASPA for PostgreSQL data using libpq and SQL sentences which are supported by JASPA thanks to its high level of Postgis compatibility.

http://mapserver.org/input/vector/postgis.html

Configure MapServer

The CONNECTION parameter is used to specify the parameters to connect to the database. CONNECTION parameters can be in any order. Most are optional. The CONNECTIONTYPE parameter must be set to POSTGIS, dbname is required, user is required, host defaults to localhost, port defaults to 5432 (the standard port for PostgreSQL).

The DATA parameter is used to specify the data used to draw the map.

DATA [geometry_column] FROM [table_name|sql_subquery] USING UNIQUE [unique_key] USING srid=[spatial_reference_id]

The “using unique” and “using srid=” clauses are optional, but using them improves performance.

CONNECTIONTYPE POSTGIS
CONNECTION "host=yourhostname dbname=yourdatabasename user=yourdbusername password=yourdbpassword port=yourpgport"
DATA "geometrycolumn from yourtablename using gid"

Mapfile example

LAYER 
    NAME        "soils"
    CONNECTIONTYPE postgis
    CONNECTION "user=postgres password=postgrespg dbname=tutorial host=localhost"
    DATA        "geom from soils using unique gid"
    STATUS      ON
    TYPE        POLYGON
    GROUP       CARTOINICIAL
       
    FILTER "area(geom) > 10000 and soil_code >= 1"
        
    CLASS
      NAME            "Disponibilidad optima"
      EXPRESSION      ([soil_code] = 3)
      COLOR           164 164 164
      OUTLINECOLOR    255 255 255
    END                   
    
    CLASS
      NAME            "Disponibilidad menor"
      EXPRESSION      ([soil_code] = 1 or [soil_code] = 2)
      COLOR           192 192 192
      OUTLINECOLOR    255 255 255
    END                   
END

Mapserver uses the && operator to limit the search of geometries to a smaller area. Mapserver sends a query to JASPA similar to this one:

SELECT
 asbinary(force_collection(force_2d(geom)),'NDR'), gid::text 
FROM suelos 
WHERE geom && setSRID('BOX3D(4000 4500, 6100 7250)'::BOX3D, 
 find_srid('','soils','geom') )' 

Enable Jaspa for gvSIG 1.11:

Copy the patch file "gvsigpatch.zip" into the bin directory of gvSIG installation. -> ... / .../gvsiginstallation/bin

Unpack in same directory. Overwrite if it asks.

	Check that when the gvsigpatch.zip is descompressed, it does not create any folder as gvSIG(2).

To connect to Jaspa, we must choose as Driver: "PostGIS JDBC Driver":

	gvSIG does not support editing simple geometries like LineString, Points or Polygons.

Enable Jaspa for Kosmo 2.0.1:

Install Kosmo 2.0.1. Download the Jaspa patch "saigjaspa.jar" and rename it as "saig.jar". In the folder bin of your Kosmo distribution, replace the file saig.jar for the file you just downloaded.

To connect to Jaspa, we must choose as Database Type: "PostGIS":