Generate and host your own raster tiles customized with Mapbox Studio

If you have never saw maps hosted in Mapbox platform you would probably agree on the quality of its designs. The business of Mapbox is to host and server geospatial data. For this reason, all the great tools Mapbox facilitates are oriented to help their users to prepare and work with their data.

One of the provided tools is Mapbox Studio. Mapbox Studio (MbS) is a desktop application that allows to create CartoCSS themes that are later used to generate raster tiles. Briefly explained, what MbS does is to download OpenStreetMap data in vector format and render it on the fly applying the specified CartoCSS style.

The result of working with MbS is not a set of tiles but a style, that is, a set of rules that express which colour must be used to render roads, at which levels must labels appears and with which size, which colour must be used for ground, etc. This style can be later uploaded to Mapbox platform so that raster tiles were generated on the cloud and we can consume the tiles paying for the service. (Hope one day I can contract their services, they deserve by their great job).

The question we can make us is: how we can generate the raster tiles locally from a given MbS style?

Well, this article is about that. Continue reading.

Working with Mapbox Studio and create your custom style

Let’s start from the beginning so download Mapbox Studio application and install on your system. Once installed execute it and you will be asked to be connected to the Mapbox platform.

There are two main reasons why Mapbox requires you to register as a user. First, the power of the platform is on the cloud and the goal is you upload all your data to the servers. That includes the styles you create.

Second, MbS retrieves data in vector format from Mapbox servers. When you register as a user you get an API token that identifies your requests. Each time MbS makes a request to extract data it has your token that identifies you as user. This way Mapbox can control if any user is making a bad usage of their platform.
Screen Shot 2015-07-25 at 23.43.26

Once logged in you will be allowed to create new map styles. The easiest way is to start using one of the starter styles created by the great Mapbox designers:

Screen Shot 2015-07-25 at 23.47.38

Here we have chose the Mapbox Outdoors style. In the image you can see the style code (CartoCSS which is inspered by CSS) and the resultant tiles obtaining from painting the vector information with the given style rules:

CartoCSS is a Mapnik stylesheet pre-processor developed by MapBox and inspired by Cascadenik. It is like a CSS language specially developed to style maps.

Screen Shot 2015-07-25 at 23.54.20

Store the style with a new name somewhere on your computer, for example, customstyle. If you look at your disk you will see a customstyle.tm2 folder has been created containing a bunch of files that defines the style rules (take a look they are not dangerous).

Finally, modify some properties, for example @land or @crop colors and save to see the result:

Screen Shot 2015-07-25 at 23.54.47

Great !!! You just have created your first custom style.

Generating raster tiles from MbS style

Looking for a solution I discovered the tessera and tl tools. Tessera is a node based command line application. It is based in some modules from mapbox (concretely tilelive) plus others implemented by the author (Seth Fitzsimmons). The result is we can execute tessera passing a MbS defined style, open a browser pointing to a local address and see a map with the raster tiles generated with our MbS style.

Similarly, tl is a node based command line tool we can execute, passing a set of options, to generate a MBTiles file or a pyramid of tiles following the well known z/x/y.png format.

I know about both tools at the article Converting Mapbox Studio Vector Tiles to Rasters from Azavea Labs.

How to install the tools?

NOTE: You need to have NodeJS installed in your system, along with the npm package manager command line tools.

I don’t like to install global node packages (or at least more than the necessary) so I’m going to install the previous tools in a custom folder:

Inside the directory execute next sentence, which install the tessera and tl packages among others:

You will see a hidden directory named .npm_modules has been created which contains some subdirectories with the same name as the previous packages.

Running tessera

Let’s try to run tessera for the first time. Because it is installed as a local node module execute:

Tessera requires you pass an URI so it can server its content. It accepts URIs from Mapbox hosted file, Mapnik, Tilemill, Mapbox Studio, …

Repeat again indicating the path to our previously created style indicating the protocol tmstyle://.

First seems tessera is working at port 8080 but later we get an error about MAPBOX_ACCESS_TOKEN. If you remember from the first section, Mapbox requires all the requests be signed with the user token. So, you need to get the access token from your account and set it as environment variable before execute tessera:

We are close to make it work. The problem now is our MbS style is using a font we have not installed in our system. One easy, but brute force, solution is to install all Google Web Fonts on your system. For this purpose you can use the Web Font Load installation script. In my case I have installed them in the user’s fonts folder ~/Library/Fonts.

Once fonts were installed try executing tessera again:

That’ s a bit strange, we have just installed the fonts but they are not found. What is happening? Well, tessera uses mapnik to create the raster tiles and it looks for fonts in the folders specified by the environment variable MAPNIK_FONT_PATH, so let define the variable:

and execute the script again:

OMG !!! This seems a never ending story. Now we need to install the Arial Unicode font. Look for it, install in your system and execute tessera again:

Great !!! It seems tessera is working fine. Let’s go to open our browser pointing to http://localhost:8080 and see the result:

A map implemented using Leaflet web mapping library is shown, rendering raster tiles that are created in the fly. Look at the console to see the tessera output information:

We can see how tiles at current zoom, the zoom level 8, has been generated.

At this point we have tessera working but what about generate a local pyramid of tiles for a given zoom levels and a given bounding box?

Generating a custom pyramid of tiles with tl command line tool

Before continue we need to know which bounding box we want to generate, the whole World? or only a piece. In my case I want three zoom levels (7, 8 and 9) wrapping Catalonia.

There are some online tools you can use to get the bbox of a region, but one I like it the Bounding Box Tool from Klokan Technologies.

The tl tool can run three main commands but are only interested in the copy one, which copies data between two providers. In our case the MbS style is one provider and the file system is the other. Run the tl command to see the available options:

So let’s go to execute the command to copy data from our MbS style to the local tiles folder. We want to generate tiles from zoom level 7 to 9 and indicating a bounding box wrapping Catalonia.

Remember the -b options must be indicated as [minLon minLat maxLon maxLat].

Ough !!! That hurts, a segmentation fault. After looking for a while I realised it seems a bug. To solve it go to tl/node_modules/abaculus/node_modules and remove the mapnik folder dependency. It is redundant because there is one installed in parent folder.

Execute the command again and see the output:

The tl tool has created a local tiles directory and generated all the raster tiles for the given zoom levels and bounding box. The output shows in addition the time required to generate each tile.

That’s all. Now we only need to host the tiles at our own servers !!!


Related Posts:

Randomatic, to generate random sequences

This is my own implementation of a tool to generate random character sequences: Ranomatic !!!

  • Allow uppercase, lowercase letters, numbers and other non ASCII characters
  • Easy to use
  • Mobile ready

Related Posts:

Architexa product review

Architexa product is an Eclipse plugin from company. As their web site say:

Architexa helps you understand and document large/complex Java code bases within Eclipse

and allowing to create and explore diagrams that make sense.

I have tried it really little but the conclusions are clear: Architexa is a tool with a great potential.


Installing Architexa is really easy because it is prepared as any other Eclipse plugin (see the install section).

I’m using Eclipse 4.2 (Juno) and the steps were:

  • Go to Help > Install new software and add a new place called architexa with the URL:
  • Select the Architexa plugin and click next button until installation is done.

Really easy, don’t you?

After Eclipse restarts you will be asked for a valid Architexa user. Go to the registration page and register for a free license. That’s all.

Exploring a project

To test Architexa I have opened a relatively small maven project, which allows to download files from an FTP server. It haven’t a great domain model neither thousand of classes but has all the necessary to test the basic Architexa capabilities.

  • Layered diagrams
  • Class diagrams
  • Sequence diagrams

The bad

Before to continue, I must say Architexa seems to me a product with a great potential, but on the other hand it leaves me with bad feelings.

I prefer to comment all the bad things first so the good things comes later and the reader was left with a good feeling.

  • The Architexta web site is IMO horrible and much more the personal area of each user ( In addition it seems not much stable, at least for me the profile and setting sections fails with a 500 server error.
  • Once Architexa is installed it needs to build an index from your code. Initially I don’t built the index (when the tool ask me to do it) and after importing the project and building it by hand, it seems not work properly. For some reason my index was corrupted and I need to remove and import the project a couple of times before it woks.
  • The layered, class and sequence diagrams are powerful tools but the way to explore and navigate could be a bit more intuitive. In addition the shapes and colors used could be improved.

As you can see the bad things are almost all related to design and visual aspects, not to the product functionality. Nothing a good web designer can solve.

My opinion for Architexa guys is: Architexa is a great product so make it looks like a great product.

Working with the diagrams

Because the project is a small the most useful diagrams has been the class and sequence diagrams.

In the case of class diagram I added some classes related to the task to download and read radar files. Once a class is added to the diagram you can make actions like:

  • select which methods can be visible in the diagram
  • navigate from a method to other classes (show called method)
  • show which classes references a method (show calling method)

Thanks to this actions you can explore the classes and its dependencies in both directions.

The sequence diagram works in a similar way, you start adding a class or method and, for example, given a method add all the used methods from the same class or from other classes:

Finally, in the layered diagram I have added some classes to see its dependencies. Easily we can see the classes and the packages they belong to.

In addition, on any diagram you can select a class or method and navigate directly to the source code to see the corresponding lines of code.


As I commented previously Architexa is a tool with a great potential. It can help team members to understand better how code works or documenting processes.

As a future features I would like to suggest its integration with the debugger. First the possibility to highlight the current executed method on the class or sequence diagram. Second, the possibility to allow to create a diagram step by step while debugging, that is, selecting which methods or classes we want to add to the sequence diagram while advancing step by step in the code.

Congratulations to the Architexa team for their product !!!

Related Posts:

Creating static maps in OpenLayers using PhantomJS

Many times in a web mapping application it is desired to save a picture with the current map information.

Those who works with Google Maps API has also the Static Maps API, which works similarly than Google Maps but produces static images. For example, next call:

produces the image:

Unfortunately, using libraries other than Google Maps, like OpenLayers or Leaflet, there is no similar solution. Probably the best, simple and powerful one, is to install a plugin on your browser to take screenshots. But well.. I think that does not deserve to write a post :p

How to render a web page element to an image?

After writing my last post (Taking Web Page Screenshots), where I show to to take a screenshot of a whole page, I was thinking on using PhantomJS to render only a portion of a page to an image.

The PhantomJS’s WebPage object has a clipRect property which determines the portion of the web page that must be rendered. With this in mind we can see a solution could be:

  • Get the bounding rectangle of the desired DOM element to be rasterized.
  • Set the clipRect property
  • Render the page to a file.

For that purpose I have prepared a little JavaScript application to run with PhantomJS. Its usage is as follows:

For example, the next execution against the demo of Animated Cluster Strategy for OpenLayers selecting the first map:

Produces the image:

Next is the whole code of the program (called rasterize_element.js and based on the rasterize.js application attached on the PhantomJS package):

Note: The code is accesible at GitHub:Gist.

Alternatives and references

Of course I’m not the first one that has explore this issue. A nice snippet from n1k0 can be found at GitHub:Gist. It does more or less the same as the code shown in this post.

Another alternative is the use of CasperJS. As its home page says:

CasperJS is an open source navigation scripting & testing utility written in Javascript and based on PhantomJS — the scriptable headless WebKit engine. It eases the process of defining a full navigation scenario and provides useful high-level functions, methods & syntactic sugar for doing common tasks such as:

With CasperJS capturing a page element is as easy as:

Related Posts: