README.md

# RegionChooser

[RegionChooser](https://transfer.hft-stuttgart.de/gitlab/hft_gitlab/regionchooser) is a Java project. Its graphical interface allows to extract a specific region from multiple [CityGML](https://www.ogc.org/standards/citygml) files and save it as a smaller CityGML file.

![RegionChooserScreenshot](region_chooser_screenshot.png)

It uses:

* [Java 8](https://simstadt.hft-stuttgart.de/getting-started/install-software/#java-8)
* JavaFX
* [Openlayers](https://openlayers.org/)

RegionChooser was developed during [SimStadt & SimStadt II](https://www.hft-stuttgart.de/forschung/projekte/aktuell/simstadt-20)  projects.

## Installation

The easiest way to install RegionChooser is to [install SimStadt](https://simstadt.hft-stuttgart.de/getting-started/install-software/#simstadt).

RegionChooser executables are packaged inside SimStadt.zip file.

## Usage

### Select a repository

You first need to run SimStadt in order to select a [repository](https://simstadt.hft-stuttgart.de/getting-started/repository-structure/#repository). Once a repository is selected, SimStadt can be closed.

### Start RegionChooser

* `RegionChooser.bat` in Windows
* `./RegionChooser.sh` in Linux
* `./RegionChooser.command` in macOS

### Select a region

* Once a repository has been imported, a map should be shown with the convex hulls of the available CityGML files.
* It is possible to define a polygon by clicking repeatedly on the map.
* If an intersection is found with at least one CityGML file, a list of files will be shown on the right.
* The selection might intersect multiple files. The user can select the desired files.
* By clicking on `Download Region`, a new CityGML file will be created, by merging the intersections of the polygon with each selected CityGML file.

### Get coordinates of polygon

The coordinates of the currently drawn polygon can be exported to [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) by clicking on `Copy coordinates`. It can be useful for further processing, e.g. in a Python script.

As an example:

> POLYGON((9.176194 48.779168, 9.171473 48.775265, 9.176923 48.772890, 9.179842 48.774474, 9.181043 48.774134, 9.183103 48.775661, 9.182073 48.776962, 9.176194 48.779168))

### Import a polygon

If no polygon has been drawn yet, "WKT Polygon" input field can be used. Simply copy a [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) polygon into the field, click on `Import Polygon`, and the geometry should be imported into RegionChooser.

With this feature, it should be easy to share geometry between users.

## Command-line

RegionChooser can also be called from the command-line:

```bash
Launching RegionChooser CLI --help
Usage: region_chooser [-hlV] [-e=31467] -o=output.gml -w=polygon.wkt -i=input.
                      gml[,input.gml...] [-i=input.gml[,input.gml...]]...
Extracts a region from one or more citygmls.
  -i, --input=input.gml[,input.gml...]
                            Citygml files to extract from
  -o, --output=output.gml   Output file
  -e, --epsg=31467          EPSG id for coordinate reference system.
                            Will use the one from input.gml if unspecified.
  -l, --local               Are WKT coordinates in local CRS?
                            Coordinates are in WGS84 if unspecified.
  -w, --wkt=polygon.wkt     File containing WKT polygon, or - for stdin
  -h, --help                Show this help message and exit.
  -V, --version             Print version information and exit.
```

As an example:

```bash
java -classpath "Desktop\SimStadt_0.10.0-SNAPSHOT_master_20221019_7d2546f\lib\*"
     eu.simstadt.regionchooser.RegionChooserCLI
	 --input Grombühl.proj\LoD2_32_566_5516_2_BY.gml,Grombühl.proj\LoD2_32_568_5516_2_BY.gml,Grombühl.proj\LoD2_32_570_5516_2_BY.gml
	 --output Grombühl.proj\Grombühl.gml --wkt "POLYGON((9.920858224863567 49.807325539080495, 9.918540796274696 49.79447295986074, 9.992612680429975 49.79358644932381, 9.991926034922162 49.807325539080495, 9.920858224863567 49.807325539080495))"
```

## Development

In order to compile, test and install RegionChooser into your local Maven repository:

```bash
git clone https://transfer.hft-stuttgart.de/gitlab/hft_gitlab/regionchooser.git
cd regionchooser
mvn clean install
```

The RegionChooser jar will then be available to SimStadt for packaging, when a SimStadt+RegionChooser bundle is created.

## Author

Eric Duminil, [HfT Stuttgart](https://www.hft-stuttgart.de/)

## Contributors

Matthias Betz, [HfT Stuttgart](https://www.hft-stuttgart.de/)

## License
[MIT](https://choosealicense.com/licenses/mit/)