# public rtv /Stage

### Subversion checkout URL

You can clone with HTTPS or Subversion.

Fetching contributors…

Cannot retrieve contributors at this time

file 1174 lines (920 sloc) 39.545 kb
 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 % Desc: Stage user manual% Author: Richard Vaughan, Andrew Howard% Date: 10 Jun 2002% CVS: $Id: stage.tex,v 1.22 2004-08-23 18:47:28 rtv Exp$\documentclass[letter,11pt,twoside]{report}% this one apparently fixes the < and > chars\usepackage[T1]{fontenc}\usepackage{subfigure}\usepackage{times}\usepackage{tabularx}% why did we need this?%\usepackage{verbatim}% make all captions small and slanted\usepackage[small,sl]{caption}\usepackage{fullpage}%\usepackage{epsf}\usepackage{epsfig}\usepackage{graphicx}% add nifty DRAFT watermark thingy in PS\usepackage{draftcopy}% A nice environment for displaying command line args (AH)\newenvironment{xarg}[1]{\noindent{\tt #1}\\\hspace*{2em}\begin{minipage}[t]{5in}}{\end{minipage}\vspace*{1em}}\def\VERSION {1.5}\def\HOMEPAGE {{\tt http://playerstage.sourceforge.net}}\def\SFPAGE {{\tt http://sourceforge.net/projects/playerstage/}}\begin{document}\setcounter{page}{0}\pagenumbering{roman}\titlepage \begin{tabular}{lcr}   \begin{tabular}{c}        Player/Stage project\\         \includegraphics{notext_ps_logo}    \end{tabular}   &   \hspace{5cm}   &   \begin{tabular}{r}     {\bf Autonomy Laboratory}\\     Simon Fraser University\\     Burnaby, British Columbia, Canada\\     \vspace*{2em}\\     {\bf USC Robotics Laboratory}\\     University of Southern California\\     Los Angeles, California, USA\\     \vspace*{2em}\\     {\bf Stanford Robotics Laboratory}\\     Stanford University\\     Stanford, California, USA\\   \end{tabular} \end{tabular}  \vspace{4cm}   \centerline{ \Huge{Stage}}  \vspace{0.5cm}  \centerline{\large{Version \VERSION{} User Manual}}  \vspace{2cm}  \centerline{\large Richard T.~Vaughan \\ Andrew Howard \\ Brian P.~Gerkey}  \vspace{1cm}  \centerline{This document may not contain the most current documentation on}  \centerline{Stage. For the latest documentation, consult the Player/Stage homepage:}  \centerline{\HOMEPAGE}  \vspace{4cm} \centerline{\today}\tableofcontents%\newpage%\listoffigures%\newpage%\listoftables%\newpage% reset page number to start with 1\setcounter{page}{0}\pagenumbering{arabic}\chapter{Introduction}\section{ Stage and the Player/Stage Project}The Player/Stage Project produces software tools to support researchin autonomous robotics, sensor systems and animats (artificialcreatures). Stage is a robot simulator. It models a population ofmobile robots, sensors and environmental objects in a two-dimensionalworld. Stage is designed with multi-agent systems in mind, so itprovides fairly simple, computationally cheap models of lots ofdevices rather than attempting to emulate any device with greatfidelity. This design is intended to be useful compromise between theconventional high-fidelity robot simulations, the minimal simulationsdescribed by Jakobi\cite{jakobi:radical}, and the grid-worldsimulations common in animat research\cite{wilson:animat}. We intendStage to be just realistic enough to enable users to move controllersbetween Stage robots and real robots, while still being fast enough tosimulate large populations. We also intend Stage to be comprehensibleto undergraduate students, yet sophisticated enough for professionalreseachers.Stage devices are usually controlled through \emph{Player}; anetworked robot server. Player provides a convenient interface to aset of device drivers for real robots and sensors. Stage simulates apopulation of devices and makes them available thorugh Player. Userswrite robot controllers and sensor algorithms as clients' to thePlayer server'. Typically, clients cannot tell the difference betweenthe real robot devices and their simulated Stage equivalents (unlessthey try very hard). We have found that robot controllers developed asPlayer clients controlling Stage robots will work with little or nomodification with the real robots and vice versa. With a little care,the same binary program can often control Stage or real robots withouteven being recompiled. Thus the Player/Stage system allows rapidprototyping of controllers destined for real robots. Stage can also bevery useful by simulating populations of realistic robot devices youdon't happen to own.  Various sensors and actuators are provided, including sonar orinfrared rangers, scanning laser rangefinder, color-blob tracking,fiducial tracking and mobile robot bases with odometry. {\bf Note:Some models from previous versions may not yet be available in thisrelease, but we're working on them. Let us know which ones you need.}\section{How to get Stage and related software}The main source for all things Player/Stage is the projecthomepage:\\\\ \indent\HOMEPAGE\\\noindent Access to source code releases, access to the CVSdevelopment tree, bug tracking, user mailing lists, etc.~ isavailable from the Sourceforge project management page:\\\\\indent\SFPAGE\\\noindent The current release is available as the source tarballStage-.src.tgz at:\\\\ \indenthttp://sourceforge.net/project/showfiles.php?group\_id=42445\\Where \verb++ indicates the most recent (i.e. largest)version number you find at the site. Previous versions weresignificantly different; this manual does not apply to them.\section{What's in the Package?}In the release tarball you will find:\begin{itemize}\item Documentation, including this manual and release notes (in the  directory \verb'docsrc').\item C source code for 'stage' the simulation engine (in \verb'src').\item C and C++ code for the 'libStage' client library (in \verb'src').\item Example worldfiles and bitmaps (in \verb'worlds' ).\item Example Player configuration files for using Player withStage(in \verb'config').\end{itemize}\section{Platform and Requirements}Stage was developed and tested under Linux kernel 2.4 and 2.6,glibc-2.2 and OS X.3. The C and C++ source code is reasonableANSII/POSIX so it often compiles elsewhere. No promises, but peoplehave found it to work on a variety of set-ups. Some people have hadsuccess with Microsoft Windows and CYGWIN, but this is not currently atarget tested by the maintainers. Using a UNIX-like system willprobably be easier for you. Player/Stage programs are Free Softwaretoo, so using them with Linux can cost you \$0, freeing up your budgetto do more science for the benefit of society and/or your company.\subsection{Dependencies}\begin{itemize}\item libRTK2 [the Player/Stage GUI toolkit \HOMEPAGE] \item GTK+ (packaged with GNOME)\item glib (usually packaged with GTK+)\item pkg-config (usually packaged with GTK+)\item X11R6 (usually installed by default on Linux, Solaris and BSD, optional free download on OS X)\end{itemize}Optional, but very useful, and recommended if you ever want to usecontroller code on real robots:\begin{itemize}\item Player [\HOMEPAGE]\end{itemize}\section{Ownership and Licensing}Stage is released under the GNU General Public License. Stageprograms, images, examples, source code and documentation are owndedand copyrighted by their authors. The authors, roughly in order ofdate of contribution, are:\begin{itemize}\item[] Richard Vaughan [vaughan@sfu.ca]\item[] Kasper Stoy \item[] Andrew Howard [ahoward@robotics.usc.edu]\item[] Brian Gerkey [gerkey@robotics.stanford.edu]\item[] Boyoon Jung \item[] Jakob Fredslund\item[] Esben \O{}sterg\aa{}rd\item[] Jason K~ Douglas\item[] Kim Jinsuck\item[] Gabe Sibley\item[] Dave Naffin\end{itemize}The list of authors above is a partial one: the code itself containsthe definitive ownership and licensing statements.See your name here by contributing devices, superior algorithms,bugfixes, examples, docs, etc. If you contributed to Stage and weforgot to add you here, either add yourself here (if you have CVSwrite access) or let us know and we'll be happy to correct theommision.\section{Bugs and feedback}This is constantly evolving research software. It is bound to containbugs, despite developer and user testing. Stage is occasionallyoverhauled, revealing or introducing new bugs. If you find somethingthat appears to be a bug, or if some aspect of Stage's behavior seemswrong or non-intuitive, let us know. If you have a problem, pleasefirst check the website and bug tracking logs - hundreds of questionshave been answered there. If you can't find an answer there,{\emph usethe bug tracker} to tell us about the problem. Better still, fix itand send us the patch. To stay in touch with the developers and otherusers, join the mailing lists.When submitting bugs, include as much information as possible,including the Stage version, OS type and version, and any outputmessages. A detailed description of what happened will enable us(hopefully) to repeat and analyze the problem. Of course, there is NOWARRANTY on this software, and no guarantee that we will fix yourproblem. Remember, you didn't pay for this stuff\footnote{If you {\emdid} pay for this stuff: thanks, and please ignore the referringparagraph. If you are interested in funding Player/Stage research anddevelopment, get in touch with one of the maintainers. If you really,absolutely need formal, paid support for Player/Stage for some reason,we could probably work something out, but we'd encourage you toconsider the community-based approach first. It usually works verywell.} and we are not responsible for getting it to work on yourdesk. But we use Stage for our research and we want it to workproperly, so we will do our best. Again {\emph please use thesourceforge bug tracking tools}; that's the best way to see yourproblem solved. Sending email directly to the authors is lesseffective than using the tracking tools and is considered impolite.We'd like to hear from you when the software works, as well as when itdoesn't. It's more relaxing. If you do something cool with Stage, letus know.\section{Citations}If you use Player/Stage Project software for your research ordevelopment, please acknowledge our work in your publications.At the time of writing, there is no peer-reviewed article about Stagealone, but there is a formal USC School of Engineering technicalreport, available online (URL inside www.usc.edu goes here). Thereference is:\begin{quote} Richard T.~Vaughan. "Stage: A Multiple Robot Simulator". Technical Report IRIS-00-394, Institute for Robotics and Intelligent Systems, School of Engineering, University of Southern California, 2000.\end{quote}The report is out of date on the details of using Stage, but itexplains the motivation and design, which are still relevant.The appropriate reference for Player is our peer-reviewed article inthe proceedings of IROS 2001: \cite{GerkeyVaughan01a}:\begin{quote} Brian~P. Gerkey, Richard~T. Vaughan, Kasper St\o{}y, Andrew Howard, Maja~J Matari\'c and Gaurav~S Sukhatme. \newblock {Most Valuable Player: A Robot Device Server for Distributed Control}. \newblock In {\em Proc. of the IEEE/RSJ Intl. Conf. on Intelligent Robots and Systems (IROS)}, pages 1226--1231, Wailea, Hawaii, October 2001.\end{quote}These papers (and several newer ones on various aspects of theproject) are available at:\begin{verbatim} http://playerstage.sourceforge.net/pubs.html\end{verbatim}If you have space (and are feeling generous), you can also insert a footnotealong these lines:\begin{quote} The Player/Stage Project is a collaboration between the USC Robotics Research Lab, Stanford University Robotics Lab, the Autonomy Lab at Simon Fraser University, and contributors around the world. All Player/Stage software is freely available under the GNU General Public License from http://playerstage.sourceforge.net.\end{quote}By including such acknowledgements, you make us feel good and furtherour careers. More importantly, you encourage more people to use andcontribute to this software. You may even inspire someone to writesomething even better under a similar license so you can use it.\subsection{Attribution}Please do not refer to Stage or the Player/Stage Project as being {\em from} USC or otherwise imply exclusive affiliation with USC. While the Player/Stage Project began at USC, for several years it has been an international, multi-institution collaboration. The Project is controlled by its maintainers and contributors and no other institution. Thus, referring to USC's Stage robot simulator'' is not correct. You should call it the Stage robot simulator from the Player/Stage Project'' or just Stage''. \section{Acknowledgements}\subsection{Funding}Financial support at USC has come from DARPA grant DABT63-99-1-0015(MARS), NSF grant ANI-9979457 (SCOWR), DARPA contract DAAE07-98-C-L028(TMR), ONR Grants N00014-00-1-0140 and N0014-99-1-0162, and JPLContract No. 1216961. Development at HRL Laboratories was supported bya DARPA contract (SDR). Development at the Autonomy Lab is supported byan NSERC Discovery Grant, SFU President's Award and faculty start-upgrants to Richard Vaughan.\subsection{People}Thanks to our contributors and users, particularly members of the USCRobotics Lab, SFU Autonomy Lab and playerstage-developers mailing listwho have been generous with their advice, bug reports and fixes, andcode contributions. Thanks to Doug Gage at DARPA IPTO for hislong-standing support. Thanks also to Gaurav Sukhatme and Maja Mataricat USC, and Dave Payton at HRL for allowing the birth and growth ofStage at their laboratories.%////////////////////////////////////////////////////////////////////////////\chapter{Installing and Running Stage}{\bf This section is under construction. Please refer to the README.stage file in the Stage distro for the latest information.}{\bf Note to users of previous (<1.5) versions:} the build order ofP/S components has changed with v.1.5. The correct build order is:\begin{enumerate}\item libRTK\item Stage\item Player\end{enumerate}\section{Building and Installing Stage}You must install libRTK {\em before} building Stage, and if, like mostpeople, you want to use Player with Stage, you must install Player{\em after} installing Stage. This is because both Stage and Playerdraw most of their graphics using libRTK and Player uses the stageclient library 'libstage', included with the Stage distro, tocommunicate with Stage. All Player/Stage Project components,including Stage, Player and libRTK are available from the Player/Stagefiles page:\begin{verbatim} http://sourceforge.net/project/showfiles.php?group_id=42445\end{verbatim}\noindent Build and install libRTK following the instructions in thepackage's README and INSTALL files. Now download the Stage tarball andunpack it with:\begin{verbatim}$ tar xzvf Stage-.tgz\end{verbatim}\noindent (where is the most recent release of Stage;i.e. the largest numbered release not less than 1.5). Now follow theinstructions for your release in the top-level README and INSTALLfiles.\subsection{Notes on specific build targets}Stage should build on most UNIX-like systems that have GTKinstalled. GTK is an essential part of the GNOME desktop system and isavailable for many platforms. GTK itself requires glib and pkg-config;Stage makes extensive use of these packages. Make sure you have GTKinstalled before attempting to install libRTK and Stage.\subsubsection{Linux}No special configuration should be required for most Linux distros.\subsubsection{Solaris}No special configuration should be required for most Solaris distros.\subsubsection{Darwin/OS X}OS X does not have X11 or GTK installed by default. Apple distributestheir own X11 package based on XFree86 which works well. The easiestway to get GTK+ and its dependencies installed on OS X is probably viathe excellent Fink'' ports system.You may need to tell the compiler where to find the Fink-installedheaders and libraries using the standard environment variables\verb+CFLAGS, CPPFLAGS+ and \verb+LIBRARY_PATH+ before buildingStage. For example, if your Fink base directory is /sw (the default):\begin{verbatim} $export CFLAGS=-I/sw/include$ export CPPFLAGS=-I/sw/include $export LIBRARY_PATH=/sw/lib\end{verbatim}\subsubsection{Microsoft Windows}Some people have experimented with building Player and Stage onWindows, with mixed success. Windows support is not a priority for thedevelopers, but we're generally interested in cross-platform supportso if you have success building, using or tweaking Stage on Windows,please let us know.\section{Running Stage}\subsection{Theory of operation}Stage is a 'server' that provides simulation services to one or more'clients'. Clients connect to Stage over the network using theInternet Protocol (TCP/IP). Thus clients can talk to a Stage server onthe same machine (the most common scenario), or on a local network, orover the Internet. Clients can ask Stage to create and modifysimulated worlds containing robots and other objects. Clients cancreate multiple worlds, and multiple clients can manipulate a singleworld. Most people will use Player as their Stage client. Player containsdrivers that create simulated robots in Stage and present them to theuser like any other Player device. Users then write their robotcontrollers as clients to {\em Player}: the fact that the robots aresimulated is hidden from the client program. Player is a verypowerful, flexible robot interface; this manual only describes itsinteraction with Stage. Refer the Player manual, available in thePlayer package and on the project web site for details of Player.The process of using Stage goes like this:\begin{enumerate}\item start the Stage server.\item start a client program, e.g. Player.\item the client connects to Stage and requests that Stage create oneor more simulated worlds'', containing one or more models''.\item the client then sets up the simulated world(s) by configuringthe properties of the models.\item the client may subscribe to model properties. When subscribed,the client is informed of any changes to the property.\item the client may change any property of a model or create and destroy models and worlds at any time. \end{enumerate}Note that a particular client may not provide access to all the features of Stage; for example the {\tt stageclient} Player driver does not yet allow dynamic creation and destruction of models as this is currently beyond the scope of the Player protocol.\subsection{Worlds}A world is a \subsection{Models} Stage models are highly configurable - they can behave like mobilerobots with sensors or simply act as obstacles, depending how they areconfigured. To run Stage do: \begin{verbatim}$ stage \end{verbatim} \section{Command Line Arguments}\section{Controlling the robots}The virtual robots in Stage are controlled by talking to the Stageserver. Player includes drivers for this purpose, based on thelibstage'' client library included with Stage. Player provides a setof standard interfaces to a variety of robots, both real andsimulated. Users typically target their controllers to the Playerinterfaces so they can then run on real robots or simulated robots inStage or Gazebo (a 3D, hi-res robot simulator from the Player/StageProject). Example Player controllers in various languages (including C++,C, Python, TCL \& LISP) are included in the Player distribution.Try using the Player example client\verb+/utils/playerv/playerv+ to check that you can controlStage robots and read from their sensors. playerv is a very usefultool for testing and debugging your controller code.Client libraries in other languages including Java and Python are alsoavailable. Check the website for the latest resources.%////////////////////////////////////////////////////////////////////////////\chapter{Using the Stage GUI}Stage presents a window showing the state of each simulated world. Thewindow is resizable and contains a menu and a main display areashowing a view of the world.\section{World view}The main display area shows the world, the simulated entities (objectsand devices), and optionally, representations of the data generated bydevices and the configuration of these devices.\subsection{Mouse}The user can pan and zoom the world view and manipulate entities withthe mouse:\subsubsection*{Clicks on the background}\begin{tabular}{|l|l|}\hline Mouse action & Result\\\hlineLeft-click and drag & pan the window\\Right-click and drag TOWARDS the center of the window & zoom in\\Right-click and drag AWAY FROM the center of the window & zoom out\\ \hline\end{tabular}\subsubsection*{Clicks on entities}\begin{tabular}{|l|l|}\hline Mouse action & Result\\\hlineLeft-click and drag & move the entity\\Right-click and drag & rotate the entity\\\hline\end{tabular}\subsection{Keyboard}The world view can also be panned and zoomed with the keyboard. Thekeybindings are:\subsubsection*{Clicks on entities}\begin{tabular}{|l|l|}\hline Key & Action\\ \hline & scroll the window \\ & scroll the window in large increments \\ & zoom in \\ & zoom out \\\hline \end{tabular}\section{Menu}\subsection{File Menu}\begin{tabular}{|l|l|}\hline Export Image & save a screenshot into a bitmap file (choose PPM orJPEG format from the submenu).\\Export Movie & save a movie of the window contents. Choose the movie'sspeed as a multiple of real-time, then start and stop the movierecording from the submenu. The movie is saved in the currentdirectory.\\Save & send a Save'' message to the client. Clients should save thecurrent world state. For example, Player saves the current objectposes in the current worldfile.\\Quit & exit Stage\\\hline\end{tabular}\subsection{View Menu}\begin{tabular}{|l|l|}\hline Models & toggle view of the lines that make up a model's body\\Data menu & toggle visualizations of data generated by devices\\Geometry menu & toggle visualizations of sensor geometry\\Configuration menu & toggle visualizations of sensor configuration\\Grid & toggle view of a 1m grid\\Matrix & toggle view of underlying bitmap representation\\Debug & toggle view of debug info, showing raytracing in action\\\hline\end{tabular}\chapter{Property Reference}{\bf This section is incomplete}Each model has several {\em properties} associated with it; theseproperties specify characteristics such as the model's size or sensorrange. The table below lists all of the properties. The basicmodel is implemented in /src/model.c. Model extensions areimplemented in /src/model\_.c.\vspace{1em}\\\noindent\begin{tabularx}{\columnwidth}{lll}\hline Type & Datatype & Description \\\hline STG\_PROP\_GEOM & stg\_geom\_t & size and local pose. \\ STG\_PROP\_VELOCITY & stg\_velocity\_t & velocity in x,y,$\theta$. \\STG\_PROP\_COLOR & stg\_color\_t & RGB color. \\STG\_PROP\_POSE & stg\_pose\_t & pose in parent's coordinate system. \\STG\_PROP\_LINES & stg\_line\_t[] & array of lines that define a body. \\\hline\end{tabularx}%------------------------------------\chapter{libStage API Reference}{\bf This section is incomplete}The Stage distribution includes the libstage C library that makes iteasy to write clients to the Stage server. libstage is used byPlayer's Stage drivers.\section{Client}\section{World}\section{Model}%////////////////////////////////////////////////////////////////////////////\chapter{libStage WorldFile Introduction}\label{sec:world}libstage can read a file that describes a world, including models andtheir properties, then create that world in the Stage server. Theworld description file is called a worldfile''. This chapterdescribes worldfile syntax.Note that the world file format has changed significantly fromprevious versions.\section{Basic Syntax}A simple world file might look like this:\begin{quote}\begin{verbatim}# This world file creates two robots with lasers.bitmap "cave.pnm" resolution 0.02model( name "robot1" pose [1 1 0] laser.view [ 0.0 8.0 180.0 ] laser.samples 180)model( name "robot2" pose [2 1 0] laser.view [ 0.0 8.0 180.0 ] laser.samples 180)\end{verbatim}\end{quote}This example shows the basic syntactic features of the world file format: comments, models and properties.Comments are indicated by the \verb'#' symbol; they may be placedanywhere in the file and continue to the end of the line. Forexample:\begin{quote}\begin{verbatim}# This world file creates two robots with lasers.\end{verbatim}\end{quote}%Entities are indicated using \verb'type ( ... )' entries; each suchentry instantiates an entity of type \verb'type'. For example:\begin{quote}\begin{verbatim}model ( ... )\end{verbatim}\end{quote}creates a single model. %Models may be nested to indicate that one%entity is a child'' of another; thus:%\begin{quote}%\begin{verbatim}%position ( player () laser() )%\end{verbatim}%\end{quote}%creates a single position device with a Player server and laser attached to%it. Think of child entities as physically sitting on their parent.%%Entities have properties, indicated using \verb'name value' pairs:\begin{quote}\begin{verbatim}model ( name "robot1" pose [1 1 0] ... )\end{verbatim}\end{quote}This entry creates a model named robot1'' with initial position $(1,1)$ and orientation of $0$. Property values can be either numbers(\verb'6665'), strings (indicated by double quotes \verb'"robot1"') ortuples (indicated by brackets \verb'[1 1 0]').\section{Defining new entity types}Notice that the two robots in the example differed only in their nameand pose. For convenience, we can define a type of model that has pre-set properties using the \verb'define' statement.For example, the world file from the previous section can be re-writtenin a more concise form as follows:\begin{quote}\begin{verbatim}# This world file creates two robots with lasers.# It uses the 'define' construct to define a new type of entity.bitmap "cave.pnm" resolution 0.02define laserbot model( laser.view [ 0.0 8.0 180.0 ] laser.samples 180)laserbot( name "robot1" pose [1 1 0] )laserbot( name "robot2" pose [2 1 0] )\end{verbatim}\end{quote}New entities are defined using \verb'define newentity oldentity (...)'.For example, the line:\begin{quote}\begin{verbatim}define mybiggreenmodel model ( color "green" size [10 10] )\end{verbatim}\end{quote}defines a new model type \verb'mybiggreenmodel' which is the primitive model with itsd \verb'color' and \verb'size' properties set.This entity may be instantiated using the standard syntax:\begin{quote}\begin{verbatim}mybiggreenmodel ( name "robot1" pose [1 1 0] )\end{verbatim}\end{quote}This entry creates a model named \verb'robot1' that is big and green.\section{Using include files}The \verb'include' statement can be used to include entity definitionsinto a world file. For example, the world file from the previous sectioncan be divided into an include file called \verb'myrobots.inc':\begin{quote}\begin{verbatim}# This is an include file.# It uses the 'define' construct to define a new type of entity.define mybiggreenrobot model ( color "green" size [10 10] )\end{verbatim}\end{quote}and a world file called \verb'myworld.world':\begin{quote}\begin{verbatim}# This world file creates two robots with lasers.# It uses the 'include' statement to include the robot definitions.include "myrobots.inc"bitmap "cave.pnm"resolution 0.02myrobot ( name "robot1" pose [1 1 0] )myrobot ( name "robot2" pose [2 1 0] )\end{verbatim}\end{quote}The definitions are included using the \verb'include "filename"'statement.\section{Units}The default units for length and angles are meters and degreesrespectively. Units may be changed using the following globalproperties:\begin{table}[h]\begin{tabularx}{\columnwidth}{llX}\hlineName & Values & Description \\\hline\verb'unit_length' & \parbox{30mm}{\verb'"m"'\\\verb'"cm"'\\\verb'"mm"'}& Set the unit length to meters, centimeters or millimeters. \\\verb'unit_angle' & \parbox{30mm}{\verb'"degrees"' \\ \verb'"radians"'} &Set the unit angle to degrees or radians.\\\hline\end{tabularx}\end{table}\noindent The following example uses millimeters rather than metersfor the unit length unit:\begin{quote}\begin{verbatim}# This world file creates two robots with lasers.# It uses the 'include' statement to include the robot definitions.unit_length "mm"include "myrobots.inc"bitmap "cave.pnm"resolution 0.02myrobot ( name "robot1" pose [1000 1000 0] )myrobot ( name "robot2" pose [2000 1000 0] )\end{verbatim}\end{quote}Be warned that the length specfication applies to the include files as well,so choose a unit length early and stick to it.\section{Examples}See the {\tt examples} directory in the Stage distribution for moreworld file examples.\section{Properties reference}Each sub-model defines several properties that can be set in theworldfile. Chapter \ref{chap:propref} lists all the properties.%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\chapter{libStage Worldfile Property Reference}\label{chap:propref}This chapter describes the properties that can be set in aworldfile. Worldfile loading is part of libstage, implemented in/src/stagecpp.cc.SI Units are used whenever possible. Distances are specified inmeters, angles in radians, mass in KG, etc. All values in tuples [likethis] are floats.Stage provides a basic model and several extensions. Each extensiondefines a particular sensor or actuator, and may add some propertiesto the basic model. Extension properties only exist if they havebeen explicitly set in the worldfile. They do not have default values.\section{World properties}World properties are set in the top-level of the worldfile,i.e. outside a model'' block.\begin{tabularx}{\columnwidth}{llX}\hlineName & Values & Description \\\hline\verb'bitmap' & \verb'filename' & load the named image file (variousformats are supported) and convert it into a list of linesegments. Typcially used to load a floorplan image as a background obstacle environment.\\\verb'resolution' & \verb'float' & set the resolution of Stage'sunderlying bitmap representation. All obstacle detection and sensorraytracing is done with this resolution, so it defines the limit onsensor accuracy. Smaller values give increased accuracy at the expenseof speed and memory space. Values of 0.01 or 0.02 (1cm or 2cm) are themost commonly used. \\\end{tabularx}\newpage\section{Basic Model}\subsection*{Properties}\begin{tabularx}{\columnwidth}{llX}\hlineName & Values & Description \\\hline\verb'name' & \verb'string' & A unique name for this entity. This nameis referenced in the Player config file to identify this simulateddevice.\\\verb'pose' & \verb'[x y a]' & Set the pose ([x,y] position andorientation [a] in the parent's coordinate system).\\\verb'origin' & \verb'[x y a]' & Set the model's pose ([x,y] positionand orientation [a] in the its own local coordinate system (e.g. tooffset a robot's center of rotation from center of mass).\\\verb'size' & \verb'[sizex sizey]' & Entity dimensions.\\ \verb'mass'& \verb'float' & mass in KG.\\\verb'lines.count'& \verb'integer' & number of lines that make up thismodel's body.\\\verb'lines.points[i]' & \verb'[x1 y1 x2 y2]' & specifies the startand end points of the line \verb'i'. These lines are normalized to fitinside the rectangle defined by the \verb'size' property.\\\verb'nose'& \verb'integer' & if non-zero, the model is drawn with a'nose', indicating its heading.\\\verb'velocity'& \verb'[vx vy va]' & forward (vx), sideways (vy)and rotational (va) velocity.\\\verb'color' & \verb'string' & Descriptive color (e.g. \verb'"red"' or\verb'"blue"'); only colors listed in the X11 color database should be used(look for \verb'rgb.txt' in your X installation).\\\verb'bitmap' & \verb'filename' & load the named image file (variousformats are supported) and convert it into a list of linesegments. The model's \verb'lines' property will be set with thelines.\\\\\hline\end{tabularx}\subsection*{Defaults}\begin{tabularx}{\columnwidth}{llX}\hlineName & Value\\\hline\verb'name' & \verb'""'\\\verb'size' & \verb'[0 0]'\\\verb'lines' & a unit rectangle\\\verb'pose' & \verb'[0 0 0]'\\\verb'origin' & \verb'[0 0 0]'\\\verb'color' & \verb'"black"'\\\verb'mass' & \verb'1000.0'\\\hline\end{tabularx}\subsection*{GUI Properties}The properties in this section (\verb'gui.*') control the appearanceand behavior of the model in the GUI. They have no effect on thesimulation.\begin{tabularx}{\columnwidth}{llX}\hlineName & Values & Description \\\hline\verb'gui.boundary'& \verb'integer' & if non-zero, the model is drawn with abounding box.\\\verb'gui.grid'& \verb'integer' & if non-zero, the model is drawnunderlayed with a regular grid.\\\verb'gui.movemask'& \verb'integer' & A bitmask that controls themouse events that are sent to this model. Format: bit 0: translate,bit 1: rotate, bit 2: scale. For example the value '7' enablestranslation, rotation and scaling, and the value '5' enablestranslation and scaling only.\\\verb'gui.nose'& \verb'integer' & if non-zero, the model is drawn with a'nose', indicating its heading.\\\\\hline\end{tabularx}\subsection*{Defaults}\begin{tabularx}{\columnwidth}{llX}\hlineName & Value\\\hline\verb'gui.boundary' & \verb'0'\\\verb'gui.grid' & \verb'0'\\\verb'gui.movemask' & \verb'7'\\\verb'gui.nose' & \verb'1'\\\hline\end{tabularx}\newpage\section{Laser model}The Laser sensor model simulates a scanning laser rangefinder.\subsection*{Properties}\begin{tabularx}{\columnwidth}{llX}\hlineName & Values & Description \\\hline\verb'laser.return' & \verb'int' & controls how the model appears to alaser sensor. Set to 0 to be invisible, 1 to be visible or 2 to be'bright', i.e. return a non-zero reflectance like aretroreflector. This bright setting is useful for picking out specialobjects in your laser scan.\\\verb'laser.pose' & \verb'[x y a]' & pose of the laser sensor in local CS.\\\verb'laser.size' & \verb'[x y]' & size of the laser sensor. \\% TODO - check units - deg v. radians\verb'laser.view' & \verb'[min max fov]' & minimum and maximum rangeof the laser sensor, and field of view in radians. \\\verb'laser.samples' & \verb'integer' & the number of samples returnedby the laser. Each sample will correspond to 1/fov radians of thefield of view.\\\hline \\\end{tabularx}\newpage\section{Fiducuial model}The Fiducial sensor model locates models that have a non-zero\verb'fidicial.return' property. It returns the identity, range,bearing, orientation and size of the detected fiducials (note thatPlayer's fiducial interface does not return an individual size foreach fiducial.\subsubsection*{Properties}\begin{tabularx}{\columnwidth}{llX}\hlineName & Values & Description \\\hline\verb'fiducial.return' & \verb'integer' & the value returned if we areinspected by a fidicual finder. Set to zero to be invisible (so thesensor can't see you or the things behind you), or -1 to betransparent (so the sensor can see right through you).\\\verb'fiducial.view' & \verb'[min max fov]' & the minimum andmaximum range of the sensor in meters, and its field of view inradians.\\\verb'fiducial.id_limit' & \verb'float' & the maximum range at which afiducial's ID can be read. If this is < 0, the sensor's maximum rangeis used.\\ \hline\end{tabularx}\newpage\section{Position model}The Position model simulates a mobile robot base. It allows clients todrive a model around, and to read odometry data.\subsection*{Properties}\begin{tabularx}{\columnwidth}{llX}\hlineName & Values & Description \\\hline\verb'position.return' & \parbox{30mm}{\verb'"visible"'\verb'"invisible"'} & Specifies whether or not this object is anobstacle for collision detection.\\%\verb'position.drive' & \verb'"diff"' or \verb'"omni"' & Selects differential or omnidirectional drive\\%\verb'init_odom' & \verb'[x y a]' & Initial odometry (position and orientation).\\%\verb'reset_if_no_subscribers' & \verb'"yes"' or \verb'"no"' & If \verb'"yes"', %then the odometry will be reset to 0.0, 0.0, 0.0 if no clients are subscribed%(Prior versions of Stage always did this.)%If \verb'"no"', then previous values will remain.\\\hline\end{tabularx}\newpage\section{Ranger model}The Ranger sensor model simulates an array of rangefinders. Itapproximates real-world sonar and infrared rangefinders.\subsection*{Properties}\begin{tabularx}{\columnwidth}{llX}\hlineName & Values & Description \\\hline\verb'ranger.return' & \verb'int' & Specifies whether or not this entity will bedetected by ranger sensors. Set to 1 to be visible, 0 to be invisible.\\\verb'ranger.count' & \verb'integer' & The number of rangertransducers.\\ \verb'ranger.pose[i]' & \verb'[x y a]' & The pose of transducer\verb'i' in local coordinates.\\ \verb'ranger.size[i]' & \verb'[x y]' & The size of transducer \verb'i'.\\\verb'ranger.view[i]' & \verb'[min max fov]' & The minimum and maximumrange (in meters) and the field of view (in radians) of transducer\verb'i'.\\\hline\end{tabularx}\newpage\section{Blobfinder model}The Blobfinder sensor model simulates color-blob-tracking devices suchas ACTS and the CMUCam.\subsection*{Properties}\begin{tabularx}{\columnwidth}{llX}\hline Name & Values & Description \\ \hline \verb'blob.return' & \verb'int' & Specifies whether or not this entitywill be seen by a blobfinder; set to 1 to be visible, 0 to beinvisible. The channel in which we appear is determined by our\verb'color' property and the viewer's \verb'blob.channels'property.\\\verb'blob.count' & \verb'integer' & the number of color channels totrack.\\\verb'blob.range' & \verb'float' & the maximum range of the blobfinder.\\\verb'blob.image' & \verb'[width height]' & the width and height ofthe blobfinder's virtual image in pixels.\\\verb'blob.ptz' & \verb'[pan tilt zoom]' & the pan and tilt of thecamera, and the field of view, all in radians.\\\verb'blob.channels' & \verb'["color0" "color1" ...]' & Thecolor detected by each channel. Descriptivecolor names from the X11 color database should be used(e.g. \verb'"red"' or \verb'"blue"'). Look for \verb'rgb.txt' in yourX installation).\\\hline\end{tabularx}\newpage\section{Energy model}The Energy model simulates battery energy storage, expenditure andrecharging. A model can be configured to have a charging probe. If theprobe touches another object, energy is transferred from the probee tothe prober.\subsection*{Properties}\begin{tabularx}{\columnwidth}{llX}\hline Name & Values & Description \\ \hline \verb'energy.return' & \verb'float' & The amount of energy per secondthis device will supply when probed. \\\verb'energy.capacity' & \verb'float' & Storage capacity in Joules.\\\verb'energy.range' & \verb'float' & Length of our charging probe.\\\hline\end{tabularx}\bibliographystyle{plain}\bibliography{playerstage}\end{document}
Something went wrong with that request. Please try again.