Map Chart

The MapChart can be used to display regions of the world in an interactive chart. Each region can be colored individually based on a data set. For example, population, temperature, etc.

// Creation of a Map Chart
const lc = lightningChart()
const mapChart = lc.Map({ type: MapTypes.Europe })

The appeal of Map chart is a simplistic and easy to use solution to display regional differences, without requiring more complicated geospatial data visualization technology, like tile servers. Map chart runs completely in frontend.

Access to LightningChart resources

The Map chart feature utilizes static file assets distributed along side LightningChart library. In order to use MapChart, setting up local hosting of LC resources is needed.

For instructions of setting up LightningChart resources, please see LightningChart resources

View

A Map chart displays a specific view of the world. The currently available options are:

• World
• Europe
• Africa
• Asia
• North America
• South America
• Australia
• USA
• Canada

const mapChart = lc.Map({ type: MapTypes.World })

Loading regions data

The main idea of Map chart is to load different data values for separate regions displayed in the chart. Most map types (world, europe, africa, asia, NA, SA) separate regions by Countries, where as USA view separates regions to States etc.

Each regions data value is a single number (population, temperature, etc.). Countries are identified using the ISO 3166-1 standard as three-letter codes (e.g. Finland = "FIN")

mapChart.invalidateRegionValues([
    { ISO_A3: 'FIN', value: 1 },    // Finland value = 1
    { ISO_A3: 'SWE', value: 2 }     // Sweden value = 2
])

Alternatively, you can use callback syntax which requests a value for every region found in the map:

mapChart.invalidateRegionValues((region, prev) => {
    console.log(region)
    return 0
})

In case of Australia, USA and Canada views, the ISO_A3 standard is not applicable. Instead, regions are identified with name property:

mapChart.invalidateRegionValues([
    { name: 'Alabama', value: 1 },
    { name: 'Alaska', value: 2 }
])

Coloring regions by data

mapChart.setFillStyle(
    new PalettedFill({
        lut: new LUT({
            interpolate: true,
            steps: [
                { value: 0, color: ColorRGBA(255, 0, 0) },
                { value: 10, color: ColorRGBA(0, 255, 0) },
                { value: 100, color: ColorRGBA(0, 0, 255) },
            ]
            // This property is used to specify fallback color for regions which have no data.
            color: ColorRGBA(255, 255, 255),
        }),
    }),
)

For more details about style API, please see Styles, colors and fonts.

Real-time data

For animated or real-time use cases, data displayed by Map chart can be easily updated during run-time as fast as needed by simply calling invalidateRegionValues method again.

Cursors

Please see common Cursors section.

Legend

Please see common Legend section.

Positioning charts

Please see common Positioning charts section.

Color themes

Please see common Color themes section.

Chart title

chart
    .setTitle('Voltage')
    .setTitleFont(font => font.setSize(10).setFamily('Segoe UI'))
    .setTitleFillStyle(new SolidFill({ color: ColorRGBA(255, 0, 0) }))

For more details about style API, please see Styles, colors and fonts.

Background style

MapChart has 2 different levels of backgrounds:

• Chart background (entire chart area)
• Engine background (additional background shared by entire engine)
  • Understanding difference between chart/engine background is mainly useful if you are using the legacy Dashboard feature - in this case, engine background is shared across the whole dashboard.

chart
    .setBackgroundFillStyle(new SolidFill({ color: ColorRGBA(255, 0, 0) }))
chart.engine.setBackgroundFillStyle(new SolidFill({ color: ColorRGBA(0, 0, 255) }))

For more details about style API, please see Styles, colors and fonts.

Space around chart

chart.setPadding({ left: 10, right: 10, top: 10, bottom: 10 })

Disable animations

const chart = lc.MapChart({ animationsEnabled: false })

Drilldown to regions

Map chart currently doesn't expose a convenient method of finding which map region was clicked or otherwise interacted with. This is in the works currently, please let us know if you use case requires it.

Overlay with XY features

A common use case is to use Map chart as a geospatial background outline (where regions are), and do actual data visualization using XY features, such as scatter charts, bubble charts, pictures or heatmaps.

This can be done by creating a Map chart and XY chart completely overlaid above each other, make the XY chart background completely transparent and then synchronize the Map charts geospatial coordinate system with the XY axes:

// Easiest way to overlay 2 charts is to use the same container DIV
const mapChart = lc.Map({ container })
const chartXY = lc.ChartXY({ container })
chartXY
    .setBackgroundFillStyle(transparentFill)
    .setSeriesBackgroundFillStyle(transparentFill)
    .setSeriesBackgroundStrokeStyle(emptyLine)
    .setPadding(0)
chartXY.engine.setBackgroundFillStyle(transparentFill)
chartXY.getDefaultAxes().forEach((axis) => axis.setTickStrategy(AxisTickStrategies.Empty).setStrokeStyle(emptyLine))
mapChart.addEventListener('viewchange', (event) => {
    const { latitudeRange, longitudeRange, margin } = event
    chartXY.getDefaultAxisX().setInterval({ start: longitudeRange.start, end: longitudeRange.end })
    chartXY.getDefaultAxisY().setInterval({ start: latitudeRange.start, end: latitudeRange.end })
})

// Now XY chart X = longitude and Y = latitude and the map chart and xy chart are aligned perfectly.
chartXY.addPointSeries().add(
    // Location of Helsinki 60.1699° N, 24.9384° E
    { x: 24.9384, y: 60.1699 }
)

Custom Map charts

If you want to display a map view that is not supported by the built-in map types, you have two options:

1. Ask us to add support for your requirement.

2. Implement a custom Map chart.

Map chart is ultimately a fairly simple feature as its really just a group of Polygons with some convenience features. LightningChart JS XY charts expose a handy feature for displaying polygons, the Polygon series. It's fairly straightforward to find coordinate data of your desired map regions and loading those into a polygon series to display any kind of geospatial regions.

A common file format available in internet is so called "GEOJSON", which is easy to parse in JavaScript (since its really just JSON). And the best thing is this file is just a list of polygons and their coordinates with some extra metadata.

Below you can find a reference snippet of a functioning minimal code that reads in a .geojson file and displays its polygons using LightningChart polygon series.

const polygonSeries = chart
    .addPolygonSeries()
    .setDefaultStyle((figure) =>
        figure.setStrokeStyle(new SolidLine({ thickness: 1, fillStyle: new SolidFill({ color: ColorRGBA(0, 0, 0) }) })),
    )

fetch('japan.geojson')
    .then((r) => r.json())
    .then((geojson: GeojsonFeatureCollection) => {
        geojson.features.forEach((feature) => {
            feature.geometry.coordinates.forEach((polygons) => {
                polygons.forEach((polygonCoordinates) => {
                    // polygonCoordinates: [number, number][]
                    // PolygonFigure expects: { x: number, y: number }[]
                    const polygonCoordinatesXY = polygonCoordinates.map((tupleXY) => ({ x: tupleXY[0], y: tupleXY[1] }))
                    const polygonFigure = polygonSeries.add(polygonCoordinatesXY)
                })
            })
        })
    })

interface GeojsonFeatureCollection {
    features: Array<{
        geometry: {
            coordinates: Array<Array<[number, number][]>>
        }
    }>
}