Guide to Creating MapRun Courses

MapRun is an Android/iOS orienteering app that provides GPS based punching and timing for courses. You should use the newer MapRunF version as it supports private temporary courses, as we will use in this guide (at least until it replaces the older MapRun app).

To create a course for use by MapRun, you need both a geo-referenced base map in KMZ format, and a course in KML format. This guide aims to provide an introduction as to how this can be done, starting with informal course creation, as well as discussing methods used to create more formal, public courses. It broadly follows the guidance provided on the MapRunners Step by Step Guide page, but with a focus on easy course creation using OpenOrienteeringMap and Google Earth. The intent is to encourage people to create their own courses, and then challenge their friends to attempt them, as well as to provide an introduction to the process needed to create MapRun courses more generally.


Contents

  1. Initial Setup
  2. Creating a Suitable Base Map
    1. Using the OpenOrienteeringMap Website
    2. Using OpenOrienteering Mapper to convert an Existing Orienteering Map
    3. Using OCAD to convert an Existing Orienteering Map
    4. Using MapRunF to Create a KMZ Map
  3. Creating a Suitable Course File
    1. Using Google Earth Pro
    2. Creating a KML Course File Using GPS
    3. Setting a Course in the OpenOrienteeringMap Website
    4. Using MapRunF to Create a QuickStart Course
    5. Creating a Suitable KML Course File from IOF XML
  4. Assigning a Suitable Course Name with Type and Scoring Details
  5. Uploading the Course to the MapRun Server
    1. Uploading a Private, Temporary CheckSites Course
    2. Uploading a Public, Permanent MapRun Course
  6. Accessing a Course in the MapRunF App
    1. Accessing a Private, Temporary CheckSites Course
    2. Accessing a Public, Permanent MapRun Course
    3. Checking Your Results
  7. Over to You
  8. References

Initial Setup

You need to install MapRunF on your smartphone. You can download it from the Play/Apple Store. When you run it for the first time, select the "Name" tab, and fill in all your "User Details".

You need Google Earth Pro installed on your PC, Mac, or Linux system. Documentation is available at Google Earth Help. There is a good introductory Google Earth Pro: A tutorial from UWaterloo in Canada if you are new to it. And Google have a collection of tutorials on their Become a Google mapping expert page. I recommend you change its Preferences so that Zooming does not tilt.

Creating a Suitable Base Map

Firstly you need a base/master map that shows features in the area used for the course. This map need to be oriented with True North up, and be geo-referenced lat/long coordinates for the area covered by the map. It must be converted to Google's KMZ format for use here. A suitable map may be provided by your course coordinator, in which case you can skip over this section. Otherwise, there are several possibilities for creating the map, ranging from quick and easy Street-O map creation using the OpenOrienteeringMap site, to converting existing orienteering maps to the required form.

Using the OpenOrienteeringMap Website

OpenOrienteeringMap (positioned over ACT) is a website for quick and easy Street-O map creation, based on information from OpenStreetMap. This has less detail, and inconsistent mapping quality, compared to traditional orienteering maps, but its quick, easy and available for many areas. And you only need access to a web browser.

Start by zooming in and moving the map view until you can view the desired area. Note the hints in green at the top of the page. Click on the desired scale (likely 10000 or 7500), orientation (portrait or landscape), and select "PseudO" style. Then click to set the centre of your desired map. You can move the centre point by selecting it, then dragging to where desired, which moves the map. At this point you could also plot all your controls, as I discuss in the next section on creating a suitable course file, though this is not needed if you intend to use Google Earth to do this more accurately.

Next update the details in the box on RHS. Edit the name by clicking on the pen icon next to it. Edit the race instructions (to anything), and change the other fields of wanted. You can then "Save & get PDF map". At this stage your window will look something like this:

Next select "MapRunF KMZ" to download the KMZ file you need. This map is not tiled, as MapRun would prefer. For now though, just use the untiled KMZ file. You have your required KMZ map file!

Note I had previously suggested you use the "Create KMZ file with 512x512 tiles from an un-tiled KMZ file" on the MapRunners O-Utils page. However it currently fails to handle all the OOMap kmz files, and can cause a "FormatException: Invalid double" error in the MapRunF app. So for now, don't do this.

Using OpenOrienteering Mapper to convert an Existing Orienteering Map

Ideally you'd like to use a specific orienteering map, particularly for public, permanent courses. However these maps are usually aligned with Magnetic North up, and may not be geo-referenced. Hence these maps need to be converted to be geo-referenced and aligned with true north. Jon Glanville has documented the process of doing this using OpenOrienteering Mapper 0.9.2 or later, starting with either a Purple Pen map image or a PDF map (that is exported to JPEG). It involves identifying two reference locations on the map image, and determining their geographic coordinates with Google Map or Google Earth. Then transforming and rotating the map as required. He provides a spreadsheet to do the messy calculations needed. The result is then exported as a JPG and JGW (world) file. Using these files you can create the required KMZ file using the "Create a KMZ file (with 512x512 tiles) from a jpg and jgw file" utility on the MapRunners O-Utils page (scroll down until you see that option). Browse and select the JPG and JGW (world) files for your map. Set dpi to 150. It should look similar to image below. Then select "Go" to generate and download the resulting KMZ file.

And then you have your required KMZ map file! I have created a brief summary of the process. More detailed description and links TBA.

The result may have features that don't quite align with those in a Google Earth / GPS view, due to the use of local coordinate systems and various input data sources, but will better align with conventional orienteering expectations. Experiments so far suggest the results are quite useable.

Using OCAD to convert an Existing Orienteering Map

Another alternative, if the orienteering maps masters are available in OCAD format, and you have the OCAD program, is to follow the geo-referencing process described in the MapRunners Maps - KMZ Files ("Geo-Reference a Map in OCAD" section) if needed, and then export the result as a KMZ file, with 512x512 tiles at 150dpi. This method will likely result in the best quality maps.

Again, the result may have features that don't quite align, but again this may well be acceptable.

Using MapRunF to Create a KMZ Map

The latest, just released (Apr 2020), version of MapRunF v4.8.8 has a new feature to "Create a KMZ Map" from an image/photo. You need to take a photo of, or have an image file of, a suitabe base map. The process is similar to that using OpenOrienteering Mapper that we described above, but is done within the MapRunF app. This makes the process available to anyone with the app, but accuracy is restricted by the limited screen space on most mobile devices. There is a video illustrating this feature (along with the associated course creation feature).

Creating a Suitable Course File

Next you need to create a KML file that describes the course as a series of Placemark locations. I will generally follow the process described on the Setting a course in Google Earth page. You may start the process using a printed map and laying out where you'd like the controls. But you then need to determine their exact geographic coordinates more accurately than you can generally achieve using just a map. As discussed in the MapRunners page on the need for Accurate Latitude and Longitude of Controls. There are several possibilities for creating this also, primarily either using Google Earth to position the controls, or using GPS with a phone mapping app to log the desired control locations.

Using Google Earth Pro

The method recommended by MapRunners uses the Google Earth Pro program on your computer. In it, you use the aerial view and zoom in to accurately identify the desired control feature and place the control placemark at that location. In more detail:

Start the "Google Earth Pro" program on your computer. "Open" your KMZ map file. This will add the map under your "Temporary Places" in the "Places" box on LHS, and overlay the map on the Google Earth aerial view.

"Add" a "Folder" under "My Places" (right/control click on the name to get the popup menu to do this) named for the course you are creating. Then within this folder "Add" a "Folder" called "Course1" where you will place the controls for the course. nb. This name is required. Alternatively, particularly the first time doing this, you might want to open an "example KML file" that contains a suitable "Course1" folder, and move it to this location. Make sure the "Course1" folder is highlighted.

You can now add the controls for your course, placing them approximately based on the underlying map that is currently visible. Note that the start control "S1" and finish control "F1" must have those names, and would normally be co-located. To add a control in the current folder, click the yellow pin on the tool-bar. This opens the Info dialog for the new placemark, and drop a new placemark icon in the map area. Drag the icon to the desired location. Enter the name for this placemark (eg "S1"). You can change the icon for the placemark by clicking the icon symbol to the right of its name. You can change it to an orienteering, start or finish control with "Add Custom Icon..." and using the icon URLs in the Setting a course page. Alternatively, if you've opened the "example KML file", or have previously created KML folders in your "My Places", you can select "Properties/Get Info" (PC/Mac) from the popup menu on one of the placemarks (start, finish or a control) to make its properties, including icon, the current default (this will move you view to its location). Move your view back by double-clicking on your current KMZ map in "Places". Then create and place the course controls at the desired locations on the map, named "1", "2" etc. Lastly create the finish control "F1", co-located with the start. The aim here is to place all the controls to make an interesting event, deciding on the overall spread of controls and the navigational challenges to be posed. You now have the first iteration of your course. I suggest you "File" -> "Save My Places" at this point if you haven't already!

However you now need to tweak the location of your controls using the Google Earth image, as placing controls using just the map is not accurate enough. So you switch off the map layer by unchecking the box next to the KMZ map name in your "Temporary Places". Then adjust each control (pin) to a nearby streetlight (for StreetO) or other feature that is visible on the Google Earth satellite image. Note that it is important that your view is looking down from above. Zoom in on the image view to each control in turn. Right/control click on each control (either on the icon on the image, or name in the "Places" box) and select "Properties/Get Info". This opens the info box and highlights the control icon. To identify the correct location, zoom in as far as necessary, select and move each control into place exactly over the desired feature. You may need to move the properties box to find the icon to move whilst doing this. Also when zooming in and out, you may find Google Earth shifts your view and compass angle. You can reset these with View -> Reset -> "Tilt and Compass" (or use shortcut keys "u" for up & "n" for north).

I also recommend entering the control description as the placemark "Description", and select "OK" to save. Repeat for each control. You can switch to Street View to check placement. Or alternatively have Google Map open in a browser window to cross-check street location and view with the Google Earth image. The Setting a course page has further guidance on this process. Whilst doing this, when you are viewing the properties of a placemark, your window may look something like:

The order of the controls in the "Places" box determines the order in the final KML file. You can select & drag controls to reorder. The start & finish controls should be first and last. In between, controls should usually be in either numeric order (for scatter courses), or the desired line course order, as appropriate.

Finally you need to save this set of controls as a KML file. Right/control click your new course folder in the "Places" box, and select "Save Place As...". Change the file type to "Kml", choose the desired target filename and folder and Save.

You now have your KML file!

If you added the control descriptions to the placemarks, you can use my KML File Placemarks Lister script to display a (tab separated) text table of the control location details. Which you can then copy and paste into a spreadsheet or similar to build the control description table.

Creating a KML Course File Using GPS

To create a course where control locations are not easily identified in the Google Earth images, you likely need to walk the course, and record a GPS waypoint at each control location. Then export it, transfer to your computer, and review in Google Earth. The details of how this is done will depend on the app used on your smartphone. I have successfully used this approach with OruxMaps on an android phone, as I describe in my MapRun GPS Course guide.

Having transferred the KML file of waypoints to your computer, you should load, review and add information to your KML course in "Google Earth Pro". In brief, open "Google Earth Pro" and then open the kml file. Move the "Waypoints" folder enclosing your waypoint locations into a suitable course folder under "My Places". Re-order the waypoints into the desired course order (may well be reversed if you walked the course in order ... walk it backwards maybe!). Edit the "Properties/Get Info" for each control, check name correct, and add control description if wanted. Select the "Course1" folder, select "Save Place As..." in the popup menu. Change the file type to "Kml", choose filename and folder and Save. You now have your KML file!

Setting a Course in the OpenOrienteeringMap Website

You can choose to just add all your controls in the OpenOrienteeringMap (positioned over ACT) websites, as mentioned above in the Using the OpenOrienteeringMap Website section. After positioning your map as it described, you then click each location you want to place a control, and fill in the control options. When done, select "MapRunF KML" to save your course. You now have your KML file! You can just use this directly, or you could open it in Google Earth, adjust the control locations to correct any errors, as decribed above, and then "Save Place As..." to update the file. Even if you do this, you can use the PDF of this map as a printed map.

Using MapRunF to Create a QuickStart Course

The latest, just released (Apr 2020), version of MapRunF v4.8.8 has a augmented QuickStart feature that allows the use of a map, and dropping control pins onto a Google Earth view of the area in the app. This is similar to using Google Earth Pro on your computer, but in the app. This makes the process available to anyone with the app, but again accuracy may be restricted by the limited screen space on most mobile devices. There is a video illustrating this feature (along with the associated KMZ map creation feature).

Creating a Suitable KML Course File from IOF XML

The Step by Step Guide mentions other approaches to creating the course KML file from a geo-referenced OCAD map or a geo-referenced OpenOrienteeringMapper map. It notes that: "Alternatively, IOF XML can be created by any of the orienteering course setting systems including OCAD, Corpse, Condes, PurplePen, but extreme care must be taken with the accuracy of the O-map used and the placement of controls on the map. Remember that moving a control by 1mm on a 1:10000 map moves it by 10m on the ground. (You can) convert existing IOF XML files to KML so that the real-world position of the controls can be checked in Google Earth", and then use to create a MapRun course.

I have written a IOF XML v3 to KML File Convertor script that takes a georeferenced IOF XMLv3 file, and generates a KML file. By default, all courses are included, each in a separate folder in the KML file. For use as a MapRun course, you need to delete all but the required course for any maprun event. This can be done in Google Earth, or by using a text editor on the KML file. Or, if you know which number course you want, you can select just that course for conversion from the file. If necessary you can determine the require course number by looking at a conversion of all the courses in either Google Earth, or by using my KML Course Placemarks Lister script.

Alternatively, if you save the course as an IOF XML v2 file, you can use the conversion script on the MapRunners O-Utils page. Its about half-way down the page, look for "Convert Georeferenced IOF XML Course File to KML Course Files (in a Zip file)". Once you have the zipfile, unzip and use the KML for the desired course.

Assigning a Suitable Course Name with Type and Scoring Details

MapRun determines the type and scoring details for a course using codes at the end of the course name. These are described on the Event Types and Scoring Schemes pages. And yes its rather complex, however in most cases you would choose between a small number of alternatives. Also, since the name chosen is kept permanently if any results are uploaded, and cannot be reused, it is important that you choose a name that uniquely identifies your course. Hence you should include some date specification, as well as a unique enough name. And if you are uploading a course for testing, something like "test1" in the name is a useful guide to what the course is.

Lets assume you have a Street-O course whose base name is "Yarramundi May 2020". If you want a timed scatter course for a specific number of controls (eg. 18 controls as with the ACT type A Street-O course), then append code "PXAS18". If you are creating multiple versions of a course, I also recommend putting the course type after the name but before the code to help users know the course type. So a suitable course name for this scoring would be "Yarramundi May 2020 A PXAS18". For the other timed course classes (B 15, C 12 or D 08 controls, change the PXAS number, which needs to be 2 digits, to match).

For a scored scatter course, MapRun provides a number of Scoring Schemes. If you want say Victorian Bendigo Park style scoring (which is the closest to the PowerWalk class in the ACT, with 20 points per control and 10 points per minute late penalty) for a 60 min period, use code "PXAS ScoreV60". So my example name (with PW class tag) becomes "Yarramundi May 2020 PW PXAS ScoreV60". If you are just creating a single instance of a scatter course (as we recommend initially), then no need for the course class in the name, so could just use "Yarramundi May 2020 PXAS ScoreV60".

For a traditional timed line course, visiting controls in the order specified in the KML file, use code "PXAC", eg. "Yarramundi May 2020 PXAC".

If you want multiple scoring schemes for a course, in MapRun you need to create multiple copies of the course, each with the relevant name and type tags.

Uploading the Course to the MapRun Server

For people to use your course, it needs to be uploaded to the MapRun server either as a private, temporary CheckSites course, or as a public, permanent course that will be generally available for an extended period.

Uploading a Private, Temporary CheckSites Course

The MapRun server allows anyone to upload a private, temporary course CheckSites that will be available for a limited time. This is intended for testing a new course or for simple private events for a small number of people - as in create a course and challenge your friends with it!

To do this, go to the Setup Check Sites page. Enter the course name, including the type and scoring codes as discussed above. Select a suitable short-term expiry date (the default is 1 week). Browse to and select the map KMZ and course KML files for your course, and Submit this information.

Finally and critically, make sure you record the Map Code then displayed at the bottom of the page, as this is needed for you or anyone else to access the course in the MapRunF app. The course will remain available for download to the app until the expiry date.

Uploading a Public, Permanent MapRun Course

If you have developed and validated a course intended for a public event, or for extended access in MapRun, then it can be uploaded as a public, permanent course by your local MapRun administrator. Contact your local orienteering club to find out who this is. If there is no local MapRun administrator, you need to Contact MapRun Support to discuss options.

Accessing a Course in the MapRunF App

Once a course has been uploaded to the MapRun server, people can access it with the MapRunF on their smartphone. How it is accessed depends on how it was uploaded.

Accessing a Private, Temporary CheckSites Course

Open the MapRunF app. Select the menu button (bottom right) on the Home screen. Select "Check Sites". Enter the map code provided when the course was uploaded to the Check Sites page, and select OK. The course will be downloaded to the phone and selected, as long this is done before its expiry date on the server. You can now "Go to Start" to review the course, or to actually start the course if on location, by walking up to the start location when the timer will start. If just reviewing a course, you can exit by selecting the Home icon (top left) and confirming abort.

Before tackling a private course, you may wish to alter some of the "Options and Settings" being used for the course by selecting that button. You may want to tighten the "punchTolerance" from the broad default of 15m to a setting like 10m. This defines how close you need to be to the control location for it to register. Noting that your phone GPS will have a degree of error, so some amount of tolerance is needed. You can also change the eventType and scoreType from the default set by the tags in the course name. And you should check that "Display present location" is off unless you are deliberately checking the control placement locations.

If you have downloaded a number of courses, they will all be permanently stored locally on your phone, unless you delete them. You can select any local (offline) course by choosing "Select Event". Then the "Access Local Events (Offline)" button at the bottom. Then select the desired event.

Accessing a Public, Permanent MapRun Course

You access permanent, public courses by choosing "Select Event". Navigate the folders to find the desired event (eg. "ACT" then "Permanent" then "MR Lotus Bay") and select it. Again select "Go to Start" to review or start the course. With public courses you will likely find that many of the course settings have been locked and cannot be changed in the app.

Checking Your Results

Results for any courses attempted are stored on your phone. You can review these results by selecting "Show Results". Select any result for more details.

Results for public events may also be uploaded to the server. You can select the "All Results for this Event" to view these.

If you have reviewed a course, a "Did Not Start" result is created. You can delete any result (or local course) by "swiping left" (or right :-) on the result and confirming delete.

Over to You

Hopefully this enough to get you going creating and using some MapRun courses. Have fun!

References

Guidance for creating and using MapRunF courses are provided on the MapRunF site - http://maprunners.weebly.com/maprunf.html, including:

And also see:


Please send any comments, suggestions for improvements, or other feedback to: Lawrie.Brown@canb.auug.org.au
Guide last updated by: Lawrie Brown - Tuesday, 04-Aug-2020 17:48:12 AEST