Index: trunk/workshop-foss4g/geometry_returning.rst
===================================================================
--- trunk/workshop-foss4g/geometry_returning.rst	(revision 81)
+++ trunk/workshop-foss4g/geometry_returning.rst	(revision 1)
@@ -1,15 +1,15 @@
 .. _geometry_returning:
 
-Partie 18 : Fonctions de construction de gÃ©omÃ©tries
-====================================================
+Section 18: Geometry Constructing Functions
+===========================================
 
-Toute les fonctions que nous avons vu jusqu'Ã  prÃ©sent traitent les gÃ©omÃ©tries "comme elles sont" et retournent:
+All the functions we have seen so far work with geometries "as they are" and returns
+ 
+* analyses of the objects (:command:`ST_Length(geometry)`, :command:`ST_Area(geometry)`), 
+* serializations of the objects (:command:`ST_AsText(geometry)`, :command:`ST_AsGML(geometry)`), 
+* parts of the object (:command:`ST_RingN(geometry,n)`) or 
+* true/false tests (:command:`ST_Contains(geometry,geometry)`, :command:`ST_Intersects(geometry,geometry)`).
 
-* 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.
+"Geometry constructing functions" take geometries as inputs and output new shapes.
 
 
@@ -17,9 +17,9 @@
 -------------------------------
 
-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.
+A common need when composing a spatial query is to replace a polygon feature with a point representation of the feature. This is useful for spatial joins (as discussed in :ref:`polypolyjoins`) because using :command:`ST_Intersects(geometry,geometry)` on two polygon layers often results in double-counting: a polygon on a boundary will intersect an object on both sides; replacing it with a point forces it to be on one side or the other, not both.
 
- * :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.
-
+ * :command:`ST_Centroid(geometry)` returns a point that is approximately on the center of mass of the input argument. This simple calculation is very fast, but sometimes not desirable, because the returned point is not necessarily in the feature itself. If the input feature has a convexity (imagine the letter 'C') the returned centroid might not be in the interior of the feature.
+ * :command:`ST_PointOnSurface(geometry)` returns a point that is guaranteed to be inside the input argument. It is substantially more computationally expensive than the centroid operation.
+ 
 .. image:: ./geometry_returning/centroid.jpg
 
@@ -28,24 +28,24 @@
 ---------
 
-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.
+The buffering operation is common in GIS workflows, and is also available in PostGIS. :command:`ST_Buffer(geometry,distance)` takes in a buffer distance and geometry type and outputs a polygon with a boundary the buffer distance away from the input geometry. 
 
 .. 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.
+For example, if the US Park Service wanted to enforce a marine traffic zone around Liberty Island, they might build a 500 meter buffer polygon around the island. Liberty Island is a single census block in our ``nyc_census_blocks`` table, so we can easily extract and buffer it.
 
 .. code-block:: sql
 
-  -- CrÃ©ation d'une nouvelle table avec une zone tampon de 500 m autour de 'Liberty Island'
+  -- Make a new table with a Liberty Island 500m buffer zone
   CREATE TABLE libery_island_zone AS
-  SELECT ST_Buffer(the_geom,500) AS the_geom
-  FROM nyc_census_blocks
+  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();
-
+  -- Update the geometry_columns table
+  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.
+The :command:`ST_Buffer` function also accepts negative distances and builds inscribed polygons within polygonal inputs. For lines and points you will just get an empty return.
 
 .. image:: ./geometry_returning/liberty_negative.jpg
@@ -55,13 +55,13 @@
 ---------------
 
-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.
+Another classic GIS operation -- the "overlay" -- creates a new coverage by calculating the intersection of two superimposed polygons. The resultant has the property that any polygon in either of the parents can be built by merging polygons in the resultant.
 
-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.
+The :command:`ST_Intersection(geometry A, geometry B)` function returns the spatial area (or line, or point) that both arguments have in common. If the arguments are disjoint, the function returns an empty geometry.
 
 .. code-block:: sql
 
-  -- Quelle est l'aire que ces deux cercles ont en commun ?
-  -- Utilisons la fonction ST_Buffer pour crÃ©er ces cercles !
-
+  -- What is the area these two circles have in common?
+  -- Using ST_Buffer to make the circles!
+  
   SELECT ST_AsText(ST_Intersection(
     ST_Buffer('POINT(0 0)', 2),
@@ -76,32 +76,31 @@
 --------
 
-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` :
+In the previous example we intersected geometries, creating a new geometry that had lines from both the inputs. The :command:`ST_Union` does the reverse; it takes inputs and removes common lines. There are two forms of the :command:`ST_Union` function: 
 
- * :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.
-
+ * :command:`ST_Union(geometry, geometry)`: A two-argument version that takes in two geometries and returns the merged union.  For example, our two-circle example from the previous section looks like this when you replace the intersection with a union.
+ 
    .. code-block:: sql
 
-     -- Quelle est l'aire totale de ces deux cercles ?
-     -- Utilisons ST_Buffer pour crÃ©er les cercles !
-
+     -- What is the total area these two circles cover?
+     -- Using ST_Buffer to make the circles!
+ 
      SELECT ST_AsText(ST_Union(
        ST_Buffer('POINT(0 0)', 2),
        ST_Buffer('POINT(3 0)', 2)
      ));
+  
+   .. image:: ./geometry_returning/union.jpg
+   
 
-   .. image:: ./geometry_returning/union.jpg
+ * :command:`ST_Union([geometry])`: An aggregate version that takes in a set of geometries and returns the merged geometry for the entire group. The aggregate ST_Union can be used with the ``GROUP BY`` SQL statement to create carefully merged subsets of basic geometries. It is very powerful,
+ 
+As an example of :command:`ST_Union` aggregation, consider our ``nyc_census_blocks`` table. Census geography is carefully constructed so that larger geographies can be built up from smaller ones. So, we can create a census tracts map by merging the blocks that form each tract (as we do later in :ref:`creatingtractstable`). Or, we can create a county map by merging blocks that fall within each county.
 
-
- * :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.
+To carry out the merge, note that the unique key ``blkid`` actually embeds information about the higher level geographies. Here are the parts of the key for Liberty Island we used earlier:
 
 ::
 
   360610001009000 = 36 061 00100 9000
-
+  
   36     = State of New York
   061    = New York County (Manhattan)
@@ -109,33 +108,33 @@
   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``.
+  
+So, we can create a county map by merging all geometries that share the same first 5 digits of their ``blkid``.
 
 .. code-block:: sql
 
-  -- CrÃ©ation d'une table nyc_census_counties en regroupant les blocs
+  -- Create a nyc_census_counties table by merging census blocks
   CREATE TABLE nyc_census_counties AS
-  SELECT
-    ST_Union(the_geom) AS the_geom,
+  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
+  
+  -- Update the geometry_columns table
   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.
+An area test can confirm that our union operation did not lose any geometry. First, we calculate the area of each individual census block, and sum those areas grouping by census county id.
 
 .. code-block:: sql
 
   SELECT SubStr(blkid,1,5) AS countyid, Sum(ST_Area(the_geom)) AS area
-  FROM nyc_census_blocks
+  FROM nyc_census_blocks 
   GROUP BY countyid;
 
 ::
 
-  countyid |       area
+  countyid |       area       
  ----------+------------------
   36005    | 109807439.720947
@@ -145,5 +144,5 @@
   36085    | 149806077.958252
 
-Ensuite nous calculons l'aire de chaque zone de nos nouveaux polygones de rÃ©gion de la table count :
+Then we calculate the area of each of our new county polygons from the county table:
 
 .. code-block:: sql
@@ -154,5 +153,5 @@
 ::
 
-  countyid |       area
+  countyid |       area       
  ----------+------------------
   36005    | 109807439.720947
@@ -162,19 +161,18 @@
   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.
+The same answer! We have successfully built an NYC county table from our census blocks data.
 
-Liste des fonctions
--------------------
+Function List
+-------------
 
-`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_AsText(text) <http://postgis.org/docs/ST_AsText.html>`_: Returns the Well-Known Text (WKT) representation of the geometry/geography without SRID metadata.
 
-`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_Buffer(geometry, distance) <http://postgis.org/docs/ST_Buffer.html>`_: For geometry: Returns a geometry that represents all points whose distance from this Geometry is less than or equal to distance. Calculations are in the Spatial Reference System of this Geometry. For geography: Uses a planar transform wrapper. 
 
-`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_Intersection(geometry A, geometry B) <http://postgis.org/docs/ST_Intersection.html>`_: Returns a geometry that represents the shared portion of geomA and geomB. The geography implementation does a transform to geometry to do the intersection and then transform back to 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.
+`ST_Union() <http://postgis.org/docs/ST_Union.html>`_: Returns a geometry that represents the point set union of the Geometries.
 
-`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.
+`substring(string [from int] [for int]) <http://www.postgresql.org/docs/8.1/static/functions-string.html>`_: PostgreSQL string function to extract substring matching SQL regular expression.
 
-`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.
-
+`sum(expression) <http://www.postgresql.org/docs/8.2/static/functions-aggregate.html#FUNCTIONS-AGGREGATE-TABLE>`_: PostgreSQL aggregate function that returns the sum of records in a set of records.
