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.
Your location is managed through the MapImage Location Service. This service runs when location is started and stops when location is stopped. (See the Start / Stop Location menu item below.) It runs even though the device is turned off or you go to another application. It exits only when the application stops, usually via the Back button.
For later versions of Android, there should be a notification in the Notification Bar when it is running.
When location is started, there is a marker on the image for your current location. You can also optionally show your track on the image. See the Start / Stop Tracking menu item for more information.
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.
Map Image supports Android 10 and higher. It requests permissions for FINE_LOCATION, COARSE_LOCATION, and FOREGROUND_SERVICE. These permissions can be added or revoked at any time by the user. Starting with Android 12, the user has the option of selecting either Precise (FINE) or Approximate (COARSE) location. FINE location is needed for meaningful use of Map Image. It will prompt you on start up if it is not granted. If location is not granted at all, you can still view and manipulate the maps, but showing your location and tracking will not be available. Without FINE location, tracking and the location indicator will be inaccurate.
Map Image will prompt for location if not granted. It must do this using a dialog provided by the operating system. The dialog varies with the version and does not always appear. In particular it will not appear if you have selected "Don't ask again". It does not prompt for FOREGROUND_SERVICE. That should be granted automatically. It needs a foreground service so you can continue to track with the device turned off.
The granted permissions are shown in the Info menu item. In the event you end up with the wrong permissions, you can set them manually in the system Settings under Apps. On some devices you can tap hold the desktop icon, and an info icon will appear. This will take you to the correct place to do set the permissions manually..
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 place marks on the corners and get the latitude and longitude from the place marks. 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
The image directory is the directory where all your images and calibration files are stored. You need to allow MapImage access to this directory by selecting it in a system file chooser. You do this with the "Get Image Directory" menu item. The directory can be on the external SD card. You can use this to switch to different directories with different images, if you like.
The maps must be put in this directory by the user. PNG, JPG, and GIF are accepted. 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.
Allows you to pick a new image among those in the image directory. This item may appear as an icon on the title bar.
Checks all the installed images to see if they include the current location and allows you to select one.
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. When location is stopped, the MapImage Location Service is not running.
When the MapImage Location Service is running ad tracking is started, MapImage stores locations and shows the GPS track on the image. When tracking is stopped, it no longer stores new locations or shows the track but keeps the locations already there. On restarting tracking, it will show the accumulated locations as a track as well as new track points.
When tracking is on and the app is paused, locations will continue to be accumulated, and the accumulated locations will continue to be available. Any accumulated locations will be kept until the service stops or Clear Track is performed.
Save the accumulated locations as a GPX file. You will be prompted for additional, optional componenets of the file name (Prefix, Category, Location, and Suffix) that will be inserted in the file name. The file name is of the form
[Prefix_]-yyyy-mm-dd_HH-mm-ss_[_Category][_Location][Suffix].gpx
The square brackets are not included and indicate that component is optional. Leave a component empty in the dialog if you do not want it in the filename. If Prefix is empty, then it will use MapImage as the prefix. After picking the components, you will get a system file picker letting you choose where to save the file. You can also rename it there. The values for Prefix, Category, Location, and Suffix will be saved for the next use. Note that since the date will be added, these do not have to be changed to make a unique file name.
The track will consist of separate track segments for each time tracking is stopped and restarted.
Tracking does not have to be on to save the GPX file, and it should be safe to stop tracking before saving. It saves the information stored in the service, not what is shown on the image.
Clears the accumulated locations in the MapImage Location Service. The tracks will also be cleared and not saved when the service stops.
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. When using tracking, especially when you want to save a GPX file, it is suggested to use Fast.
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. The location includes the accuracy. It also shows the requested permissions and if they are granted or not.
Re-scales and centers the image. This can also be accomplished by double tapping the image.
Use a system file chooser to select the directory with your images and allow MapImage permission to use it.
Displays this page.
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