NAME
BQMap - BRTT Qt graphics extension for drawing a map
SYNOPSIS
$(QTNATIVELIBS) -lbqplot_native -lbanner -lbrttutil -lbumapdata $(DBLIBS) $(TRLIBS)
#include "BQ.h"
DESCRIPTION
BQMap objects are used to display geographic base maps. Maps
can be latitude-longitude map image grids expressed as color pixels, such as the NASA Bluemarble images,
or Digital Elevation Model (DEM) latitude-longitude grids, such as the NASA SRTM30 DEM grid, or vector
polylines representing shorelines, displayed as polygons with outlines and fills, or other non-filled polylines,
such as political boundaries and rivers, such as the Global Self-consistent Hierarchial High-resolution Shoreline (GSHHS)
database from NOAA's National Geophysical Data Center.
BQMap objects are complex objects that make use of other helper classes,
including BQMapLayer(3) and BQNavigator(3).
The default BQTaskbar(3) and BQViewport(3) event handlers are used
to implement a basic
taskbar and mouse interaction for panning and zooming
the map. The BQViewport parent object is controlled automatically
from BQMap objects. All of the actual map rendering is handled
through the BQMapLayer objects. BQMap objects themselves
only orchestrate the interactions from all of its helper classes and the
other objects it creates and uses.
This class inherits the BQConfigure class which is itself a subclass of the BUConfigure class
with extensions to process Qt colors and fonts. The configure methods are implemented
in the BUConfigure parent (see BUConfigure(3)).
INHERITS FROM
BQViewportItem,
BQConfigure
CONSTRUCTOR
BQMap(BQViewport *master, int make_navigator=1, int make_grids=1);
BQMap(QWidget *parent, int make_navigator=1, int make_grids=1);
Where master is the BQViewport master for this object, or
alternatively parent is a parent QWidget that is used to automatically
construct a BQViewport object as the master viewport for this object.
The make_navigator and make_grids flags control whether or
not a QNavigator(3)
window is made and whether or not latitude-longitude grid lines are
automatically made through
an internally generated BQAxes()3 object.
METHODS INHERITED FROM BQConfigure
-
void configure (Pf *params);
An Antelope parameter file object pointer that contains the BQMap object
parameters. The parameters are described below.
-
void configure (...);
A variable argument list composed entirely of character string key-value pairs with
a single NULL terminating argument. This is an alternate method for specifying
the BQMap object parameters. The parameters are described below.
METHODS INHERITED FROM BQViewportItem
-
void setLayer (QString name);
This will cause the BQMap object to be put into the BQLayer object buffer with name name (see BQLayer(3)).
The BQLayer object will automatically be created if an object with name name does not exist.
-
void showItem();
-
void hideItem();
These will cause the map object to be shown (displayed) or hidden (not displayed).
BQMap METHODS
-
void setDefaults();
When a BQMap object is created the various map layer and taskbar definitions
and configurations are not defined. The application programmer can customize
the object by calling the various configuration options described below.
Alternatively this method can be called to set up a default object configuration.
-
BQMap *getTaskbar();
This returns the BQTaskbar(3) object associated with this object.
OBJECT CONFIGURATION PARAMETERS
-
fill_land landfillColor
Specifies a color to use for filling land areas.
Can be specified in any of the forms documented in BQ_ParseColor(3).
If this is specified as a "" string, then land areas will not be filled.
This defaults to "#fff2e5".
This is substituted for the $FILL_LAND
tokens in the BQMapLayer(3) definitions.
-
fill_water waterfillColor
Specifies a color to use for filling water areas.
Can be specified in any of the forms documented in BQ_ParseColor(3).
If this is specified as a "" string, then water areas will not be filled.
This defaults to "#e0e0ff".
This is substituted for the $FILL_WATER
tokens in the BQMapLayer(3) definitions.
-
maplayer_definitions maplayerDefinitionsString
This item configuration option is used to define the various base map layers.
Note that map layers within BQMap objects are abstractions, implemented
by BQMapLayer(3) objects
and do not necessarily map one-to-one to BQLayer objects.
The maplayerDefinitionsString is an Antelope parameter file string that
contains these parameters.
Following is the default maplayerDefinitionsString for this option.
/B>
maplayer_definitions &Arr{
bluemarble &Arr{
mapdata_source_file /opt/antelope/data/maps/bmd/bluemarble.world.200407.v01.grid.bmd
opacity 1.0
antialias 0
type grid
bq_layer image
}
dem_srtm30 &Arr{
mapdata_source_file /opt/antelope/data/maps/bmd/srtm30.dem.world.v01.grid.bmd
opacity 1.0
antialias 0
type grid
bq_layer image
}
water_mask &Arr{
mapdata_source_file coasts.vector.bmd
opacity 1.0
antialias 0
type vector_fill
bq_layer water
outline_linewidth -1
background_color $FILL_WATER
fill_color $FILL_LAND
transparent_color $FILL_LAND
}
coasts &Arr{
mapdata_source_file coasts.vector.bmd
opacity 1.0
antialias 1
type vector_fill
bq_layer vector
outline_linewidth 1
outline_color #000000
background_color $FILL_WATER
fill_color $FILL_LAND
}
political &Arr{
mapdata_source_file political.vector.bmd
opacity 1.0
antialias 1
type vector
bq_layer vector
levels &Tbl{
1 \#ff0000
0 \#8000a000 3
0 \#80ff00ff
}
}
rivers &Arr{
mapdata_source_file rivers.vector.bmd
opacity 1.0
antialias 1
type vector
bq_layer vector
levels &Tbl{
1 \#c0c0ff
}
}
}
/B>
-
The parameter file must contain an associate array named maplayer_definitions.
The maplayer_definitions array defines the various base map layers that can be displayed.
Each entry in the maplayer_definitions array is another associative array with a
unique and arbitrary map layer name and there are automatically generated BQMapLayer(3)
objects for each entry. Each of the map layer associative arrays are passed through
the BQMapLayer::configure method to the individual BQMapLayer objects using
the "definition" option name with the string "definition" substituted for
the map layer name. The definitions of the individual map layer parameters are in BQMapLayer(3).
-
maplayers maplayersString
This item configuration option is used to define a specific set of map layers to be displayed.
Note that map layers within BQMap objects are abstractions, implemented
by BQMapLayer(3) objects
and do not necessarily map one-to-one to BQLayer objects.
The maplayersString is an Antelope parameter file string that contains these parameters.
Following is the default maplayersString for this option.
maplayers &Tbl{
coasts
political
rivers
}
-
The parameter file must contain a table named maplayers. Each entry on the maplayers table
must correspond to a name from the maplayer_definitions array. Map layers are
created and displayed in the order in this table. A new set of map layers and ordering can
be accomplished by calling this configuration option.
-
define_maplayers_template maplayersTemplateDefinitionString
This item configuration option is used to define a new map layers template.
The maplayersTemplateDefinitionString is an Antelope parameter file string that
contains these parameters.
Following is a typical maplayersTemplateDefinitionString for this option.
name bluemarble
maplayers &Tbl{
bluemarble
rivers
political
}
-
The parameter file must contain a parameter named name which will be the name of this template.
The parameter file must also contain a table named maplayers. Each entry in
the maplayers table must correspond to a name from the maplayer_definitions array.
Map layers are created and displayed in the order in this table. Use of this
template (with maplayer_template configuration option) will cause the
associated map layers to be displayed.
Note that this configuration option can be called multiple times to define multiple templates.
-
define_maplayers_templates maplayersTemplatesDefinitionString
This is an alternative way to define map layers templates. In this case multiple templates can
be defined with a single configuration call.
Following is a typical maplayersTemplatesDefinitionString for this option.
maplayers_templates &Arr{
vector &Arr{
maplayers &Tbl{
coasts
rivers
political
}
}
bluemarble &Arr{
maplayers &Tbl{
bluemarble
rivers_image
political
}
}
dem &Arr{
maplayers &Tbl{
dem
rivers_image
political
}
}
demw &Arr{
maplayers &Tbl{
dem
water
rivers_image
political
}
}
}
-
In this case the template names appear as the key values in an associative array
named maplayers_templates.
-
maplayers_template maplayersTemplateNameString
This is the name of a previously defined map layers template that should be displayed.
-
maplayer_show maplayerNameString
This causes the named maplayer to be displayed.
-
maplayer_hide maplayerNameString
This causes the named maplayer to be hidden.
-
maplayer_visibility_toggle maplayerNameString
This causes the named maplayer's visibility to be toggled; i.e. a layer that is
currently displayed will be hidden
and a layer that is currently hidden will be displayed.
-
maptaskbar_buttons_definitions taksbarButtonsDefinitionsString
This item configuration option is used to define the optional taskbar buttons.
The BQMap class uses a BQTaskbar object which offers a very simple internal
taskbar in which buttons and associated actions can be defined. The taskbar buttons are
implemented as BQText objects. This is completely optional.
The taskbarButtonsDefinitionsString is an Antelope parameter file string that
contains these parameters.
Following is a typical taskbarButtonsDefinitionsString for this option.
map_buttons_definitions &Arr{
basemap &Arr{
height 26
description base map
states &Arr{
bluemarble &Arr{
label BaB
description NASA Bluemarble
action configure maplayers_template bluemarble
opacity 0.5
background_color blue
fill_color yellow
order 0
}
dem &Arr{
label BaD
description SRTM30 DEM
action configure maplayers_template dem
opacity 0.5
background_color \#fff2e5
fill_color black
order 1
}
demw &Arr{
label BaW
description SRTM30 DEM with water masks
action configure maplayers_template demw
opacity 0.5
background_color \#fff2e5
fill_color black
order 2
}
vector &Arr{
label BaV
description vector shorelines
action configure maplayers_template vector
opacity 0.5
background_color \#fff2e5
fill_color black
order 3
}
}
}
projection &Arr{
height 26
description map projection
states &Arr{
globe &Arr{
label PrGl
description globe projection
action configure projection globe
opacity 0.5
background_color \#fff2e5
fill_color blue
order 0
}
edp &Arr{
label PrE
description equal distance projection
action configure projection edp
opacity 0.5
background_color \#fff2e5
fill_color blue
order 1
}
merc &Arr{
label PrM
description Mercator projection
action configure projection merc
opacity 0.5
background_color \#fff2e5
fill_color blue
order 2
}
geog &Arr{
label PrLL
description lat-lon projection
action configure projection geog
opacity 0.5
background_color \#fff2e5
fill_color blue
order 3
}
}
}
political &Arr{
height 26
description toggle political
states &Arr{
on &Arr{
label P
action configure maplayer_show political
opacity 0.5
background_color \#fff2e5
fill_color red
order 0
}
off &Arr{
label P
action configure maplayer_hide political
opacity 0.5
background_color \#fff2e5
fill_color red
order 1
show_not_symbol yes
}
}
}
rivers &Arr{
height 26
description toggle rivers
states &Arr{
on &Arr{
label R
action &Tbl{
configure maplayer_show rivers
configure maplayer_show rivers_image
}
opacity 0.5
background_color \#fff2e5
fill_color blue
order 0
}
off &Arr{
label R
action &Tbl{
configure maplayer_hide rivers
configure maplayer_hide rivers_image
}
opacity 0.5
background_color \#fff2e5
fill_color blue
order 1
show_not_symbol yes
}
}
}
nav &Arr{
height 26
description show/hide navigator window
states &Arr{
auto &Arr{
label NaA
description auto
action configure show_nav auto
opacity 0.5
background_color \#fff2e5
fill_color blue
order 0
}
on &Arr{
label Na
description on
action configure show_nav on
opacity 0.5
background_color \#fff2e5
fill_color blue
order 1
}
off &Arr{
label Na
description off
action configure show_nav off
opacity 0.5
background_color \#fff2e5
fill_color blue
order 2
show_not_symbol yes
}
}
}
zoomin &Arr{
height 26
label +
description zoom in
action &Tbl{
mod=shift configure zoom 2.0
mod=notshift configure zoom 1.1
}
opacity 0.5
background_color \#fff2e5
fill_color black
}
zoomout &Arr{
height 26
label -
description zoom out
action &Tbl{
mod=shift configure zoom 0.5
mod=notshift configure zoom 0.9090909090909
}
opacity 0.5
background_color \#fff2e5
fill_color black
}
}
-
The parameter file must contain an associate array named map_buttons_definitions.
The map_buttons_definitions array defines the various taskbar buttons that can be displayed.
This parameter file string is passed to
the BQTaskbar::configure method with
the "taskbar_buttons_definitions" option name with the
string "buttons_definitions" substituted for the string "map_buttons_definitions".
The definitions of the individual taskbar parameters are in BQTaskbar(3).
-
maptaskbar_buttons taksbarButtonsString
This item configuration option is used to define a specific set of taskbar buttons to be
displayed and used.
The taskbarButtonsString is an Antelope parameter file string that contains these parameters.
Following is a typical taskbarButtonsString for this option.
map_buttons &Tbl{
basemap neb 1.0v-2 1.0v-2 0
projection neb -1r-1 0r 1
political neb -1r-1 0r
rivers neb -1r-1 0r
nav neb -1r-1 0r
zoomin neb -1r-1 0r
zoomout neb -1r-1 0r
}
-
The parameter file must contain a table named map_buttons.
This parameter file string is passed to
the BQTaskbar::configure method with
the "taskbar_buttons" option name with the
string "buttons" substituted for the string "map_buttons".
The definitions of the individual taskbar parameters are in BQTaskbar(3).
-
projection projectionString
This is a convenience option that will cause the map projection to be set and for the
map scales to be adjusted to keep the viewport so it is showing approximately the same map limits.
This must be one of globe, for a spherical globe projection, edp, for equal
distance projection, merc, for Mercator projection, or geog for straight
geographic longitude-latitude projection.
-
zoom zoomFactor
This is a convenience option that will cause the map to zoom in or out according to zoomFactor. A factor > 1.0
causes the map to zoom in. The center coordinate of the map viewport is preserved.
-
show_nav showNav
This determines when the BQNavigastor(3) window is shown. It should be
a boolean string to indicate if the window should be shown, or "auto", which
causes the window to automatically be shown/hidden depending on the range of the map.
-
latr latitudeRef
This is a convenience option and specifies a reference latitude in degrees.
See BQViewport(3) for a definition.
-
lonr longitudeRef
This is a convenience option and specifies a reference longitude in degrees.
See BQViewport(3) for a definition.
-
range range
This is a convenience option and specifies a X-axis range in degrees.
See BQViewport(3) for a definition.
-
cache_maxsize cacheMaxsize
This is an integer number of bytes that defines the maximum uncompressed map tile cache size.
Most of the grid map files contain compressed map tile images. These tiles must first be
decompressed before they can be used. In order to avoid the performance penalty in order
to decompress these compressed tiles every time that tile needs to be
displayed, the BQMap object maintains a cache with uncompressed tile images.
This number specifies how big that cache
can be. When an expansion of a new tile causes the cache size to go over this limit,
the oldest tiles in the cache
are freed until the cache size comes back below the tolerance.
This defaults to 500000000.
-
nthreads numberThreads
The rendering of grid images into the current map projection and scales is threaded
within BQMap. This integer
specifies how many threads to be used in this rendering.
This defaults to 16.
EXAMPLE
Following is a simple example program that uses
BQMap.
#include "BQ.h"
int
main (int argc, char **argv)
{
int ret;
QApplication app (argc, argv);
QWidget *frame = new QWidget();
BQMap *map = new BQMap(frame);
map->setDefaults();
map->configure (
"latr", "40",
"lonr", "-100",
"range", "90",
NULL );
double t0 = now();
frame->setGeometry (0, 0, 1500, 1000);
frame->show();
frame->setWindowTitle ("bqplot_test_map");
printf ("view setup %f\n", now()-t0);
ret = app.exec();
return ret;
}
SEE ALSO
bqplot(3),
BQViewport(3),
BQLayer(3),
BQConfigure(3),
BQMapLayer(3), BQNavigator(3),
BQTaskbar(3)
AUTHOR
Danny Harvey, BRTT