# How to dføur

[ToC]

## Intro

The dføur sandbox environment is available at [sandbox.dfour.space](https://sandbox.dfour.space/de/).

This Mini How-To gives you a quick introduction how to work with the platform, browse and download prepared datasets and how you can add your own map based analysis to share with others.

To start uploading snapshots in your own, personal workspace (up to 20MB in file size), get in contact with us via Twitter (@cividitech) or Discord.

## Create your own Snapshot - Option 1: QGIS Plugin

The experimental QGIS Pugin "[Spatial Data Package Export](https://github.com/cividi/spatial-data-package-export)" is available via the [QGIS plugin repository](https://plugins.qgis.org/plugins/SpatialDataPackageExport/) or on [GitHub](https://github.com/cividi/spatial-data-package-export/releases/).

[Direct Download](https://github.com/cividi/spatial-data-package-export/releases/download/0.2.1/SpatialDataPackageExport.0.2.1.zip)

To install:

1. make sure to have [QGIS](https://qgis.org) 3.14 or later installed
2. Open Plugins -> Manage Plugins
3. Search for Spatial Datapackage Export
4. Click Install


Alternativly download the latest release from github.com/cividi/spatial-data-package-export/releases and manually install via zip or build from source.

## Create your own Snapshot - Option 2: Write your own exporter

Datapackage consists of metadata and data itself. For rednering a map you need to include the styling (Mapbox Simple Styles) to the exported GeoJSON.
Datapackage (Snapshot) = metadata + styled (geo)json

The full spec, a JSON schema and examples are available [here](https://github.com/cividi/spatial-data-export).

### 1. Metadata. Here is recommended minimal schema to use:

name: "{{ name }}"
license: "ODC-By-1.0"
licenses:
    - 
        url: "https://opendatacommons.org/licenses/by/1.0/"
        type: "ODC-By-1.0"
views:
    - 
        name: "mapview"
        specType: "gemeindescanSnapshot"
        spec:
            title: "{{ title }}"
            description: "{{ description }}"
            attribution: ""
            bounds: "{{ bounds_to_have }} "
            legend: "{{ legend }}""
        resources: ["data-layer", "mapbox-background"]
sources:
    -
        url: "https://www.openstreetmap.org/copyright"
        title: "Karte: Mapbox, © OpenStreetMap"
resources:
    - 
        name: "data-layer"
        mediatype: "application/vnd.geo+json" or "application/vnd.simplestyle-extended" see below
        data:
            name: "data"
            type: "FeatureCollection"
            features: "{{ STYLED DATA }}"
    -
        name: "mapbox-background"
        path: "mapbox://styles/gemeindescan/ckc4sha4310d21iszp8ri17u2"
        mediatype: "application/vnd.mapbox-vector-tile"
        data: 

In this schema you have variables in "{{ _variable_ }}", which you would rewrite to text: "{{ _variable_ }}" --> "desired variable"
{{ bounds_to_have }} - defines the frame of the map.
- example:

"geo:47.310897, 8.458443", "geo:47.446897, 8.638687"

{{ legend }} - legend shown
- example:

[{"label": 0, "size": "3.0", "shape": "circle", "primary": false, "fillColor": "#f30000", "fillOpacity": 0.7, "strokeColor": "#232323", "strokeWidth": 1.0, "strokeOpacity": 1.0},
{"label": 1, "size": "3.0", "shape": "circle", "primary": false, "fillColor": "#f30a00", "fillOpacity": 0.7, "strokeColor": "#232323", "strokeWidth": 1.0, "strokeOpacity": 1.0}, 
{"label": 2, "size": "3.0", "shape": "circle", "primary": false, "fillColor": "#f41400", "fillOpacity": 0.7, "strokeColor": "#232323", "strokeWidth": 1.0, "strokeOpacity": 1.0}]

### 2. Styled data

{{ STYLED DATA }} -- your data, each data point has to have style properties, depending on which type of data layer you want to add.

#### 2.1. Mediatypes

A layer can be either of these three mediatypes:

- `application/geo+json` -> [Simple Style GeoJSON](https://github.com/mapbox/simplestyle-spec)
- `application/simplestyles-extended` -> Circles from points w/ a radius
- `application/vnd.mapbox-vector-tile` -> Mapbox style background layer

### 3. Examples

- example for a layer with points shown as circles

{"type": "Feature", 
         "properties": 
             {
               "name": "2EtJFks9cv5AD1V7tOao2L", 
               "score": 13, 
               "category": "13", 
               "fill": "true", 
               "fillColor": "#f98500", 
               "fillOpacity": 0.7, 
               "stroke": "true", 
               "color": "#232323", 
               "opacity": "1.0", 
               "weight": 1.0, 
               "radius": "3.0", 
               "strokeColor": "#232323"
              }, 
              "geometry": {"type": "Point", 
                "coordinates": [8.5552764, 47.3757927]}
                }
                   

- example for a layer with polygons styled as [Simple Styles](https://github.com/mapbox/simplestyle-spec)

{"type": "Feature", 
         "properties": {"name": "2EtJFks9cv5AD1V7tOao2L", 
               "score": 13, 
               "category": "13",  
               "fill": "#f98500", 
               "fill-opacity": 0.7, 
               "stroke": "true", 
               "color": "#232323", 
               "opacity": "1.0", 
               "weight": 1.0, 
               "radius": "3.0", 
               "strokeColor": 
               "#232323"}, 
        "geometry": {
              "type": "Polygon", "coordinates": [[[8.5552764, 47.3757927],[8.5452764, 47.3657927],[8.5552764, 47.3657927]]]}}               

More detailed mappings of the property names are available [here](https://hackmd.io/@n0rdlicht/HkaDNg_rL).

## Annotate
Leave marks, create a note and come back to your thread of thoughts anytime.

## Upload via web interface

Once you acquired a new snapshot via QGIS or your own scripts. Once logged in with your personal account, you can upload a new snapshot via the plus button on the bottom of the list or replace an existing one.


## Upload via [frictionless-dfour](https://github.com/cividi/frictionless-dfour) plugin

If you are using [frictionless-py](https://framework.frictionlessdata.io) install the dfour storage plugin

pip install frictionless-dfour

To read from the workspace:

from frictionless import system
from pprint import pprint

source = "https://sandbox.dfour.space"
dialect = DfourDialect(snapshotHash="<SNAPSHOT-HASH>", username:"<YOUR-USER>", password: "<YOUR-PASSWORD>")

storage = system.create_storage("dfour", source, dialect=dialect)
pkg = storage.read_package()

To write a prepared package to dfour

from frictionless import system
from pprint import pprint

target = "https://sandbox.dfour.space"
dialect = DfourDialect(workspaceHash:"<WORKSPACE-HASH>", username:"<YOUR-USER>", password: "<YOUR-PASSWORD>")

storage = system.create_storage("dfour", target, dialect=dialect)
storage.write_package(pkg.to_copy(), force=True)

Or run it from the command line to sync with a local folder

export DFOUR_USERNAME=your-dfour-username
export DFOUR_PASSWORD=your-dfour-password
dfour workspace dfour-workspace-hash path-to-local-folder-to-sync -e https://sandbox.dfour.space

## Examples

- [(Geo)Spatial Data Data Package Specification](https://github.com/cividi/spatial-data-package)
- [Streetwise Spatial Data Package](https://github.com/Streetwise/streetwise-datapackage)
- [Basic Datasets Lenzburg](https://github.com/cividi/scl-lenzburg)