Home

Documentation

Project Support

Changes in Version 5 of GraspExtrasSoftwareFitspipe

Author:
isani
Timestamp:
Fri Sep 14 08:47:28 2012

Legend:

Unmodified
Added
Removed
Modified

  • GraspExtrasSoftwareFitspipe

    v4 v5
    1 1  '''[wiki:GraspExtrasSoftware fitspipe]''' 
    2 2  A streaming FITS image server.  This server is often run on TCP port 9999 and currently supports 16 bit 2D FITS image data (and corresponding headers.)  It is best suited for "video" style applications when an external client, possibly on another host, needs to process or display live images from a "feed" within the server. 
    3 3  External clients need only be able to read (concatenated) FITS format from stdin.  The receiver client '''fitspipe-get''' handles the network communication with fitspipe server.  The tools '''fitspipe-get''', '''fitspipe-put''', and several other tools which can process this streaming video format are documented below on this page. 
    4 4  {{{ 
    5 5  % fitspipe -h 
    6 6  }}} 
    7 7  Currently produces the following help summary: 
    8 8  {{{ 
    9 9  Network FITS Video Stream Server v2.01 (svn 5372, Feb 03 2012) 
    10 10  usage: fitspipe <port> [daemon=false] 
    11 11  Listens on port for fitspipe network clients. Clients can either 
    12 12  "put" images into particular feed, or "get" images from one. 
    13 13  Protocol is handled by fitspipe-put and fitspipe-get respectively. 
    14 14  By default, fitspipe becomes a background process.  This can be 
    15 15  prevented by adding "daemon=false".  There are no other options 
    16 16  for the server.  Make sure your firewall protects "port" adequately. 
    17 17  }}} 
    18 18  Typing "help" on the socket of a running fitspipe produces: 
    19 19  {{{ 
    20 20  help 
    21 21  + fitspipe v2.01 Feb 03 2012 (compiled Feb 03 2012) commands: 
    22 22  +   <Dump in a FITS file>                 - Same as "put feed=default" 
    23 23  +   version                               - Show fitspipe server version 
    24 24  +   put feed=<feedname>                   - To submit a FITS file 
    25 25  +   get feed=<feedname> [frame=<frameno>] - To retrieve a FITS frame 
    26 26  +   list or ls                            - List available feeds 
    27 27  +   composite compenable=<true|false> [compgeom=wxh compfeeds=<feed1,feed2,...>] 
    28 28  +                                         - Set up composite of multiple feeds 
    29 29  +   shutdown                              - Make this server exit 
    30 30  +   exit or quit or q                     - Close the connection 
    31 31  . OK 
    32 32  }}} 
    33    == Starting the Service == 
      33  === Starting the Service === 
    33 33  The "fitspipe" service is started at boot time from rc.local.  Typically, the rc.local script of a host offering fitspipe service will include a single line: 
    34 34  {{{ 
    35 35  fitspipe 9999 
    36 36  }}} 
    37 37  By default the server becomes a daemon/background process after the listening socket is open. 
    38    == Creating Feeds == 
      38  === Creating Feeds === 
    38 38  Feeds are created when a data provider produces the first frame.  In the future, we intend to implement a way to create feeds with nothing in them to ease startup problems resulting from not being able to start "fitspipe-get" to get video from a feed until the first frame has arrived. 
    39    == Putting Frames In (fitspipe-put) == 
      39  === Putting Frames In (fitspipe-put) === 
    39 39  Only 2D (NAXIS3=1), Basic FITS (no extensions), at 16 bits per pixel is accepted.  The simplest form of a client which produces frames for the "default" feed would be one which makes a socket connection to port 9999 (or whichever port the server is using) and writes an entire FITS file on the socket.  The server knows this method is being used when the conversation begins with "SIMPLE=T".  The client may leave the connection open and send the next frame when it is ready in the same manner.  Normally, the client used for this purpose is the program '''fitspipe-put'''.  This client uses a more complete version of the protocol which sends a "put feed=<feedname>" on a single line before each FITS frame.  The feedname, host, and port can be specified on the '''fitspipe-put''' command line, as in this example: 
    40 40  {{{ 
    41 41  grasp_vidgrab ... | fitspipe-put localhost:9999/default 
    42 42  }}} 
    43 43  Or the equivalent: 
    44 44  {{{ 
    45 45  grasp_vidgrab ... | fitspipe-put server=localhost port=9999 feed=default 
    46 46  }}} 
    47 47  The feed name can be any identifier (avoid spaces though) and grasp_vidgrab can be replaced by anything which produces concatenated FITS on its stdout. 
    48    == Getting Frames Out (fitspipe-get) == 
      48  === Getting Frames Out (fitspipe-get) === 
    48 48  Once a "feed" exists, the '''fitspipe-get''' tool is used to handle making a socket connection to the fitspipe server and converting the stream of FITS images something which can be read from stdout (just as the original output of grasp_vidgrab, but it doesn't have to be on the same host as grasp_vidgrab.  Also, multiple clients can register to receive the video.  In this way, fitspipe plus fitspipe-get can function as a tee, and way of distributing FITS data to different hosts. 
    49 49  The '''fitspipe-get''' tool takes the same parameters as '''fitspipe-put''' plus an additional parameter called '''fullheader=true|false''' which is described below 
    50 50  {{{ 
    51 51  fitspipe-get server=localhost port=9999 feed=default | ... 
    52 52  }}} 
    53 53  When used together with the '''fitspipe-put''' example from above, this produces the same result that reading the standard output of grasp_vidgrab in the original example would have.  In other words, a simple process which only knows how to produce FITS files on its output has been tunneled through the network. 
    54    === fitspipe-get fullheader=true === 
      54  ==== fitspipe-get fullheader=true ==== 
    54 54  By default, the '''fitspipe''' server sends a minimal, abbreviated header with each video frame.  This is fine when the connection is being used, for example, to display the images for the user with a graphical display program such as '''zimfits.'''  For other connections which may want a complete set of metadata and time stamps in each video frame header, the server should be send a command like "get feed=default fullheader=true" to enable this extra information.  The "fullheader=true" command line option to '''fitspipe-get''' does this. 
    55    == Viewing the Frames == 
      55  === Viewing the Frames === 
    55 55  Another unsupported "extra" provided with the STARGRASP software is an X-Window system utility called '''zimfits.'''  Zimfits requires an X-Display and can read back-to-back basic FITS images on its standard input and display them in a window.  It can read from grasp_vidgrab or fitspipe-get.  To display with fitspipe-get, use the following syntax: 
    56 56  {{{ 
    57 57  fitspipe-get server=localhost port=9999 feed=default | zimfits 
    58 58  }}} 
    59 59  Essentially, put '''zimfits''' in for the '''...''' in the fitspipe-get example above.  Try '''zimfits -h''' for more information on its command line options: 
    60 60  {{{ 
    61 61   --help      Display command line options 
    62 62   -if F       Read from file F instead of stdin 
    63 63   -box NXxNY[:X0,Y0]  Read only a subarray from a file centered at X0,Y0 
    64 64   -fzoom N    Zoom/pan via prebinned files, start at extension .rN at 2^N bin 
    65 65   -binx A     Bin factor in x (default 1) 
    66 66   -biny A     Bin factor in y (default 1) 
    67 67   -anax A     Anamorphic display magnification factor in x (default 1) 
    68 68   -anay A     Anamorphic display magnification factor in y (default 1) 
    69 69   -dt T       Delay at least T sec between frames 
    70 70   -xflip      Flip images in x 
    71 71   -yflip      Flip images in y 
    72 72   -rot R      Rotate images by 90 deg CCW (R=+1) or CW (R=-1) 
    73 73   -nstat N    Size of statistics box (default 32) 
    74 74   -stat X     Start running statistics X 
    75 75   -follow     Follow PSF if persistent stats (default 1) 
    76 76   -nofollow   Do not follow PSF if persistent stats (default 1) 
    77 77   -eofquit    Quit upon EOF on input 
    78 78   -novideo    Suppress X video display (but do stats if requested) 
    79 79   -pkbord N   Border to ignore for PSF search (default 30) 
    80 80   -psfwhm F   Smoothing to apply for PSF search (default 0.0) 
    81 81   -leak N     Leaky average number of previous frames to subtract (default 0) 
    82 82   -auto N     Autoscale or not? (0/1, default 1) 
    83 83   -z0 Z       Set stretch threshold to Z 
    84 84   -z1 Z       Set stretch saturation to Z 
    85 85   -slin S     Stretch non-linearity: S = 0/1/2/3 for lin/log/sqrt/rtlog (0) 
    86 86   -ignore N   Ignore pixels valued N for autoscaling (0) 
    87 87   -fmt N      0/1 for human/program stats output (0) 
    88 88   -passthru   Copy all input to stdout 
    89 89   -v V        Set verbosity level to V (default 0) 
    90 90  }}} 
    91 91  and mouse input and keystrokes accepted in the running window: 
    92 92  {{{ 
    93 93   left_mouse   Zoom out by a factor of 2 
    94 94   mid_mouse    Pan to center on mouse location 
    95 95   right_mouse  Zoom in by a factor of 2 
    96 96   @            Recenter and restore 1:1 zoom 
    97 97   !            Recenter and restore 1:1 zoom 
    98 98   #            zoom in by x64 and print data values on pixels 
    99 99   $            Toggle between sampling and averaging when zoomed out 
    100 100   (space)      Pause the display of FITS images 
    101 101   ,            Single step to the next FITS image 
    102 102   -            Set the stretch threshold at this pixel value 
    103 103   +            Set the stretch saturation at this pixel value 
    104 104   a            Toggle autoscale on and off 
    105 105   s            Report on statistics in a box at mouse location 
    106 106   S            Persistent report on statistics in previous box 
    107 107   b-b          Report on statistics in a box defined by two b's 
    108 108   B-B          Persistent report on statistics in previous box 
    109 109   x            Report on psf statistics at mouse location 
    110 110   X            Persistent report on psf statistics at previous location 
    111 111   p            Report on JT psf statistics at mouse location 
    112 112   P            Persistent report on JT psf statistics at previous location 
    113 113   j            Auto-detect a star and report on JT psf statistics 
    114 114   J            Persistent version of 'j' 
    115 115   o            Auto-detect a star and report on donut psf statistics 
    116 116   O            Persistent version of 'o' 
    117 117   m            Auto-detect a star and provide psf moments 
    118 118   M            Persistent version of 'm' 
    119 119   ?            Create the command menu window 
    120 120   q            Quit 
    121 121  }}}