Program Grmapa

Version: 1.02 beta3

author: Grzegorz Zlotowicz

License: freeware.

### What is Grmapa?

Grmapa is a computer software ,making possible nonvisual browsing of geographic maps with text and sound, instead of graphic. Program works under Windows operating system. It requires a sound card, and screen-reading software for blind users. Currently Grmapa communicates with NVDA, Jaws for Windows, Window-eyes, or - if none of above is running - texts are spoken via default SAPI5 synthesizer.

After program installation, maps of interesting areas are needed. Maps can be imported from OpenStreetMap project, or - in Polish language version - downloaded using "Download map..." Grmapa function.

Grmapa map file contains 3 categories of geographical informations: points, lines and areas. Points are most frequently roads intersections, and so called points of interest: shops, banks, restaurants, etc. Lines are paths, roads, rivers, boundaries of regions etc. Areas are e.g. forests, lakes, larger rivers, parkings, factories etc.

### Launching program

After launching the program, random presentational sound is played in left speaker. It's some sort of intro, but - more importantly - test of correct setting of speakers. Sounds in Grmapa are placed spatially, so inverse setting of speakers or headphones, would misguide user. This test can be repeated in any time, using "Which left speaker" function from Sound menu, or pressing ctrl+k shortcut key. Playing sample sound can be interrupted by calling any program function.

If left speaker is heard to the right, and moving the speakers would be too problematic, there is a possibility of quick inversion of sound channels using the "Exchange channels" function from sound menu (ctrl+i). Next step is to load map using "Open map" function from Map menu (shortcut ctrl+o). List of installed maps will be displayed. Select one, and press Enter or click OK button. Next, the "Select start point" window will appear. In the edit field, we can enter part of point or street name, where we want to start map exploration. All points and intersections on selected map are searched, and after some time - there will be a list of found places. After selecting one of them, program will move us there. If in any moment we want to change start point, we can do so by using function "Select start point" from Map menu. It's best to start using Grmapa on known areas, which will let to familiarize ourself with Grmapa's way of presenting space.

### Import from OpenStreetMap

Openstreetmap.org is a world map created by international community, available on ODBL license.

Grmapa makes it possible to import OSM data in two modes: import from file, or from server. Import from file: - XML files are supported, having name extension .osm or .xml.

Binary PBF format, or XML files compressed in bz2, are not supported. On the internet (e.g. on geofabrik.de server) data dumps of all countries, or regions can be downloaded in osm.bz2 compressed format. Most probably, whole country import will take ages, and will not work correctly: Grmapa is not optimized to work on such large maps.

Import from server: More practical possibility, using XAPI interface available on few servers, makes possible to import any area. After setting up the start point and import radius for import, requested area is downloaded and imported. When import radius is long, and/or area is densely populated, downloaded data can reach hundreds megabytes and overload the server, So you should carefully use this feature. Known problems: Currently import doesn't support relation informations contained in OSM data.

There are objects displayed as lines that should be areas, or objects without type (the issue of missing import rules requiring supplement). Information on such "unknown" objects are indirectly available in object tags. OSM data do not include information about the level of significance of the object, which is crucial for filtering objects at high zoom levels. This parameter definitions are also a matter of supplementing the rules of import.

### Delete map

If we downloaded some maps, which we do not need anymore, we can get rid of them using "Delete map" function from Map menu. After selecting one of map from displayed list and confirming operation - map will be deleted.

### Navigation

Virtual space of loaded terrain can be compared to giant chessboard. Each of its' box is a square which side is 10 meters long. User's direction is north. Using arrow keys moves one square in choosen direction: Up arrow - to the north, Left arrow - to the west, Right arrow - to the east, and Down arrow - to the south.

Few squares around user are illustrated by sounds, so it's important to have speakers or headphones properly positioned. Objects placed to the left of user, are heard in left speaker, object to the right of user - in right speaker. Quieter sounds mean further objects. Objects behind user, are played a bit lower than other, which introduces a new dimension in space presentation, but perceiving it may require a bit of practice in using program.

Initial volume of sounds is set at very low level, to avoid situation, that program sounds will make a speech impossible to hear, leading to losing control of computer by user. Volume can be changed in any time using Pgup and Pgdn shortcut keys, or commands from Sound menu. Muting speech can be achieved using Ctrl+space shortcut key, or command from Sound menu.

To hear all sounds which can appear on a map, we can use a "All sounds presentation" command from Sound menu.

Name of object on current square is automatically announced by used screen reader. If it's not enough information, using Space key , we can hear more, e.g. object type, city, region etc.

If we're located at line, for example road, direction of this line is automatically spoken. Direction of line can be repeated at any time using slash (/) key.

### User direction

Initial user direction is north. It can be changed at any time using "Navigation" menu, or keyboard shortcuts: Left and right arrows pressed with Control key, are turning user by 90 degrees to the left or right. Left and right arrows pressed with shift key, are turning user by 15 degrees.

After changing user direction e.g. to the west, directions of moves using arrows will also change: Up arrow - west, left - south, down - east, right - north.

Current user direction is announced after pressing dot key (".").

### One square size

Initial one square size set to 10 meters, can be changed in range from 2 meters (maximum accuracy) to 10 kilometers (viewing huge areas). Square size can be changed in Navigation menu, or by shorcut keys ctrl+pgup and ctrl+pgdn. There is also possibility of quickly switching to biggest square (Ctrl+Shift+Pgup) and smallest one (Ctrl+Shift+Pgdn). Announcing current square size is available after pressing "," key.

### Height level - third map dimension

Information about relative height level of object gives knowledge about relations betwen roads, when one runs above other. Height levels are numbered: 0 - ground level. -1 - road partially below ground. -2 - tunnel. 1 - bridge. 2 - viaduct. When height level changes, corresponding sound is played, and program announces current height level after name and direction of way. Manual announcement of height level is assigned to h keyshortcut .

### Navigation using mouse

Using arrows to move around the map is not only method of navigation. Second one is navigation using mouse or touchpad.

It allows to change position more intuitively.

For user convenience, additional operations can be easily performed: Single left-button mouse click announces the type of currently focused object, double click announces direction of object (if it's a line), triple click automaticaly inserts bookmark at current position, without asking for bookmark name entry.

Navigation using mouse is disabled by default, and can be switched from the Navigation menu, or using shortcut key ctrl+y. After enabling this mode, the system mouse cursor becames invisible. It is impossible to point or click mouse in other windows, because Grmapa captures all events of this device and doesn't forward it to the operating system. After switching to an other window using keyboard, mouse will work normally, but after returning to Grmapa, mouse will be captured again. After disabling navigation using mouse, cursor and operation of mouse will be restored, also in Grmapa window.

### Setting mouse sensitivity

To adjust mouse sensivity to user's needs, Grmapa offers the command "Change mouse sensitivity". It is available only if navigation using mouse is enabled. Quick shortcut key - Shift+y. In edit field of opened window there is an instruction text. Moving mouse to the left decreases one square physical space (increases sensitivity). Moving to the right - increases square physical space (decreases sensitivity). Move up/down - checking sensitivity without change. Single left button click - announces the sensitivity value.

### Objects in area

Program announces the name of current object, and sounds ilustrate few squares around the user. If we want to know more about further area, it is possible using commands from "Area" menu, or shortcut keys: p - points, k - intersections, i - addresses, l - lines, o - polygons, or j - everything, function combining results of all previous.

Area is relative, and depends on the current single square size. If the square size is small, it will be box measuring few hundrets meters in each direction; if the square size is big - it'll measure hundrets of kilometers.

Question for keywords can be ignored by pressing Enter and leaving edit box empty - listed will be all objects, without searching by keywords.

### Go to coordinates

If we want to go to some known geographical coordinates, it's possible using the apropriate Navigation command or Ctrl+g shortcut key. Enter decimal latitude and longitude separated by space, and press Enter or OK button. Program will move us to selected place and we can explore it, if given coordinates are covered by currently opened map. Instead of coordinates in the edit box we can paste anything (e.g. internet link), or another text, which contains decimal latitude and longitude, and Grmapa will try to get the coordinates.

### Checking program update

Command "Check program update", is available in Help menu. It checks if server contains newer version than currently running. If so, an invitation to visit Grmapa homepage will be displayed.

### Switching sound card

Grmapa generates sound through default system playback device. If we have installed an other sound card, we can switch Grmapa to use this one. Open menu "Sound". Open "Switch sound card" dialog. Select playback device from the list and click Ok. Program will automatically play the left speaker test on selected device.

### Changing the direction announcement mode

Since version 0.94, Grmapa offers few direction announcement modes. Clock face relative to the north, and relative to user direction, degrees relative to the north and to the user direction, simple compass (8 directions) and advanced compass (32 directions). Mode change is possible in the Settings menu, "Direction announcement..." command, or ctrl+. shortcut key.

### Bookmarks

Bookmarks are user-defined orientational points, having geographical coordinates and name. Can be useful during map exploration, for defining some places we want easily return to, or for marking stages of planned route. All bookmarks operations are available in Bookmarks menu, or shortcut keys. Enter - Inserts new bookmark, or edit existing one. When new bookmark is inserted, program suggests its name consisting of the number, and name of current square. If current square is empty - "Point" will be default name. Name of bookmark can be freely modified before confirmation. Delete - deletes bookmark. u - opens list of all currently defined bookmarks. Bookmarks can be saved to disk in Loadstone-gps file format. Such file can be copied to phone and used in real navigation. Some programs can import Loadstone-gps database text file, and not checkpoints file. It's possible to switch bookmark save format in the settings menu. Settings must be saved, to have bookmark save format set permanently. Bookmarks saved by Grmapa or Loadstone-gps software, can be loaded using ctrl+l keyboard shortcut. Ctrl+c keyboard shortcut copies last saved bookmarks file to clipboard in such a way, that it's possible to paste it in the file explorer window. Menu Bookmarks: "Open folder" command, opens folder of last saved bookmarks file, and highlights this file, so it's easy to open context menu, and run the "Send to bluetooth interface" then.

### Additional bookmarks list operations

If bookmarks are defined for reference, their order can be meaningless. It becames important, when bookmarks define route. In most cases, they're added in correct order, but after some modifications, bookmarks order may be broken.

To manually move bookmark on list, user has "Move bookmark" command (ctrl+u shortcut key). On displayed list of all bookmark, select one which you want to move. Next, on displayed list, select position of bookmark - it will be placed above selected one. On this second list, we can select last position called "end of list", to place moved bookmark at the end.

If all bookmarks names are prefixed with numbers, command "Sort bookmarks numerically" (ctrl+u shortcut) lets set bookmarks order automatically.

Finally if we have a route composed of bookmarks marking next stages of route, we can calculate length of such route using "Bookmarks distance sum" (m shortcut key) command. The sum of bookmarks distance is calculated assuming that each next is in a straight line from the previous one, which may turn out to be rather simplistic example.

If you made some operations on list of bookmarks, after which the numbering became invalid (e.g. Removing or inserting bookmarks), you can correct numbering using Bookmarks: Renumber bookmarks command. Program asks to enter first bookmark number(default 1), and each next bookmark gets the number one greater than previous bookmark. If bookmark had a number at the beginning of name, it is firstly removed. Entering initial number greater than 1 can be useful if we plan to add further bookmarks at the beginning of route.

### Starting position

The starting position is a specific place on a specific map, from which you want to always start the adventure with Grmapa. It is loaded automatically when you start the program, but some movement using arrow is needed to hear the background noise. This is necessary, otherwise left speaker test would not be heard. Using "Map: Save starting position" we can write the current position as starting.

Manual jump to starting position can be achieved using Map: "Load starting position" command.

### User settings save and load

Using the command Settings: Save the user settings, you can save the current settings, which will then be automatically loaded every time you start Grmapa. Stored are: - volume level; - Mono mode; - Sound mute mode; - Inverted speakers mode; - Playback device name (if other than default); - checking update at startup; - Use mouse mode; - Mouse sensivity. To manually restore the saved settings while working with the program, you can use the command Settings: Load settings. Settings are stored in a user.ini file in program folder.

### Automatic checking of updates

Automatic update check at startup command in settings menu allows to enable checking availability of new Grmapa version. After switching this option, settings must be saved to take effect during next program run.

### GPS: log playback

Since version 0.95 Grmapa lets play GPS log, saved in NMEA format. Such log can be generated e.g. in Loadstone-GPS software, using "Start logging" function.

Playback of log in Grmapa starts after selecting log file in "Open log" command in GPS menu. Program announces changing user direction and position. Position changes lesser than current square size are ignored. Otherwise, current square will be changed, sound of user move will be played, and new direction and square name will be announced. Log playback can be paused, which lets easily explore neighbourhoot of current position.

Current position in log can be scrolled shortly (by 10 seconds) and long (by 1 minute), and to the beginning or end. in "omit stops in NMEA log" mode, available in settings menu and enabled by default, playback is 20 times faster on events, which not caused change of position. Review of points, lines and polygons in area is possible without pausing GPS - log is automatically paused while object lists are displayed.

in "Say" menu there are additional useful functions of announcing current GPS receiver state, such as number of satellites, or current GPS time. Time is announced in UTC.

### GPS: device connectivity

Connection of Grmapa and GPS device works similar to log playback, but in real time. It's possible after pairing bluetooth GPS receiver and the computer using system tools. After successful installation, GPS receiver will be available in bluetooth devices. In device properties window, on the "Services" tab, list of serial ports of receiver will be presented. Incoming port, and SPP slave (outgoing) may appear there. We're interested in the outgoing one, e.g. com9. After selecting GPS: Connect device... in Grmapa, program asks to enter serial port number. Enter acquired previously port number (without com prefix) e.g. 9 digit. Connecting to device can take a moment. If successful, commands announcing time and satellites number, will give real information. Jump to current position on the map will take place, when current position can be acquired from receiver. If however the error number will appear, it may mean few things: Error 2 - bad com port number was given. Error 121 - port number is correct, but receiver is not connected. Other error numbers (e.g. 1321), or above errors in case of proper connection and port number, may mean Bluetooth technology problem. In such case we can try: - Select "Allow incoming connections" on the Bluetooth icon context menu; - Restart Windows; - Unpair GPS receiver and pair it again; - Disable and enable com port on Services tab; - Quick reinstallation of Bluetooth driver (most reliable results in my tests). Unfortunately, even after successfully establishing a connection, it can be unexpectedly broken (I observed such behaviour under Windows 7 and 8.1).

### Known problems and missed features

English language translation is initial, so please report all language errors.

Grmapa installation directory must be writable for program (please, don't install this version in program files folder).

Map rendering on 180 meridianand on poles, needs to be improved.

Addresses (category of points) are not recognized during import from OpenStreetmap.org.

Height levels in Openstreetmap imports need improvement.

Most wanted feature: line explorer: a possibility of exploring lines in more intuitive manner.

### Grmapa versions

Grmapa is released in two versions: stable and beta. One or more beta versions appear before stable version.

Users of beta version can early report found bugs, which will be fixed in the next stable version.

Last beta version is functionally identical to next stable, e.g. 1.0 beta4 is identical to 1.0.

If you are using a beta version, there is no need of upgrading to next stable. Also, such upgrade would cause that only next stable versions will be announced in update checking function. To have possibility of checking updates of beta version, use last beta.

Beta versions will appear more frequently, but can contain new and unstable features, so are rather dedicated for more experienced users.

### License and thanks

Grmapa is freeware. Author takes no responsibility for improper work of program.

Sounds come from www.freesound.org website .

Import map function uses map data of openStreetMap.org project.

Communication of Grmapa with Screen-reading software is based on Universal Speech library - Copyright 2011-2012, Quentin Cosendey http://quentinc.net/

Sound playback is powered by Openal-soft (http://kcat.strangesoft.net/openal.html).

HRTF profiles prepared with data provided by (http://recherche.ircam.fr/equipes/salles/listen/index.html).

Grmapa databases are managed by SQLITE (www.sqlite.org).

Internet connections use Curl (curl.haxx.se/) and Curlpas interface (curlpas.sourceforge.net) to this library.

Compression powered by 7-zip (www.7-zip.org, GNU LGPL licensed archiver), decompression uses 7z.dll library, part of 7-zip, and sevenzip interface (code.google.com/p/d7zip/) to this library.

### Contact

Questions, comments, bug reports, and improvement suggestions regarding Grmapa can be send via e-mail to grzezlo@wp.pl.

### Development history

### Version 1.0 released on 2016-03-03

First multi-lingual version.

Grmapa initially translated to English.

Added Serbian translation by Gradimir Kragić and Dragan Miljojčić.

New function: go to QTH location (shortcut key ctrl+q). Can be used to view users' current location in Maidenhead system coordinates, or move to specified position given as QTH. Grmapa accepts locators of size from 4 to 8 characters. Displayed QTH locators are always 8 characters long. After accepting entered QTH locator, user will be positioned at the center of specified square.

Week days are now correctly displayed in weather forecasts.

Corrected bookmarks loading and saving functions.

During program startup, maps directory is created if not exists.

After importing from OSM and confirming opening of imported map, user is positioned at the import start point.

### Version 1.01 released on 2016-08-06

Import from OpenStreetMap: corrected error occurring during import process.

Fixed program freeze in searching start point dialog, when used map contained small amount of points.

OpenStreetMap import: after import from file, user is positioned at calculated center of map.

Bookmarks loading: utf-8 BOM header in files is now processed properly.

Bookmarks loading from Loadstone database text file: headers, empty lines and lines with comment are better handled.

Go to coordinates: corrected error when more than 6 digits were given after a dot in coordinate.

Documentation: explained difference between stable and beta version.

Start point selection list: type of result (area or line) is now translatable.

### Version 1.02 released on 2016-09-02

Corrected bookmarks saving as Loadstone database text file.

Import from OpenStreetMap: after import error, temporary file is properly closed, so next try doesn't cause file creation error.