MAP THIS! GPS MAP VIEWER FOR PSP
--------------------------------

DISCLAIMER
----------
This software is distributed under GPL license and provided for education purposes only.
It is not fully tested and therefore should be used with caution.
I shell not be responsible for any damages and/or legal problems which may arise from using this 
application & underlying hardware setup.
This software acquires image data from Google Maps online service. Please read and understand Google Maps' "Terms of Use"
agreement before using this application.

MAIN FEATURES
-------------
- Scroll through large (up to 65536x65536 pixels) maps.
- Zoom in/out. The number of zoom levels depends of on the size of the map.
- Large coverage. The program uses imagery from Google Maps, which currently have pretty good coverage of
  North America, Western Europe, Australia, Japan. Visit Google maps, to find out if they provide required 
  coverage for your location.
- Customizable map size, level of detail and coverage.
- Ability to display zipped maps (currently buggy)
- Ability to display satellite and hybrid maps from Google.
- WIFI map retrieval: ability to acquire and store map data to memory stick over WIFI
- Linux/Cygwin script is also provided to generate a map of given size and detail for a given location.
- GPS support: ability to read and interpret NMEA sentences from a GPS receiver communicating through PSP's serial port.
  Rather simple DYI hook up with GPSlim 236 receiver from Holux is explained in following thread:
  http://www.dcemu.co.uk/vbulletin/showthread.php?t=30035
  In GPS mode there are following features:
     - Speed, direction, altitude, latitude, longitude, number of satellites in view.
     - NORTH UP mode: map is displayed with NORTH always on top. The arrow in the middle turns to shows current direction.
     - TRACK UP mode: map rotates so that direction of movement is always from top down.
     - Record GPS data (captures NMEA sentences in gps.txt file for later replay)
- POI/Attractions data support. Ability to select and display different types of attractions.
- PSPSDK compatible source code provided.
  
INSTALLATION
------------

1.5  users: copy contents of 1.5 folder to ms:/PSP/GAME
1.0  use EBOOT.PBP from 1.0 folder with data files from 1.5 folder
2.0+ try using EBOOT.PBP from NOGPS folder with data files from 1.5 folder
2.7+ generate maps of up to 32x32 size with provided cygwin script and html files, 
     copy them on MS and view through the PSP's browser.

CONTROLS
--------

MENUS:

[ANALOG PAD]                    MOVE UP/DOWN; SELECT LETTER ON DANZEFF KEYBOARD
[UP/DOWN]                       MOVE UP/DOWN
[LEFT/RIGHT]                    MOVE CURSOR IN TEXT ENTRY MODE
[X]                             CONFIRM SELECTION
[SELECT]                        EXIT
[START]                         DISPLAY HELP SCREEN / START MAP DOWNLOAD ON WIFI SCREEN
[L-TRIGGER]                     TOGGLE DIGITS IN TEXT ENTRY MODE
[R-TRIGGER]                     TOGGLE UPPER CASE IN TEXT ENTRY MODE

MAPS:
 
[ANALOG PAD]                    MOVE CURSOR; TURNS OFF GPS MODES
[UP/DOWN]                       ZOOM IN/OUT
[LEFT]                          TOGGLE GPS DATA RECORDING (ONLY IN GPS MODE)
[RIGHT]                         TOGGLE NORTH UP/TRACK UP MODES  (ONLY IN GPS MODE)
[SQUARE]                        TURN ON GPS MODE (THE GPS MODE TURNS OFF WHEN YOU MOVE THE CURSOR OR EXIT THE MAP)
[CIRCLE]                        DISPLAY POI/ATTRACTIONS MENU
[TRIANGLE]                      TURN ON/OFF POI DISPLAY (TURNS OFF IF ZOOM LEVEL IS CHANGED)
[START]				  DISPLAY HELP SCREEN
[SELECT]                        EXIT THE MAP



DETAILS
-------

GETTING THE MAPS:

First go to Google maps and check if they cover the desired area @ at resolution that you want.
You'll need following information in order to get the maps for your area:
Latitude/Longitude of some location inside the desired map - these must be in decimal format.
Base zoom: 0-15; 0 being the most detailed. 
Size of a side of the map in 256pixel chunks. The map size must be equals to powers of 2, ie 4,8,16,32,64,128,256...
You map will always be square, so for example size=16 will generate 4096x4096 map at the base zoom with 4 zoom in bars.

To get your lat/lon coordinates, select _GLOBAL_MAP.zip in the main menu. Zoom in and point the
 cursor at your location on the map. The coordinates will be displayed on top. Alternatively, you
 can plug in your GPS receiver and turn on the GPS mode to find out your precise location.

NOTE: WIFI SWITCH MUST BE OFF IN ORDER FOR GPS COMMUNICATION TO WORK.

Now if you have WIFI, exit the WORLD map with [SELECT] and go to === WIFI MAP UPLOAD === option
 on the main menu. The WIFI entry form should "remember" your last position.
While choosing the size of your map, keep in mind that it may take significant amount of time to download and
 a lot of space on your memory stick.

Here is some numbers for reference:

Size 	# of 256x256pixel tiles				size on MS
------------------------------------------------------------------
16			340				~3   MB
32			1364				~5   MB
64			5460				~30  MB
128			21844				~170 MB
256			87380				~550 MB
	
You can manually zip up the small maps to save some space, but zipping maps over size 16 will slowdown the mapviewer performance.

MAKE SURE THAT WIFI SWITCH IS ON & ALL POWER SAVE SETTINGS ARE DISABLED IN PSP SYSTEM MENU BEFORE YOUR PRESS [START] 
TO START THE DOWNLOAD.

Currently, there is no recovery in case something happened during WIFI download. So if you have a weak signal, 
some map tiles may be missing or downloaded incorrectly. So if your new map does not work and/or hangs the viewer, 
try re-downloading it again or using the provided cygwin script to generate it.


As said above, you can use the getmaps.sh script in scripts directory to "generate" the maps.
To use it, you'll need to install cygwin (www.cygwin.com) - freeware linux-like environment for PC.
You can try to run it under linux too...
Make sure you have following commands installed: wget, bc
Running ./getmap.sh without arguments will print out the usage options.

Once getmaps.sh is finished you should see the new folder: _MAP_FOR......
Copy it to the maps directory on your PSP and your should be able to see in the viewer.

NOTE: all map folders and zips must start with '_' character.

Alternatively, gethybrid.sh script will generate the "hybrid" maps. In order to run it, you must install
JRE, ImageMagic and Netpbm library (all freeware). I have also put in a few sample scripts to show how to "fish" POI data from different online vendors.
Perhaps other people can enhance those and create new ones..

TESTING MAPS
------------
./testmap.sh [map size] {jpg} - creates html files for viewing/testing maps in the browser.
Just drop the files in the folder for the map that you want to test and view them trough the browser.
This technique can be used for displaying maps through PSP's browser for FW2.6+ users.
I also provided pre-made html files for regular 8x8, 16x16, 32x32 & 64x64 maps in scripts/html4testing folder  

CONFIGURATION
-------------

You can tweak some options and parameters in config.txt in system folder.
The comments explain different options...

POI/ATTRACTIONS
---------------

Each attraction type is defined in a separate file inside the applicable map folder.
The file must starts with '_' character in order to be read by the selector menu.

Data format:
[lat],[lon],[description1 38 characters long],[description2 15 char long],

You can specify a png image to be displayed as an POI icon.
The image must consist of 2 frames, lined up horizontally "cursor on display" & "cursor off display"

Format:
!IMAGE:[image name (must be png file)],[image width][image height]

Below is an example of a Gas station file:
#
!IMAGE:gas_icon.png,40,20,
#
41.003630,-74.519120,TJ Gulf; Oak Ridge, NJ,
40.596870,-74.365130,Texeco; Edison, NJ,
39.795585,-75.040591,Super Wawa GasStation; Blackwood, NJ,
...................................

Attractions are only loaded for the area, "visible" on the screen.
You'll need to "reload" attractions with [TRANGLE] if you move away from that area of zoom in/out.
The program only displays up to 1000 POIs at once. If you current map segment contains more than
 1000 POIs, the viewer displays a message asking to "zoom in" and try again.

Attractions are not displayed if "TRACK UP" GPS mode is enabled.

KNOWN BUGS, PROBLEMS
--------------------
- Hybrid jpg maps sometimes don't load in unzipped state. If this happens, try zipping them.
- zip implementation has a memory leak, which may hang the program after a few loads of zipped maps.
- WIFI part has no retry/correction logic for dropped requests. It is advised to use provided scripts instead of it.

Enjoy,

DENIS



























	
