Table of Contents
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.
Here's the result of such an interactive drawing display generated with dwg2maptiles:
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.
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 "N@2x.png" 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
In this example, we provide two overlay layers to the map of the Swiss canton of Zurich: the protected forrest area and the wildlife corridors. The original data came in EPSG:2056 (LV95) coordinates and was transformed to EPSG:3857 using dwgmapconvert.