wm/README.md

81 lines
2.5 KiB
Markdown
Raw Normal View History

2021-05-19 22:57:49 +03:00
WangMüller algorithm in PostGIS
--------------------------------
This is a work-in-progress implementation following "Line generalization based
2021-05-19 22:57:49 +03:00
on analysis of shape characteristics" by Wang and Müller, 1998.
2021-05-19 22:57:49 +03:00
Structure
---------
2021-05-19 22:57:49 +03:00
There will be 2 deliverables from this folder:
2021-05-19 22:57:49 +03:00
2021-05-19 22:57:49 +03:00
- `wm.sql`, the implementation.
2021-05-19 22:57:49 +03:00
- paper `mj-msc-full.pdf`, a MSc thesis, explaining it.
2021-05-19 22:57:49 +03:00
2021-05-19 22:57:49 +03:00
It contains a few supporting files, notably:
2021-05-19 22:57:49 +03:00
2021-05-19 22:57:49 +03:00
- `tests.sql` synthetic unit tests.
- `test-rivers.sql` tests with real rivers.
- `Makefile` glues everything together.
2021-05-19 22:57:49 +03:00
- `layer2img.py` converts a PostGIS layer to an embeddable image.
2021-05-19 22:57:49 +03:00
- `aggregate-rivers.sql` combines multiple river objects (linestrings or
multilinestrings) to a single one.
2021-05-19 22:57:49 +03:00
- `init.sql` initializes PostGIS database for running the tests.
- `rivers.sql` is an OpenStreetMap snapshot of select rivers (`Makefile`
contains code to update them).
2021-05-19 22:57:49 +03:00
- ... and a few more files necessary to build the paper.
2021-05-19 22:57:49 +03:00
2021-05-19 22:57:49 +03:00
Running
-------
2021-05-19 22:57:49 +03:00
2021-05-19 22:57:49 +03:00
`make help` lists the select commands for humans. As of writing:
2021-05-19 22:57:49 +03:00
```
2021-05-19 22:57:49 +03:00
# make help
2021-05-19 22:57:49 +03:00
mj-msc-full.pdf Thesis for publishing
test Unit tests (fast)
test-rivers Rivers tests (slow)
clean Clean the current working directory
clean-tables Remove tables created during unit or rivers tests
help Print this help message
wc Character and page count
refresh-rivers Refresh rivers.sql from Open Street Maps
```
To execute the algorithm, run:
- `make test` for tests with synthetic data.
- `make test-rivers` for tests with real rivers. You may adjust the rivers and
data source (e.g. use a different country instead of Lithuania) by changing
2021-05-19 22:57:49 +03:00
the `Makefile` and the test files. Left as an exercise for the reader.
2021-05-19 22:57:49 +03:00
Building the paper (pdf)
------------------------
2021-05-19 22:57:49 +03:00
```
2021-05-19 22:57:49 +03:00
# make -j$(nproc) mj-msc-full.pdf
2021-05-19 22:57:49 +03:00
```
2021-05-19 22:57:49 +03:00
`mj-msc.tex` results in `mj-msc-full.pdf`, which will be at some point
published. It needs quite a few dependencies, including a functioning Docker
2021-05-19 22:57:49 +03:00
environment, postgresql client, geopandas, pygments, osm2pgsql, poppler, and a
"quite extensive" LaTeX installation. This was tested on Debian 11.
2021-05-19 22:57:49 +03:00
2021-05-19 22:57:49 +03:00
Contributing
------------
Please reach out to me before contributing. As of writing, this is not ready to
accept broader contributions, TODO:
2021-05-19 22:57:49 +03:00
- [x] Elimination operator.
2021-05-19 22:57:49 +03:00
- [x] Exaggeration operator.
2021-05-19 22:57:49 +03:00
- [ ] Combination operator.
2021-05-19 22:57:49 +03:00
- [ ] CI.
2021-05-19 22:57:49 +03:00
- [ ] Known bug in `wm_self_crossing`: the program crashes with a river in
Lithuania.
2021-05-19 22:57:49 +03:00
2021-05-19 22:57:49 +03:00
License
-------
2021-05-19 22:57:49 +03:00
GPL 2.0 or later, same as PostGIS.