Exploration Guides

We're all explorers. You just need the right guide.

EGMaps – Format Your Data

OK, this is the hard part.

You collected your data in some format.  You edited your data in another.  Now EGMaps will need to receive your data in another format.  This will take some manipulation.  Exploration Guides uses OpenOffice Calc, a free spreadsheet program available for just about any computer system.  It’s essentially the free equivalent of Microsoft Excel.  If you’re really good with spreadsheets, you can probably do this yourself. If not, you may want to get some help on this part.

The data dictionary for EGMaps is given below.  This describes the seven types of data files used by EGMaps.

EGMaps Data Dictionary

EGMaps uses a set of up to seven file types. Before we get to the specific files, there are two concepts which are common throughout these files.

Numeric Extensions

EGMaps assumes that you may want to add data to your app as time passes. Maybe you find new places in a park you’re continuing to explore and want to add new points of interest to your existing map, or someone puts in a new trail which you want to add. To allow this, and to allow for large amounts of data, most of the files used by EGMaps use numeric extensions. Here’s how they work:

Mobile data can be expensive, slow, or, even worse, both. This can annoy the user, which is bad. To avoid doing this, EGMaps only loads each piece of data from the internet once, then stores it locally. If you add data later, you leave the old data files in place (for new users) and just add new ones with only the new data. New users will read all the data files. Existing users will only have to read the new data.

The first time your app runs, EGMaps will look for a .1 file. If it finds it, it will load the data, then look for a .2 file. If it find that, it will load that data and look for a .3 file. Let’s say it doesn’t find a .3 file. It stores that the last file found was the .2 file.

The next time the user runs your app, EGMaps knows it already has the data for .1 and .2, so it doesn’t look for those. It looks to see if there’s a .3 file. If it doesn’t find it, it moves on. If it finds a .3 file, it loads it, then looks for a .4 file, etc. Whatever the last file found, it saves that file number.

Six different file types in EGMaps use the numeric extensions. Each of these file numbers is stored separately, so it’s ok to have different numbers of each type of file. Maybe you have seven poi files and two trailnum files and three trailpt files. No problem.

Microdegrees

Most people think of degrees like 42º 38’15.5” north latitude, 117º7’12.2” west longitude. That works great for humans, but it’s really hard for computers to deal with. Computers like numbers. To convert latitude and longitude into numbers, we just need to do a bit of math.

Chances are, you either have degrees, minutes, and seconds, or just degrees and minutes. First, we need to convert it to just degrees. Using the location 42º 38’15.5” north 117º7’12.2” west, we can convert easily by remembering that there are 60 minutes in a degree and 3600 seconds in a degree. This gives us:

degrees_only=degrees + minutes/60 + seconds/3600.

degrees_only=42 + 38/60 + 15.5/3600 = 42 + .6333333 + 0.0430556=42.6763889 North Latitude

degrees_only=117 + 7/60 + 12.2/3600 = 117 + .1166667 + 0.0033889 = 117.1200556 West Longitude

It’s important to always use at least seven decimal places in your calculations. If you use less than seven, your location data will become less precise.

Now that you have decimal numbers for latitude and longitude, the computer will be happy, right Well, it’s close. Computers are really good at storing and calculating with integers, but no as good with floating point numbers. To allow EGMaps to be as accurate and fast as possible, latitude and longitude are stored as integer microdegrees, which is just degrees x 1,000,000. For our sample location, that gives us:

42.6763889 North Latitude x 1,000,000 = 42676388.9 North Latitude

117.1200556 West Longitude = 117120055.6 West Longitude

Now rounding those to integers (now you see why you use at least seven digits to the right of the decimal, right), that gives you:

42676389 North Latitude

117120056 West Longitude

Still not quite integers, but using the standard that North Latitude is positive, South Latitude is negative, East Longitude is positive and West Longitude is negative, that gives us a final position of:

42676389,-117120056

Two, simple, integers. They’re fast to work with for a computer, and they don’t take much space. The one place prone to problems is when us humans forget to add the negative sign. Just to double check, when you load your app, zoom way out and take a peak around on the other side of the planet, just to make sure that you didn’t inadvertently place some of your points in the wrong hemisphere. If you did, it’s no big deal just change the data file, clear your data, and try again.

Now, on to the files themselves…

Config.txt: Call this what you like. The name is specified in the app which you write. It includes things like the app name, dialog text, and, most importantly, the file names and paths for all your data. The EGMaps configuration file template is a very long, complicated file, but remember that every line beginning with an asterisk is a comment. See the sample config.txt file for more details. All these lines are required. The data required is:

  • app_name: This is the name of your app, as displayed at the top of the screen
  • DEFAULT_LATITUDE: The first time the app is run, the map will center on this latitude.
  • DEFAULT_LONGITUDE: The first time the app is run, the map will center on this longitude.
  • defaultZoom: Zoom level to use the first time the app is run.
  • hasPOIs: Does your app use POI’s?
  • POI_LIBRARY_ROOT: This is probably the main web page for your app.
  • POI_UPDATE_PATH: This is the name of your POI numeric files.
  • groupPois: Do you want your POI’s to be grouped (for example, by state)
  • poiGroupDialogText: If your POI’s are to be grouped, put in what you want to label those groups. If you don’t group them, you can just leave this as the default.
  • requirePoiGroups: If you group your POI’s, do you want to require the user to use those groups, or allow them to select all data (which may be very slow). If you don’t use groups, just ignore this.
  • showPoiNumOnTap: If you have a lot of similar POI’s, or have a lot of POI’s on the same web page, you may want to use the numbers to make it easier for users to find them.
  • loadingPoiDatabaseString: What string to do you want displayed while the POI database is loading?
  • drawingPoisString: What string do you want displayed while your POI’s are being drawn?
  • hasTrails: Does your app have trails?
  • TRAIL_NUM_UPDATE_PATH: What is the root name of your trailnum files?
  • TRAIL_PT_UPDATE_PATH: What is the root name of your trailpt files?
  • FAVORITE_TRAIL_UPDATE_PATH: What is the root name of your favorite files?
  • FAVORITE_TRAIL_NUM_UPDATE_PATH: What is the root name of your favoritenum files?
  • mainParkPageUrl: The main web page for your app
  • siteFeedbackUrl: A feedback page for your app
  • showWeather: Do you want the weather options for EGMaps used for your app?
  • zipCode: If you use weather, what is the zip code (US only). If you don’t use weather, just leave this blank.
  • PHOTO_GALLERY_PATH: This is the path used on the user’s phone to store photos taken from the app. Unless there’s a really good reason to do otherwise, it should be something like DCIM/appname or DCIM/companyname/appname.
  • thingsChangeText: This text is shown in a dialog box every time the user runs the app.
  • MAX_HINTS: How many hints do you have?
  • hint1…: The hints you want to give your users in the hint dialog box. Maximum hints is 9.

dropdata.*: This file must be called dropdata, and has a numeric extension (see numeric extensions, above). This file is not required. It is used to request that EGMaps erase all data and load a full new data set. If you only want to add data you don’t need to use dropdata.* files, just use additional numeric files for your data files.

The first time EGMaps runs with your app, it will look for dropdata.1. If the file is found, it will look for dropdata.2, then dropdata.3, etc, until it fails to find the file. It will then store the number of the last file found.

If, at some time in the future, you decide that you want to erase all your data and load new data, create a new dropdata.* file. The next time a user runs your app, EGMaps will erase all data for your app and reload, starting at the .1 files. EGMaps will store the number of the last dropdata.* file used, so you can later create dropdata.2, dropdata.3, etc.

The contents of dropdata.* files are never read, so you can just put anything you want into them. They just need to contain something so they’re not 0 bytes.

Points of Interest

EGMaps uses Points of Interest (POI) to place markers on the map. These markers can be anything, like the locations of waterfalls in a park, restaurants in a city, or sculptures in a garden. POI’s have icons, which you provide in your app, names, and links to web pages. Your app user can also use Google Maps Navigation to provide turn by turn directions to a POI. POI’s are defined by a single file.

poi.*: This file name is specified in config.txt and has a numeric extension (see numeric extensions, above). It contains the information on your points of interest/waypoints/locations on the map. The file format is a standard comma separated variable (CSV) format. This file is required if you specify hasPOIs=Y in config.txt.

number (positive integer, incrementing from 1): This must start with 1 and must increment by 1 for each additional poi.

latitude (integer): latitude of the poi, expressed in microdegrees, with north latitude being positive and south latitude being negative. (see microdegrees, above)

longitude (integer): longitude of the poi, expressed in microdegrees, with east longitude being positive and west longitude being negative. (see microdegrees, above)

elevation (integer): Elevation of the poi, expressed in meters. If you don’t have an elevation, just guess, or use 0.

name (string): Name of the poi. Name can not include either single or double quotes, slashes, backslashes, etc, as this will prevent the entire poi.* file from loading.

url (string): There are three options for this field. It can be a full URL, beginning with http:// or https://, it can be left blank, in which case POI_LIBRARY_ROOT, as defined in config.txt, will be used, or it can be a name to be appended to POI_LIBRARY_ROOT to create the full URL.

icon (string): the name of an icon located with your app. This icon will be displayed on the map at the specified location. Use only the name not the .png extension.

weight (positive integer): Required, but not currently used. Eventually, EGMaps may drop lower weight POI’s as you zoom out the map. 1 is the highest weight.

Sample data:

1,4247217,-83783433,183,”Canoe Launch”,”http://www.explorationguides.com/info/michigan/huron-river/”,”handlaunch”,1

Trails

Trails are the lines drawn by EGMaps onto the maps themselves. If you only want to display POI’s, you don’t need any of the trail files. If you want to draw trails, borders, or any other lines onto the map, you do it with trails. Trails are defined by at least two files, or four, if you also want to use the favorite trail feature.

EGMaps needs the trails for your app broken down into segments (trailnums). Each segment is made up of a series of points (trailpts).

samplemap

In the sample map above, trailpts are numbered 1, 2, etc. The order of trailpts and trailnums on the map is irrelevent. To facilitate making favorite trails later, it’s best to break trails into segments at parking areas, major points of interest, and intersections.

Trailnum.*: Trailnums are simply trail segments. In the diagram above, each trailnum is defined by a separate color. Trailnums are identified by a number, which must start at 1, and must increment by 1 for each additional trailnum. A trailnum record defines the trail number, the color, the length, vertical climb (from first point to last), vertical fall (from first point to last), the maximum and minimum elevation, the weight of the trail, and the line thickness. The format of this file is CSV. The extension of the trailnum files is numeric, incrementing from 1 as you add more files. (see numeric extensions above)

Fields:

Number (positive integer, incrementing from 1): This must start with 1 and must increment by 1 for each additional trail.

Color (8-character string): This is a 8 character string, in ARGB format, which defines the color of the line to be drawn. ARBG format defines the color precisely by Alpha (transparancy, you probably want to set this to opaque, or ff), Red component (00-ff), Green component (00-ff), and Blue component (00-ff). You can specify any color you like, such as red (ffff0000), green (ff00ff00), blue (ff0000ff), black (ff000000), white (ff111111), or, using combinations of those colors, any other color you like.

Length (integer 0 or greater): The total length of this trail segment, in meters.

Ascent (integer 0 or greater): The total climb of the trail segment, in the direction of travel, as defined in trailpt. This field, not currently used, is given in meters. If you have the data, you should include it, as it may be used in a later version of EGMaps.

Descent (integer 0 or greater): The total drop of the trail segment, in the direction of travel, as defined in trailpt. This field, not currently used, is given in meters. If you have the data, you should include it, as it may be used in a later version of EGMaps.

Maximum elevation (integer): The maximum elevation encountered in this trail segment. This field, not currently used, is given in meters. If you have the data, you should include it, as it may be used in a later version of EGMaps.

Minimum elevation (integer): The minimum elevation encountered in this trail segment. This field, not currently used, is given in meters. If you have the data, you should include it, as it may be used in a later version of EGMaps.

Weight (integer 1 or greater): How important is this trail segment? 1 is most important, followed by 2, 3, etc. This field is not currently used, but in the future it may be used to remove less important trail segments as the user zooms out. If you always want a trail shown, regardless of zoom level, set this to 1.

Thickness (integer 1 or greater): How thick should the line be drawn on the map. This line thickness is constant, regardless of zoom level. 1 is a very, very thin line. 3 is a good value for normal trails.

Sample data:

1,”ff000000”,175,15,35,200,205,1,3

Trailpt.*: Trailpt files define the individual points, in order, as you travel along a specific trailnum (or trail segment). In the map above, trailnum 1 contains the points 1, 2, 3, 4, and 5. Trailnum 2 contains the points 5, 9, 10, and 15. The direction of travel along a trail is irrelevant, (trailnum 2 could be 5, 8, 10, 15 or 15, 10, 8, 5), but the ordering of the points matters, as the line is drawn from the first point to the second to the third, etc. The format of this file is CSV. The extension of the trailnum files is numeric, incrementing from 1 as you add more files. (see numeric extensions above)

trailnum (integer): This corresponds to the number in the trailnum file. It defines the point as being on that trailnum.

latitude (integer): The latitude of the point, expressed in microdegrees. (see microdegrees, above)

longitude (integer): The longitude of the point, expressed in microdegrees. (see microdegrees, above)

elevation (integer): The elevation of the point, expressed in meters.

Sample data:

1,43263760,-79071407,300

1,43254248,-79055237,305

Favorite Trails

Favorite Trails are trails which can be selected by the user and highlighted on the map. This gives the user the ability to look at a suggested route on your web page, select it on their app, and see a highlighted route which they can then follow easily. Two files are used to control these favorite trails in EGMaps.

favoritenum.*: Favoritenun files define the favorite names for the user and give them a number to be used by favoritenum files. Favorite trails must begin with favorite 1, then increasing up from there by 1’s, not skipping any. The name is defined in your config file. The extensions are numeric, incrementing from 1 as you add more files (see numeric extensions above). The format of the file is CSV.

Favorite number (integer): This is the favorite number which favoritept will use. Favorite trails will be shown in numeric order by favorite number. Don’t skip numbers.

Favorite name (string): The name of the favorite. Don’t use quotes, backslashes, slashes, etc in the name.

Sample data:

1,”East Route”

2,”West Route”

favoritept.*: Favoritept files define the actual trail segments. The file defines which trail segments are on which favorite trail. Trail segments can be on as many favorite trails as you like, and they’re not required to be on any at all. Most favorite trails will have at least a few, maybe dozens or more, trail segments. Just use one line for each segment on each favorite. The name is defined in your config file. The extensions are numeric, incrementing from 1 as you add more files (see numeric extensions above). The format of the file is CSV.

Favorite number (integer): This is the favorite number, which corresponds to the number defined in the favoritenum file.

Trail segment number (integer): This is the trail segment, as defined in your trailnum files.

Sample data:

1,1

1,2

1,3

2,3

2,5

No comments yet.

Leave a Comment