girder_geospatial

Installation

1. Install girder.

2. Install gdal version 2 or higher on to your system.

   • To install with a wheel, run:

       pip install gdal -f https://manthey.github.io/large_image_wheels/
     

   • If not installing with a wheel:

     • Install gdal to your system with the instructions above
     • Check system gdal version by running gdal-config --version
     • Pip install the corresponding version of gdal

3. Test your gdal installation by running

python -c "from osgeo import gdal"

4. Install the geospatial plugin and desired types packages.

pip install girder-geospatial
pip install girder-geospatial-raster \
            girder-geospatial-vector \
            girder-geospatial-grid

5. Enable Girder cache by adding following to your girder config file:

[cache]
enabled = True
cache.global.backend = "dogpile.cache.memory"
cache.request.backend = "cherrypy_request"

Usage

1. Uploading a geospatial file

   After the plugin is enabled in Girder, simply upload a geospatial file that gdal or ogr can handle. To see lists of supported formats see the gdal and ogr format documentation. This plugin responds to the upload file event. File uploads will trigger a handler setting geospatial metadata on the uploaded file's item automatically.

2. Creating geospatial metadata on an already existing item

   If you already have data in Girder, and you don't want to reupload your data. There is an endpoint which takes an item id and creates geospatial metadata on the item.

   curl '{girderApiUrl}/item/{itemId}/geometa' -X PUT
   

   This endpoint will inspect the file and attach 'geometa' key to the given item.

3. Creating arbitrary geospatial metadata on an existing item

   Some users might want more control on what they are saving. The same endpoint in option 2 can be used to create arbitrary metadata following the base schema. In other words, as long as you have the required parameters that are defined in the base schema, you are free to add your own additional data for your own purposes.

   curl '{girderApiUrl}/item/{itemId}/geometa?geometa={geospatialMetadata}' -X PUT
   

4. Querying mongo for geospatial datasets

   To query mongo, use the following endpoint with required query parameters.

   curl '{girderApiUrl}/item/geometa?{necessaryQueryStringParameters} -X GET
   

   This endpoint accepts a number of geospatial queries, including:

   1. WKT geometry and relation
   2. Bounding box and relation
   3. Geojson geometry and relation
   4. Latitude, longitude and radius.

   When providing latitude, longitude, and radius, the relation will be always "within" as opposed to "intersects". This might create unexpected results. We recommend using options 1, 2 or 3 above.

   Also, please note these options are mutually exclusive so you cannot pass both geojson and bounding box options. The Opensearch Geo Schema validators will raise an exception if mutually exclusive parameters are passed.

5. Getting geometa from an item

   To get geospatial metadata on an item, call the following endpoint:

   curl '{girderApiUrl}/item/{itemId}/geometa' -X GET
   

Vagrant Examples

There are currently 2 vagrant examples to quickly get up and running. If you are having problems installing this plugin check ansible playbooks for ubuntu-16.04 and ubuntu-18.04.

Running tests

cd geometa
pip install -r requirements-dev.txt
pytest -n 4