Commit b87e9afd authored by Michael Auer's avatar Michael Auer
Browse files

README.md preparations for publishing on npm. Added info for installation,...

README.md preparations for publishing on npm. Added info for installation, usage, examples, related links etc.
parent 9fa8695f
# ohsome2X
## Install
```bash
1. Clone the repo:
> Query OSM History Data (count, length, area) about specific OSM Features or OSM User activity (user-count) for your areas of interest.
> Input: Accepts GeoJSON or PostgreSQL/PostGIS as input source.
git clone ssh://git@gitlab.gistools.geog.uni-heidelberg.de:2022/giscience/big-data/ohsome/libs/ohsome2x.git
> Output: Creates a GeoJSON File or new result table in your PostgreSQL/PostGIS database.
The package includes a library with a single class to run.
OR
Additionally it includes `oshome2x-cli`, a command-line tool with a configuration wizard to create and run a query-configuration-JSON.
git clone https://gitlab.gistools.geog.uni-heidelberg.de/giscience/big-data/ohsome/libs/ohsome2x.git
This library/tool makes use of the Ohsome-API (https://api.ohsome.org) as data backend and many other great open-source libraries.
2. Run the npm installer inside repo
cd ohsome2x
npm install
This software is developed by [HeiGIT](https://heigit.org):
3. Build the project
<img src="https://heigit.org/wp-content/uploads/2018/01/HeiGIT_Logo_cut-505x100@2x.png" alt="HeiGIT Logo" height="80px" width="404px">
## Install
npm run build
For use as library in Node.js:
```bash
$ npm install ohsome2x
```
To run the command-line wizard:
```bash
$ npx ohsome2x-cli
```
## Usage
There are two ways how you can use ohsome2x.
1. Use it as library in another project. You find the built library in the `/dist` folder after executing `npm run build`
2. Use the interactive command line interface. Run: `node ./ohsome2x-cli/ohsome2x-cli.js`
\ No newline at end of file
1. Use it as library in another Node.js project. You find the built library in the `/dist` folder after executing `npm run build`
2. Use the interactive command line interface.
Run:
```
npx ohsome2x-cli
OR
node ./ohsome2x-cli/ohsome2x-cli.js
```
## Example
### Query the number of buildings in a bbox around Heidelberg in a yearly resolution from 2008 to 2020
##### Step 1. You need some input (one or many polygons): heidelberg.geojson
```
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {"id": "Heidelberg"},
"geometry": {
"type": "Polygon",
"coordinates": [
[ [8.625984191894531, 49.38527827629032],
[8.735504150390625, 49.38527827629032],
[8.735504150390625, 49.433975502014675],
[8.625984191894531, 49.433975502014675],
[8.625984191894531, 49.38527827629032]
]]}}]}
```
##### Step 2. Specify your query as JSON (you can use the commandline wizard to create this): myquery.json
```
{
ohsomeQuery: {
queryType: 'elements/count/groupBy/boundary',
keys: 'building',
values: '',
types: 'polygon',
time: '2008/2020/P1Y'
},
source: {
geometryId: 'id',
name: 'heidelberg.geojson',
store: { path: 'heidelberg.geojson', type: 'geojson' }
},
target: {
horizontalTimestampColumns: false,
createGeometry: true,
transformToWebmercator: false,
storeZeroValues: true,
computeValuePerArea: true,
name: 'heidelberg_buildings_count.geojson',
store: { path: 'heidelberg_buildings_count.geojson', type: 'geojson' }
}
}
```
##### Step 3. Run the Query
```bash
$ npx ohsome2x-cli run --conf myquery.json
```
## API
Node:
```ecmascript 6
const Ohsome2X = require('ohsome2x');
// you can create this config using the command-line wizard, run: npx ohsome2x-cli
const config = {
ohsomeQuery: {...},
source: {...},
target: {...}
}
const ohsome2x = new Ohsome2X(config);
// This will return a Promise
ohsome2x.run().catch(console.log);
```
TypeScript:
```typescript
import Ohsome2X = require('ohsome2x');
import {Ohsome2XConfig} from 'ohsome2x/dist/config_types_interfaces';
// you can create this config using the command-line wizard, run: npx ohsome2x-cli
const config: Ohsome2XConfig = {
ohsomeQuery: {...},
source: {...},
target: {...}
}
const ohsome2x = new Ohsome2X(config);
// This will return a Promise
ohsome2x.run().catch(console.log);
```
### Related
- [OhsomeHeX](https://ohsome.org/apps/osm-history-explorer) - The OSM History Explorer: Uses this library as backend
- [OhsomeAPI](https://api.ohsome.org) - WebAPI to query OSM History Data
- [OSHDB](https://github.com/GIScience/oshdb) - The OpenStreetMap History Database: Query OSM History Data with Java
- [ohsome.org](https://ohsome.org) - Get Information about all these technologies and more
- [heigit.org](https://heigit.org) - The Heidelberg Institute for Geoinformation Technology: The non-profit company behind all those useful tools.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment