Naphthalene Possum Management

    @giscience/ohsome2x
    TypeScript icon, indicating that this package has built-in type declarations

    2.5.6 • Public • Published

    ohsome2X

    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.

    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.

    Additionally it includes ohsome2x-cli, a command-line tool with a configuration wizard to create and run a query-configuration-JSON.

    This library/tool makes use of the ohsome API (https://api.ohsome.org) as data backend and many other great open-source libraries.

    Currently supported ohsome API query types are:

    //standard
    elements/count/groupBy/boundary
    elements/length/groupBy/boundary
    elements/area/groupBy/boundary
    elements/perimeter/groupBy/boundary
    
    //ratio 
    elements/count/ratio/groupBy/boundary
    elements/length/ratio/groupBy/boundary
    elements/area/ratio/groupBy/boundary
    elements/perimeter/ratio/groupBy/boundary
    
    //group by tags within each boundary
    elements/count/groupBy/boundary/groupBy/tag
    elements/length/groupBy/boundary/groupBy/tag
    elements/area/groupBy/boundary/groupBy/tag
    elements/perimeter/groupBy/boundary/groupBy/tag
    
    //contributors
    users/count/groupBy/boundary
    

    This software is developed by HeiGIT:

    HeiGIT Logo

    Usage

    There are two ways how you can use ohsome2x.

    1. Without installation using the npm package runner npx

    Info: The npx command comes with the installation of npm.

    To run the command-line wizard:

    Syntax info:
    $ npx @giscience/ohsome2x
    -------------------------
    USAGE:
    with 'npx'
    npx @giscience/ohsome2x createconfig [(-o|--out) path]
    npx @giscience/ohsome2x run (-c|--conf) fullConfig.json
    as local command
    node ohsome2x-cli.js createconfig [(-o|--out) path]
    node ohsome2x-cli.js run (-c|--conf) fullConfig.json
    -------------------------

    2. With installation as library to use it in your Node.js script

    1. For use as library in Node.js install the package:

      $ npm install @giscience/ohsome2x
    2. You find the built library in the /dist folder after executing:

      $ npm run build
      
    3. Write your own JavaScript or TypeScript file:

      See Examples and API section to learn how to do it. Enjoy!
      

    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-file (you can use the commandline wizard to create this): myquery.json

    Info: for the filter Syntax see: https://docs.ohsome.org/ohsome-api/stable/filter.html

    {
      "ohsomeQuery": {
        "queryType": "elements/count/groupBy/boundary",
        "filter": "building=* and building!=no and geometry: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
    $ npx @giscience/ohsome2x run --conf myquery.json

    API

    Basic Usage

    Node:

    const Ohsome2X = require('@giscience/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:

    import Ohsome2X = require('@giscience/ohsome2x'); 
    import {Ohsome2XConfig} from '@giscience/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);

    Events

    The Ohsome2X object currently provides 2 event types that can be listened to:

    • progress for getting progress updates. Especially useful for iterative processing of large input datasets

      progress provides the following object to your callback (use processed and total to compute a progress percentage):

      {
          "type":      "progress",                
          "processed": <number> of already finished input geometries, 
          "total":     <number> of all input geometries,
          "cursor":    <number> that indicates the current state of iterative processing in case you configured source and target as PostGIS-Stores and specified a fetchSize,
          "fetchSize": <number> fetchSize that is currently used to fetch the next chunk of source data,
          "timestamp": <string> ISO timestamp 
      }
    • finished to get some information on duration and finishing time:

      {
          "type":         "finished", 
          "duration":     <string> a human readable duration like '2 days 13 hours 45 min 12 seconds', 
          "duration_ms":  <number> duration in milliseconds, 
          "timestamp":    <string> ISO timestamp
      }

    Example:

    const Ohsome2X = require('@giscience/ohsome2x');
    
    // you can create this config using the command-line wizard, run: npx ohsome2x-cli
    const config = {
                  ohsomeQuery: {
                      "queryType": "users/count/groupBy/boundary",
                      "filter": "natural=tree and type:node",
                      "time": "2010/2020/P1Y"
                  },
                  source: {
                       "schema": "public",
                       "name": "my_source_table_name",
                       "geometryId": "id", // name of the id column. Can be numbers or strings.
                       "geometryColumn": "geom",
                       "fetchSize": 5000, // this option triggers an iterative processing 
                       "cursor": null, // can be used to resume an interrupted iterative processing at a certain position. Get this information from the 'fetch' event.
                       "store": {
                           "host": "your.postgis.server.com",
                           "port": "5434",
                           "database": "your_database_name",
                           "user": "username",
                           "password": "secret",
                           "type": "postgis"
                       }
                  },
                  target: {...another PostGIS target config...}
    }                               
    
    const ohsome2x = new Ohsome2X(config);
    
    // define functions to be executed when an event is reported
    ohsome2x.on('progress', (evt)=>console.log(evt, ((evt.processed / evt.total) * 100).toFixed(0) +'%'));
    ohsome2x.on('finished', (evt)=>console.log(evt.duration));
    
    // This will return a Promise
    ohsome2x.run().catch(console.log);

    Related

    • OhsomeHeX - The OSM History Explorer: Uses this library as backend
    • ohsome API - WebAPI to query OSM History Data
    • OSHDB - The OpenStreetMap History Database: Query OSM History Data with Java
    • ohsome.org - Get information about all these technologies and more
    • heigit.org - The Heidelberg Institute for Geoinformation Technology: The non-profit company behind all those useful tools.

    Install

    npm i @giscience/ohsome2x

    DownloadsWeekly Downloads

    23

    Version

    2.5.6

    License

    MIT

    Unpacked Size

    110 kB

    Total Files

    24

    Last publish

    Collaborators

    • mcauer
    • tyr_asd