DTVF: Data Structure

The DTVF data structure consists of an arbitrary hierarchy of directories, with each leaf (i.e. lowest level) directory containing a complete, self-contained, set of files for visualisation. This hierachy allows developers to effectively provide grouping to their data. Each level in the tree contains a meta.json file detailing the name of that group and the user-facing names/locations of its sub-groups. Each leaf directory, should contain a complete set of data for visualisation.

Controls within the visualisation will be generated allowing the user to select an option for each group level, ultimately selecting a single leaf directory; the contents of this leaf directory will then be plotted. There is now no sytem to combine data from multiple direcotories; whilst this may promote data duplication, these visualisation data files are normally quite small, and the simplicity of the expected data format should help new users get up and running much quicker.

Update: If wholly different data sets are needed (perhaps with different default map options), the DTVF now supports the ability to use multiple root directories, each containing a separate hierarchal structure (as outlined above).

Branch Directory

A branch directory is a directory in which no visualisation data exists; the directory only exists to act as a group for its sub-directories. Within such a directory, the meta.json files is used to provide a user-facing group name, and details for each of the sub-directories (that will become sub-groups within the framework).

Without this file, or the proper contents within it, the framework will not be able to offer the grouping or data you may expect. A example of a meta.json file for a branch directory is shown below.

{
    "label": "My Group #1",
    "groups": [
        {
            "name": "My Subgroup #1",
            "directory": "sub-group-1"
        },
        {
            "name": "My Subgroup #2",
            "directory": "sub-group-2"
        },
        {
            "name": "My Subgroup #3",
            "directory": "sub-group-3"
        }
    ]
}

Root Directory

The root directory for your data structure is essentially a branch directory, but will require some additional metadata in the form of a tree.json file and an additional global node within its meta.json file. Note that if you're plotting data with no grouping (i.e. the data files are just within the root directory), the above conditions are still applicable.

The tree.json file defines the structure of the Layer Tree that is shown to the user; this control allows them to hide/show different layers of data on the visualisation. Details about this file and its use can be see on the Layer Tree page.

The meta.json file of the root directory will be the same as those seen in the branching directory, however that content will be nested within a local JSON node, and an additional global node is added to specify global visualisation options.

{
    "global": {
        "defaultCenter": [0.39713859558105463, 52.75354199742786],
        "defaultZoom": 15,
        "defaultBearing": -30,
        "defaultPitch": 65
    },
    "local": {
        "label": "My Group #1",
        "groups": [
            {
                "name": "My Subgroup #1",
                "directory": "sub-group-1"
            }
        ]
    }
}

Leaf Directory

A leaf directory is the lowest level within a group and contains the actual data to be visualised. Leaf directories will also contain a meta.json file, but in this case it will describe the data sets available within the group (rather than any sub-groups).

The meta.json file here will contain a dataSets JSON array, within which each object defines a single data set to be plotted. Each data set will be added to the visualisation as a single source, and will be displayed via a single layer (caveat: additional layers may actually be added to define interaction areas, clustering, labels etc).

Each of these datasets will comprise of a single GeoJSON file (read more about their expected contents on the GeoJSON page), one or more metadata files (in which each location's non-geographic data is added), and one or more timeseries files (in which temporal data series are defined).

An example leaf directory's meta.json file is shown below:

{
    "dataSets": [
        {
            "name": "assets-1",
            "dataLocation": "assets-1.geojson",
            "locationType": "circle",
            "metaFiles": ["assets-1-meta.json"],
            "timeseriesFiles": ["assets-1-timeseries.json"]
        },
        {
            "name": "assets-2",
            "dataLocation": "assets-2.geojson",
            "locationType": "circle",
            "metaFiles": ["assets-2-meta.json"]
        },
        {
            "name": "assets-3",
            "dataLocation": "assets-3.geojson",
            "locationType": "circle"
        }
    ]
}

Location Types

Each data set specifies a locationType property; this property defines the type of layer(s) that the framework will create to represent this data.

The following options are available for the locationType property:

• circle or point: Only available for data sources that define point locations. This option will render colored circles around each location. If the locationType field is missing, this option will be assumed.
• symbol: Only available for data sources that define point locations. This option will render pre-defined icons at each location.
• fill or polygon: Only available for fata sources that define polygons/regions. This option will render a colored, polygonal shape in each vertex corresponds to a coordinate listed in the data source.
• extrusion of building: Only available for fata sources that define polygons/regions. This option will use the additional fill-extrusion-base and fill-extrusion-height properties of each location to render a 3d extruded polygon for each location.
• line: Will generate colored lines following the set of coordinates listed for each location.