Generating Map Tiles

Introduction

QCAD comes with two command line tools to create map tiles for use with online map displays such as Leaflet. Leaflet is a JavaScript library to work with interactive maps in a browser.

Presenting a Drawing Online

The simplest use case for an online map is to provide visitors of a web site with an interactive, zoomable view of a drawing.

Here’s an example that generates the map tiles for any given drawing file:

dwg2maptiles -z 0-6 -c -b white -hq-postfix=@2x -a -o path/to/output/directory drawing.dxf

The -z switch specifies the zoom levels to generate, here from zoom level 0 to zoom level 6. This means that starting from level 0 (whole drawing of auto zoom), the user can zoom in 6 times until the limit is reached. Each time the user zooms in, the drawing is enlarged by a factor of 2, so with 6 zoom levels, the user can zoom in by a factor of 2^6 (=64). Generating more zoom levels requires more time and disk space. Each additional zoom level typically requiring four times more time and disk space to generate than the previous one.

The tiles are generated in the given output directory (-o) with the standard directory structure and file names for map tiles (z/x/y.png).

In the above example, we want the drawing to be rendered on a white background (-b white). White lines should be corrected to black to make sure all lines are visible (-c).

The -hq-postfix=@2x argument tells dwg2maptiles to generate high-quality (hq, high-res, retina) tiles at 512x512px along with the standard resolution tiles at 256x256px.

To further increase quality, we also use the -a switch for antialiasing.

View example with Leaflet online

Generating Georeferenced Map Tiles

dwg2maptiles can also be used to generate exact overlays for world maps. For this, a drawing usually has to be transformed from a local coordinate system into Web Mercator coordinates as commonly used by online maps.

QCAD Professional comes with a separate command line tool to transform drawings from one coordinate reference system (CRS) to another: dwgmapconvert.

dwgmapconvert is typically used to convert all coordinates in a given drawing file from a known, local coordinate system to the EPSG:3857 (sometimes called “Web Mercator”) coordinate system. This is the coordinate system used by most online maps, for example Google maps or mapbox. To use a drawing as input for dwg2maptiles and produce georeferenced map tiles, the drawing needs to be in the EPSG:3857 coordinate system.

In the EPSG:3857 coordinate system the whole world map fits into a 20037508.3427892m square at zoom level 0. If a drawing is converted into this coordinate system, the drawing is transformed in such a way that it fits into that world square and that the drawing is located at the correct, projected world coordinates.

For example, if a drawing was created in EPSG:2056 (also LV95, the local Swiss coordinate system), it can be transformed to EPSG:3857 with dwgmapconvert as follows:

dwgmapconvert -segment-length=0.5 -crs-in=EPSG:2056 -crs-out=EPSG:3857 -f -o drawing_epsg3857.dxf drawing_epsg2056.dxf

Since map projections are usually non-linear, curves and longer lines need to be split up into small line segments which can then be projected in a non-linear way. If the switch -segment-length is provided, dwgmapconvert does this segmentation automatically, using the given segment length. The segment length is specified in drawing units of the original drawing (here Meter).

-crs-in is used to specify the input coordinate system, here EPSG:2056.

-crs-out is used to specify the output coordinate system which must be EPSG:3857 if the output should later be used with dwg2maptiles.

dwgmapconvert comes with support for LV95 as input and WebMercator as output.

Other coordinate systems will be added in future releases or can be added by the user.

To add support for a new coordinate system, two equations must be provided to convert the coordinates from the new coordinate system to WGS84 (Longitude/Latitude, like GPS coordinates).

New coordinate systems can be added to a JSON configuration file called CRS.json, located in the “scripts” folder of the QCAD installation that is used. Here’s an example CRS.json file that configures the coordinate system LV95. To be able to use LV95 as input for the dwgmapconvert tool, we need to provide the “toWgs84” section with equations for the x and y coordinate conversion. Here, we also use two auxiliary variables, x_ and y_ which must be initialised in the x equation in order to be accessible in both equations.

We could also provide a “fromWgs84” section to allow conversion from other coordinate systems into LV95. Both sections are optional, depending on the conversion direction you want to support.

{
  "CRS" : [
    {
      "id" : "EPSG:2056 CH1903+ / LV95",
      "toWgs84" : {
        "x": "x_ = (y-1200000)/1000000; y_ = (x-2600000)/1000000; (2.6779094 + 4.728982*y_ + 0.791484*y_*x_ + 0.1306*y_*x_*x_ - 0.0436*y_*y_*y_) * 100 / 3",
        "y": "(16.9023892 + 3.238272*x_ - 0.270978*y_*y_ - 0.002528*x_*x_ - 0.0447*y_*y_*x_ - 0.0140*x_*x_*x_) * 100 / 36"
      },
      "aliases" : [ "LV95", "Swiss" ]
    }
  ]
}

Generating Map Tiles

Once we have converted the drawing to EPSG:3857 coordinates, we can use dwg2maptiles to generate the tiles for the overlay layer in leaflet:

dwg2maptiles -web-mercator -skip-empty -hq-postfix=@2x -z 22 -b transparent -o path/to/output/directory drawing_epsg3857.dxf

Note that we need to pass the -web-mercator switch to dwg2maptiles to let it know that it should not perform an auto zoom but generate a map overlay in exact EPSG:3857 coordinates as present in the file.

-skip-empty tells dwg2maptiles to not generate tiles that don’t contain any part of the drawing. Without this switch, 2^zoomLevel tiles will be generated per zoom level. That would be 4’194’304 tiles for zoom level 22. Since an overlay drawing very likely only covers a very small part of the world map, this switch should always be used when creating overlay maps.

-b transparent sets the background to transparent, so the map can be used as an overlay for an existing world map (e.g. Google Map, mapbox, etc.). To control the color in which black or white lines are displayed, the background can be set to black transparent or white transparent with -b "#00ffffff" (white transparent background, black lines) or -b "#00000000" (black transparent background, white lines) respectively. Be sure to also pass the -c switch in this case to force automatic color correction.

The argument -hq-postfix=@2x can be used to generate high-res tiles (512px) in addition to the normal 256px tiles. The value “@2x” is recommended and widely used for high-res tiles, also in leaflet. With this switch, for every low-res tile “N.png”, a high-res tile “[email protected]” is created.

Using Multiple Processes (and CPU Cores)

Generating map tiles can be a CPU intensive task, depending on zoom levels, drawing complexity and other settings.

To generate map tiles faster, you can divide the job among multiple available CPU cores. For this feature, dwg2maptiles offers the -s switch to generate only a slice of the required tiles. The -s switch expects two comma-separated parameters: the slice to generate and the total number of slices used. For example -s 1,4 would generate the first slice of four slices in total. To generate all tiles of the above example using four CPU cores, you could run:

dwg2maptiles -web-mercator -skip-empty -hq-postfix=@2x -z 22 -s 1,4 -b transparent -o path/to/output/directory drawing_epsg3857.dxf &
dwg2maptiles -web-mercator -skip-empty -hq-postfix=@2x -z 22 -s 2,4 -b transparent -o path/to/output/directory drawing_epsg3857.dxf &
dwg2maptiles -web-mercator -skip-empty -hq-postfix=@2x -z 22 -s 3,4 -b transparent -o path/to/output/directory drawing_epsg3857.dxf &
dwg2maptiles -web-mercator -skip-empty -hq-postfix=@2x -z 22 -s 4,4 -b transparent -o path/to/output/directory drawing_epsg3857.dxf &
wait

Of course you could also divide tasks by zoom levels or use slices for higher zoom levels only and a single process for all the lower (cheaper) zoom levels, etc.

Example

An interactive example provides two overlay layers to the map of the Swiss canton of Zurich: the protected forest area and the wildlife corridors. The original data came in EPSG:2056 (LV95) coordinates and was transformed to EPSG:3857 using dwgmapconvert.

View example with Leaflet online