ckanext-versioned-tiledmap

A CKAN extension with a map view for versioned-datastore backed resources.

Overview

A CKAN plugin with a map view for versioned-datastore backed resources allowing for map visualizations of large resources with millions of data points.

This repository is a fork* of ckanext-map.

*you can't fork repositories within the same organisation, so this repository is a duplicate of ckanext-map.

Installation

Path variables used below: - $INSTALL_FOLDER (i.e. where CKAN is installed), e.g. /usr/lib/ckan/default - $CONFIG_FILE, e.g. /etc/ckan/default/development.ini

Pre-install setup

This extension depends on the following projects, which must be installed first: - versioned-datastore-tile-server

Installing from PyPI

shell pip install ckanext-versioned-tiledmap

Installing from source

1. Clone the repository into the src folder: shell cd $INSTALL_FOLDER/src git clone https://github.com/NaturalHistoryMuseum/ckanext-versioned-tiledmap.git

2. Activate the virtual env: shell . $INSTALL_FOLDER/bin/activate

3. Install via pip: shell pip install $INSTALL_FOLDER/src/ckanext-versioned-tiledmap

Installing in editable mode

Installing from a pyproject.toml in editable mode (i.e. pip install -e) requires setuptools>=64; however, CKAN 2.9 requires setuptools==44.1.0. See our CKAN fork for a version of v2.9 that uses an updated setuptools if this functionality is something you need.

Post-install setup

1. Add 'versionedtiledmap' to the list of plugins in your `$CONFIGFILE: ini ckan.plugins = ... versioned_tiledmap `

2. Install lessc globally: shell npm install -g "less@~4.1"

3. Add latitude and longitude fields for the resources you want to use this view for.

Configuration

These are the options that can be specified in your .ini config file.

| Name | Description | Default | |---------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------| | versioned_tilemap.tile_layer.url | The URL to use for the base world tiles | https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png | | versioned_tilemap.tile_layer.attribution | The attribution text to show for this layer (can be HTML) | Base tiles provided by OpenStreetMap. <a href="openstreetmap.org/copyright">View copyright information</a> | | versioned_tilemap.tile_layer.opacity | The opacity for the tile layer | 0.8 | | versioned_tilemap.zoom_bounds.min | Minimum zoom level for initial display of the resource's data | 3 | | versioned_tilemap.zoom_bounds.max | Maximum zoom level for initial display of the resource's data | 18 | | versioned_tilemap.style.plot.point_radius | The integer radius of the rendered points (including the border) | 4 | | versioned_tilemap.style.plot.point_colour | The hex value to render the points in | #ee0000 | | versioned_tilemap.style.plot.border_width | The integer border width of the rendered points | 1 | | versioned_tilemap.style.plot.border_colour | The hex value to render the borders of the points in | #ffffff | | versioned_tilemap.style.plot.grid_resolution | The integer size of the cells in the grid that each tile is split into for the UTFGrid. The default of 4 produces a 64x64 grid within each tile | 4 | | versioned_tilemap.style.gridded.cold_colour | The hex value to be used to render the points with the lowest counts | #f4f11a | | versioned_tilemap.style.gridded.hot_colour | The hex value to be used to render the points with the highest counts | #f02323 | | versioned_tilemap.style.gridded.range_size | This many colours will be used to render the points dependant on their counts | 12 | | versioned_tilemap.style.gridded.resize_factor | A resize value to use when smoothing the tile. This value will be used to scale the tile and then down (with anti-aliasing) to produce a smoother output. Increasing this value will negatively impact performance | 4 | | versioned_tilemap.style.gridded.grid_resolution | The integer size of the cells in the grid that each tile is split into. The default of 8 produces a 32x32 grid within each tile and therefore matches the default grid.json setting too | 8 | | versioned_tilemap.style.heatmap.point_radius | The integer radius of the rendered points (including the border) | 8 | | versioned_tilemap.style.heatmap.cold_colour | The hex value to be used to render the points with the lowest counts | #0000ee | | versioned_tilemap.style.heatmap.hot_colour | The hex value to be used to render the points with the highest counts | #ee0000 | | versioned_tilemap.style.heatmap.intensity | The decimal intensity (between 0 and 1) to render the tile with | 0.5 | | versioned_tilemap.info_template | The name of the template to use when a point is clicked | point_detail | | versioned_tilemap.quick_info_template | The name of the template to use when a point is hovered over | point_detail_hover |

Usage

After enabling this extension in the list of plugins, the Map view should become available for resources with latitude and longitude values.

Testing

There is a Docker compose configuration available in this repository to make it easier to run tests. The ckan image uses the Dockerfile in the docker/ folder.

To run the tests against ckan 2.9.x on Python3:

1. Build the required images: shell docker compose build

2. Then run the tests. The root of the repository is mounted into the ckan container as a volume by the Docker compose configuration, so you should only need to rebuild the ckan image if you change the extension's dependencies. shell docker compose run ckan