Map Image

This application displays images that represent maps. To be useful the maps must have an associated calibration file that assigns the latitude and longitude for the pixels of the map. The current location can then be displayed in Map Image, showing where the user is on the map. The user must supply the image and the calibration file and put them in the app's Image Directory.

The images can be large as they are implemented by tiles. (See the Acknowledgement.)

The application does not use a data connection and so can be used in locations where there is no connection, such as out in the woods. It also does not run up data charges.

Operations

You may zoom the image out using two fingers and pan using one or two fingers. Double tap toggles zooming in and restoring to the default size.

If the double tap is performed so the second tap is held down and moved, then instead of restoring to the original size, you can continue to zoom in and out about that point with the one finger as long as it is held down. This is similar to a feature of Google Maps.

The app remembers the image and the last zoom and pan values when it exits, so that it should come back to where you left it when it resumes. It also remembers if location was being used.

Permissions

As of Andoid 6.0 (API 23, Marshmallow), permissions requested by an application do not have to be accepted on installation. They can be added or revoked at any time by the user. The application must check whether it has the permissions every time it needs them. Map Image requires permission for FINE_LOCATION in order to use location. It will prompt for this if not granted, or you may change it yourself in the system-wide Application Manager. Map Image will still run and show the maps even if this permission is not granted, but it will not show the current location.

Map Image also requires permission for READ_EXTERNAL_STORAGE. You should always grant this as the purpose of Map Image requires reading user-supplied files. In the event you do not, you will be prompted once every time Map Image is started, unless you ask to receive no more prompts. Location is disabled when there is no permission for READ_EXTERNAL_STORAGE.

If you have asked to get no more prompts and you now want to change the permissions, do it manually in the system-wide Application Manager.

Calibration

The calibration is specified in a text file with lines of the form:

integer x, white space, integer y, white space, decimal longitude, white space, decimal latitude.

These can optionally be followed by:

white space, then a comment.

x and y are the pixel coordinates in the image, starting at (0, 0) in the upper left and ending at (width-1, height-1) in the lower right. There must be at least three such lines, but there can be as many over this as you like. The app will find the best fit to all the values specified.

The user must create the .calib file by knowing the latitude and longitude for points in the image. These could be the corners or landmarks.

One way to determine these values is by placing the image as an overlay in Google Earth (Add | Image Overlay) then adjusting it to match up with what is displayed in Google Earth. You can then put placemarks on the corners and get the latitude and longitude from the placemarks. Use Add Placemark and move the pushpin icon so the point is at each corner in turn.

This is an example of a calib file corresponding to an image of width 832 and height 1079. (The calibration points are at the corners in this case):

   0     0   -83.603411    42.642879 NW
 831     0   -83.568607    42.643245 NE
 831  1078   -83.568255    42.609770 SE
   0  1078   -83.603059    42.609404 SW
 

Image Directory

The image directory is named MapImage and will be on the internal SD card by defaut. It can be set from the menu in the activity where you choose a new image, and you can choose to set it on the external SD card if there is one. You can also have several and change them via this menu item.

The maps must be put in this directory by the user. Any image format accepted by Android may be used. PNG or JPG are most common. In addition, in order to use location, there must be a file with the same prefix, but with the suffix .calib. This file must contain the calibration information.

Menu Items

New Image

Allows you to pick a new image among those in the image directory.

Image from Location

Checks all the installed images to see if thewy include the current location and allows you to select one.

Start Location

Start using location. Starting and stopping location allow you to save battery if desired. The cursor only shows if you are using location and there is a valid location. You do not have to turn off location before exiting. It is turned off when the app exits, and it is restored to what it was before when the app resumes.

Stop Location

Stop using location.

Set Update Interval

Set how often the location is updated. Choices are Fastest, Fast, and Slow, corresponding to 0 sec, 1 sec, and 6 sec. The system may not update as fast in practice as specified.

Info

Shows information about the image including its path in the file system and image size, information about the screen size and density, the calibration numbers, the location if it is available, and if the location is within the image.

Reset

Re-scales and centers the image. This can also be accomplished by double tapping the image.

Help

Displays this page.

Acknowledgement

The scaling, zooming, and panning in the View is based on the work of Dave Morrissey.

https://github.com/davemorrissey/subsampling-scale-image-view/wiki