The NZ Buildings system is used to manage New Zealand's national building outlines dataset. This dataset is published under CC-BY-4.0 on the LINZ Data Service.
The Topography team at Land Information New Zealand built this system and use it to:
- validate building outlines captured via feature extraction
- assign additional attributes (capture metadata, administrative boundaries)
- manually add, modify or delete building outlines where required
- compare a new set of building outlines against existing building outlines and categorise matching, added, removed or related buildings
- manage the lifecycle of building outlines across multiple data captures
- prepare data to be published on the LINZ Data Service
- A PostgreSQL/PostGIS database schema for data storage
- A QGIS plugin for data maintenance
- A data dictionary hosted on readthedocs
- ISO 19115 geospatial metadata to accompany the published datasets
All of the components build upon other free and open source software. See ACKNOWLEDGEMENTS.rst for a summary.
The database for the NZ Buildings system is a PostgreSQL database with the PostGIS database extension for handling geographic objects.
- PostgreSQL and PostGIS must be installed. Supported versions are tested on GitHub Actions (note the matrix variables in the
pgtap
job that show version numbers for PostgreSQL and PostGIS). - For development / testing, install pgTAP.
First install the project into the OS data share directory:
sudo make install
Then you can load the schema into a target database:
nz-buildings-load $DB_NAME
NOTE: the loader script will expect to find SQL scripts under /usr/share/nz-buildings/sql
, if you want them found in a different directory you can set the BUILDINGSCHEMA_SQLDIR
environment variable.
The nz-buildings-load
script will also upgrade as it currently replaces the existing schema. All data will be lost.
For development, creating an alias that reinstalls scripts, rebuilds a test database and re-runs tests locally is helpful.
alias buildingsdb='cd $DEV/nz-buildings && sudo make uninstall clean install && make check && cd -'
$DEV
is the directory that nz-buildings
has been cloned into.
Testing uses pgTAP via pg_prove
.
make check
A database called nz-buildings-pgtap-db
is created with some test data in order to run the tests.
GitHub Actions is used for continuous integration.
- The QGIS plugin currently requires
QGIS 3.4.x
.
The plugin can be installed in the local plugin folder from this repository.
make deploy
Clone, then create and activate a virtual environment.
python3 -m venv .venv
source .venv/bin/activate
python3
must be 3.6+.
Upgrade pip
and install the required dependencies.
pip install --upgrade pip
pip install -r requirements-dev.txt
I Install commit-msg
git hook.
pre-commit install --hook-type commit-msg
Creating a symlink from the repo to the local QGIS plugin directory makes it easy to evaluate changes to QGIS plugin code.
ln -s $DEV/nz-buildings/buildings $HOME/.local/share/QGIS/QGIS3/profiles/default/python/plugins
Testing uses Python unittest
inside a real QGIS instance.
Individual test cases can be executed within QGIS by using the Script Assistant plugin, which will reload a test every time it is executed to allow ease of writing tests and checking their output.
GitHub Actions and the QGIS Testing Environment are used for continuous integration.
The NZ Buildings Data Dictionary is automatically built on every commit to master
.
DOCUMENTATION.rst details the source code requirements in order create a valid data dictionary.
This system is under the 3-clause BSD License, except where otherwise specified. See the LICENSE file for more details.