Map (Offline)

This page describes the offline Map component and how it can be set up and configured to create visually appealing, engaging, and performant geographic maps.

This component utilizes WebGL technologies, enabling Maps to render quickly and smoothly which is highly beneficial when working with large datasets. The benefit of using this Map component over the standard Map (External API) component is that you do not need to have external access to the internet or external APIs.

There is a wide range of customizations available for the Map including adjusting styles, colors, fonts, adding custom icons and interactive layers (including Points, Circles, Lines, Animated Points, Heatmaps, and customizable Layers).

The following screenshot illustrates a sample Map with defined circles.

The Map has features that enable you to:

• Visualize and animate geographic data

• Visualize streaming and moving data geographically

• Display and interact with large quantities of data on a map

• Query and filter map features

• Dynamically display and style custom client-side data on a map

• Programmatically add points, circles, lines, and popups to maps

• Annotate polygons and lines on geographic data and store annotated points in view states for use in other components

• Overlay multiple layers of data on top of each other

The following sections describe how to configure the properties of the Map component.

Set up an offline Map

To set up an offline Map component, click-and-drag the component into the workspace and configure the following:

Refer to Offline Map properties described in the next section for details on additional properties.

Offline Map properties

The following sections provides details on how to configure the properties of the Offline Map component.

Basics

Open the Basics properties on the right and configure the properties described in the following table.

Map

Configure the properties, described in the following table

The Map properties allow you to configure the zoom setting for the map when it loads latitude and longitude coordinates and the style of the map.

Points

Use the Points properties to configure a custom point image at a specific geographic coordinate, with an option to add clustering. The following screenshot shows an Map with clustering.

Configure the Points Layer properties, described in the following table.

The Point properties illustrated in the screenshot are described in the table below.

Selected

The Selected properties, relating to the Points you have configured, are shown in the screenshot and described below.

Actions

Click here to read more about Actions.

Icon Scale Interpolate

Icon scale interpolation means that, instead of smoothly scaling or transitioning point styles (size, color, opacity) as you continuously zoom, the map holds each property constant until you hit the next defined zoom stop, then jumps to the new value. 

The Icon Scale Interpolate properties, relating to the Points you have configured, are shown in the screenshot and described below.

Circles

You can configure custom circles with clustering as illustrated in the following screenshot.

Configure the properties, described in the following table.

The Circle Layer properties shown in the screenshot are described below.

Selected

The Selected properties, shown in the following screenshot, are described below.

Actions

Refer to Actions for details.

Lines

The Lines properties enable you to configure lines with customizable styling, as illustrated in the screenshot.

The Line Layer properties are described in the following table.

Colors

Point

Actions

Refer to Actions for details.

Concentric Circles

The Concentric Circles properties enable you to add concentric circles layers to maps, helping you with:

• Visualizing Range: Showing coverage areas, like cell tower range.

• Data Analysis: Segment areas for demographic or environmental studies.

• Navigation: Indicate distances for logistics and emergency planning.

• Comparative Studies: Compare impacts at different distances.

• Interactive Maps: Enhance user engagement with dynamic information.

You can specify a latitude and longitude to set the center of the first circle at that location. The radius of the first circle can be defined based on a distance from this center point, such as a 50KM radius. Subsequent circles can either be drawn from the edge of the first circle or independently, each with its own specified radius and center point.

The Concentric Circles properties, shown in the screenshot, are described in the table below.

Sample data source

The following example shows concentric circles over Irish airports and uses the data source shown in the code snippet below.

([]
        id:(1 2);
        location:(`Dublin`Cork);
        distance:( (25 50 100);(25 50 75));
        colors:(("#FF0000";"#FFA500";"#00FF00");("#FF0000";"#FFA500";"#00FF00"));
        latitude:( 53.2528 51.8491);
        longitude:(-6.2574 -8.4899)
        )
                    

Heatmap

Heatmaps show the density of points over an area by displaying a continuous gradient between points.

As well as being useful for visualizing point density, heatmaps also help you to visualize relative differences between those points. The following screenshot shows an example of a heatmap.

Configure the properties described in the following table.

The Heatmap properties, shown in the screenshot, are described below.

Colors

These settings, shown below, specify the gradient colors used in the Heatmap.

Actions

Refer to Actions for details.

Heatmap Grid

The Heatmap Grid feature in KX Dashboards allows you to visually represent large datasets using color gradients, making it easier to identify patterns, trends, and outliers. Each grid cell corresponds to a data point, with colors indicating values, enabling you to quickly assess variations across the data. This feature is highly effective for data analysis, providing an intuitive way to interpret complex information at a glance.

Configure the properties described in the following table.

Colors

These settings, shown below, specify the gradient colors used in the Heatmap.

Actions

Refer to Actions for details.

Bounds

These properties are described in the following table.

Annotation

The Annotation properties, shown below, enable you to add annotations to the map using lines or polygon shapes.

Animated Circles

These properties enable you to configure customized animated circles on your map, as illustrated below.

Configure the properties described in the following table.

The Animated Circles properties, shown in the screenshot, are described below.

Actions

Click here to read about Actions..

Icons

These properties present a list of icons that have been added to the css\assets\images folder on the server. These icons, shown in the following screenshot, can be used by the Icon property in the Points properties. Click + Icon to add more icons.

Night/Day Layer

These properties enable you to add a layer to determine the region of day and night time based on a current date/time value, as illustrated below.

The properties are described below.

Style

You can use the Style properties, shown below, to override the default colors used in the map component.

3D Models

With the 3D Models in map, you can see 3D models when you zoon into the data property, as illustrated in the screenshot below.

Configure set the 3D Models properties described in the table below.

Tile Server

Integrating a custom-styled tile server with Maps in KX Dashboards allows you to load and display dynamic, custom-designed map layers. This integration provides full control over the map's appearance, enabling you to apply unique styling and visual elements to geographic data. By leveraging vector tiles from external servers, you can create highly customizable, interactive maps tailored to your specific needs, enhancing the overall data visualization experience in KX Dashboards. The following illustrates a map using custom tile server.

Configure the properties described in the following table.

Refer to Tile Server Installation and Setup for detailed instructions on working with Tile Server.

External API

This Map component can also be used online, if needed, which enables you to set external APIs.

External APIs refer to external services that provide mapping data and functionalities.

You can set the properties described in the following table.

Layers

The Layers properties, shown below, enable you to add the following types of layers on to your map.

• Data Layers

• Media Layers

• Hosted Layers

• Simple Layers

Data Layers

A Data layer combines GeoJSON geometric coordinates with kdb+ data. You can draw regions on the map based on GeoJSON coordinates and then map kdb+ data to each of these regions to create insightful visualizations. This enhances your ability to derive meaningful insights from complex geographic and tabular datasets. The following example shows unemployment rate data across US states. Values are highlighted in color gradient from highest (bright red) to lowest (bright green).

Configure the properties described in the following table.

The Data Layers properties, shown in the screenshot, are described below.

Color Palette

Actions

Click here to read about Actions.

Media Layers

A media layer allows you to add a geo-referenced video or image on top of a map layer, as illustrated in the following screenshot.

Configure the Media Layer properties described in the following table. Click the trash can icon to delete a layer.

Hosted Layers

You can add a hosted GeoJSON layer to your maps. Each layer provides rules about how the renderer must draw certain data in the browser and the renderer uses these layers to draw the map on the screen, as illustrated below.

Configure the Hosted Layer properties described in the following table. Click the trash can icon to delete a layer.

Simple Layers

You can add a text based GeoJSON layer to the maps. Each layer provides rules about how the renderer draws certain data in the browser and the renderer uses these layers to draw the map on the screen. An example of a text file converted to GeoJSON is shown below.

Configure the Simple Layer properties described in the following table.

Margins

Refer to Margins for details.

Format

Refer to Format for details.

Drawing a line

This section describes how to draw a line on a map to calculate the distance between 2 or more spots. Once the line is drawn, the distance (in kilometers) is shown in a popup. An example of this is illustrated in the following screenshot.

To draw a line annotation on an Map:

1. In the annotation control, on the right-hand side of the map, click on the line icon.

2. Select the starting point on the map by using a left or right mouse click.

3. You can click at any other point on the map to connect this line.

4. The line is displayed as a yellow dashed line while editing.

5. Once you are finished editing you can click on the line. This sets the line to blue.

To delete a line from an Map:

1. Select the line and click on the trash icon in the annotations properties, on the left-hand side of the map.

Drawing a polygon

This section describes how to draw a polygon on an Map by selecting a set of points/circles. This is illustrated in the following screenshot.

To draw a polygon on an Map:

1. In Preview mode, click on the polygon icon in the annotation controls, on the right-hand side of the map.

2. Click on the map where you want to start the polygon and then click on multiple sections of the map to connect the polygon points.

3. The polygon is displayed as a yellow dashed line while editing.

4. Once you are finished editing, you can click on the line. This sets the polygon to blue.

To delete a polygon:

1. Select the polygon and click on the trash icon in the annotations menu.

Tile Server Installation

KX Dashboards uses tileserver-GL , a self-hosted map tile serv er for use whe n leveraging web-based maps and online map tilers are unavailable to be used in offline use cases and air gapped environments.

Prerequisites

• Latest Version of KX Dashboards 2.2.5 or greater or KX platform build 4.9.2 or greater

• Node JS 18.17.0 or greater

• https://github.com/maptiler/tileserver-gl

Operating systems

• Windows (x64) or greater

• Ubuntu 22.04 or greater

• macOS 14 (x64/arm64) or greater

Getting Started

Install from npm, to the directory which you wish to install to.

Choose from one of the following options:

Option 1: Install globally from npmjs

npm install -g tileserver-gl

Option 2: Install locally from source

git clone https://github.com/maptiler/tileserver-gl.git
    cd tileserver-gl
    npm install

Map Data

To render data offline, an mbtiles file is required for the area of interest. While there are many ways to acquire and create mbtiles files, it is recommended that you use the mbtiles files here: https://osm.dbtc.link/mbtiles/

Adding Map Data and Styles

Once the OpenStreetMap (OSM) data is downloaded, this needs to be copied to the same directory as the tileserver-gl install (along with the accompanying config.json file, if present).

The following URL can be used to obtain a set of sample fonts and files for the tile server:

https://github.com/maptiler/tileserver-gl/releases/download/v1.3.0/test_data.zip

From the test_data.zip file, the styles and fonts directories should be copied to the tileserver-gl installation folder.

The tileserver-gl directory structure should therefore look similar to this:

Inside the styles folder, the following styles are provided: osm-bright and klokantech-basic.

Before you start the tile server

Tileserver-gl defaults to port 8080, therefore it is important to assign a new port config when starting the tileserver-gl, to target a different port as your KX Install will likely conflict with this port assignment.

It is recommended to use port 8082, which was tested abd working.

For longer term use, it is recommended that the user write a startup script for ease of deployment, KX is not responsible for providing this.

Start up code below:

tileserver-gl 2024-06-25-planet.mbtiles -p 8082

KX Dashboards Tile server Integration

• Drag the Map component onto the canvas.  

• In the Tile Server property section, check Enable.

• The Style can be specified in one of two ways: Using a URL Using the Editor

Set the style using URL

1. Check Set Style using a URL .

2. Using a browser, navigate to the host and port for the Tile Server. Right click the link for the chosen Style and copy the link to the clipboard.

3. Paste the URL into the Style URL property in KX Dashboards

4. Save and r eload/ refresh the page.

Set the style using Editor

1. Uncheck Set Style using a URL.

2. Using a browser, navigate to the host and port for the Tile Server. Click the link for the chosen s tyle and copy the contents to the clipboard.

3. Paste the contents into the Style Editor property.

4. Save and r eload/ r efresh the page.

Further Reading

• Navigate Dashboards workspace

• Configure data source connections

• Use view states

• Publish & Export a dashboard