Quick Start

---

Mapsense.js is a JavaScript library for vector maps in the browser. It brings the scalability of tiled geographic datasets to the interactivity, control, and dynamism of D3. A D3 selection is maintained across incoming tiles, letting you set things like styles or interaction just once. Mapsense.js is based on the Polymaps API, but uses D3 to handle drawing and selection. Having a basic understanding of D3 will make using Mapsense.js a snap. Read these docs to learn more about Mapsense.js.

Mapsense Data is a source of vector map data for creating interactive data driven maps. Data tiles are generated dynamically in response to a tile request, letting you control precisely what features and properties are returned.

Initialization

First of all, we need to include d3.js, topojson.js and mapsense.js:

<script src="http://d3js.org/d3.v3.min.js" charset="utf-8"></script>
<script src="http://d3js.org/topojson.v1.min.js" charset="utf-8"></script>
<script src="mapsense.js" charset="utf-8"></script>

You will need to create a node in the DOM for the map to be contained in with a unique ID:

<div id="myMap"></div>

Now let's create a map and initialize it. Here we create the map with a string representing the id attribute of the DOM node which the map will be contained in, and then call .center() and .zoom() to specify the initial viewpoint of the map.

var map = mapsense.map("#myMap")
  .center({lon: -122.410886, lat: 37.787041})
  .zoom(14);

Accessing and modifying map features

One way to access individual map features in geoJson or topoJson layers before they are displayed is by using the selection() method. This method sets a function that will be called on the D3 selection representing all of the geoJson (or topoJson) data in the map. For example, to give all buildings a special class:

baseMapLayer.selection(function(d){
  d.attr("class", function(feature){
    if(feature.sub_layer == "building") {
      return "my_pretty_building";
    });

Another option for accessing and formatting map data is to specify a load event handler. The handler will be called after each tile is loaded and will be passed the tile containing the raw topology and the projection. To access or mutate the feature list for geoJson or topoJson maps use tile.features(), which either returns the feature list, or sets the feature list if passed an argument.

var layer = mapsense.topoJson().on("load", loadLayer);
...
function loadLayer(tile, projection) {
  var newFeatures = [];
  tile.features().forEach(function(feature){
    var newFeature = processFeature(feature);  // processFeature performs some mutation on feature
    newFeatures.push(newFeature);
  }
  tile.features(newFeatures);
}

geoJson and topoJson layers

To bring static geoJson data in to your map, you can use d3's json function to load a local geojson file:

d3.json("my_data.geojson", function(data){
  map.add(mapsense.geoJson()
    .features(data.features)
    .selection(function(d){
        d.attr("class", "neighborhood");
    })
  );
});

To load a remote topoJson layer, we specify the url when we create the layer.

var hurricaneUrl = "https://{S}-sample.com/hurricanes/{Z}/{X}/{Y}.topojson";
var hurricaneLayer = mapsense.topoJson().url(mapsense.url(hurricaneUrl).hosts(['a','b','c','d']));
map.add(hurricaneLayer);

Custom layers

Custom layers can be created by extending either the layer, geoJson, or topoJson classes and providing a map() function which takes the map object as an argument as well as registering any event listeners for that layer. The event listeners should call map.pan() and map.zoom() to manipulate the map view point if needed.

var myLayer = function() {
  var myLayer = mapsense.geoJson();

  var __map__ = myLayer.map;
  myLayer.map = function(m) {
    if (!arguments.length) return __map__();
    __map__(m);
    // add event listeners and do any other initialization
    window.addEventListener("mousedownCallback", mousedown, false);
  }

  return myLayer;
}
...
map.add(myLayer());