******************************************************************************** libscoach and libscoachdraw version 1.0 ******************************************************************************** ******************************************************************************** INTRODUCTION ******************************************************************************** Copyright (C) 2001 Patrick Riley, Paul Carpenter, Gal Kaminka, Manuela Veloso This library is intended to facilitate the creation of coach clients and coachable player clients for the SoccerServer system (http://sserver.sourceforge.net/) The home page of libscoach is at: http://www.cs.cmu.edu/~robosoccer/sim/libscoach/ This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Parts of this library are based on files from the SoccerServer system (http://sserver.sourceforge.net/), which was also released under the LGPL. See the headers of the files for details. Copyright (C) 2001 RoboCup Soccer Server Maintainance Group. Patrick Riley, Tom Howard, Itsuki Noda, Mikhail Prokopenko, Jan Wendler Copyright (C) 2000, 2001 RoboCup Soccer Server Maintainance Group. Patrick Riley, Tom Howard, Daniel Polani, Itsuki Noda, Mikhail Prokopenko, Jan Wendler Parts of this library are also based on ATTCMUnited2000 code, copyright Patrick Riley, Peter Stone, and Manuela Veloso. See the headers of the files for more details. Copyright (C) 1998,1999,2000 Patrick Riley, Peter Stone, Manuela Veloso ******************************************************************************** OVERVIEW ******************************************************************************** Two versions of the library can be built with the provided code: libscoach and libscoachdraw. libscoachdraw provides strictly more functionality, but it is bigger and slower and requires Magick++, the C++ to ImageMagick (http://www.imagemagick.org/) We used version 5.3.3, but other versions may work as well. The general capabilities of the library are: libscoach: * Provides data structures to represent coach language messages (adapted from SoccerServer code) * Parsing of coach language messages (almost unchanged from the SoccerServer version) * CoachMessageRepository class for storing coach messages and handling the linking of defined objects. * A condition evaluation system which is easy to plug into. * A system to provide iteration over the pieces of a message * System set up for named thingys to be linked to what they point to. * Region have much more capability than in the SoccerServer, most notably iterators allowing iteration over points in a region, point inclusion tests, and closest point calculations. * Miscellaneous geometry routines * Error reporting and action logging scheme for layered disclosure (see "Layered disclosure: Revealing agents' internals", Patrick Riley, Peter Stone, and Manuela Veloso. In C. Castelfranchi and Y. Lesp\'erance, editors, Intelligent Agents VII. Agent Theories, Architectures, and Languages --- 7th. International Workshop, ATAL-2000, Boston, MA, USA, July 7--9, 2000, Proceedings , Lecture Notes in Artificial Intelligence. Springer-Verlag, Berlin, Berlin, 2001.) libscoachdraw: * A FieldImage class for creating images to represent things such as formations. * All coach message components can draw themselves to a FieldImage. * Note that this requires Magick++ from ImageMagick. I apologize that not all of the code is documented well. In order to get this release ready in a timely manner I was unable to spend sufficient time to document the code. A few important notes are included in this file. I hope that this library will still be useful. ******************************************************************************** USAGE INSTRUCTIONS ******************************************************************************** Here is some more details about what you have to do to get this working. ** The Makefile If you wish to create libscoachdraw, you will need to set MAGICKROOT (near the top of the Makefile) to the directory where you have ImageMagick installed. If you only want to build one of the two version of the library, modify the all: $(LIBNAME) $(LIBNAME_DRAW) line. Then, 'gmake full' should compile everything. ** Functions you must provide In order to actually use the library, your source code must provide two functions. The two versions shown below will work. bool LogAction_worker(int level, const char* str) { return false; } void my_error(const char *msg) { } These are to handle information and error reporting. See the CMUnited99 source code release for examples of how these are used and our implementation of the functions. http://www.cs.cmu.edu/afs/cs/usr/pstone/mosaic/RoboCup/CMUnited99-sim.html ** How to use the library You will probably want to include to make the libscoach directory an include directory with a -I flag. The library is statically linked, so just add the following to your link line: -L -lscoach (for the regular version) or -L -lscoachdraw (for the version with drawing primitives) where is the directory where you installed libscoach ** Some code notes If you want to use the version of the library with drawing, you will need to define WITH_DRAW before you include any .h from the libscoach area. I recommend simply adding -DWITH_DRAW to your compile line. You must provide an evaluator to the Region and CM_Condition classes in order for the coach message processing to work. See coach_mess_eval.h for the interface you must implement. It is important that you call CoachMessageRepository::updateRegions() when your world model changes (i.e. when the points returned by your CoachMessageEvaluator could change) so that the region classes will return the correct answers with respect to regions with relative points. If you want to parse a coach message, call parse_coach_lang_string(char*), which returns 0 on success. The resulting data structure will be in g_pMess (see global.h). Note that you are responsible for deleting this memory! ******************************************************************************** MORE INFORMATION ******************************************************************************** The file License contains the full license for the software. The home page of libscoach is at: http://www.cs.cmu.edu/~robosoccer/sim/libscoach/ I am considering putting this library on sourceforge.net to facilitate a true open-source, distributed development effort. If you think this would be useful, please send me an email (pfr@cs.cmu.edu). Contact Patrick Riley (pfr@cs.cmu.edu) if you have questions or comments about this library. Patrick Riley pfr@cs.cmu.edu http://www.cs.cmu.edu/~pfr