source: trunk/workshop-foss4g/geometries.rst @ 19

.. _geometries:

Partie 8 : les géometries
=====================

Introduction
------------

Dans :ref:`une partie précédente<loading_data>` nous avons charger différentes données. Avant de commencer à jouer avec, commençons par regarder quelques exemples simples. Depuis pgAdmin, choisissez encore la base de donnée **nyc** et ouvrez l'outils de requêtage SQL. Copiez cette exemple de code SQL (aprÚs avoir supprimer le contenu présent défaut si nécessaire) puis exécutez-le.

.. code-block:: sql

  CREATE TABLE geometries (name varchar, geom geometry);
  
  INSERT INTO geometries VALUES 
    ('Point', 'POINT(0 0)'),
    ('Linestring', 'LINESTRING(0 0, 1 1, 2 1, 2 2)'),
    ('Polygon', 'POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))'),
    ('PolygonWithHole', 'POLYGON((0 0, 10 0, 10 10, 0 10, 0 0),(1 1, 1 2, 2 2, 2 1, 1 1))'),
    ('Collection', 'GEOMETRYCOLLECTION(POINT(2 0),POLYGON((0 0, 1 0, 1 1, 0 1, 0 0)))');
    
  SELECT Populate_Geometry_Columns();
  
  SELECT name, ST_AsText(geom) FROM geometries;

.. image:: ./geometries/start01.png

L'exemple ci-dessus créé une table (**geometries**) puis y insert cinq géométries : un point, une ligne, un polygone, un polygone avec un trou, et une collection. Au final, les lignes insérées sont sélectionnées et affichées dans le tableau de sortie.

Les tables de métadonnées
-------------------------

Dans le respect de la spécification Simple Features for SQL (:term:`SFSQL`), PostGIS fournit deux tables pour récupérer et s'informer sur les types de géométries disponibles dans une base de données spécifique.

* La premiÚre table, ``spatial_ref_sys``, définit tout les systÚme de projection connu de la base de données et sera décrite plus en détals plus tard.  
* La seconde table, ``geometry_columns``, fournit une liste de toutes les "entités" (définit comme un objet avec un attribut géométrique) et les détails de base relatives à ces entités. 

.. image:: ./geometries/table01.png

Dans l'exemple founit en introduction, la fonction :command:`Populate_Geometry_Columns()` détecte toute les colonnes de la base de données qui contiennent des géométries et met à jour la table ``geometry_columns`` pour y inclure leurs références.

Regardons maintenant table ``geometry_columns`` de notre base de données. Copiez cette commande dans la fenêtre de requêtage :


.. code-block:: sql

  SELECT * FROM geometry_columns;

.. image:: ./geometries/start08.png

* ``f_table_catalog``, ``f_table_schema``, et ``f_table_name`` fournissent le nom complet de la table contenant une géométrie donnée. Étant donné que PostgreSQL n'utilise pas de catalogues, ``f_table_catalog`` est toujouts vide.  
* ``f_geometry_column`` est le nom de la colonne qui contient la géométrie -- pour les tables ayant plusieurs colonnes géométriques, il y a un enregistrement dans cette table pour chacune.
* ``coord_dimension`` et ``srid`` définissent respectivement la dimension de la géométrie (en 2-, 3- or 4-dimensions) et le systÚme de références spatiales qui fait référence à la table ``spatial_ref_sys``.  
* La colonne ``type`` définit le type de géométrie comme décrit plus tÎt, nous avons déjà vu les points et les lignes.  

En interrogeant cette table, les clients SIG et les libraires peuvent déterminer quoi attendre lors de la récupration des données et peuvent réaliser les opération de reprojection, transformation ou rendu sans avoir a inspecter chaque géométrie.

Réprésenter des objets du mode réel
-----------------------------------

La spécification Simple Features for SQL (:term:`SFSQL`), le standard ayant guidé le développement de PostGIS, définit comment les objets du monde réel doivent être représentés. En considérant une forme continue à une seule résolution fixe, nous obtenu un piÚtre représentation des objets. SFSQL considÚre uniquement les représentations en 2 dimensions. PostGIS a étendu cela en ajoutant les représentation en 3 et 4 dimensions, plus récemment la spécification SQL-Multimedia Part 3 (:term:`SQL/MM`) a officiellement définit sa propre représenation.

Notre table exemple contient différents types de géométries Nous pouvons récupérer les informations de chaque objets en utilisant les fonctions qui lisent les métadonnées de la géométrie.

 * :command:`ST_GeometryType(geometry)` retourne le type de la géométrie
 * :command:`ST_NDims(geometry)` retourne le nombre de dimension d'une géométrie
 * :command:`ST_SRID(geometry)` retourne l'identifiant de référence spatiale de la géométrie

.. code-block:: sql

  SELECT name, ST_GeometryType(geom), ST_NDims(geom), ST_SRID(geom)
    FROM geometries;

::

       name       |    st_geometrytype    | st_ndims | st_srid 
 -----------------+-----------------------+----------+---------
  Point           | ST_Point              |        2 |      -1
  Polygon         | ST_Polygon            |        2 |      -1
  PolygonWithHole | ST_Polygon            |        2 |      -1
  Collection      | ST_GeometryCollection |        2 |      -1
  Linestring      | ST_LineString         |        2 |      -1



Les points
~~~~~~~~~~~

.. image:: ./introduction/points.png
   :align: center

Un **point** spatiale représente une localisation unique sur la Terre. Ce point est représenté par une seule coordonnée (incluant soit 2, 3 ou 4 dimensions). Les points sont utilisés pour représenter des objets lorsque le détails exact du contour n'est pas important à une échelle donnée. Par exemple, les villes sur une carte du monde pourraient être décrite sous la forme de points alors qu'une carte régionale utiliserait une représentation polygonale des villes.

.. code-block:: sql

  SELECT ST_AsText(geom) 
    FROM geometries
    WHERE name = 'Point';

::

  POINT(0 0)

Ceraints des fonctions spécifiques pour travailler avec les points sont :

 * :command:`ST_X(geometry)` retourne la composante X
 * :command:`ST_Y(geometry)` retourne la composante Y 

Donc, nous pouvons lire les coordonnées d'un point de la maniÚre suivante :

.. code-block:: sql

  SELECT ST_X(geom), ST_Y(geom)
    FROM geometries
    WHERE name = 'Point';

La table des stations de métros de la ville de New York  (``nyc_subway_stations``) est un ensemble de données représenté sous la forme de points. La requête SQL suivante reverra la géométrie associée à un point (dans la colonne :command:`ST_AsText`).

.. code-block:: sql

  SELECT name, ST_AsText(the_geom)
    FROM nyc_subway_stations
    LIMIT 1;


Les lignes 
~~~~~~~~~~~

.. image:: ./introduction/lines.png
   :align: center

Une **ligne** est un chemin entre plusieurs points. Elle prend la forme d'un tableay ordonné de deux (ou plus) points. Les routes et les riviÚres sont tipyquement représenté sous la forme de lignes. Une ligne est dire **fermée** si elle commence et se fini en un même point. Elle est dite **simple** si elle ne se coupe pas ni se touche elle-même (sauf à ses extrémités si elle est fermée). Une ligne peut être à la fois **fermée** et **simple**.

Le réseau des rues de New York (``nyc_streets``) a été chargé plus tÎt. Cet ensemble de données contient les détails comme le nom et le type. Une rue du monde réelle pourrait être constituée de plusieurs lignes, chacune représentant une file de la avec différents attributs.

La requête SQL suivante retourne la géométrie associée à une ligne (dans la colonne :command:`ST_AsText`) :

.. code-block:: sql

  SELECT ST_AsText(geom) 
    FROM geometries
    WHERE name = 'Linestring';
  
::

  LINESTRING(0 0, 1 1, 2 1, 2 2)

Les fonctions spatiales permettant de travailler avec les lignes sont les suivantes :

 * :command:`ST_Length(geometry)` retourne la longueur d'une ligne
 * :command:`ST_StartPoint(geometry)` retourne le premier point d'une ligne
 * :command:`ST_EndPoint(geometry)` retourne le denier point d'une ligne
 * :command:`ST_NPoints(geometry)` retourne le nombre de points dans une ligne

Donc, la longueur de notre ligne est :

.. code-block:: sql

  SELECT ST_Length(geom) 
    FROM geometries
    WHERE name = 'Linestring';

::

  3.41421356237309


Les polygones
~~~~~~~~~~~~~~

.. image:: ./introduction/polygons.png
  :align: center

Un polygone est représenté comme une zone. Le contour externe du polygone est représenté par une ligne simple et fermée. Les trous sont représenté de la même maniÚre.

Les polygones sont utiliser pour représenter les objets dont les tailles et la forme sont importants. Les limites de villes, les parks, les batiments ou les cours d'eau sont habituellement représenté par des polygones lorsque l'échelle est suffisament élevée pour voir distinguer leurs zones. Les routes et les riviÚres peuvent parfois être représenté comme des polygones.

La requête SQL suivante retournera la géométrie associée à un polygon (dans la colonne :command:`ST_AsText`).

.. code-block:: sql

  SELECT ST_AsText(geom) 
    FROM geometries
    WHERE name LIKE 'Polygon%';

.. note::

  PlutÎt que d'utiliser le signe ``=`` dans notre clause ``WHERE``, nous avons utilisé l'opérateur ``LIKE`` pour pouvoir définir notre comparaison. Vous auriez sans doute voulu utiliser le symbole ``*`` pour exprimer "n'importe quelle valeur" mais en SQL vous devez utiliser : ``%`` et l'opérateur ``LIKE`` pour informer le systÚme que cette comparaison doit être possible.

::

 POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))
 POLYGON((0 0, 10 0, 10 10, 0 10, 0 0),(1 1, 1 2, 2 2, 2 1, 1 1))

Le premier polygon a seulement une ligne. Le second a un "trou". La plupart des systÚmes de rendu graphique supportent le concept de "polygone", mais les systÚme SIG sont les seuls a accepter que les polygones puisse contenir des trous.

.. image:: ./screenshots/polygons.png

Certaines des fonctions spatiales spécifique de traitement des polygones sont :

 * :command:`ST_Area(geometry)` retourne l'aire de polygones
 * :command:`ST_NRings(geometry)` retourne le nombre de contour (habituellement 1, plus lorsqu'il y a des trous)
 * :command:`ST_ExteriorRing(geometry)` rentourne le contour extérieur
 * :command:`ST_InteriorRingN(geometry,n)` retourne le contour intérieur numéro n
 * :command:`ST_Perimeter(geometry)` retourne la longueur de tout les contours

Nous pouvons calculer l'aire de nos polygones en utilisant la fonction area :

.. code-block:: sql

  SELECT name, ST_Area(geom) 
    FROM geometries
    WHERE name LIKE 'Polygon%';

::

  Polygon            1
  PolygonWithHole    99

Remarquez que le polygone contenant un trou a une aire égale à l'aire du contour externe (un carré de 10 sur 10) moins l'aire du trou (un carré de 1 sur 1).

Les collections
~~~~~~~~~~~~~~~~ 

Il y a quatre types de collections, qui regroupe ensembles plusieurs géométries simples.

 * **MultiPoint**, une collection de points
 * **MultiLineString**, une collection de lignes
 * **MultiPolygon**, une collection de polygones
 * **GeometryCollection**, une collections hétérogÚne de n'importe quelle géométrie (dont d'autre collections)

Les collections sont un concept présents dans les logiciels SIG  plus que dans les application de rendu graphique générique. Elles sont utiles pour directement modeler  les objets du monde réel comme des objet spatiaux. Par exemple, comment modéliser une parcelle qui é coupée par un chemin ? Comme un **MultiPolygon**, ayant une partie de chaque coté du chemin.

.. image:: ./screenshots/collection2.png

Notre collection exemple contient un polygon et un point :

.. code-block:: sql

  SELECT name, ST_AsText(geom) 
    FROM geometries
    WHERE name = 'Collection';

::

  GEOMETRYCOLLECTION(POINT(2 0),POLYGON((0 0, 1 0, 1 1, 0 1, 0 0)))

.. image:: ./screenshots/collection.png

Certaines des fonctions spatiales spécifiques à la manipulation des collections sont :

 * :command:`ST_NumGeometries(geometry)` retourne le nombre de composantes d'une collection
 * :command:`ST_GeometryN(geometry,n)` retourne une composante spécifique
 * :command:`ST_Area(geometry)` retourne l'aire totale des composantes de types polygones
 * :command:`ST_Length(geometry)` retourne la longueur totale des composantes de types lignes



Entré / Sortie des géométries
-----------------------------

Within the database, geometries are stored on disk in a format only used by the PostGIS program. In order for external programs to insert and retrieve useful geometries, they need to be converted into a format that other applications can understand. Fortunately, PostGIS supports emitting and consuming geometries in a large number of formats:

 * Well-known text (:term:`WKT`)
 
   * :command:`ST_GeomFromText(text)` returns ``geometry``
   * :command:`ST_AsText(geometry)` returns ``text``
   * :command:`ST_AsEWKT(geometry)` returns ``text``
   
 * Well-known binary (:term:`WKB`)
 
   * :command:`ST_GeomFromWKB(bytea)` returns ``geometry``
   * :command:`ST_AsBinary(geometry)` returns ``bytea``
   * :command:`ST_AsEWKB(geometry)` returns ``bytea``
   
 * Geographic Mark-up Language (:term:`GML`)
 
   * :command:`ST_GeomFromGML(text)` returns ``geometry``
   * :command:`ST_AsGML(geometry)` returns ``text``
   
 * Keyhole Mark-up Language (:term:`KML`)
 
   * :command:`ST_GeomFromKML(text)` returns ``geometry``
   * :command:`ST_AsKML(geometry)` returns ``text``
   
 * :term:`GeoJSON`
 
   * :command:`ST_AsGeoJSON(geometry)` returns ``text``
   
 * Scalable Vector Graphics (:term:`SVG`)
 
   * :command:`ST_AsSVG(geometry)` returns ``text``
 
The following SQL query shows an example of :term:`WKB` representation (the call to :command:`encode()` is required to convert the binary output into an ASCII form for printing):

.. code-block:: sql

  SELECT encode(
    ST_AsBinary(ST_GeometryFromText('LINESTRING(0 0 0,1 0 0,1 1 2)')), 
    'hex');

.. image:: ./geometries/represent-04.png

For the purposes of this workshop we will continue to use WKT to ensure you can read and understand the geometries we're viewing.  However, most actual processes, such as viewing data in a GIS application, transferring data to a web service, or processing data remotely, WKB is the format of choice.  

Since WKT and WKB were defined in the  :term:`SFSQL` specification, they do not handle 3- or 4-dimensional geometries.  For these cases PostGIS has defined the Extended Well Known Text (EWKT) and Extended Well Known Binary (EWKB) formats.  These provide the same formatting capabilities of WKT and WKB with the added dimensionality.

Here is an example of a 3D linestring in WKT:

.. code-block:: sql

  SELECT ST_AsEWKT(ST_GeometryFromText('LINESTRING(0 0 0,1 0 0,1 1 2)'));

.. image:: ./geometries/represent-05.png

.. code-block:: sql

  SELECT encode(ST_AsEWKB(ST_GeometryFromText(
      'LINESTRING(0 0 0,1 0 0,1 1 2)')), 'hex');

.. image:: ./geometries/represent-06.png

In addition to emitters for the various forms (WKT, WKB, GML, KML, JSON, SVG), PostGIS also has consumers for four (WKT, WKB, GML, KML). Most applications use the WKT or WKB geometry creation functions, but the others work too. Here's an example that consumes GML and output JSON:

.. code-block:: sql

  SELECT ST_AsGeoJSON(ST_GeomFromGML('<gml:Point><gml:coordinates>1,1</gml:coordinates></gml:Point>'));

.. image:: ./geometries/represent-07.png

Function List
-------------

`Populate_Geometry_Columns <http://postgis.org/docs/Populate_Geometry_Columns.html>`_: Ensures geometry columns have appropriate spatial constraints and exist in the geometry_columns table..

`ST_Area <http://postgis.org/docs/ST_Area.html>`_: Returns the area of the surface if it is a polygon or multi-polygon. For "geometry" type area is in SRID units. For "geography" area is in square meters.

`ST_AsText <http://postgis.org/docs/ST_AsText.html>`_: Returns the Well-Known Text (WKT) representation of the geometry/geography without SRID metadata.

`ST_AsBinary <http://postgis.org/docs/ST_AsBinary.html>`_: Returns the Well-Known Binary (WKB) representation of the geometry/geography without SRID meta data.

`ST_EndPoint <http://postgis.org/docs/ST_EndPoint.html>`_: Returns the last point of a LINESTRING geometry as a POINT.

`ST_AsEWKB <http://postgis.org/docs/ST_AsEWKB.html>`_: Returns the Well-Known Binary (WKB) representation of the geometry with SRID meta data.

`ST_AsEWKT <http://postgis.org/docs/ST_AsEWKT.html>`_: Returns the Well-Known Text (WKT) representation of the geometry with SRID meta data.

`ST_AsGeoJSON <http://postgis.org/docs/ST_AsGeoJSON.html>`_: Returns the geometry as a GeoJSON element.

`ST_AsGML <http://postgis.org/docs/ST_AsGML.html>`_: Returns the geometry as a GML version 2 or 3 element.

`ST_AsKML <http://postgis.org/docs/ST_AsKML.html>`_: Returns the geometry as a KML element. Several variants. Default version=2, default precision=15.

`ST_AsSVG <http://postgis.org/docs/ST_AsSVG.html>`_: Returns a Geometry in SVG path data given a geometry or geography object.

`ST_ExteriorRing <http://postgis.org/docs/ST_ExteriorRing.html>`_: Returns a line string representing the exterior ring of the POLYGON geometry. Return NULL if the geometry is not a polygon. Will not work with MULTIPOLYGON

`ST_GeometryN <http://postgis.org/docs/ST_GeometryN.html>`_: Returns the 1-based Nth geometry if the geometry is a GEOMETRYCOLLECTION, MULTIPOINT, MULTILINESTRING, MULTICURVE or MULTIPOLYGON. Otherwise, return NULL.

`ST_GeomFromGML <http://postgis.org/docs/ST_GeomFromGML.html>`_: Takes as input GML representation of geometry and outputs a PostGIS geometry object.

`ST_GeomFromKML <http://postgis.org/docs/ST_GeomFromKML.html>`_: Takes as input KML representation of geometry and outputs a PostGIS geometry object

`ST_GeomFromText <http://postgis.org/docs/ST_GeomFromText.html>`_: Returns a specified ST_Geometry value from Well-Known Text representation (WKT).

`ST_GeomFromWKB <http://postgis.org/docs/ST_GeomFromWKB.html>`_: Creates a geometry instance from a Well-Known Binary geometry representation (WKB) and optional SRID.

`ST_GeometryType <http://postgis.org/docs/ST_GeometryType.html>`_: Returns the geometry type of the ST_Geometry value.

`ST_InteriorRingN <http://postgis.org/docs/ST_InteriorRingN.html>`_: Returns the Nth interior linestring ring of the polygon geometry. Return NULL if the geometry is not a polygon or the given N is out of range.

`ST_Length <http://postgis.org/docs/ST_Length.html>`_: Returns the 2d length of the geometry if it is a linestring or multilinestring. geometry are in units of spatial reference and geography are in meters (default spheroid)

`ST_NDims <http://postgis.org/docs/ST_NDims.html>`_: Returns coordinate dimension of the geometry as a small int. Values are: 2,3 or 4.

`ST_NPoints <http://postgis.org/docs/ST_NPoints.html>`_: Returns the number of points (vertexes) in a geometry.

`ST_NRings <http://postgis.org/docs/ST_NRings.html>`_: If the geometry is a polygon or multi-polygon returns the number of rings.

`ST_NumGeometries <http://postgis.org/docs/ST_NumGeometries.html>`_: If geometry is a GEOMETRYCOLLECTION (or MULTI*) returns the number of geometries, otherwise return NULL.

`ST_Perimeter <http://postgis.org/docs/ST_Perimeter.html>`_: Returns the length measurement of the boundary of an ST_Surface or ST_MultiSurface value. (Polygon, Multipolygon)

`ST_SRID <http://postgis.org/docs/ST_SRID.html>`_: Returns the spatial reference identifier for the ST_Geometry as defined in spatial_ref_sys table.

`ST_StartPoint <http://postgis.org/docs/ST_StartPoint.html>`_: Returns the first point of a LINESTRING geometry as a POINT.

`ST_X <http://postgis.org/docs/ST_X.html>`_: Returns the X coordinate of the point, or NULL if not available. Input must be a point.

`ST_Y <http://postgis.org/docs/ST_Y.html>`_: Returns the Y coordinate of the point, or NULL if not available. Input must be a point.