############################################################
# Georgia Tech AVS demo - the source-based filter UAV demo #
# - the adaptive video system                              #
# @author: Wenchang Yan                                    #
# @time: Feb, 2002                                         #
# (C) Copyright 2001, Georgia Institute of Technology      #
############################################################
 

0) Description
1) Source tree
2) Installation
3) How to run
4) Miscellaneous
5) Contact
6) Known Bugs

------------------------------------------------------------
0) Description

   I use alphabetic letters as various components in the following figure,
which depicts GaTech's wireless video source and source-based filters
demo. The numbers refer to video and control paths. We need your advice
to see a) if it's practically feasible (especially for the bandwidth) to
integrate with BBN distributor and b) what kind of modifications we'll
make to finally work out a detailed plan.
 

                              GUI
                   .-----   Control (D)   ----.
                   |                          |
                   v                          ^ (4)
                   v                          ^
        (1)        |          (2)             |       (3)
 WebCam =====> Video Channel - - - -> Video Channel =====> Video Display
   (E)          Source (A)            Receiver (B)              (C)

 
 

 The demo we have now consists of 5 components. The Source (A)  and the
WebCam (E) are on one laptop, the Receiver (B), the Displayer (C), and
the GUI Control (D)  run on
another laptop. Link (2) and (4) are wireless -- we set up an Ad-Hoc
peer-to-peer connection between the 2 laptops using WaveLan wireless PC card.
The 2 links are implemented in ECho API (mainly TCP connection), which is an
event delivery middleware developed at GaTech. Link (1) uses video4Linux API.
The GUI is in Java, the same GUI also have a window displays the video.
In order to integrate with BBN, we added some functionality to Dirk Farin's
DVDview to let it show PPM raw image directly. So we can also use DVDview as
component (C). The control path, link (4), works because of Java Natvie
Method (JNI). The source-based filtering starts from the control buttons
on the GUI, then applies to (A) dynamically by passing the various filters
from (B) to (A).

------------------------------------------------------------

1) Source tree

    The top directory of the avs demo is avs. The subdirectories and their contents are:

    doc/                                                the related document
    player/                                        the Java source and JNI code for the avs receiver
    playerBBN/                                 almost the same as player/ but CORBA interface is added
                                                                 for integration with BBN's UAV demo
    src/                                               the C source of the avs sender
    strlt/                                             the source filter directory, includes the e-code

------------------------------------------------------------

2) Installation

a) Required software before installing the avs demo

The avs demo is built on ECho, the event delivery middleware system developed here at GaTech. However the ECho is built on other systems like connection manager (cm), cmrpc and portable binary IO (pbio) etc. In addition, since the demo has a webcam as a standard video capture tool, the vdev intreface must be also installed before intalling the avs demo. The following is a list of the packages and their names of each top source tree.

ECho packages:

atl/                                           ECho attribute

cercs_env/                           the related info here in CERCS at GaTech

chaos_base/                        the related info for chaos group

cm/                                           the connection manager

cmrpc/                                      the connection manager

comm_group/                          cm based communication group

drisc/                                      for e-code generation ?

echo/                                           the ECho channel system

ecl/                                            e-code

gen_thread/                           generic thread interface

pbio/                                          the portable binary IO

pds/                                             the portable directory service - like CORBA naming service. In
                                                          development.

                                                  Note: the suggested order of the above packages is : (cercs_env must be present)
                                                           drisc -> ecl -> pbio -> gen_thread -> atl -> cm -> echo ->
                                                           comm_group -> cmrpc -> pds
 
 

Webcam interface:

vdev/                                        a webcam interface

The Video displayer:

dvdview/                            a modified version of the DVDview. DVDview is a 3rd party MPEG
                                                   playback software. This modified version can display PPM frame as well.
                                                  However, another PPM frame displayer is also provided in the Java GUI
                                                  control of the avs demo, which may be removed to use the modified
                                                  dvdview instead finally.
 

The installation of the above packages are based on GNU libtool and thus self explained.

Other packages may needed:

Any JDK above version 1.2. Please Do NOT use Kaffe JVM.

JacORB as the ORB to run the interface to trigger adaptation from BBN's UAV Quo side.

Jakarta-ant is a Java building tool. We need it to build the CORBA interface.
 
 

b) The installation of avs package

     First run `bootstrap' under avs/,  then type make to build the binaries for the source side of
     the demo. Hopefully it will build everything under src/, player/, and playerBBN/.

     Secondly, goto avs/playerBBN to build another version of the avs receiver, which includes the CORBA interface to receive the adapation triggered by the Quo contract region change. The build for this part is little bit awkward because I don't have much time to clean the building process. You MUST type `make' under avs/playerBBN first to install the usual Java GUI and JNI native method as you did in avs/player. Then you type `ant' (hope you have jakarta-ant installed) to install the CORBA interface and the testing Java CORBA client.

-----------------------------------------------------------------
 

3) How to run

     I ONLY describe the way that leads you run under Linux.

a) Hook up the video capturing device.

We use `Creative Labs USB WebCam', so please find a USB WebCam which is compatible with V4L interface.

b) The set up of the environment variables under Linux

     LD_LIBRARY_PATH:          this variable must be setup so that includes the paths to locate all the
                                                           libraries for echo, cm, pbio, atl, ecl, cmrpc and
                      gen_thread. i.e. libecho.a, libcm.a, ... etc. In addition,
                      avs/player/.libs must also be appended to it in order to
                                                             invoke the JNI native methods.
                                                           Note:
                                                           If you want to run the receiver of the demo under avs/player
                       instead of the receiver under avs/playerBBN, please make sure
                                                            replace the avs/player/.libs with avs/playreBBN/.libs
                                                            in the LD_LIBRARY_PATH.

    AVS_STRLT_PATH:             this variable is for the searching of the streamlet source filter function
                                                           while doing the source filtering. Must be set to avs/strlt.

     FORMAT_SERVER_HOST:   this variable is the host id at which the format server will be found.
                                                          Usually you can set it to `localhost' if you have pbio installed on the
                                                          localhost.

c) Run the demo

    (the following are the steps to run the demo on one single host. If you run the source and receiver on 2 different host, the set up may change accordingly.)
 

Step 1: Start up the pbio format server (please setup FORMAT_SERVER_HOST correctly first.)

             Goto pbio/, type `./format_server &'.
             You may see `Trying connection to format server on localhost ... failed Forking server to
              background'. But it's fine, the format_server has already started running.

Step 1.5 (Optional): Start the dvdview PPM displayer.

             You may not need it running because we have a display window in the Java GUI to display the
             PPM frames for the current version of this demo. If you don't want to use the dvdview, just
             SKIP  this step.

             Goto dvdview/src, Type the following command line,

               ./dvdview -z PORT_NUMBER -E ANYTHING

              e.g.

               ./dvdview -z 12345 -E MPEGfilename
 

Step 2: Start the video source.

              Goto avs/src. Type the following command line,

              ./avs_source -c <numOfClients> -n <numOfFrames>

              e.g.

             [wyan@fern src]$ ./avs_source -c 1 -n 0

     Then the following will appear:

      Echo channel ID:

{IP_HOST,S24,w204d198.lawn.gatech.edu},{IP_ADDR,4,-951202618},{IP_PORT,4,32906},@e849050800000000

      Echo 2C (320x240-color) channel ID:
                 {IP_HOST,S24,w204d198.lawn.gatech.edu},{IP_ADDR,4,-951202618},{IP_PORT,4,32906},@a055050800000000

              Meaning: One client suffices for this demo.
                                The value of zero to the `-n' command line option indicates the frames will be fed to
                                the receiver forever.
                                The long output string is the ECho channel Id, you may cut&paste it (Echo 2C ID) to
                                 pass it in the command line when you start up the avs receiver. We used to have the
                                 pds (portable directory service) running helping us locate this Channel Id through its
                                 naming service. But it has some problem, so you have to bear with us for this
                                 cut&paste interface for the time being.

Step 3: Start the video receiver - You may have another option to run the video receiver integrated
                                                              with BBN's UAV demo. See Step 3' & Step 3.5 below.

              Goto avs/player. Type the following command line,

               $JAVA_HOME/bin/java VIEWER_NAME ECho_Channel_Id Channel_Type

               e.g.

                java avs.ViewClient
       "AnyName" "{IP_HOST,S24,w204d198.lawn.gatech.edu},
       {IP_ADDR,4,-951202618},{IP_PORT,4,32906},@a055050800000000"
       "2C"

               Meaning: Please use JDK.
                                 The first command line string is the name of the view window, you may type
                                  anything here. The second command line string is the ECho channel Id which you
                                  copied from the source side dump. Please put this Id in quotes.
                                  The last commandd line string is the starting channel type:
                                   we start from 320x240 (2) color level (C).
                                   Note: We use the following naming rule in the avs demo for describing the image
                                               type: The first number maps to the size of the PPM frame:

                                               2: 320x240
                                               3: 160x120
                                               4: 80x60

                                              The second Roman letter indicates if the image is a color image or grey image.

                                               C: color image, ie. usually 3 bpp
                                               G: grey image, ie. usually 1 bpp

                                                e.g. '3G' means 160x120 grey image.

                 Note:  As to the control buttons on the Java GUI, it's not supposed to run under any
                             permutated order, mostly due to the mechanic of how ECho channel is implemented.
                            If an incorrect chaining of the adapatation is applied, it will either crash the source or
                            the sink side. However, here're some rules for applying the control button:

                            0. If a series buttons have been clicked to apply the adaptation, you need to undo the
                                button in first-in-last-out order if you want to apply the next chain of adaptation.
                                i.e. you'd better come back to 320x240 color mode before applying the new serial of
                                button-clickings.
                           1. EdgeDetect can only be applied after GreyImage
                           2. If any of the CropImage is applied, it must be the first one in the adapation chain -- ie.
                                cropImage may be only applied at the first stage from 320x240 color (2C) raw channel.

Step 3': Start the video receiver that can accept adaptation from the trigger in BBN's UAV.
              Assume you have JacORB intalled to bring up the ORB. First need to setup the right
           $CLASSPATH environment. Make sure you setup LD_LIBRARY_PATH environment variable
              correctly -- i.e. playerBBN/.libs must replace player/.libs or at least in front of it
              in the searching order.

              e.g. under Linux, type

            export \
      CLASSPATH=$JacORB_ROOT/lib/jacorb.jar:$JacORB_ROOT/classes:$CLASSPATH:.
 

              Goto avs/playerBBN. Type the following command line,

                  jaco avs.ViewClientWrapper VIEWER_NAME ECho_Channel_Id Channel_Type

              Or

               java -classpath $CLASSPATH -Dorg.omg.CORBA.ORBClass=org.jacorb.orb.ORB -Dorg.omg.CORBA.ORBSingletonClass=org.jacorb.orb.ORBSingleton  avs.ViewClientWrapper VIEWER_NAME ECho_Channel_Id Channel_Type e.g. jaco avs.ViewClientWrapper "a" "{IP_HOST,S24,w204d198.lawn.gatech.edu},{IP_ADDR,4,-951202618},{IP_PORT,4,32861},@a055050800000000" "2C"

              Or

               java -classpath $CLASSPATH -Dorg.omg.CORBA.ORBClass=org.jacorb.orb.ORB -Dorg.omg.CORBA.ORBSingletonClass=org.jacorb.orb.ORBSingleton \ avs.ViewClientWrapper "a" "{IP_HOST,S24,w204d198.lawn.gatech.edu},{IP_ADDR,4,-951202618},{IP_PORT,4,32861},@a055050800000000" "2C"

             Meaning: avs.ViewClientWrapper is the wrapper class of ViewClient class under
           avs/player.
                              The rest of the command line options have the same meaning as in Step 3.
 
 

Step 3.5 (Optional): If you picked up Step 3 from above - Please stop here, this step is only for the
                                      testing purpose on the case see how the avs video receiver takes adaptation from
                                      the outside adapatation scheme, like Quo contract.

               First Goto avs/playerBBN, type `more refIOR'.
               Because the current testing version dumps the IOR to a file named `refIOR' under
             avs/playerBBN. Then type,

                  jaco avs.AdaptClient IOR_FROM_refIOR_file

                Or

                      java -classpath $CLASSPATH -Dorg.omg.CORBA.ORBClass=org.jacorb.orb.ORB -Dorg.omg.CORBA.ORBSingletonClass=org.jacorb.orb.ORBSingleton avs.AdaptClient IOR_FROM_refIOR_file

                 e.g.
          java -classpath $CLASSPATH -Dorg.omg.CORBA.ORBClass=org.jacorb.orb.ORB -Dorg.omg.CORBA.ORBSingletonClass=org.jacorb.orb.ORBSingleton avs.AdaptClient
IOR:000000000000001849444c3a6176732f41646170744176735561763a312e300
000000003000000000000002e000100000000000a3132372e302e302e310081f300
000016373836343831323531392f00103e0e03422c16011e3900000000000000000
034000101000000000a3132372e302e302e310081f3000000163738363438313235
31392f00103e0e03422c16011e39000000000000000000010000000800000000000
00000

         This will give you a simple testing program to test the dynamic adaptation. --------------------------------------------------------------------

4) Miscellaneous
  a) The dynamic Qos support (fps control) has been added to the original avs demo. So the /playerQos is created and contained the new version on the player side. The /playerQos also has all the functionality which has in the /player. So the player under /player won't be maintained anymore. May, 2002. --------------------------------------------------------------------
5) Contact

       Wenchang Yan
        wyan@cc.gatech.edu

6) Known Bugs
   
     a) The ECho source on used in the demo (An old version of ECho) works under gcc2.95/2.96. Although it may also work under gcc3.*, it may cause run time error in the demo when it does derived channel creation. ECho has a new version works with gcc3.*, but then some changes in the new ECho prohibits the usage of this avs demo. For example, the format Id of the channel Id changes and the format_server changes.

     b) The jdk1.4 may throws `undefined symbol: gxx_personality...'  exception at run time. This is because gcc3.* requires libstdc++ at run time. You may explicitly put libstdc++ into the linking when you build your JNI code at the player side.