# NagVis Worldmap

## Introduction

The NagVis Worldmap was introduced in NagVis 1.9. It has been developed to make it possible to create modern and interactive geographical maps.

You can put any kind of NagVis object on a worldmap which is then rendered using Open Street Map.

The most significant different to classic maps is that the single worldmaps don't have a dedicated set of map objects. In fact a worldmap is mainly the definition of a viewport (visible area, zoom) on the world. Each object you position on a worldmap is saved globally across all your worldmaps. This means if you add an object to a worldmap on a high zoom (detail level), the object is also added to worldmaps which are showing the whole earth. This has been done this way out of the assumption that each geographically positioned object has a single position on all maps.

## Prerequisites

There is no special software needed on the NagVis server, but there is one special requirement. To be able to use this feature, the browser opening NagVis worldmaps needs to be able to fetch the background images (map tiles) from the internet, or a local mirror, see below. In most corporate environments this means that your client needs to have a proxy server configured.

The worldmaps use the official tile servers of Open Street Map (`https://{s}.tile.openstreetmap.org/`) as a default. Alternative tile server (local mirror) may be set in configuration, for example: `worldmap_tiles_url="http://my-tiles.local/{z}/{x}/{y}.png"`

The switch2osm guides might help you to spin up your local OpenStreetMap mirror.

## The first call

NagVis comes with a demo worldmap called "demo-worldmap". If your NagVis is configured correctly and your browser is able to fetch the background images from the tile server, you should see a map of germany with three nodes. One node is showing the map "demo-ham-racks", which contains hosts located in Hamburg, one hostgroup "cgn" which contains all hosts located in Cologne and another hostgroup "muc" which contains all hosts located in Munich.

This worldmap is defined using the map configuration file "demo-worldmap.cfg". The contents look like this:

    define global {
        alias=Demo: 4 Worldmap
        parent_map=demo-overview
        backend_id=demo
        iconset=std_geo
        icon_size=32

        sources=worldmap
        worldmap_center=50.86837814203458,10.21728515625
        worldmap_zoom=6
        worldmap_tiles_saturate=33

        filter_group=my_group
    }

The attributes after `icon_size=32` are worldmap specific definitions.

The `sources=worldmap` (mandatory) line tells the map to use the worldmap source, which cares about putting all the objects having geographical coordinates, for rendering the map.

The `worldmap_center=50.86837814203458,10.21728515625` (mandatory) specifies the latitude and longitude coordinates to use as initial center for the worldmaps viewport.

The `worldmap_zoom=6` (mandatory) specifies the initial zoom level to be used when rendering the worldmap. NagVis allows zoom levels from 2 (world) to 20 (building, detail).

The `worldmap_tiles_saturate=33` (optional) dims the colors of default OpenStreetMap so that red motorways or large green forests don't interfere with actual map objects. Possible values are 0 (no colors, grayscale) through 100 (full colors).

The `filter_group=my_group` (optional) is an attribute for filtering the host objects on a worldmap by their memberships in the given host group. Only members of the group will be shown on the worldmap.

## Create your own worldmap

You can start creating your own worldmap by using the way you use for other maps too. Select Options > Manage Maps, then fill the Create Map form while choosing Geographical map (interactive) from the map type dropdown and hit Create.

After opening the new map, you can pan and zoom to get the viewport you like, then choose Edit Map > Viewport > Save View to persist the current viewport as initial viewport in the current worldmap.

You can also create a new worldmap from an existing one by zoom and pan to create the viewport you like to use for your new worldmap, then choose Edit Map > Viewport > Save as new Map.

## Objects on worldmap and zoom

The map object (host, line, textbox, ...) may be configured to only show at certain zoom levels. Related object attributes are:

Parameter | Default | Description
--- | --- | ---
min_zoom | 2 | Only show the object at specified zoom level or higher (more detailed view)
max_zoom | 20 | Only show the object at specified zoom levels or lower (wider view)

## Scalable textboxes on worldmap

Static textboxes can scale according to the view zoom level. In other words, a box shrinks as you zoom out, or grows as you zoom in.

Parameter | Default | Description
--- | --- | ---
scale_to_zoom | No | Scale the textbox size down to 50% for every zoom level below `normal_size_at_zoom`, or 50% up for every zoom level above.
normal_size_at_zoom | 19 | At this zoom level, the `scale_to_zoom=yes` textboxes are displayed at original 1:1 (100%) size.