Guide to Creating MapRun Courses

MapRun is an Android/iOS orienteering app that provides GPS based punching and timing for courses. You should use either MapRun6 or the older MapRunF.

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 or OpenOrienteering Mapper and Google Earth. However I do discuss a number of other approaches, depending on the resources and programs available. Hopefully this will 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 MapRun 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. Creating a Suitable KML Course File from a Purple Pen Course
    5. Creating a Suitable KML Course File from IOF XML
    6. Using MapRun to Create a QuickStart Course
  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 MapRun App
    1. Accessing a Private, Temporary CheckSites Course
    2. Accessing a Public, Permanent MapRun Course
    3. Checking Your Results
    4. Finalise Printed Map PDF
  7. Over to You
  8. References

Initial Setup

You need to install a suitable version of the MapRun app on your smartphone. The current versaion of the app is MapRun6, although the older MapRunF still works. You can download either of these from the Play/Apple Store as needed. When you run the app for the first time, select the "Name" tab, and fill in all your "User Details". If you have a suitable Garmin watch, you can use the MapRunG app on the watch along with the phone app, to log your progress around a course.

You also 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 older versions of the MapRun app. Newer versions have corrected this, so it may now be worth doing.

For any IT geeks, the error is caused by the <Rotation> fields having an empty value in the doc.kml XML file that specifies the tiles locations, included inside the KMZ archive (its just a zip file). It is possible to edit this file with a programming text editor to insert 0.0 values to correct the error, and then update the file in the KMZ archive.

Using OpenOrienteering Mapper with an Existing Orienteering Map

Ideally you'd like to use a specific orienteering map, particularly for public, permanent courses, that has been created for this use. If you have a geo-referenced OCAD or OMAP file, and have OpenOrienteering Mapper 0.9.5 or later, you can open the map with it, and export it as a KMZ. Select File -> Export as ... KMZ, specifying 150dpi and keeping the tiling default. You can then open this KMZ in GE to verify it is correctly located. Note that the accurate alignment of map features with physical location will depend on how accutely the map has been drawn, and the accuracy of the geo-referencing. But you have your required KMZ map file!

If you have a non geo-referenced OCAD or OMAP file, or just a JPEG or PDF image of the map, then you need to create a geo-referenced version of it. Jon Glanville has developed a process for doing this using OpenOrienteering Mapper 0.9.5 or later. It involves identifying two reference locations on the map image, and determining their geographic coordinates with Google Earth, using a spreadsheet do perform some required calculations, and then updating the Map -> Georeferencing dialog with the relevant details. See my brief summary of the process.

Using OCAD to convert an Existing Orienteering Map

Another alternative, if the orienteering maps masters are available in OCAD format, and you have the (very expensive) 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.

Using MapRun to Create a KMZ Map

Versions of MapRunF from v4.8.8 on (Apr 2020 or later) have 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).

Recently (from Feb 2021), the new MapRun Console also has a web accessible version of this utility to "Create KMZ Map". This is likely preferable to using the app version.

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" which you can call "Controls" (or any reasonable name) where you will place the controls for the course. Alternatively, particularly the first time doing this, you might want to open an "example KML file" that contains a suitable folder structure, and move it to this location. Make sure the "Controls" 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. Then select the course folder (which contains the "Controls" folder for your course), 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.

Creating a Suitable KML Course File from a Purple Pen Course

If you have a geo-referenced OCAD file, then you can use this as the base map in Purple Pen to both create a printable PDF map file, and also create an initial version of the course KML file, which you then open in Google Earth Pro and nudge into accurate position. Open Purple Pen and Create a New Event. Select your geo-referenced OCAD file as the map, and specify the other course options as needed. Then add co-located start and finish controls, create a new course, and place all wanted controls as accurately as possible based on the map. You can then create a PDF of the course(s) for printing. You can also export the course as an IOF XML file, and following the process I describe in the next section to convert this to KML. I recommend using an "IOF XML v3" file and my conversion script for this.

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.

Once you have the initial KML file, I strongly recommend opening it in Google Earth Pro and nudging the controls into accurate positions. As I describe in the section above on Using Google Earth Pro.

Using MapRun to Create a QuickStart Course

Versions of MapRunF from v4.8.8 on (Apr 2020 or later) have an 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).

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 MapRun 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 MapRun App

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

Accessing a Private, Temporary CheckSites Course

Open the MapRun 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.

You should use a Check Sites course to confirm the accuracy of your KML file before publishing it as a public course (or indeed sharing it privately with others). When doing this I recommend reducing the "punchTolerance" to a value smaller than you would use on the published course. So if leaving as default 15m, then check at 10m. If using 10m (a typical value for a street orienteering course), then check at 8m. Note this is about the lowest reasonable value to use, given the typical phone GPS accuracy of circa 4-5m. For this use, you should enable "Display present location". You may want to enable "Start Anywhere", which lets you start checking from any control. And you may want to enable "Display location pins", so you can place markers at corrected control locations if needeed, which you can view later, using the "Email Track" menu option when viewing your results. This sends you a copy of your course track, and any location pins, as a GPX file that you can open in Google Earth to help refine your course.

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. When viewing a result, there is a menu with more options. These include letting you view details of your split times. Options to review results (to include controls that failed to punch), do a manual upload, or email track to you.

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.

Finalise Printed Map PDF

Finally, if you're creating a course for others to use, you need to create a suitable map for them to print or view. If you've started with either an OOM map, or used Purple Pen to create your course, you already have the basic map. But you probably need to add additional text, and perhaps images, as needed. The text should include the full MapRun course name, start/finish location, course setter, and any other required instructions. You may wish to adjust the appearance of features in the map if possible to maximise readability. And since none of the common programs support free text control descriptions, these need to be added separately. I find the easiest way to do this is to type them into a table in Word, save as PDF, crop & export to JPEG image. This can then be added to the map, either in Purple Pen, or directly onto the PDF with Acrobat or similar.

Over to You

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

References

Guidance for creating and using MapRun courses are provided on the MapRun site - http://maprunners.weebly.com/, 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 - Sunday, 29-Aug-2021 16:29:09 AEST