This file describes how to make a map with ARNL and a laser.  If you
only have SONARNL you should see SonarMapping.txt for directions.

Ways to start mapping
=====================

You need to generate laser scan log files before you can use the mapper. 
You can do this two ways.

The way to get a better higher precision map is to run sickLogger from
the examples directory in Linux or the bin directory in windows.
Include a filename argument for the log file, if you don't give it a
filename it'll default to 1scans.2d)...  This filename needs to have
the file extension ".2d". The program automatically connects with the
robot and then starts up the laser.  At the point where the laser
starts, sickLogger disables the sonar -- your clue that the system is
ready for you to start driving.  If it can't connect due to any error,
Aria will tell you and exit.

The easier way to do a map is to simple run the guiServer example and
then connect with MobileEyes and then select 'Tools->Map
Creation->Start Mapping' and give it a file name, then drive the robot
around, and then stop mapping by selecting 'Tools->Map Creation->Stop
Mapping'.  

The first way with sickLogger will make a better map because it will
use the laser with readings of every .5 degrees instead of the typical
1 degree as with guiServer and most other programs.... other programs
maps may turn out fine, but if you have problems use sickLogger.

Driving the robot to make a map
===============================

There are three ways you can drive the robot to make a map

Attach an analog joystick to the joyport on the robot, not on the
computer.  If you have a newer yellow analog joystick all you need to
do is plug it in.  If you have an older analog joystick you'll need to
calibrate the joystick... to calibrate: Leaving the stick centered,
press the trigger button for a second or so, then release it. Now
rotate the stick around its extremes two or three times, holding it in
each corner for a second or two. You are now ready to drive.  You can
then drive the robot by holding the trigger and moving the joystick.
To make goals you can press the top button on the old analog joystick
(this requires at least AROS1_5) or the 'goal' button on the new
analog joystick.  With the new analog joystick you may also be able to
use the throttle to control your speed.

You could also attach USB joystick attached to robot computer (this
depends on having a robot equiped with an accessible usb port): To
drive the robot just press the trigger button and then move the
joystick how you wish the robot to move.  You can use the throttle on
the side of the joystick to control the maximum (and hence scaled)
speed at which the robot drives.  To make a goal you can press any of
the other buttons on the joystick itself (button 2, 3, or 4).

You could run this with the keyboard, but not very versatile.  Use the
arrow keys to control the robot, and press g to make a goal.


How to map an environment 
=========================

This section gives some general advice on how to use the mapping
software in your environment.  Before you go and start the mapping
algorithm on your robot it is a good idea to develop an exploration
strategy for driving your robot around.  The exploration strategy
depends on your environment.

Environment without cycles

If your environment does not contain any cycles, e.g. an office
environment with one corridor and connecting rooms, then the
exploration strategy can be simple.  Just joystick the robot into each
room along the corridor.  However, if your robot is equipped with only
one 180 degree scanner then the mapping algorithm might still detect
cycles because of the different viewing angles when going into
opposite directions in a room or corridor.  Therefore you still might
need to follow the advise for environments containing cycles.

Environment with cycles

Usually most environments contain cycles and this software is
especially made for such places.  However, there are several
assumptions and restrictions the mapping algorithm assumes.

* Loops are only closed once

One assumption is that after closing a loop the resulting map does not
have to be changed anymore along the loop and the poses of all scans
belonging to the loop are fixed.  This means that going along the loop
another time does not change the form of the loop anymore.

* Loops have to be closed when they are closed

Furthermore, there is the limitation that if the algorithm is not able
to close a loop at one time then it will most probably not be able to
close it later when the robot comes to the same area again.  This
means that when you drive the robot along a loop back to a previously
visited place you should make sure that the robot recognizes this
loop.  You might need to continue driving the robot in the already
visited area until it detects the loop.  Only after it detected and
closed a loop, you can drive the robot into new and unexplored area.

* Small loops first (usually)

Usually it is better to map an environment by closing smaller loops
before going for larger ones as this in general reduces the search
space for loop detection.  However, this depends on the environment
and in some cases where there are small loops along a large cycle, it
might be better to close the large one first because otherwise you
might violate one of the following points.

* No loop just a few meters before another loop

After closing a loop or moving in already mapped terrain
the robot should go several meters into unexplored area before 
it closes another loop.  The reason for this is that after 
closing the loop or moving in already mapped terrain the 
search space for loop detection is reset and all scans 
belonging to previously closed loops are fixed, i.e. they 
can't change their pose anymore.

* No loops during exploration of new terrain

This is similar to the previous point.  After a loop is closed
the search space for loop detection is reset and the poses
of scans along the loop are fixed.  This might be disadvantageous
for example when there are several small loops along a large cycle.


The above hints should give you a general feeling about how
the algorithm can be employed in your environment.  If you have
a rough topological map of the environment then this should
help a lot in developing an exploration path that meets the 
above criteria.  

A different approach is to just try and get your own experience
in how the mapping algorithm performs.  Remember to enable the
logging feature of the mapping software so you can play back
and analyse the mapping process later.


Converting the .2d to a map file
================================

Best done on the same machine, not with an exported X DISPLAY.
Besides, your desktop PC is probably faster than the robot's computer.

There are three ways to open a .2d in Mapper3.

You can either start Mapper3 and then go into the File menu and select
'Open'.  

You can simply start Mapper3 with the name of the .2d you would like
to process.  

If you are using Linux on the robot's onboard computer, running guiServer,
you can download files from within Mapper3: Choose 'Open From Robot' from 
the File menu, connect to the robot, and download the .2d file you just made.
Once Mapper3 is done converting to a map file, you can use 'Save To Robot' to
save the map file on the robot computer. 

Uploading and downloading files is not currently possible by servers running 
in Windows. Instead, you can use sftp, scp, or ftp to transfer files.

One you start load the scan (or start laser mapper with a scan)
Mapper3 will begin processing the .2d and will draw the map as it is
making the map (on a grey background) and and then when it is
registering the map the robot icon will move in the lower right
corner.  When it finishes making the map the 'Finish' button will
ungrey.  If you'd like to create a .wld file for the simulator you can
select the <mapName>.2d window and then go to the file menu and select
Export and then world file.  You can then click the 'Finish' button
which will close the window and open another window with a white
background.  You can then go to the file menu and select 'save as' to
save it as a map file.


You can then close the .2d file and edit the .map with the tools on
the left.  You can also insert items from the insert menu.  If you use
more than one robot home ARNL will start the robot in the one that is
calculates as most probable.  Although you can use your map, as is,
you may want to edit it to take out extra, moveable objects, such as
the people who were standing around and watching you make the log.
Use the eraser tool on the top toolbar to erase transients.  Leave
desks and tables, though, since those probably won't move.  You'll
want to put in goals at points you'd like the robot to drive to.  You
can do this with the goal tool on the top toolbar.  You'll also want
to put forbidden lines or areas where you don't want the robot to
drive.

If you have a docking station you'll want to put a goal in for the
dock.  For the pioneer dock put this point about 1 meter and a half
back from the dock with a heading pointing at the dock, you'll need to
give this the name of 'dock' for things to work.

You'll then want to copy this .map file (and .wld) to the
Arnl/examples directory on your robot so that you can start up the
examples with your map file more easily.  If you use Mapper3 to save
them to the robot they should already be in this directory.

You can change maps at run time by connecting to the server with MobileEyes,
and entering the new name as the value of the Map parameter in the Files
section of the Robot Configuration dialog.

The underlying mapping technology of Mapper3 is from ScanStudio
which you can find in our LaserMapping package (along with a
description of how to use it).  We have licensed this fine technology
from its creator and author Steffen Gutmann.  If you need support
contact support@mobilerobots.com.