FrameView2d - Frequently Asked Questions (FAQ)

The information in this file is provided without warranty
for its accuracy or completeness. Use of this file or its
information is entirely at your own risk.

CONTENTS

     * 1 Introduction and General Information
          + 1.1 What is FrameView2d?
          + 1.2 Who has written it?
          + 1.3 Does it run on my machine?
          + 1.4 Does FrameView2d require any proprietary libraries to run?
          + 1.5 Is FrameView2d copyrighted? What is the licensing agreement?
          + 1.6 What is the latest version of FrameView2d?
          + 1.7 How do I send a bug report?
          + 1.8 How do I send a compilation bug report?
     * 2 Network Sources and Resources
          + 2.1 Where can I get FrameView2d?
          + 2.2 Does FrameView2d have a mailing list?
          + 2.3 Does FrameView2d have a world wide web home-page?
     * 3 General Features
          + 3.1 How do I get help on the command line?
          + 3.2 How do I zoom in and out in the viewer?
          + 3.3 How do I get the initial zoom area?
          + 3.4 How do I move the viewing area?
          + 3.5 How do I quit the FrameView2d?
          + 3.6 How do I visualize my data?
          + 3.7 Can I use doxygen to produce an online documentation 
                of the source code?
     * 4 Usage with of the Soccer Monitor Device (of the robocup.org)
          + 4.1 How do I connect to the soccer server?
          + 4.2 How do I drag and drop players/ball on the screen?
          + 4.3 Are there some short-keys to move players or the ball?
          + 4.4 What does 'skipped n SHOW messages' mean?
          + 4.5 What's the meaning of the 'scale 1.0' button?
          + 4.6 What's the meaning of the 'detail 1' button?
          + 4.7 How do I connect with protocol version 1 instead of 2?
     * 5 Common Problems
          + 5.1 ...
     _________________________________________________________________

1 INTRODUCTION AND GENERAL INFORMATION

1.1 What is FrameView2d?

   FrameView2d is a viewer for moved 2d vector graphics. It runs on 
   Linux (Unix) computers that run the X Window System. 
   FrameView2d was born from a need to easily visualize 2 dimensional 
   systems. In 1999 when the development started it was the need to 
   visualize (with all details!) the soccer field of the robocup
   simulation league. The architecture of FrameView2d was from the
   beginning kept as general and modular as possible and not just
   hacked to fit the  needs of the robocup soccer server. So by now
   FrameView2d is also used to  visualize many other two dimensional
   system. 

   You can use UDP/IP communication sockets to send commands 
   to FrameView2d. For applications which are independent of FrameView2d
   you can easily define communication stubs as it is the case for the
   robocup soccer server. A generic communication device is also included.
   It understands a very easy description language to build and move 2d 
   objects. 

1.2 Who has written it?

   FrameView2d was written by Artur Merke. The development started in
   August 1999 (after the robocup championship in Stockholm ;-) and was
   gradually improved (and is still developed) in the spare time of
   the author.

1.3 Does it run on my machine?

   FrameView2d is just tested to run for Linux. However it should also
   run on any other Unix systems (actually the development started
   under SunOS), provided that system is running the X Window System,
   version X11/R6. 

   FrameView2d does not require any of the X11 extensions that many other 
   programs need to compile or run (no Gtk, Qt or Motif is needed)!

1.4 Does FrameView2d require any proprietary libraries to compile/run?

   No. FrameView2d requires only the basic X11 library (libX11) to run
   which is available as free-ware.

   FrameView2d does not require any of the X11 extensions that many other 
   programs need to compile or run (so no Gtk, Qt or Motif is needed)!

1.5 Is FrameView2d copyrighted? What is the licensing agreement?

   FrameView2d is licensed under the GNU GENERAL PUBLIC LICENSE. This means
   that you can freely distribute FrameView2d under certain conditions. The
   file COPYING.TXT contains the full licensing agreement. You are advised
   to read this license to be sure of your restrictions and obligations
   when modifying or distributing FrameView2d.

1.6 What is the latest version of FrameView2d?

   The distribution that this FAQ.TXT file was packed into is

       FrameView2d version 1.2

   created on

       25 March 2001

   (or some later version/date if I forgot to actualize the upper
    entries ;-)

1.7 How do I send a bug report?

   If you discover a bug, please comply with the following procedure:

      *  Make sure you have the latest version. Do NOT report a bug
         from an old version.

      *  Find out exactly how to reproduce the bug. If it is a
         behavioural problem, define it in detail, explaining the exact
         key presses and key releases involved. Suggest exactly how you 
         would like it to function.

      *  If an error message was reported, quote the error message in
         full, letter for letter.

      *  If the bug is a program crash, recompile FrameView2d with the -g
         option and use gdb to list a backtrace.

      *  Email the author. Be sure to quote the version number. The
         operating system version, the version of libc you are using,
         and the version of X.

      *  It is not necessary to prove that there really is a problem
         with a lengthly litigative argument. Rather demonstrate it
         with a precise procedure.

1.8 How do I send a compilation bug report?

   It is considered important when FrameView2d does not compile
   and install cleanly on a particular LINUX system, hence please
   report such problems. 

   If you have a genuine compilation difficulty, please send the
   version number, the output of make and build phases of the installation, as
   explained in the INSTALL.TXT file.

   However I AM NOT HERE TO TEACH YOU HOW TO INSTALL A PROGRAM. 

2 NETWORK SOURCES AND RESOURCES

2.1 Where can I get FrameView2d?

   The latest stable release can be obtained from
       http://i11www.ira.uka.de/~amerke/frameview

2.2 Does FrameView2d have a mailing list?

   No. Correspondence to be addressed through the
   author. Please don't bug me with generic queries.
   There are newsgroups and local Linux User Groups
   for that.

2.3 Does FrameView2d have a world wide web home-page?

   http://i11www.ira.uka.de/~amerke/frameview	

3 GENERAL FEATURES

3.1 How do I get help on the command line?

   Just type

      2dview -help
   or 
      2dview -help | less

   to view the list of command line options.

3.2 How do I zoom in and out in the viewer? 

   You can use the left mouse button to define a new rectangle to zoom
   into a smaller region. You can also use the '+'/'-' keys to zoom in
   and out in the region.

3.3 How do I get the initial zoom area? 

   You can press the 'i' key in the FrameView2d screen to get the
   initial magnification factor. More sophisticated UNDO/REDO
   facilities of zooming areas are not yet supported.

3.4 How do move the viewing area?

   You can use the cursor keys to move the viewing area. 
   You can also use a short click of the left mouse button to change
   the center of the viewing area.

3.5 How do I quit the FrameView2d?

   You can always quit FrameView2d hitting the 'q' key. Some devices
   also support a quit button.

3.6 How do I visualize my data?

   There are two possibilities to use FrameView2d to visualize own
   data. You can use the generic device AsciiDevice by calling

      2dview -ascii  ...

   and then send you data in the AsciiDevice format over an UDP
   connection. See the 
    
      client2dview.C

   file for some simple examples ('make Client2dview' to get a working sample)

   The other way is to extend FrameView2d by writing your own device. 

3.7 Can I use doxygen to produce an online documentation of the source code?

   Yes. There is a 'Doxyfile' contained in the source code release. 
   So just run

   doxygen

   in your FrameView2d directory to get an new subdirectory doc/html
   containing the documentation. 

4 USAGE WITH OF THE SOCCER MONITOR DEVICE (of the robocup.org)	

4.1 How do I connect to the soccer server?

    See 3.1 for command line options or just type

       2dview -m_host <machine.name>

    you can skip the m_host option if the soccer server runs on 
    the same machine as FrameView2d.

4.2 How do I drag and drop players/ball on the screen?

    You need at least soccer server version 7.02 to use this
    feature (look at www.robocup.org)

    To move a player or the ball you have to click with the right 
    (or middle) mouse button on it. As long as you hold the mouse button
    on an object you can drag it to a new position. The old
    position is marked with a cross inside a circle. This is useful
    if you drag a player during a running game.

4.3 Are there some short-keys to move players or the ball?

   Yes. It is sometimes more convenient to instantly move an object. 
   Put 

      2dview -keys 

   to get a description how to do it. You can also hit the 'k' key
   in the FrameView2d screen to get a description on the xterm from 
   which you started FrameView2d. 

4.4 What does 'skipped n SHOW messages' mean

   This is a message indicates that FrameView2d gets more messages
   then it can actually process. There can be several reasons for
   this

   * your machine or X11 connection are simply to slow. 

   * you did connect more the once to the server. This can happen if
     you hit the 'c' or press the '(re)connect' button while a 
     connection is already running. 

   * you quit the FrameView2d while connected to the soccer
     server. Because there is no possibility to say the soccer server
     to stop sending the visual information it can happen that if you
     restart FrameView2d you'll get new visual data AND the old visual
     data (you get the new data automaticly because FrameView2d always
    tries to establish a connection to soccer server)

4.5 What's the meaning of the 'scale 1.0' button?	
   
   Click with the right mouse button on this menu button.
   This gets you to 'scale 1.2'. This means that all players and the
   ball are show 1.2 as large as they really are. You resize the
   objects up to factor 2.0 (but it is easy to change it to any other
   factor)  

   To get the objects smaller just reduce the scale clicking the 
   left mouse button on the 'scale X.X' menu button.

4.6 What's the meaning of the 'detail 1' button?

   Use the right/left mouse buttons to change the details level. The
   default level is 1, on which you can just see the player numbers. 
   Increasing the level you can also see the type of players (not yet
   implemented) and their stamina  (already implemented).

4.7 How do I connect with protocol version 1 instead of 2?

   You can connect to the soccer server with the old version 1 including
   the option

   -m_version 1

   into you command line call. The default version is 2, because it
   can show the positions of the players more exactly (using
   SHOWINFO_SCALE2) and provides information about the type, stamina
   and neck_angle of players. But sometimes there are reasons to use 
   protocol version 1, e.g.:

   *   you use own tools which still communicate with the version 1 of
       the soccer monitor protocol.

   *   because version 2 of the robocup soccer monitor protocol 
       needs more bandwidth, on some slow networks version 1 could
       perform better.

5 COMMON PROBLEMS

5.1 ...