Mapv: a canvas-based library for drawing large point, line and area datasets on web maps

The problem Mapv solves: too many coordinates for a marker layer

A map with a few hundred markers is a solved problem. A map with a million GPS traces, a city's worth of taxi pickups, or a week of cell-tower pings is not. Adding one DOM element per record collapses the browser long before the data runs out, and even a vector layer that batches its draw calls starts to stutter once the feature count climbs.

Mapv's answer is to skip the per-record object entirely and paint onto a canvas. The README describes it as a library for showing large amounts of geographic information, with points, lines and areas as the three data shapes and several display types for each: direct point rendering, heatmap, grid, and clustering. The audience is therefore narrow and specific. It is for people who already have a map on the page (the examples directory is full of baidu-map and amap files) and who want to add a dense visual layer on top of it, not for people who need an interactive map component with tooltips, routing and geocoding. Mapv draws; it does not answer questions about places.

The repository is a Baidu project, maintained under the huiyan-fe organization, and the README's "who is using it" list names Baidu Huiyan, Baidu Traffic Cloud and the Baidu Maps open platform. That origin shows in the examples: most of them assume the Baidu Maps JS API is loaded first, with a smaller amap directory for AMap users.

How Mapv works: data in, canvas layers out

The mechanism visible in the repository is a rendering pipeline rather than a scene graph. You hand Mapv a dataset, which in the examples is usually an array of objects carrying a geometry and some attributes, and you pick a layer type. The library then computes whatever intermediate structure that layer needs and draws it to a canvas.

The layer types imply different intermediate structures. A heatmap layer has to accumulate density into a raster grid before it can color it. A grid or honeycomb layer has to bin coordinates into cells and aggregate a value per cell. A cluster layer has to group nearby points so that one drawn symbol stands for many records. The animation layers (the repository has examples named baidu-map-animation-layer-point and baidu-map-animation-layer-polyline) keep a time dimension so that records appear and move as the animation advances. The forceEdgeBundling example is a different kind of computation: it takes a set of edges and routes them into bundles before drawing, which is a layout problem, not a drawing problem.

Because everything lands on canvas, the output is pixels. There is no per-feature DOM node to attach an event listener to, and the README does not describe a hit-testing API. If your design needs a hover tooltip on every individual point, that is a gap you will have to fill yourself, typically by keeping the source data and doing your own spatial lookup against pointer coordinates.

The build is Rollup. package.json defines a pre step that writes the version number into build/version.js, a build step that runs rollup -c, and a mini step that pipes the bundle through uglifyjs. There is a second Rollup config, rollup.config.3d.js, and a matching index.3d.js entry, which is where the 3d-map examples come from. The published main field points at build/mapv.js.

Installing Mapv and drawing a first layer

The README gives two installation routes. If you use a bundler, install from npm; the README states that Mapv works with CommonJS bundlers such as Webpack, Browserify or fis.

npm install mapv

If you would rather not build anything, the README offers script tags pointing at prebuilt files on the project's own hosts, and points at the releases page for the last published version.

<script src="http://mapv.baidu.com/build/mapv.min.js"></script>

To work on the library itself rather than consume it, the README's development section is short. Installing dependencies is npm install; npm test is listed under development and, in package.json, test simply runs the dev script, which is a Rollup watch build. That is worth knowing before you run it: npm test does not execute a test suite, it starts a watcher.

npm install
npm test

The publishing script is npm run publish, which triggers prepublish and therefore a full build plus minification.

npm run publish

For a first real use, the honest starting point is the examples directory, not the README. Files such as examples/baidu-map-point-heatmap.html, examples/baidu-map-point-grid.html and examples/baidu-map-point-cluster.html each show a complete page: map initialization, data loading and the layer call. Open one in a browser, then change the data source and the layer type. The README's own example section is a gallery link, so the working code lives in those files. The API reference is a separate document, API.md, at the repository root.

The version story is the biggest risk

Three version numbers disagree, and a reader should notice before committing. The README says the current release is a pre-release of Mapv 2.0 and that the API is unstable and may change at any time. The release list in the repository stops at 2.0.12, dated 2017-03-21. package.json reads 2.0.62. The last push to the repository was on 2026-06-10, so work has happened since those tagged releases, but the tagged releases do not reflect it.

For an adopter this has a concrete consequence: a version pin such as 2.0.12 does not correspond to the code in master, and the code in master is the code the README describes as unstable. There is no changelog in the repository listing to bridge the two. If you need a fixed target, pin a specific build artifact or a commit hash rather than a semver range, and read API.md against the examples you plan to copy.

A second limitation is the browser target. The README states that Mapv is written with canvas and supports modern browsers, generally everything except IE8 and below. That sentence is from an era when IE8 was the floor. It tells you the library assumes canvas, but it does not tell you which canvas features, and the 3D entry point implies WebGL for those examples. Test the specific layer type you need in the specific browsers you support rather than trusting the compatibility sentence.

A third is the licence mismatch. The README carries a BSD-3-Clause text with a Baidu copyright notice and a non-endorsement clause, while package.json declares "license": "ISC". Those are different licences with different terms. The repository's LICENSE file is the authoritative text, and if the discrepancy matters to your legal review, it is a question for your own counsel, not something the README resolves.

Mapv versus deck.gl and Leaflet-based heat layers

The closest comparison in spirit is deck.gl. Both take large coordinate datasets and render them without one DOM node per record. The difference is the rendering back end and the surrounding assumptions. deck.gl is built around WebGL layers and a GPU-driven pipeline, and it is designed to sit on top of a base map through a documented layer interface. Mapv's default path is canvas 2D, with a separate 3D entry point and config for the examples that need it. For a few hundred thousand points, canvas 2D is often enough and has a smaller conceptual surface. For millions of points with continuous interaction, the GPU path is the one built for it. Mapv's 3D support exists but the repository presents it as an additional build (index.3d.js, rollup.config.3d.js) rather than the main line.

The other common alternative is not a library at all: Leaflet or OpenLayers with a heat plugin. That route gives you a mature map component with events, controls and a large plugin ecosystem, and a heat layer that handles density. It does not give you the grid, honeycomb, cluster and edge-bundling layer types that Mapv ships, and it will not help if your base map is Baidu Maps rather than a tile layer. If your base map is already Baidu or AMap, Mapv's examples match that stack directly, which is a real advantage over adapting a Leaflet plugin to a non-Leaflet map.

A third option is to do it yourself with a canvas overlay. If all you need is one heatmap and you already have a canvas layer on the map, writing the density accumulation yourself is a few hundred lines and removes a dependency whose API the README calls unstable. Mapv earns its place when you need several of its layer types and the animation layers, not when you need one.

Maintenance, upgrade cost and what the licence means for you

The repository is not archived, and the last push was on 2026-06-10. That is recent enough that the code is not frozen, but the release tags are not: the newest listed release is 2.0.12 from 2017-03-21. Anyone who tracks the project by releases will be looking at code roughly nine years older than the branch it is published from. The practical upgrade path is therefore git, not npm version ranges. Follow master, or pin a commit, and accept that the README's own warning about API instability applies to what you pull.

The dependency footprint is light, which keeps the upgrade surface small. The only runtime dependency in package.json is babel-plugin-external-helpers; everything else (Rollup, Babel presets, uglify-js) is a dev dependency used to produce the bundle. That means adopting Mapv does not drag a tree of transitive packages into your application, and the build tooling only matters if you are rebuilding the library rather than consuming build/mapv.js.

On licensing: the README's BSD-3-Clause text permits redistribution of source and binary forms provided the copyright notice, the condition list and the disclaimer are retained, and it forbids using the Baidu name to endorse derived products without permission. package.json says ISC instead. ISC is similarly permissive, so the practical difference for most consumers is small, but the two declarations are not identical and the non-endorsement clause in the README text has no counterpart in ISC. Check the LICENSE file and get your own legal read if you are redistributing Mapv inside a product that carries your branding.

Editorial conclusion

Adopt Mapv if you already draw on Baidu Maps, AMap or a plain canvas and need heatmap, grid, cluster or animation layers without pulling in a full data-visualization stack. Do not adopt it if you need a documented, stable API: the README calls the 2.0 API unstable and subject to change, and the release list stops at 2.0.12 from 2017-03-21 while package.json already reads 2.0.62, so pin a build and treat the API reference and the examples directory as the real specification before you commit to it.

Frequently asked questions

Official sources

1. huiyan-fe/mapv on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases