source: trunk/workshop-foss4g/geometry_returning.rst @ 81

.. _geometry_returning:

Partie 18 : Fonctions de construction de géométries
====================================================

Toute les fonctions que nous avons vu jusqu'à présent traitent les géométries "comme elles sont" et retournent:

* une analyse des objets (:command:`ST_Length(geometry)`, :command:`ST_Area(geometry)`),
* une sérialisation des objets (:command:`ST_AsText(geometry)`, :command:`ST_AsGML(geometry)`),
* une partie de l'objet (:command:`ST_RingN(geometry,n)`) ou
* un résultat vrai/faux (:command:`ST_Contains(geometry,geometry)`, :command:`ST_Intersects(geometry,geometry)`).

Les "fonctions de construction de géométries" prennent des géométries en entrée et retourne de nouvelles formes.


ST_Centroid / ST_PointOnSurface
-------------------------------

Un besoin commun lors de la création de requêtes spatiales est de remplacer une entité polygonale par un point représentant cette entité. Cela est utile pour les jointures spatiales (comme indiqué ici : :ref:`polypolyjoins`) car utiliser :command:`ST_Intersects(geometry,geometry)` avec deux polygones impliquera un double comptage : un polygone pour le contour externe intersectera dans les deux sens; le remplacer par un point le forcera à être dans un seul sens, pas les deux.

 * :command:`ST_Centroid(geometry)` retourne le point qui est approximativement au centre de la masse de la géométrie passée en paramÚtre. C'est un calcul simple et rapide, mais parfois non profitable, car le point retourné peut se trouver à l'extérieur de l'entité elle-même. Si l'entité fournie est convexe (imaginez la lettre 'C') le centroïde renvoyé pourrait ne pas être à l'intérieur du polygone.
 * :command:`ST_PointOnSurface(geometry)` retourne un point qui est obligatoirement dans l'entité passée en paramÚtre. Cette fonction coûte plus cher en ressource que le calcul du centroïde.

.. image:: ./geometry_returning/centroid.jpg


ST_Buffer
---------

L'opération de zone tampon est souvent disponible dans les outils SIG, il est aussi disponible dans PostGIS. La fonction :command:`ST_Buffer(geometry,distance)` prend en paramÚtre une géométrie et une distance et retourne une zone tampon dont le contour est à une distance donnée de la géométrie d'origine.

.. image:: ./geometry_returning/st_buffer.png

Par exemple, si les services des parcs américains souhaitaient renforcer la zone du traffic maritime autour de l'île 'Liberty', ils pourraient construire une zone tampon de 500 mÚtres autour de l'île. L'île de 'Liberty' est représentée par un seul bloc dans notre table ``nyc_census_blocks``, nous pouvons donc facilement réaliser ce calcul.

.. code-block:: sql

  -- Création d'une nouvelle table avec une zone tampon de 500 m autour de 'Liberty Island'
  CREATE TABLE libery_island_zone AS
  SELECT ST_Buffer(the_geom,500) AS the_geom
  FROM nyc_census_blocks
  WHERE blkid = '360610001009000';

  -- Mise à jour de la table geometry_columns
  SELECT Populate_Geometry_Columns();

.. image:: ./geometry_returning/liberty_positive.jpg

La fonction :command:`ST_Buffer` permet aussi d'utiliser des valeurs négatives pour le paramÚtre distance et construit un polygone inclus dans celui passé en paramÚtre. Pour les points et les lignes vous obtiendrez simplement un résultat vide.

.. image:: ./geometry_returning/liberty_negative.jpg


ST_Intersection
---------------

Une autre opération classique présente dans les SIG - le chevauchement - crée une nouvelle entité en calculant la zone correspondant à l'intersection de deux polygones superposés. Le résultat à la propriété de permettre de reconstruire les entités de base à l'aide de ce résultat.

La fonction :command:`ST_Intersection(geometry A, geometry B)` retourne la zone géographique (ou une ligne, ou un point) que les deux géométries ont en commun. Si les géométries sont disjointes, la fonction retourne une géométrie vide.

.. code-block:: sql

  -- Quelle est l'aire que ces deux cercles ont en commun ?
  -- Utilisons la fonction ST_Buffer pour créer ces cercles !

  SELECT ST_AsText(ST_Intersection(
    ST_Buffer('POINT(0 0)', 2),
    ST_Buffer('POINT(3 0)', 2)
  ));

.. image:: ./geometry_returning/intersection.jpg



ST_Union
--------

Dans l'exemple précédent, nous intersections des géométries, créant une nouvelle géométrie unique à partir de deux entités. La commande :command:`ST_Union` fait l'inverse, elle prend en paramÚtre des géométries et supprime les parties communes. Il y a deux versions possibles de la fonction  :command:`ST_Union` :

 * :command:`ST_Union(geometry, geometry)`: une version avec deux paramÚtres qui prend les géométries et retourne l'union des deux. Par exemple, nos deux cercles ressemblent à ce qui suit si nous utilisons l'opération union plutÎt que l'intersection.

   .. code-block:: sql

     -- Quelle est l'aire totale de ces deux cercles ?
     -- Utilisons ST_Buffer pour créer les cercles !

     SELECT ST_AsText(ST_Union(
       ST_Buffer('POINT(0 0)', 2),
       ST_Buffer('POINT(3 0)', 2)
     ));

   .. image:: ./geometry_returning/union.jpg


 * :command:`ST_Union([geometry])`: une version agrégée qui prendre un ensemble de géométries et retourne une géométrie contenant l'ensemble des géométries rassemblées. La fonction agrégée ST_Union peut être utilisé grâce au SQL ``GROUP BY`` pour créer un ensemble rassemblant des sous-ensembles de géométries basiques. Cela est trÚs puissant.

Comme exemple pour la fonction d'agrégation  :command:`ST_Union`, considérons notre table ``nyc_census_blocks``.
Les géographie du recensement sont construites de maniÚre à ce qu'on puisse créer d'autres géographies à partir des premiÚres. ainsi, nous pouvons créer une carte des secteurs de recensement en fusionnant les blocs que forme chaque secteur (comme nous le ferons aprÚs dans :ref:`la création des tables secteurs<creatingtractstable>`). Ou, nous pouvons créer une carte du comté en fusionnant les blocs qui relÚvent de chaque comté.

Pour effectuer la fusion, notez que la clé unique ``blkid`` incorpore des informations sur les géographies de niveau supérieur. Voici les parties de la clé pour Liberty Island que nous avons utilisé précédemment.

::

  360610001009000 = 36 061 00100 9000

  36     = State of New York
  061    = New York County (Manhattan)
  000100 = Census Tract
  9      = Census Block Group
  000    = Census Block

Ainsi, nous pouvons créer une carte du comté en fusionnant toutes les géométries qui partagent les 5 premiers chiffres de  ``blkid``.

.. code-block:: sql

  -- Création d'une table nyc_census_counties en regroupant les blocs
  CREATE TABLE nyc_census_counties AS
  SELECT
    ST_Union(the_geom) AS the_geom,
    SubStr(blkid,1,5) AS countyid
  FROM nyc_census_blocks
  GROUP BY countyid;

  -- Mise à jour de la table geometry_columns
  SELECT Populate_Geometry_Columns();

.. image:: ./geometry_returning/union_counties.png

Un test de surface peut confirmer que notre opération d'union n'a pas perdu de géométries. Tout d'abord, nous calculons la surface de chacun des blocs de recensement et faisons la somme de ces surfaces en les groupant par l'identifiant de recensement des comtés.

.. code-block:: sql

  SELECT SubStr(blkid,1,5) AS countyid, Sum(ST_Area(the_geom)) AS area
  FROM nyc_census_blocks
  GROUP BY countyid;

::

  countyid |       area
 ----------+------------------
  36005    | 109807439.720947
  36047    | 184906575.839355
  36061    | 58973521.6225586
  36081    | 283764734.207275
  36085    | 149806077.958252

Ensuite nous calculons l'aire de chaque zone de nos nouveaux polygones de région de la table count :

.. code-block:: sql

  SELECT countyid, ST_Area(the_geom) AS area
  FROM nyc_census_counties;

::

  countyid |       area
 ----------+------------------
  36005    | 109807439.720947
  36047    | 184906575.839355
  36061    | 58973521.6225586
  36081    | 283764734.207275
  36085    | 149806077.958252

La même réponse ! Nous avons construit avec succÚs une table des régions de NYC à partir de nos données initiales.

Liste des fonctions
-------------------

`ST_AsText(text) <http://postgis.org/docs/ST_AsText.html>`_: retourne la représentation Well-Known Text (WKT) de la géométrie/géographie sans métadonnée SRID.

`ST_Buffer(geometry, distance) <http://postgis.org/docs/ST_Buffer.html>`_: Pour les géométries: retourne une géométrie qui représente tous les points dont la distance depuis cette géométrie est inférieure ou égale à la distance utilisée. Les calculs se font dans le systÚme de référence spatial de cette géométrie. Pour les géographies: utilise une fonction de transformation planaire pour effectuer le calcul.

`ST_Intersection(geometry A, geometry B) <http://postgis.org/docs/ST_Intersection.html>`_: retourne une géométrie qui représente la portion commune des géométries A et B. L'implémentation du type géographie fait une transformation vers une géométrie pour faire l'intersection puis reprojette le résultat en WGS84.

`ST_Union() <http://postgis.org/docs/ST_Union.html>`_: Renvoie un objet géométrique qui représente l'ensemble d'union des objets géométriques désignés.

`substring(string [from int] [for int]) <http://www.postgresql.org/docs/8.1/static/functions-string.html>`_: Fonction de chaîne PostgreSQL pour extraire une sous-chaîne de caractÚres.

`sum(expression) <http://www.postgresql.org/docs/8.2/static/functions-aggregate.html#FUNCTIONS-AGGREGATE-TABLE>`_: Fonction d'agrégation PostgreSQL qui retourne la somme des valeurs d'une colonne dans un ensemble d'enregistrements.