Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update drivers documentation #1133

Open
wants to merge 4 commits into
base: gh-pages
Choose a base branch
from
+1,268 −245
Open

Update drivers documentation #1133

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d868abd
First commit of drivers improvements
Oct 5, 2020
288e4a5
Second commit of drivers improvements
Oct 6, 2020
f84fe44
Third commit of drivers improvements
Oct 12, 2020
bf80a41
Integrate Erwan comments
Oct 13, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
213 changes: 213 additions & 0 deletions docs/dev/ASCRead.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,213 @@
---
layout: docs
title: ASCRead
category: h2drivers
is_function: true
description: ASC → Table
prev_section: h2drivers
next_section: CSVRead
permalink: /docs/dev/ASCRead/
---

### Signatures

{% highlight mysql %}
ASCRead(VARCHAR path);
ASCRead(VARCHAR path, BOOLEAN deleteTable);

ASCRead(VARCHAR path, VARCHAR myTable);
ASCRead(VARCHAR path, VARCHAR myTable, BOOLEAN deleteTable);

ASCRead(VARCHAR path, INTEGER type);
ASCRead(VARCHAR path, INTEGER type, BOOLEAN deleteTable);

ASCRead(VARCHAR path, VARCHAR myTable, INTEGER type);
ASCRead(VARCHAR path, VARCHAR myTable, INTEGER type, BOOLEAN deleteTable);

ASCRead(VARCHAR path, VARCHAR myTable, GEOMETRY geomFilter,
INTEGER downScaleInt, BOOLEAN asPolygons);
ASCRead(VARCHAR path, VARCHAR myTable, GEOMETRY geomFilter,
INTEGER downScaleInt, BOOLEAN asPolygons, BOOLEAN deleteTable);
{% endhighlight %}

### Description

Import Esri ASCII Raster file as `POINT` or `POLYGON` geometries.

Pixels are converted into `PointZ` (or `PolygonZ`) geometry with Z as the pixel value (stored as `DOUBLE`).

Where:

- `path` : the adress of the `.asc` file. This file may be zipped in a `.gz` file *(in this case, the `ASCRead` driver will unzip on the fly the `.gz` file)*,
- `myTable` : the name given to the resulting table,
gpetit marked this conversation as resolved.
Show resolved Hide resolved
- `type` : indicates whether the `z` data type will be casted to INTEGER (`1`) or left as DOUBLE (`2` - default value),
- `geomFilter` : extract only pixels that intersects the provided geometry envelope (`null` to disable filter),
gpetit marked this conversation as resolved.
Show resolved Hide resolved
- `downScaleInt` : a coefficient used for exporting less cells (`1` all cells, `2` for size / 2, ...),
- `asPolygons` : if `true`, pixels are converted into polygons (default value = `false` return points),
- `deleteTable` : if `true` and table `tableName` already exists in the database, then table `tableName` will be removed / replaced by the new one. Else (no `deleteTable` parameter or `deleteTable` equal to `false`), an error indicating that the table `tableName` already exists will be throwned.
gpetit marked this conversation as resolved.
Show resolved Hide resolved

### Examples

We assume that we have the following `.asc` file, named `dem` and placed here: `/home/user/`.

```java
ncols 4
nrows 4
xllcorner 10
yllcorner 10
cellsize 5.0
NODATA_value -9999
28 27 26 25
27 25 24 23
26 23 20 19
25 20 18 17
```


##### 1. Using the `path`

{% highlight mysql %}
CALL ASCREAD('/home/user/dem.asc');
{% endhighlight %}

Returns the table `dem`, with the following values:

| PK | THE_GEOM | Z |
|:-----:|:--------:|:---:|
| 1 | POINT Z (12.5 27.5 28) | 28.0 |
| 2 | POINT Z (17.5 27.5 27) | 27.0 |
| 3 | POINT Z (22.5 27.5 26) | 26.0 |
| 4 | POINT Z (27.5 27.5 25) | 25.0 |
| 5 | POINT Z (12.5 22.5 27) | 27.0 |
| 6 | POINT Z (17.5 22.5 25) | 25.0 |
| 7 | POINT Z (22.5 22.5 24) | 24.0 |
| 8 | POINT Z (27.5 22.5 23) | 23.0 |
| 9 | POINT Z (12.5 17.5 26) | 26.0 |
| 10 | POINT Z (17.5 17.5 23) | 23.0 |
| 11 | POINT Z (22.5 17.5 20) | 20.0 |
| 12 | POINT Z (27.5 17.5 19) | 19.0 |
| 13 | POINT Z (12.5 12.5 25) | 25.0 |
| 14 | POINT Z (17.5 12.5 20) | 20.0 |
| 15 | POINT Z (22.5 12.5 18) | 18.0 |
| 16 | POINT Z (27.5 12.5 17) | 17.0 |

**Remark**: If the `dem.asc` has been zipped into a `.gz` file, execute the following instruction:

{% highlight mysql %}
CALL ASCREAD('/home/user/dem.asc.gz');
{% endhighlight %}

In this case, since the `myTable` parameter has not been specified, the resuling table will be named `DEM_ASC`.

##### 2. Using `myTable`

{% highlight mysql %}
CALL ASCREAD('/home/user/dem.asc', 'myDEMTable');
{% endhighlight %}

Returns the table `myDEMTable` (same as `dem` table)

| PK | THE_GEOM | Z |
|:-----:|:--------:|:---:|
| 1 | POINT Z (12.5 27.5 28) | 28.0 |
| 2 | POINT Z (17.5 27.5 27) | 27.0 |
| ... | ... | ... |


##### 3. Using `type`

Here we want to convert Z value into INTEGER
{% highlight mysql %}
CALL ASCREAD('/home/user/dem.asc', 1);
{% endhighlight %}

Returns the table `myDEMTable`

| PK | THE_GEOM | Z |
|:-----:|:--------:|:---:|
| 1 | POINT Z (12.5 27.5 28) | 28 |
| 2 | POINT Z (17.5 27.5 27) | 27 |
| ... | ... | ... |


##### 4. Using `geomFilter`
Here, we want to keep only `POINT`s that intersect this geometry: `POLYGON((15 15, 15 25, 25 25, 25 15, 15 15))`

{% highlight mysql %}
CALL ASCREAD(
'/home/user/dem.asc',
'myDEMTable',
ST_GeomFromText('POLYGON((15 15, 15 25, 25 25, 25 15, 15 15))'),
1, false);
{% endhighlight %}

Returns the table `myDEMTable`, with the following values:

| PK | THE_GEOM | Z |
|:----:|:----------------------:|:---:|
| 1 | POINT Z (17.5 22.5 25) | 25.0 |
| 2 | POINT Z (22.5 22.5 24) | 24.0 |
| 3 | POINT Z (27.5 22.5 23) | 23.0 |
| 4 | POINT Z (17.5 17.5 23) | 23.0 |
| 5 | POINT Z (22.5 17.5 20) | 20.0 |
| 6 | POINT Z (27.5 17.5 19) | 19.0 |
| 7 | POINT Z (17.5 12.5 20) | 20.0 |
| 8 | POINT Z (22.5 12.5 18) | 18.0 |
| 9 | POINT Z (27.5 12.5 17) | 17.0 |


##### 5. Using `downScaleInt`

Here we want to divide the matrix size by 2

{% highlight mysql %}
CALL ASCREAD('/home/user/dem.asc', 'myDEMTable', null, 2, false);
{% endhighlight %}

Returns the table `myDEMTable`, with the following values:

| PK | THE_GEOM | Z |
|:----:|:----------------------:|:---:|
| 1 | POINT Z (12.5 27.5 28) | 28.0 |
| 2 | POINT Z (22.5 27.5 26) | 26.0 |
| 3 | POINT Z (12.5 17.5 26) | 26.0 |
| 4 | POINT Z (22.5 17.5 20) | 20.0 |


##### 6. Using `asPolygons`

Here we want to have a resulting `POLYGON` layer.

{% highlight mysql %}
CALL ASCREAD('/home/user/dem.asc', 'myDEMTable', null, 1, true);
{% endhighlight %}

Returns the table `myDEMTable`, with the following values:

<img class="displayed" src="../ASCRead_1.png"/>

| PK | THE_GEOM | Z |
|:----:|:--------------------------------------------------------------:|:---:|
| <sub>1</sub> | <sub>POLYGON Z ((10 30 28, 10 25 28, 15 25 28, 15 30 28, 10 30 28))</sub> | <sub>28.0</sub> |
| <sub>2</sub> | <sub>POLYGON Z ((15 30 27, 15 25 27, 20 25 27, 20 30 27, 15 30 27))</sub> | <sub>27.0</sub> |
| <sub>3</sub> | <sub>POLYGON Z ((20 30 26, 20 25 26, 25 25 26, 25 30 26, 20 30 26))</sub> | <sub>26.0</sub> |
| <sub>4</sub> | <sub>POLYGON Z ((25 30 25, 25 25 25, 30 25 25, 30 30 25, 25 30 25))</sub> | <sub>25.0</sub> |
| <sub>5</sub> | <sub>POLYGON Z ((10 25 27, 10 20 27, 15 20 27, 15 25 27, 10 25 27))</sub> | <sub>27.0</sub> |
| <sub>6</sub> | <sub>POLYGON Z ((15 25 25, 15 20 25, 20 20 25, 20 25 25, 15 25 25))</sub> | <sub>25.0</sub> |
| <sub>7</sub> | <sub>POLYGON Z ((20 25 24, 20 20 24, 25 20 24, 25 25 24, 20 25 24))</sub> | <sub>24.0</sub> |
| <sub>8</sub> | <sub>POLYGON Z ((25 25 23, 25 20 23, 30 20 23, 30 25 23, 25 25 23))</sub> | <sub>23.0</sub> |
| <sub>9</sub> | <sub>POLYGON Z ((10 20 26, 10 15 26, 15 15 26, 15 20 26, 10 20 26))</sub> | <sub>26.0</sub> |
| <sub>10</sub> | <sub>POLYGON Z ((15 20 23, 15 15 23, 20 15 23, 20 20 23, 15 20 23))</sub> | <sub>23.0</sub> |
| <sub>11</sub> | <sub>POLYGON Z ((20 20 20, 20 15 20, 25 15 20, 25 20 20, 20 20 20))</sub> | <sub>20.0</sub> |
| <sub>12</sub> | <sub>POLYGON Z ((25 20 19, 25 15 19, 30 15 19, 30 20 19, 25 20 19))</sub> | <sub>19.0</sub> |
| <sub>13</sub> | <sub>POLYGON Z ((10 15 25, 10 10 25, 15 10 25, 15 15 25, 10 15 25))</sub> | <sub>25.0</sub> |
| <sub>14</sub> | <sub>POLYGON Z ((15 15 20, 15 10 20, 20 10 20, 20 15 20, 15 15 20))</sub> | <sub>20.0</sub> |
| <sub>15</sub> | <sub>POLYGON Z ((20 15 18, 20 10 18, 25 10 18, 25 15 18, 20 15 18))</sub> | <sub>18.0</sub> |
| <sub>16</sub> | <sub>POLYGON Z ((25 15 17, 25 10 17, 30 10 17, 30 15 17, 25 15 17))</sub> | <sub>17.0</sub> |


##### See also

* [`CSVRead`](../CSVRead)
* <a href="https://github.com/orbisgis/h2gis/blob/master/h2gis-functions/src/main/java/org/h2gis/functions/io/asc/AscRead.java"
target="_blank">Source code</a>
Binary file added docs/dev/ASCRead_1.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/dev/CSVRead.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: CSVRead
category: h2drivers
is_function: true
description: CSV &rarr; Table
prev_section: h2drivers
prev_section: ASCRead
next_section: CSVWrite
permalink: /docs/dev/CSVRead/
---
Expand Down
37 changes: 22 additions & 15 deletions docs/dev/CSVWrite.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,42 +26,49 @@ CSVWrite(VARCHAR path, VARCHAR sqlSelectTable,
target="_blank">documentation</a> on the H2 website.</p>
</div>

Writes a CSV file from the SQL select statement `sqlSelectTable` to
the CSV file specified by `path`.
Writes a CSV file from the SQL select statement `sqlSelectTable` to the CSV file specified by `path`.

{% include stringDecode.html %}

### Examples

In the following examples, we are using a table named `AREA` and defined as follow:

{% highlight mysql %}
-- Create an example table to use with CSVWrite:
CREATE TABLE AREA(THE_GEOM VARCHAR(100), ID INT PRIMARY KEY);
INSERT INTO AREA VALUES
('POLYGON((-10 109, 90 9, -10 9, -10 109))', 1),
('POLYGON((90 109, 190 9, 90 9, 90 109))', 2);
-- Write it to a CSV file:
{% endhighlight %}

Write it to a CSV file:
{% highlight mysql %}
CALL CSVWrite('/home/user/area.csv', 'SELECT * FROM AREA');

-- Read it back:
SELECT * FROM CSVRead('/home/user/area.csv');
-- Answer:
-- | THE_GEOM | ID |
-- | ---------------------------------------- | ------ |
-- | POLYGON((-10 109, 90 9, -10 9, -10 109)) | 1 |
-- | POLYGON((90 109, 190 9, 90 9, 90 109)) | 2 |
-- | THE_GEOM | ID |
-- | ---------------------------------------- | -- |
-- | POLYGON((-10 109, 90 9, -10 9, -10 109)) | 1 |
-- | POLYGON((90 109, 190 9, 90 9, 90 109)) | 2 |
{% endhighlight %}

-- Try writing it with a specific charset and field separator:
Try writing it with a specific charset and field separator:

{% highlight mysql %}
CALL CSVWRITE('/home/user/area.csv',
'SELECT * FROM AREA', 'charset=UTF-8
fieldSeparator=;');
'SELECT * FROM AREA',
'charset=UTF-8 fieldSeparator=;');
-- Read it back:
SELECT * FROM CSVRead('/home/user/area.csv',
NULL,
'charset=UTF-8 fieldSeparator=;');
-- Answer:
-- | THE_GEOM | ID |
-- | ---------------------------------------- | ------ |
-- | POLYGON((-10 109, 90 9, -10 9, -10 109)) | 1 |
-- | POLYGON((90 109, 190 9, 90 9, 90 109)) | 2 |
-- | THE_GEOM | ID |
-- | ---------------------------------------- | -- |
-- | POLYGON((-10 109, 90 9, -10 9, -10 109)) | 1 |
-- | POLYGON((90 109, 190 9, 90 9, 90 109)) | 2 |
{% endhighlight %}

##### See also
Expand Down
Loading