MAP-LAB

A MATLAB Graphical User Interface for generating maps

User Guide

Developed by:

Dimitrios Piretzidis Prof. Michael G. Sideris

Ph.D. Candidate, Research Assistant Ph.D., Dr. h.c., P.Eng.
Department of Geomatics Engineering Department of Geomatics Engineering
University of Calgary University of Calgary
2500 University Drive NW, Calgary, AB, 2500 University Drive NW, Calgary, AB
T2N 1N4 T2N 1N4
e-mail: [email protected] e-mail: [email protected]
[email protected]

Calgary, Canada

November, 2016
 User Guide

Table of contents

Table of contents ................................................................................................................................... ii

1. Introduction ................................................................................................................................... 1
2. Overview of MAP-LAB ................................................................................................................. 4
2.1. Input data format ...................................................................................................................... 4
2.2. Projection parameters ............................................................................................................... 6
2.3. Coastline parameters ................................................................................................................ 9
2.4. Political boundaries parameters .............................................................................................. 10
2.5. Grid parameters ..................................................................................................................... 11
2.6. Plot parameters ...................................................................................................................... 13
2.7. Interpolation parameters ......................................................................................................... 15
2.8. Vector parameters .................................................................................................................. 16
2.9. Error ellipse parameters ......................................................................................................... 17
2.10. Title, Axes and Colorbar labels .......................................................................................... 18
2.11. Figure appearance and print................................................................................................ 19

ii
 User Guide

1. Introduction
MAP-LAB is a MATLAB-based Graphical User Interface (GUI), developed for producing maps and
visualizing spatial data sets. The main idea behind the design of MAP-LAB was to provide MATLAB
users and researchers with an efficient and easy-to-use GUI to generate maps without the need of writing
scripts or using MATLAB’s command window. MAP-LAB utilizes the capabilities of the M_Map
mapping toolbox, which is a library of functions and tools aided to plot geospatial information. Only one
fraction of the complete M_Map function library is implemented into MAP-LAB. More options will be
added in future releases. In this section, a quick review of MAP-LAB is given along with a brief
description on how to properly set-up the software.

Two versions of MAP-LAB are currently available; the Lite (~14 MB) and Full (~103 MB) version. The
Lite version of MAP-LAB only includes the User Guide and sample data files to help the user get familiar
with the software. The Full version of MAP-LAB additionally includes the M_Map toolbox, high-
resolution coastlines and political boundaries. MAP-LAB primarily consists of 17 m-files and 17 fig-files
that can be downloaded from its official website (http://dimitriospiretzidis.com/maplab_home.html) under
the Download section. Every m-file and its corresponding fig-file opens a GUI that controls a specific
M_Map function. All GUIs are linked to the main GUI form that is presented in Figure 1 (MAP-LAB
Launcher). To launch MAP-LAB software the user should run the start.m file located in the MAP-LAB
folder.

WARNING! Avoid opening and executing the start.fig file as it does not contain any callback
events and therefore an error message will appear on MATLAB’s command window.

(1)

(2)
(3) (4)

Figure 1 – MAP-LAB Launcher.

Before loading the main GUI form, three important preliminary tests are performed to check if the
M_Map toolbox, high-resolution coastlines and political boundaries are installed in MAP-LAB’s
directory. By running the start.m file, the Full version of MAP-LAB will load the main form of Figure 1
directly and the software will be ready for use without any additional action from the user. If the Lite
version of MAP-LAB is downloaded and no version of M_Map, high-resolution coastlines and political
boundaries is installed by the user, the warning messages displayed in Figure 2 will appear. By clicking
Yes to the M_Map warning message, MAP-LAB will automatically download and unzip the M_Map
toolbox into MAP-LAB’s directory. By clicking Yes to the GSHHS coastline and Political boundaries
warning messages, MAP-LAB will automatically download and install high-resolution coastlines and
political boundaries into MAP-LAB’s directory.

1
 User Guide

(a)

(b)

(c)

Figure 2 – Warning messages for missing (a) M_Map, (b) high-resolution coastlines and (c) political
boundaries.

After the preliminary tests, the Lite version of MAP-LAB will load the main form of Figure 1. The main
form consists of 4 basic features. These features are: (1) the main menu, (2) the Data File Path textbox,
(3) the Area Limits panel and (4) the Data Statistics panel. The last three features automatically provide
information to the user when input data are loaded into the software. The main menu consists of 5
dropdown menus presented in Figure 3.

(a) (b)

(c) (d)

2
 User Guide

(e)

Figure 3 – Dropdown menus: (a) File, (b) Select, (c) Preferences, (d) Generate and (e) Help.

The main menu is structured in order to guide the user by itself and to avoid confusion with all the
available options implemented. The main steps and user-defined attributes are the same regardless of the
map that the user wants to create. These steps are:

1. Load a file into the software

2. Select the projection parameters
3. Select the coastline parameters
4. Select the political boundaries parameters (Optional)
5. Select the grid parameters
6. Select the special parameters of the data to be plotted, which are:
a. The plotting function and the interpolation parameters, in case the user wants to create a
contour map
b. The vector parameters, in case the user wants to create a vector map.
c. The error ellipses parameters, in case the user wants to create an error ellipses map.
7. Select the title and the axes label (Optional).
8. Select the figure parameters (Optional).
9. Generate the map.

All the selected parameters are saved in global variables that used later to generate the map. The
parameters are also saved in the corresponding GUI objects. For example, if the user selects and saves the
projection parameters and then returns back to the projection GUI form, they will be able to see the last
saved parameters. All the available options for the aforementioned steps will be further discussed in
Section 2. After the selection of all the necessary parameters, MAP-LAB provides to the user the ability
to generate the following maps:

1. Contour maps
2. Vector maps
3. Error ellipses maps
4. Data distribution maps

3
 User Guide

2. Overview of MAP-LAB
An overview of MAP-LAB, along with a small overview of the basic characteristics and possibilities of
the mapping package M_Map is provided here. Focus is given only on the M_Map attributes that are
implemented in MAP-LAB. The overview covers the following topics:

1. Input data format

2. Projection parameters
3. Coastline parameters
4. Political boundaries parameters
5. Grid parameters
6. Plot parameters
7. Interpolation parameters
8. Vector parameters
9. Error ellipses parameters
10. Title, axes and colorbar labels
11. Figure appearance and print

2.1. Input data format

There are two ways of loading data into MAP-LAB; by selecting a data file and by selecting variables
from MATLAB’s Workspace. To select and load a data file into the software, the user should click on the
menu File → Load Data from File…. This option opens the dialog box presented in Figure 4. By
selecting the data file and clicking on the Open button, or simply by double-clicking the data file, the data
will be loaded into the software. If the data file has the correct format, the file path directory will be
displayed on the Data File Path textbox. Additionally, the information of the Area Limits and the Data
Statistics panel will also be displayed.

Figure 4 – Dialog box for selecting a data file.

The format of the input data file depends on the map that the user wants to create. In general, MAP-LAB
can recognize ASCII or .mat file formats. In the first and second column of the data file, the latitude and
longitude coordinates of the data must be placed respectively. The longitude values should be either from
0° to 360° or from -180° to 180°, with a preference to the second set of limits. In addition, the latitude
values should be from -90° to 90°. The limits of both the longitude and latitude should be greater than or
equal to the corresponding limits used for the projection parameters, otherwise areas without data will
appear in the resulting map. Data points with coordinates outside the projection limits are not visible in

4
 User Guide
the resulting map. The input file should have between three and five columns considering the type of
map. At least three columns required for a contour map, exactly four columns for a vector map and five
columns for an error ellipses map. When creating a vector map, the third and fourth column of the input
file should correspond to the East-West and North-South components of the vector respectively. When
creating an error ellipses map, the third, fourth and fifth column of the input file should correspond to the
semi-major axis, semi-minor axis and azimuth of the semi-major axis of the error ellipses respectively.

WARNING! MAP-LAB cannot accept data files with less than three columns or more than five
columns. In order to prevent the user from loading a file with wrong dimensions, the software
displays the error message shown in Figure 5.

Figure 5 – Error message for wrong input file format.

To select and load data from MATLAB’s Workspace into the software, the user should click on the menu
File → Load Data from Workspace…. This option opens the GUI form presented in Figure 6. From three
to five Workspace variables can be selected and imported into MAP-LAB by clicking the Load button.
When creating a vector map, the variables of East-West and North-South components of the vector
should be placed in Data set 1 and Data set 2 respectively. When creating an error ellipses map, the
variables of semi-major axis, semi-minor axis and azimuth of the semi-major axis of the error ellipses
should be placed in Data set 1, Data set 2 and Data set 3 respectively.

Figure 6 – GUI form for selecting data from Workspace.

WARNING! In case the user select less than three variables, the error message presented in
Figure 7 will appear.

Figure 7 – Error message for incomplete data selection.

5
 User Guide
WARNING! If the selected variables do not have the same dimensions, the error message given
in Figure 8 will be displayed.

Figure 8 – Error message for wrong input data dimensions.

2.2. Projection parameters

All 19 projections of the M_Map toolbox are implemented into MAP-LAB. These projections are divided
into the 4 categories given below:

1. Azimuthal projections
i. Stereographic
ii. Orthographic
iii. Azimuthal Equal-Area
iv. Azimuthal Equidistant
v. Gnomonic
vi. Satellite
2. Cylindrical and Pseudo-cylindrical projections
i. Mercator
ii. Miller Cylindrical
iii. Equidistant Cylindrical
iv. Oblique Mercator
v. Transverse Mercator
vi. Universal Transverse Mercator
vii. Sinusoidal
viii. Gall-Peters
3. Conic projections
i. Albers Equal-Area
ii. Lambert Conformal
4. Miscellaneous projections
i. Hammer-Aitoff
ii. Mollweide
iii. Robinson

The map projection can be defined by clicking on the menu Select → Projection and then clicking on one
of the four projection categories. The projection parameters depend on the projection category, and
therefore, a different GUI form is developed for each projection category (see also Figure 9,Figure 11,
Figure 12 and Figure 13. The GUI form that prompts when choosing an azimuthal projection is given in
Figure 9.

6
 User Guide

Figure 9 – Azimuthal projections form.

To define an azimuthal projection, three properties are needed, i.e., the longitude and latitude coordinates
of the center point, and the radius of the circle that encloses the projected area. Figure 10 shows an
example of an azimuthal projection, where the Stereographic projection is selected, the longitude and
latitude coordinates of the center point are chosen to be 24° and 38° respectively, and a 4°-radius is
selected.

Figure 10 – Example of azimuthal projection.

The GUI form that appears when the user selects a cylindrical and pseudo-cylindrical projection is
presented in Figure 11. In order to define a cylindrical and pseudo-cylindrical projection, the projection
type and the longitude and latitude limits need to be selected.

7
 User Guide

Figure 11 – Cylindrical and Pseudo-cylindrical projections form.

The GUI form for selecting the parameters of a conic projection is presented in Figure 12. The parameters
are the same as for the cylindrical and pseudo-cylindrical projections.

Figure 12 – Conic projections form.

The GUI form for selecting the parameters of the three miscellaneous projections is presented in Figure
13. The three miscellaneous projections provided by the M_Map toolbox are suitable for visualizing
global data sets. The projection parameters are the same as for the cylindrical and pseudo-cylindrical
projections and conic projections.

Figure 13 – Miscellaneous projections form.

Checking the Same as input data checkbox, the longitude and latitude limits will automatically take the
values of the corresponding limits of the input data. Once all the projection parameters are chosen, the
user can click on the Save button to save all the options and automatically return to the main form.

8
 User Guide
WARNING! The error message in Figure 14 appears when the projection parameters are empty
of invalid.

Figure 14 – Error message for wrong projection parameters.

2.3. Coastline parameters

The M_Map toolbox does not include high resolution coastlines, but it provides functions for reading and
plotting five different resolutions of the Global Self-consistent, Hierarchical, High-resolution Geography
(GSHHS) coastlines. These coastlines are provided by the National Oceanic and Atmospheric
Administration (NOAA) and can be downloaded from the webpage
http://www.ngdc.noaa.gov/mgg/shorelines/data/gshhs/oldversions/version1.2/. To install the GSHHS
coastlines, the user should download the following gz-files:

1. gshhs_c.b.gz (Crude resolution coastline)

2. gshhs_l.b.gz (Low resolution coastline)
3. gshhs_i.b.gz (Intermediate resolution coastline)
4. gshhs_h.b.gz (High resolution coastline)
5. gshhs_f.b.gz (Full resolution coastline)

and unzip them into the MAP-LAB subfolder named GSHHS coastlines. After that, the coastlines will be
ready for use. The Full version of MAP-LAB already contains the GSHHS coastlines, whereas the Lite
version of MAP-LAB installs the GSHHS automatically using the procedure explained above. To select
the coastline parameters using MAP-LAB, the user can click on the menu Select → Coastline
Parameters… and the form in Figure 15 will load.

Figure 15 – Coastline parameters form.

The coastline parameters that are implemented in MAP-LAB are the coastline resolution, the coastline
color and width, and the patch color. When the the Crude, Low, Intermediate, High or Full resolution are
selected, MAP-LAB uses the M_Map function m_gshhs. When the Default resolution is selected, MAP-
LAB uses the M_Map function m_coast. In the second case, the generated coastline has the same
resolution with the one generated when choosing the Crude resolution option. For computational

9
 User Guide
efficiency, the user is advised to choose the High or Full resolution coastline when studying areas in local
and regional scale, the Intermediate resolution in transnational scale and the Low or Crude resolution for
continental and global scale. In Figure 16 the difference between the coastline color and the patch color is
presented. After selecting the coastline parameters, the user can click on the Save button.

Coastline color

Patch color

Figure 16 – Coastline and patch color

WARNING! If both the selected coastline color and patch color are None, then the resulting
coastline will not be visible. To prevent that from happening, the error message given in Figure
17 will appear.

Figure 17 – Error message for empty coastline and patch color.

WARNING! When the coastline width is empty or invalid, the error message presented in Figure
18 appears.

Figure 18 – Error message for invalid coastline width.

2.4. Political boundaries parameters

MAP-LAB provides the option of plotting political boundaries, which are not contained in the M_Map
toolbox. The political boundaries include detailed country land boundaries and state/province boundaries.
These boundaries are provided by the Natural Earth public domain and can be downloaded from the
webpage http://www.naturalearthdata.com/downloads/10m-cultural-vectors/. To install the political
boundaries, the user should download the following zip-files:

1. ne_10m_admin_0_boundary_lines_land.zip (Country boundaries)

2. ne_10m_admin_1_states_provinces_lines.zip (States/Provinces boundaries)

10
 User Guide
and unzip them into the MAP-LAB subfolders named Political
boundaries\ne_10m_admin_0_boundary_lines_land and Political
boundaries\ne_10m_admin_1_states_provinces_lines respectively. After that, the political boundaries
will be ready for use. If the subfolders do not exists, they should be created by the user. The Full version
of MAP-LAB already contains political boundaries, whereas the Lite version of MAP-LAB automatically
downloads and installs the political boundaries.

The user can select the political boundary parameters by clicking on the menu Select → Political
Boundaries Parameters… and the GUI form presented in Figure 19 will load. The political boundaries
parameters implemented in MAP-LAB are the line style, line color and line width. Clicking on the Save
button, MAP-LAB saves the selected parameters.

Figure 19 – Political boundaries parameters form.

WARNING! When the country land boundary width is empty or invalid, the error message
presented in Figure 20 appears.

Figure 20 – Error message for invalid country land boundaries parameters.

WARNING! When the states boundary width is empty or invalid, the error message presented in
Figure 21 will appear.

Figure 21 – Error message for invalid states boundaries parameters.

2.5. Grid parameters

The M_Map toolbox provide several options for controlling the appearance of a grid. The options that are
implemented in MAP-LAB are the type of grid box, axes label location, font size, font color, font width

11
 User Guide
and axis tickstyle. The user can choose the grid parameters by clicking on the menu Select → Grid
Parameters... and the GUI form in Figure 22 will load.

Figure 22 – Grid parameters form.

The default option for the type of grid box is Fancy, for X-Axis and Y-Axis label location is Bottom
and Left respectively, for the color is Black, for the width and font size is 1 and 10 respectively and
for the tickstyle is Degrees-Minutes. In Figure 23, the three different types of grid box are presented
(for convenience, only the down-right corner of the map is visible).

(a) (b) (c)

Figure 23 – Grid box: (a) Off, (b) On and (c) Fancy.

When generating a global map or a map of a polar region, the grid labels should not be aligned at the edge
of the map but in the middle. For example, Figure 24(a) provides the result of a global map that is created
by selecting the Hammer-Aitoff projection and the Bottom and Left alignment options for the X-Axis and
Y-Axis location respectively. It is clear that the labels of the longitude axis are neither visible nor
separated enough from each other. In this case, it is better to select the Middle alignment for the Y-Axis
location. The resulting map, presented in Figure 24(b), is more visually appealing.

12
 User Guide

(a) (b)

Figure 24 – X-Axis location: (a) Bottom and (b) Middle.

The user can also choose the format of the axes labels. The M_Map toolbox offers two options of
displaying the axes labels; in decimal degrees format and in degrees-minutes format. An example of these
two formats is given in Figure 25.

(a) (b)

Figure 25 – Axes labels: (a) Decimal Degrees format and (b) Degrees-Minutes format.

WARNING! The error message presented in Figure 26 appears when the grid parameters are
empty or wrong.

Figure 26 – Error message for invalid grid parameters.

2.6. Plot parameters

All the plot parameters can be defined by clicking on the menu Select → Plot parameters.... The plot
parameters form is presented in Figure 27.

13
 User Guide

Figure 27 – Plot parameters form.

The user can choose among three available plotting options that are implemented in the M_Map functions
m_contour, m_contourf and m_pcolor. The m_contour function produces a contour plot by displaying
isolines, the m_contourf function produces a filled contour plot and the m_pcolor function produces a
pseudocolor plot. Figure 28 provides an example of the maps created using each one of these three
plotting functions:

(a) (b) (c)

Figure 28 – Plot functions: (a) m_contour, (b) m_contourf and (c) m_pcolor.

Three shading techniques are also implemented into MAP-LAB for producing a contour map using
m_contourf and m_pcolor functions, i.e., flat, faceted and interpolated. In Figure 29, examples of those
three shading options are presented.

(a) (b) (c)

Figure 29 – Shading techniques: (a) flat, (b) faceted and (c) interpolated.

14
 User Guide
The final parameter that the user can choose is the colormap scale. All the available colormaps are
implemented into the MAP-LAB software. After choosing the plot parameters the user can click on the
Save button and return to the main form.

2.7. Interpolation parameters

Contour maps require the interpolation of input data on a rectangular grid, even if the input data are
already defined on a grid. To choose the interpolation parameters, the user should click on the menu
Select → Data Interpolation Parameters... and the form in Figure 30 appears.

Figure 30 – Interpolation parameters form.

Four interpolation methods are implemented into MAP-LAB, i.e., linear, cubic, nearest and v4
interpolation. Apart from the interpolation method, the user can also select the interpolation limits, which
define the location of the grid, and the grid step. Clicking on the Same as datafile checkbox, the
interpolation limits are automatically filled with the area limits of the input file. After selecting all the
parameters, the user should click on the Interpolate Data button to perform the interpolation and return to
the main form. In the case that the input file has more than 3 columns, the menu in Figure 31 appears that
enables the user to choose the column they want to interpolate.

(a) (b)

Figure 31 – Menu for data set interpolation selection.

WARNING! When the interpolation parameters are empty or invalid, the error message
presented in Figure 32 appears.

Figure 32 – Error message for invalid interpolation parameters.

15
 User Guide
2.8. Vector parameters

MAP-LAB provides the user with the ability to create a vector map using the M_Map function m_vec.
The vector parameters can be selected by clicking on the menu Select → Vector Parameters... and the
form in Figure 33 will load.

Figure 33 – Vector parameters form.

An important parameter that should be defined by the user is the scale factor. The scale factor controls the
relative size of all vectors. Unsuitable values for the scale factor can result in vectors that are very long or
not visible enough. The shaft width, line width and head length parameters control the appearance of the
vectors. From Figure 34 to Figure 37 all four vector parameters are presented with different values for
each parameter. The option of centering the vectors is also supported by MAP-LAB, along with the
selection of the vector color.

Figure 34 – Vectors with different scale factor parameter.

Figure 35 – Vectors with different shaft width parameter.

Figure 36 – Vectors with different line width parameter.

16
 User Guide

Figure 37 – Vectors with different head length parameter.

WARNING! If the selected vector parameters have empty or invalid values, the error message in
Figure 38 appears.

Figure 38 – Error message for invalid vector parameters.

2.9. Error ellipse parameters

A feature of MAP-LAB that is not included into the M_Map toolbox is the capability of creating error
ellipses maps. In order to generate an error ellipses map, the user should define the error ellipses
parameters by clicking on the menu Select → Error Ellipses Parameters.... The error ellipses parameters
form is given in Figure 39.

Figure 39 – Error ellipses parameters form.

The scale factor parameter controls the relative size and of the error ellipses. The user can also define the
line style, color and width of the ellipses. When choosing to plot the ellipses center, the user can select the
edge color, face color, marker type and marker size of the center point. In Figure 40, an example of an
error ellipses map using different scale factor values is given.

17
 User Guide

Figure 40 – Error ellipses with different scale factor parameters.

WARNING! If the selected ellipses parameters have empty or invalid values, the error message
in Figure 41 appears.

Figure 41 – Ellipses parameters error message.

2.10. Title, axes and colorbar labels

Title, axes and colorbar labels can be added to the resulting map by clicking on the menu Preferences →
Title, Axes and Colorbar Labels.... All the label options are given in Figure 42. The user can also select
the label text, font size, font weight and font color.

Figure 42 – Labels form.

WARNING! The error message given in Figure 43 appears when the user inserts a label text
with an invalid font size.

18
 User Guide

Figure 43 – Error message for invalid font size.

2.11. Figure appearance and print

The user can select the figure appearance and whether or not they want to print the resulting map by
clicking on the menu Preferences → Figure Appearance and Print.... The form containing the options for
the figure parameters in given in Figure 44.

Figure 44 – Figure appearance and print form.

When a map is generated using MAP-LAB, the default option for the figure appearance is Maximized,
where the map will appear in full-screen mode. The user can change this option by selecting the Default
Size radiobutton, where the map will appear in a window. MAP-LAB has the ability to save high-
resolution images with a user-selected resolution. Clicking on the Yes radiobutton, the Resolution and
Name textboxes are activated. The resulting map will be saved as a .png image file in the current
directory. For better results, the user is advised to select a maximized window for the figure when they
choose to print a map.

WARNING! The error message in Figure 45 appears when the selected print parameters have
wrong or empty values.

Figure 45 – Error message for wrong print parameters.

19