# NagVis Geomap

## Introduction

The NagVis Geomap map source was introduced in NagVis 1.7. It has been developed to get well rendered and scaled overview maps without much work.

The geomap renders several hosts on an Open Street Map powered map which is used as background image.

For the current geomap all you need is a CSV file which tells NagVis the hosts to render and the geo coordinates where the hosts should be positioned at.

Unlike the NagVis Worldmaps, which have been introduced with NagVis 1.9, the geomaps are designed to be static maps without user interaction. You can not zoom in/out and pan like you can on the worldmaps.

## Prerequisites

There is no special software needed on the NagVis host. But there is one special requirement. To be able to use this feature, NagVis needs to be able to access the host `geomap.nagvis.org` via port 80. NagVis uses a simple HTTP based API to get the map image and the coordinates of that image.

In most cases the NagVis host does not have direct internet access. You can configure the `http_proxy` option in the `[global]` section of your NagVis main configuration to tell NagVis to use a proxy such requests. Most proxies require an authentication to control access to the internet. Please use the option `http_proxy_auth` to set the credentials.

## The first call

NagVis comes with a demo geomap called "demo-geomap". If your NagVis is configured correctly you should see a map of germany with two nodes. One node is showing the host "ham-srv1" in Hamburg. The other host "muc-srv1" is located in Munich.

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

    global {
        sources=geomap
        alias=Demo: 4 Geomap
        parent_map=demo-overview
        iconset=std_medium
        backend_id=demo
        # Geomap Parameters
        source_type=csv
        source_file=demo-locations
        width=800
        height=600
    }

The `sources=geomap` line tells the map to use the geomap source for altering the map configuration. The `source_type=csv` (new in 1.7.4) line tells the geomap source to use the CSV file defined in the `source_file=demo-locations` definition located in the `etc/geomap` directory for gathering a list of hosts and coordinates to add to the geomap.

The `demo-locations.csv` file contains the following two lines:

    ham-srv1;Hamburg Server 1;53.556866;9.994622
    muc-srv1;Munich Server1;48.1448353;11.5580067

Each line defines one host to be added to the map. The columns are separated by `;` signs. The first column contains the host-name, the second an optional alias, the third the LAT coordinate and the fourth the LONG coordinate.

(starting with git-version as of 2013-03-21): Lines starting with the usual comment characters (`;`, `#`, or `//`) are treated as comments.

: It is also possible to set `source_type=backend` to use the backend set via `backend_id` to gather the list of hosts to be shown on the geomap and their coordinates. This is only possible when using the livestatus backend. It fetches all hosts from the backend and uses all hosts which have the custom object variables `_LAT` and `_LONG` configured. It is possible to filter the fetched hosts by the membership in a host group by setting the option `filter_group` to the name of the host group.

## Configuring geomaps

The geomap source uses view parameters for configuration. For details take a look at the modify view dialog which can be opened using the header menu "Actions -> Modify view".

The view parameters can also be given as map configuration attributes in the global section of the maps.

Parameter | Default | Description
--- | --- | ---
geomap_type | mapnik | Define the render mode of the geomap. Can be osmarender, mapnik and cycle.
geomap_zoom |  | Configure the zoom level of the geomap during map request. Take a look at the OSM zoom documentation for further details.
geomap_border | 0.25 | The border to add on each side of the geomap. This value is simply added to the calculated min/max geo coordinates.
source_type | csv | The type of the datasource used for for fetching the geomap objects. Might be `csv` or `backend`.
source_file |  | The name of the CSV file to use as source for rendering the geomap. Is only used when `source_type` is set to `csv`.
width |  | Defines the width of the geomap in pixels. The maximum size of the geomap is limited by the queried webservice. geomap.nagvis.org supports up to 50 tiles per map which should make 1920x1080 resolutions possible. Please contact us if you need more.
height |  | Defines the height of the geomap in pixels. The maximum size of the geomap is limited by the queried webservice. geomap.nagvis.org supports up to 50 tiles per map which should make 1920x1080 resolutions possible. Please contact us if you need more.