From 16337c4d27a96db014786873ec0fada2778024f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Dukai?= Date: Mon, 20 Jan 2020 18:30:43 +0100 Subject: [PATCH] Update readme --- README.rst | 73 ++++++++++++++++++++++++++++++++++++++---- cjio_dbexport/utils.py | 4 +-- tests/test_db3dnl.py | 10 ++++++ 3 files changed, 79 insertions(+), 8 deletions(-) diff --git a/README.rst b/README.rst index 7278d33..550a1fd 100644 --- a/README.rst +++ b/README.rst @@ -39,7 +39,7 @@ Install for development Requires Python 3.6+ -The project is pre-alpha, please install directly from GitHub with pip: +The project is alpha, please install directly from GitHub with pip: .. code-block:: @@ -52,7 +52,7 @@ Call the *cjdb* tool from the command line and pass it the configuration file. .. code-block:: - $ cjdb tests/data/test_config.yml --help + $ cjdb config.yml --help Usage: cjdb [OPTIONS] CONFIGURATION COMMAND [ARGS]... @@ -67,7 +67,13 @@ Call the *cjdb* tool from the command line and pass it the configuration file. --help Show this message and exit. Commands: - export Export into a CityJSON file. + export Export the whole database into a CityJSON file. + export_bbox Export the objects within a 2D Bounding Box into a + CityJSON... + export_extent Export the objects within the given polygon into a + CityJSON... + export_tiles Export the objects within the given tiles into a CityJSON... + index Create a tile index for the specified extent. This tool uses a YAML-based configuration file to managing the database @@ -97,6 +103,14 @@ By default all columns, excluding the three above, are added as Attributes to th user: some_user password: some_password + tile_index: + schema: tile_index + table: tile_index_1 + srid: 7415 + field: + pk: id + geometry: geom + cityobject_type: WaterBody: - schema: public @@ -122,11 +136,60 @@ By default all columns, excluding the three above, are added as Attributes to th cityobject_id: identificatie exclude: ["xml"] +Exporting a subset +****************** + You can provide a bounding box (minx miny maxx maxy) to limit the extent of the export. .. code-block:: - $ cjdb tests/data/test_config.yml export --bbox 123.4 545.5 678.8 987.8 path/to/some/file.json + $ cjdb config.yml export_bbox 123.4 545.5 678.8 987.8 +path/to/output.json + +To export an irregular extent, provide a single +Polygon in a GeoJSON file. + +.. code-block:: + + $ cjdb config.yml export_extent polygon.geojson path/to/output.json + +To export a set of tiles into a separate CityJSON file each, provide their +tile IDs. The command below will export the tiles ``ci1``, ``ci2``, ``gb4`` +into the given directory. If you want to merge the tiles into a single file, +provide +the ``--merge`` option to ``export_tiles``. If you want to export all the +tiles from the *tile index*, then pass ``all`` as the tile ID. + +.. code-block:: + + $ cjdb config.yml export_tiles ci1 ci2 gb4 path/to/directory + +Creating a tile index +********************* + +If you have a database of a large area, you probably want to export it +piece-by-piece, in tiles. This requires a *tile index*, which is a rectangular +grid of polygons that fully covers your area, and each polygon has a unique ID. + +The ``index`` command can help you create such a tile index. It requires a +polygonal *extent* of your area as GeoJSON file and the *width* and *height* +of the tiles you want to create. The units for the tile size are same as the +unit of the CRS in the database. + +.. code-block:: + + $ cjdb config.yml index netherlands.json 1000 1000 + +The command above will, + +1. create rectangular polygons (tiles) of 1000m by 1000m for the extent +of the polygon that is ``netherlands.json``, + +2. sort the tiles in Morton-order and create unique IDs for them +accordingly, + +3. upload the tile index into the relation that is declared in +``config.yml`` under the ``tile_index`` node. Limitations @@ -136,8 +199,6 @@ Limitations + The geometry is expected to be a ``MULTIPOLYGON`` of ``POLYGON Z`` in PostGIS -+ Either export the whole database table, or subset with a bounding box - + Only tested with PostgresSQL 11, PostGIS 2.5 + CRS is hardcoded to 7415 diff --git a/cjio_dbexport/utils.py b/cjio_dbexport/utils.py index c6aebfe..7a97bf2 100644 --- a/cjio_dbexport/utils.py +++ b/cjio_dbexport/utils.py @@ -134,8 +134,8 @@ def index_quadtree(grid): id_map = { 0 : ('1', '2', '3', '4'), - 1 : ('a', 'b', 'c', 'd'), - 2 : ('e', 'f', 'g', 'i'), + 1 : ('e', 'f', 'g', 'i'), + 2 : ('a', 'b', 'c', 'd'), 3 : ('1', '2', '3', '4'), 4 : ('1', '2', '3', '4') } diff --git a/tests/test_db3dnl.py b/tests/test_db3dnl.py index c7d7bb3..b183c93 100644 --- a/tests/test_db3dnl.py +++ b/tests/test_db3dnl.py @@ -25,7 +25,9 @@ def test_parse_boundary(): @pytest.mark.db3dnl def test_build_query(db3dnl_db, cfg_parsed): features = db.Schema(cfg_parsed['cityobject_type']['LandUse'][0]) + tile_index = db.Schema(cfg_parsed['tile_index']) query = db3dnl.build_query(conn=db3dnl_db, features=features, + tile_index=tile_index, bbox=[192837.734, 465644.179, 193701.818, 466898.821]) query_str = db3dnl_db.print_query(query) @@ -53,6 +55,14 @@ def test_export_tile_list(self, data_dir, cfg_parsed, db3dnl_db, caplog): tile_list=['gb2', 'ic1', 'ic2', 'ec4']) print(cm.get_info()) + def test_export_extent(self, data_dir, cfg_parsed, db3dnl_db, caplog): + caplog.set_level(logging.DEBUG) + with open(data_dir / 'db3dnl_poly.geojson', 'r') as fo: + polygon = utils.read_geojson_polygon(fo) + cm = db3dnl.export(conn=db3dnl_db, cfg=cfg_parsed, + extent=polygon) + print(cm.get_info()) + def test_index(self, data_dir, nl_poly): tilesize = (10000, 10000) polygon = cjio_dbexport.utils.read_geojson_polygon(nl_poly)