Add compression chapter

doc/tutorials/compression.rst

@@ -0,0 +1,83 @@
+******************************************************************************
+Schema and compression
+******************************************************************************
+
+This tutorial is an introduction for investigating XML schemas and playing with
+compression of patches.
+
+------------------------------------------------------------------------------
+Compression type
+------------------------------------------------------------------------------
+
+The compression of a patch may be retrieved through its XML schema but it's
+also stored in the patch itself. Of course, both needs to be consistent so
+updating an existing schema is hardly discouraged and may lead to errors.
+
+In the first case, the XML schema needs to be parsed with ``xpath`` function to
+retrieve the ``pc:metadata`` tag of a specific patch:
+
+.. code-block:: sql
+
+  pointclouds=# WITH tmp AS (
+                    SELECT pc_pcid(pa)
+                    AS _pcid
+                    FROM airport
+                    LIMIT 1
+                )
+                SELECT unnest(
+                    xpath(
+                        '/pc:PointCloudSchema/pc:metadata/Metadata/text()',
+                        schema::xml,
+                        array[
+                            ['pc', 'http://pointcloud.org/schemas/PC/'],
+                            ['xsi', 'http://www.w3.org/2001/XMLSchema-instance']
+                        ]
+                    )
+                )
+                AS "compression"
+                FROM tmp,pointcloud_formats
+                WHERE pcid=tmp._pcid;
+
+     metadata
+  ---------------
+    dimensional
+  (1 row)
+
+
+A much easier way to retrieve the compression type is to take a look to the
+JSON summary of the patch:
+
+.. code-block:: sql
+
+  pointclouds=# SELECT pc_summary(pa)::json->'compr'
+                AS "compression"
+                FROM airport
+                LIMIT 1;
+
+    compression
+  ---------------
+   "dimensional"
+  (1 row)
+
+
+.. code-block:: sql
+
+  pointclouds=# INSERT INTO pointcloud_formats (pcid, srid, schema)
+                VALUES (
+                    34,
+                    4326,
+                    (
+                      SELECT Regexp_replace(schema, 'dimensional', 'none', 'g')
+                      FROM pointcloud_formats
+                      WHERE  pcid = 3
+                    )
+                ); 
+
+
+
+$ create table pa_dim_to_none as select pc_transform(pa, 35) as pa from pa_dim;
+
+
+------------------------------------------------------------------------------
+Update compression
+------------------------------------------------------------------------------

doc/tutorials/index.rst

@@ -11,3 +11,4 @@ pgPointcloud.
   :maxdepth: 1
 
   storing
+  compression

doc/tutorials/storing.rst

@@ -11,7 +11,7 @@ Start Docker container
 
 First we download the latest tag of the pgPoincloud Docker image:
 
-.. code-block::
+.. code-block:: bash
 
   $ docker pull pgpointcloud/pointcloud
 
@@ -25,13 +25,13 @@ For a basic usage, we have to define two environment variables:
 
 Then we can start a new container:
 
-.. code-block::
+.. code-block:: bash
 
   $ docker run --name pgpointcloud -e POSTGRES_DB=pointclouds -e POSTGRES_PASSWORD=mysecretpassword -d pgpointcloud/pointcloud
 
 Extensions are automatically created in the new database named ``pointclouds``:
 
-.. code-block::
+.. code-block:: bash
 
   $ docker exec -it pgpointcloud psql -U postgres -d pointclouds -c "\dx"
                                             List of installed extensions
@@ -55,9 +55,9 @@ Run PDAL pipeline
 For the need of the tutorial, we can download sample data from the `PDAL`_
 organization:
 
-.. code-block::
+.. code-block:: bash
 
-  $ wget https://github.com/PDAL/data/raw/master/liblas/LAS12_Sample_withRGB_Quick_Terrain_Modeler_fixed.laz /tmp
+  $ wget https://github.com/PDAL/data/raw/master/liblas/LAS12_Sample_withRGB_Quick_Terrain_Modeler_fixed.laz -P /tmp
 
 Thanks to the ``pdal info`` command, we can obtain some information on the dataset:
 
@@ -68,7 +68,7 @@ To configure the json PDAL pipeline, we need to set up the ``connection``
 parameter for the ``pgpointcloud`` writer. To do that, the Docker container IP
 adress on which the PostgreSQL database is running is necessary:
 
-.. code-block::
+.. code-block:: bash
 
   $ docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' pgpointcloud
   172.17.0.2
@@ -76,27 +76,27 @@ adress on which the PostgreSQL database is running is necessary:
 
 So the ``pipeline.json`` file looks like:
 
-.. code-block::
+.. code-block:: json
 
   {
-  "pipeline":[
-    {
-      "type":"readers.las",
-      "filename":"/tmp/LAS12_Sample_withRGB_Quick_Terrain_Modeler_fixed.laz"
-    },
-    {
-      "type":"filters.chipper",
-      "capacity":"400"
-    },
-    {
-      "type":"writers.pgpointcloud",
-      "connection":"host='172.17.0.2' dbname='pointclouds' user='postgres' password='mysecretpassword' port='5432'",
-      "table":"airport",
-      "compression":"none",
-      "srid":"32616"
-    }
-  ]
-}
+    "pipeline":[
+      {
+        "type":"readers.las",
+        "filename":"/tmp/LAS12_Sample_withRGB_Quick_Terrain_Modeler_fixed.laz"
+      },
+      {
+        "type":"filters.chipper",
+        "capacity":"400"
+      },
+      {
+        "type":"writers.pgpointcloud",
+        "connection":"host='172.17.0.2' dbname='pointclouds' user='postgres' password='mysecretpassword' port='5432'",
+        "table":"airport",
+        "compression":"dimensional",
+        "srid":"32616"
+      }
+    ]
+  }
 
 The PDAL pipeline can finally be execute with ``pdal pipeline pipeline.json``
 and an ``airport`` table is created.
@@ -111,7 +111,7 @@ Configure connection service file
 To facilitate the access to the database hosted on the Docker container, we can
 configure the PostgreSQL connection service file:
 
-.. code-block::
+.. code-block:: bash
 
   [pgpointcloud]
   host=172.17.0.2
@@ -122,13 +122,13 @@ configure the PostgreSQL connection service file:
 
 Then we can explore the content of the new ``airport`` table:
 
-.. code-block::
+.. code-block:: bash
 
   $ psql service=pgpointcloud
   psql (12.3)
   Type "help" for help.
 
-  pointclouds=# select count(*) from airport;
+  pointclouds=# SELECT COUNT(*) FROM airport;
    count
   -------
     9529