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 MapRun (v7) or the older MapRun6 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 or OpenOrienteering Mapper and either the MapRun Create KML tool or Google Earth (GE). 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 the Create KML web tool
    2. Using Google Earth Pro
    3. Creating a KML Course File Using GPS
    4. Setting a Course in the OpenOrienteeringMap Website
    5. Creating a Suitable KML Course File from a Purple Pen Course
    6. Creating a Suitable KML Course File from IOF XML
    7. 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 MapRun (v7) although the older MapRun6 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 "User Profile" tab, and fill in all your "User Details". See my Introduction to Using MapRun page for more guidance on setting up and using the app. 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 may also need Google Earth Pro (GE) installed on your PC, Mac, or Linux system, if you want access to some additional features creating the KML file. However the new MapRun Create KML web tool now provides most features that previously needed Google Earth Pro. Documentation for Google Earth Pro 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 is typically oriented with either Magnetic or 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. There current version of this site is v4.0 which includes contours on the map, and is preferable to use than the older v3 site.

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. This can be useful if you want to generate a map just with this site. Alternatively you can use either the MapRun Create KML tool or Google Earth to do this.

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". Note that the suggested file name includes a MapID value (like "5e912c9549a3b") which I strongly recommend retaining in the name. Though I would also replace the generic "oom" with a more descriptive location. You can use the MapID to reload a map view for later use or modification, which is very useful. At this stage your window will look something like this:

Next select "MapRun 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 some older versions failed 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 the Create KML tool or 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 MapRun 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 MapRun 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 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 by using either the MapRun Create KML web tool or Google Earth Pro to position the controls, or using GPS with a phone mapping app to log the desired control locations.

Using the Create KML web tool

The method currently recommended by MapRunners uses the Create KML web tool. 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. Note that there are instructions on that page on how to use it, but in more detail:

Load your map KMZ using the "Choose Map File (KMZ)" button, and optionally also an initial KML file with the "Import a Course File" then "KML file" button. Start by either checking that the control positions look correct on the KMZ map (if you have an initial KML file). Alternatively, you can add an initial set of controls (by right or double clicking on the map and entering the control number for each, starting with S1, then 1, 2 etc and lastly F1). You now need to ensure the controls are accurately located. So make the KMZ transparent by reducing the Map Opacity to zero, so you can now see the controls on the satellite imagery.

Select each control in turn, zoom in, and drag the control so it is accurately positioned over the desired feature (if visible) or at best guess location. To move a control either double-click the control, or right-click and select "Move". I find it really useful to have another browser window or tab open with Google Maps and use Streetview to help locate where the feature is in relation to visible objects around it (like driveways, house shape, vegetation etc).

There are also options to rename controls, reorder the list of controls, or delete controls, as described in the "How to Use" Instructions on the page.

You may wish to make the KMZ base map visible, to check how the adjusted control locations look on it (noting that there may be discrepencies due to small positioning errors in the base map). At this stage, your window may look something like:

When you are done, make sure you select the"Save/Download the Course KML" button to save your modified KML file before leaving the page, or all your edits will be lost!

Using Google Earth Pro

The alternatively method uses the Google Earth Pro program on your computer in a similar fashion to the Create KML web tool. 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.

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.

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 "MapRun KML" to save your course. You now have your KML file! You can just use this directly, or you could open it in the Create KML page or Google Earth, adjust the control locations to correct any errors, as decribed above, and then save the modified file. Even if you do this, you can still use the saved PDF of this map as a printed map (which you likely need to annotate further).

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. To create a KML file for the course you can use the "Create KML web tool" I describe above, and import the PPEN file with the course. You can then nudge the controls, and save the KML file it creates. Alternatively, you can 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 either the Create KML page or Google Earth Pro and nudging the controls into accurate positions, as described previously.

Using MapRun to Create a QuickStart Course

Versions of MapRun 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 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.

See my Introduction to Using MapRun page for more guidance on using the app.

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 (as we use in our street orienteering courses), 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. Alternatively, type the them as text in Word, and then add the text to the PDF with Acrobat or other PDF editing program, or using a PDF editing website like iLovePDF.

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 - Wednesday, 21-Jun-2023 16:33:06 AEST