M_Namebox: A package for names on M_Maps

M_NAMEBOX site M_MAP main-page

You have made a nice map in Matlab using M_Map by Rich Pawlowicz.

Now you're thinking of putting on some names of countries or other landmarks. Then maybe it strikes you that you've done this many times for this area, using text or gtext until your fingers get numb.

No more! :-)

Announcing M_Namebox v0.3!

M_Map now has an addition called M_Namebox, a toolbox keeping and letting you keep a database of names and their positions.

The files

The help sections of the following files are better maintained than this html-page, so please refer to the Matlab online help (or look into this list) for updated and detailed instructions.

contents.m The matlab helpfile for the toolbox
m_names.m Puts names of places on M_Maps
m_movetext.m Customization of text objects in figures
m_newname.m GTEXT-type function for adding names to an M_Map
m_savename.m Save names on an M_Map to a database
m_name_demo.m A demo of the m_name-toolbox
m_namebase.mat The main database of names and their positions
m_name_cities606.mat Database of 606 cities worldwide*
m_name_political.mat Base of 194 political place names and 318 names of populated places*
m_namebox.html HTML-documentation (this page)

Download and installation

The M_Namebox-specific site is www.nersc.no/~even/matlab/m_namebox/m_namebox.html (this page), and the files on this site will be the regularly updated. The "standard" distribution of M_Map will include M_Namebox (in the future), but not as regularly updated as here.

All files are packed into each of the file-alternatives m_namebox.zip and m_namebox.tar.gz, or you can download the files listed above, one by one (it's not that many).

The files can be put anywhere in your matlab-path since there are no references to specific directories in the code*. The best is to but them in a sub-directory since there is a contents.m-file, and this directory is best placed among the other M_Map files since this toolbox is a part of the M_Map package.


The path and name of the main m_name-database (m_namebase.mat), should be edited in the file m_names.m. Below the help section there is a customization section you can edit. There is also a minimum font-size for the names to show on map, that might have to be set right for your system.


When an M_Map of any projection or scale has been made, simply calling
puts names from the database in their right place on the map. The names might not be placed perfectly, but now you can control the positioning, size and other aspects of the strings by simple keypress:
 NUM-PAD arrows     - move text
 Home,End,PgUp,PgDn - move in larger steps
 +                  - increase font-size
 -                  - decrease font-size
 /                  - rotate anticlockwise
 *                  - rotate clockwise
 5                  - toggle object (in)visible
 b                  - toggle bold
 i                  - toggle italic
 c                  - toggle case
 w                  - word case
 l                  - toggle listbox-visible
                      (should be off when printing)
 n                  - add new name
 e                  - edit name
 s                  - save this name to mapname-base
 a                  - save all visible names on map
 h                  - help
The keys work on the current text object, which in matlab is selected by mouse-clicking on it.

The function m_names also gives a listbox where you can choose names from all available names in the area, including the invisible ones (those too small for m_names' size-limit).

After running m_names, M_Namebox primarily works as a keypress controlled "suite", but the functions are stand alone functions and have more utilities than those accessed from keyboard. Please see the documentation (help) of the functions for details, and to fully understand this toolbox.

Principle of positioning

The names are placed according to a 'between-two-points' principle: The file m_namebase.mat (or other namebase of yours) contains a database consisting of names, two corresponding long/lat-points, along with other text-appearance properties. The name is centered on the line between the lon/lat-points and font-size is chosen to make the name fill the distance between points. Thus the names are placed and sized according to the shape of country or landmark they describe, independent of the size, projection and rotation of the map. Furthermore, the names are never plotted upside-down. See m_savename on database-structure.


Whenever encountering "un-named" areas, you need to add names by yourself. After doing this, you should save the new names into the main database-file to have the new names ready for your next "visit" to this area. In some cases a specific map of yours requires a lot of adjustment of the names to look good. Then you can save these names into a special name-base-file, with a name of your choosing.

Although you can make several m_name-databases, it is recommended that you keep a well maintained default (main) database, since this is what you probably will be using every time you start putting names on a map. See m_savename for detailed instructions on building databases.

The common project of making a global database of names

If you make maps with many new names, i.e. for uncovered areas, I'd be thankful if you sent your database.mat file to me (even@nersc.no) so that I can expand the main-database for distribution with the m_names-toolbox.

Special bases

Some bases provided and collected from different sources are presented here. These are not adjusted to fit their area properly, and are therefore not included in the main database (yet). Feel free to use them when you need, but be prepared to adjust the position of the text. Whenever you have made some names fit their country or area, please send the resulting namebase-file (.mat) to me (even@nersc.no).
Sander Hulst provided this base of 606 cities worldwide. The names will be placed in the middle of the cities' positions, so a change of horizontal- or vertical alignment might be a good idea. In addition the original pinpoint-positions are stored in the third column of the names' UserData, in case You want some marks on the map.
Base of 194 political place names and 318 names of populated places.

Known problems

  1. M_names may make visible too many or too few of the names according to the font-limit for name-visibility. This limit can be set to fit your terminal, by editing the customization-section in m_names.m.
  2. When setting "NUM LOCK" on (which is best for key control) the mouse buttons no longer work on some systems. However, the same characters on the main keyboard will work just as well.


Please feel free to send any questions, complaints or suggestions to me (even@nersc.no).


Version 0.3 15-Dec-2000
The first "published" version.
April 22nd 2002
Added two new name-databases. Small changes to accomodate the additional pinpoint positions required for names like for cities.

My other functions

If you liked this, I can offer more of my functions (the ragged lot actually) in www.nersc.no/~even/matlab.html.
Jan Even Řie Nilsen [home]
Last modified: Wed Feb 25 09:14:37 CET 2004