PH GMap

Probe House Software
by WongCK
© Copyright 2012

Version 1.7

What is this?

PH GMap brings Google Maps to the Atari. You will be able to zoom in and out of the map from building all the way out to the continent. You will also be able to move around the map. Road maps and Satellite view along with hybrid view where road maps are superimposed on the satellite view are all available. With Street View, you will be able to have a virtual drive in your Atari. With routing, you can plan the route to take your Atari on.

PH GMap is freeware.

Requirements

This runs on MINT with MintNET and requires an internet connection. Development was done on Mint 1,18, while lower MINT versions are not fully verified/tested on.
You also need to have zView's JPG codec, by Zoro, installed. All codecs are available from zView package (latest release 8).
The zView codec package requries a VDI with EdDI support. This is available in NVDI, NovaVDI, fVDI etc.

A colour display will be nice, but you can run it on lower colour system like 16 - may be the road maps looks OK but the satellite view... well you decide. As I have not tried running at low colour, I have no idea how it looks like. Recommend that you use at least 256 colours to see something useful.

Installation

Make sure you have Mint and MintNet is running well, otherwise install and configure Mint & MintNet.
Extract and copy all the files into a folder of your choice. For example c:\phgmap.
For FireBee, replace the program with the one inside the FireBee folder
Copy all zView codecs into C:\GEMSYS\LDG\CODECS folder. Create that folder if you do not already have it.
Double click phgmap.prg to run it !!

The Main Window - aka Map Window

The main window displays the map
The info line display final address of the location
The info line will display the status of the map download and map conversion
The ZOOM number is displayed on the upper left corner of the map.
The Window can be resized, the map will cover the whole window until a maximum size of 1280 x 1280.
The window size cannot be bigger than 1280 x 1280. If it is, the window will bounce back to the maximum of 1280 x 1280.

Note: sometimes the main window will display a blank image (grey or black). This normally happens when the map quota has reached.

Configuration Menu

Right click on the map window for a popup Configuration menu.

Select Enter address to get into the Address Window (see next section)
Select Reload map to refresh the map. You may also press ESC to reload a map.
Select Favourites to open the Point of Interest Window. You can store up to 50 points of interest locations.
Select Markers to open the Point of Interest Window - Markers view.
Select Route path to open the Route Window. You can make routing using the markers or via a GPX file.
Select Road Map to display the map as a normal road map
Select Satellite to display the map as a satellite view of the map
Select Hybrid to display the map with a superimposed road map on the satellite view
Select Quit App to exit the application
The About displays.... well, the about of the app

On each startup, you will be reminded to right click to enter an address.

Address Window

Enter the location (city name/landmark/street address) of which the location you want to view.
1. The spelling of the location need not be accurate, but it helps if it is.
2. You may need to provide more location information, such as country, to identify a location.
3. The location displayed is an approximate location of the street address.
4. The map zoom will default to 14 to avoid confusion when the new map is displayed.

Movement and Zoom

Using the keypad to move

Movement and zooming controlled on the number keypad are as follows.

To zoom in, use the + key on the numeric keypad.
To zoom out, use the - key on the numeric keypad.
To call the Address Window from the keyboard, press the * key on the numeric keypad.
To call the Point of Interest Window from the keyboard, press the \ key on the numeric keypad.

North-west 7	North 8	North-east 9
West 4	Starting point 5	East 6
South-west 1	South 2	South-east 3

Using the mouse to move

Click anywhere on the map to make that point the center of the map.
You can also drag the map to move it along - a small square box is your visual que, the actual map is not draggable

Click anywhere on the map and hold the mouse button.
Drag the mouse, keeping the button pressed, to another location on the map.
Let go and the map will move. The point where it was first clicked will be "dragged" (moved) to the point where you let go.

Using the Scroll bar to move

Movement controlled on the mouse as follows.
1. Click on the arrows buttons to move about 25% of the map in the direction of the arrow. This is the same as using the keypad.
2. Click on the darkened area of the scroll bar to move about 80% of the map. This is equivalent to a page. There is no keypad equivalent.
3. The scroll bar itself cannot be move and does nothing when you click or drag it.
4. You can resize the window using the resize button. After resizing, make a move to force it to redraw to use the new window size.
5. Users with mouse wheel, try it and see if anything happens.

Markers

PH Gmap allows up to 9 labeled blue coloured markers to be placed on the map.

To place a marker on the map, press SHIFT and left click on the location you want to mark. You can place up to 9 markers.
To see the address of the place before you mark it, press CTRL and left click on the location. The address will be displayed on the Window Info line.
Markers are numbered 1 to 9 for easy identification.
Jump to each drapped marker by pressing the corresponding function key number. For example, to jump to marker 1, press F1.
To remove a marker, press SHIFT and the corresponding function key number. For example, pressing SHIFT-F3 will remove marker 3 from the map.
To review the markers adrress quickly, you can press "M" to scroll through the location of the markers. This is displayed on the Window Info line.
The markers locations are saved in the configuration file when you quit the program and are loaded back the next time you start the program.
Accuracy of determining the point via mouse click is affected by the placement of the map within the window. Earth arc formulae also played a part in accuracy calculation. As such some places may be out by some factor.

Point of Interest Window - Favourites and Markers

Up to 50 points of interest can be stored for easy retrival via the Point of Interest Window. With 9 possible markers, this gives a total of 59 storable locations.

To store a location as a point of interest, press ALT and left click on the location in the Map Window.
The location will be stored under the Favourites section.
To jump to your favourite location, highlight the location and press GO, or just double click on the name in the list.
On the map, the location will be marked with a RED flag with a "F" on it
To remove the location from the list, highlight it and press REMOVE on the Point of Interest window.
Switch between the Markers list and Favourites list by selection the relevent category
Accuracy of determining the point via mouse click is affected by the placement of the map within the window. Earth arc formulae also played a part in accuracy calculation. As such some places may be out by some factor.

Route Window - Routing with Markers

Markers are used to mark the start or origin location and the destination location. The route is marked out on the map via Google.
In the Route Window, the Origin Marker, Destination Marker and the Travel Mode is selected. Click on GO button to get the map.
The actual route is provided by Google and is displayed on the map.

The map is centered at the origin location. You may need to move the map to see the rest of the track.
The map type will be automatically change to suite the travel mode - for example, walking & bicycling will select the terrain map. Driving will change to roadmap.
The route on the map will show as long as the Route Window is opened. If the Route Window is closed, the next map request from Google will not have the route trace.
Distance is calculated once the map data (graphics) is available for display .

Route Window - Routing with GPX file

A GPX file contains GPS information of a trip. The GPX file contains a sequence of location travelled. These locations can be traced out on a map. A GPX file may contain 2 types of tracking information - route points and track points. Either can be used, and if they are not present, no trace will be drawn.
In the Route Window, select the GPX file as the input type.
Click on File button to pick the GPX file of display. On leaving the file selector, the map will be retrieved and the track lines will be drawn.

A blue dot marks the start/first location of the trace. A Red dot marks the destination/last point of the trace. The route itself is drawn in yellow.
Due to approximation of the location on the bitmap to actual location, there may be error in ploting the start, end and trace on the map.
The software is limited to 2048 location points - it will only read the 1st 2048 points in the GPX file.
The map is centered at the origin location. You may need to move the map to see the rest of the track.
The route on the map will show as long as the Route Window is opened. If the Route Window is closed, the next map request from Google will not have the trace information.
Distance is calculated once the map data (graphics) is available for display.

Street Views

Street Views is a technology from Google that provides panoramic views from positions along many streets in the world.
To view the scene of a particular road, DOUBLE CLICK on the road in the Map Window. The Street View Window will open and show the panoramic views of the street.
A RED DOT on the Map Window shows the location of the panoramic views on the map. A yellow pointer points to the direction where it is looking at.

The Street Views Window can be resized to a maximum of 640 x 640.
To move along the direction of the road, click in that direction on the photo.

To move straight, click around the centre of the photo.
To turn left at the junction, click at the left side of the photo.
To turn right at the junction, click at the right side of the photo.
The further you click from the centre, the larger the turn will be.
Note: This is turning while moving forward at the same time, like driving a car.

To turn without moving forward, drag the photo left or right to look left or right respectively.
To look up or down, drag the photo up and down to change the pitch of the camera
Use the mouse wheel to zoom in and out of the photo
Due to approximation of the location on the bitmap to actual location, there is error in ploting the red dot marker, so it may appear to go on to building.
You are allowed to move anywhere on the map, beware that sometime, there are no photo from Google, so it turns grey and you do not know where you are going.

Summary of commands

What	How to...( on Map Window)
Center map to a point	Left click on any point on the map.
Moving a point on the map	Left click, hold and drag that point to a new location.
Find out the address of a point	CTRL-left click on the map. Address display on Window info line.
Dropping a marker	SHIFT-left click on point to drop the marker.
Jump to a marker	Press corresponding function key number e.g. F4 jumps to marker 4.
Delete a marker	Press SHIFT & corresponding function key number e.g. SHIFT-F4 will delete marker 4.
Review markers	Press "M" to cycle through where the markers are. Addresses are display on Window info line.
Making Favourites	ALT-left click on point to save that location into the Point of Interest list.
Call out configuration menu	Right click anywhere on the map
Call out address entry dialog	Select from configuration menu or press * or C on the keyboard
Call out Point of Interest window	Select from configuration menu or press \ or F on the keyboard
Call out Route window	Select from configuration menu or press R on the keyboard
Move around map	Use the scroll bars or the numeric keypad as directions
Zoom in/out	Press + to zoom in. Press - to zoom out. There may be another way to do this.
Reload a map	Select from configuration menu or press ESC to reload a map
Home to original point	To go back to the original location as in the address entry dialog, press 5.
Change map type	Change the map type from road map to satellite via the configuration menu.
What	How to...( on Street View Window)
Street Views	Double click on the location on the Main Map Window.
Street Views - move	Click on the Street Views Window the direction you want to move in.
Street Views - turn	Drag the view to the left or right in the Window.
Street Views - pitch	Drag the view up or down to look up or down in the Window.
Street Views - Zoom	Use the mouse wheel to zoom in and out of the view.
What	Global keyboard shortcuts
CTRL-Q	Close all windows and quit PH Gmap.
CTRL-U	Close the top windows. If you close the map window, it will also quit PH Gmap.
CTRL-W	Cycle through the windows.

Error 403 and 503... Quota Exceeded errors

These are error condition that means the Google maps download quota have been reach. Even when you have not downloaded that many maps, it may be a combined quota with other users that are using your ISP. There are some people who speculate that this is a bug in Google's calculation, we cannot be sure. In any case, if you see this error in the infoline, you just have to stop using the map app for several hours ( between 2-6 hours) before Google resets the count. There's also some talk on the forums that Google limits 250 maps download every 6 hours.

Note that there's also quota limitation on StreetViews. The quota reaches quickly on streetviews as it downloads more. Normally you do not notice it while moving around.

Config and working files

The config file is called phgmap.cfg located at the same folder of the app. It is created by the app itself on exit. Information of the map settings are stored along with address information. There is no impact if you decide to delete this file. However, your saved markers and favourites will be lost.

The actual graphic file of the map is in gmap.png. It's normal PNG file. There is no impact if you decide to delete this file.

Limitations

Google maps is a free service, so Google controls the number of maps downloads per ip address.
Currently Google maps docs states that the limits is 25,000 maps downloads. Note this a based on ip address, which means that if your ISP uses a NAT to get to the internet, Google will only see one ip address for all your ISP users. This quote can be reached very fast if lots of other users uses Google maps.
Google will also throttle map downloads if the download exceeds 50 per minute. Again if you ISP uses a NAT, you will face this issue.
There's also some talk on the forums that Google limits 250 maps download every 6 hours. This seems to be likely along with the throttling.
Long internet latency or networking delay makes the app unresponsive. It looks hung, but it's not, it will come back.
For some locations, mispelled name may not be corrected.
Due to model equation of earth surface/arc and approximation used in this program, the accuracy of pinpointing locations via clicks are affected when distances between points are great.

Version updates

v1.1: Firebee native CF version
v1.1: Use nicer looking name for the application in menu/taskbar etc.
v1.1: Use internal MINT ramdisk as temporary JPG file location, hopefully will increase speed.
v1.1: Added window resize and use scroll bar to move the map
v1.2: Resize fill in entire window with map until a maximum of 1280 x 1280 where it will not stretch any more
v1.3: Auto reload map when window is resized. Limit window size to 1280 x 1280.
v1.3: UTF-8 support
v1.3: Navigation improvement - Click to center map & drag to move map
v1.3: Markers implementation
v1.3: Fixed downloading / conversion messages to better represent what it is really doing
v1.3: Fixed floating point calculation/conversion that resulted in going to mid Atlantic !!
v1.4: Added cursor key UP/DOWN to support mouse wheel on the FireBee.
v1.5: Added Streetview and Point of Interest window for Markers and Favourites.
v1.6: Added routing for markers and GPX file.
v1.6: Added Maptype terrain.
v1.7: Safeguard against opening window outside of screen size.
v1.7: Added Marker calling into Configuration menu.
v1.7: Reworked Marker router in Route Window for easier named marker selection.

Future developements

none.

Questions, comments, or error reports? Please leave a post at Atari-Forum.com
Visit my web site at https://sites.google.com/site/probehouse/