| 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 |
| 28 |
29 |
+ shutdown - Make this server exit |
| 29 |
30 |
+ exit or quit or q - Close the connection |
| 30 |
31 |
. OK |
| 31 |
32 |
}}} |
| 32 |
33 |
== Starting the Service == |
| 33 |
34 |
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 |
35 |
{{{ |
| 35 |
36 |
fitspipe 9999 |
| 36 |
37 |
}}} |
| 37 |
38 |
By default the server becomes a daemon/background process after the listening socket is open. |
| 38 |
39 |
== Creating Feeds == |
| 39 |
40 |
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. |
| 40 |
41 |
== Putting Frames In (fitspipe-put) == |
| 41 |
42 |
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: |
| 42 |
43 |
{{{ |
| 43 |
44 |
grasp_vidgrab ... | fitspipe-put localhost:9999/default |
| 44 |
45 |
}}} |
| 45 |
46 |
Or the equivalent: |
| 46 |
47 |
{{{ |
| 47 |
48 |
grasp_vidgrab ... | fitspipe-put server=localhost port=9999 feed=default |
| 48 |
49 |
}}} |
| 49 |
50 |
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. |
| 50 |
51 |
== Getting Frames Out (fitspipe-get) == |
| 51 |
52 |
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. |
| 52 |
53 |
The '''fitspipe-get''' tool takes the same parameters as '''fitspipe-put''' plus an additional parameter called '''fullheader=true|false''' which is described below |
| 53 |
54 |
{{{ |
| 54 |
55 |
fitspipe-get server=localhost port=9999 feed=default | ... |
| 55 |
56 |
}}} |
| 56 |
57 |
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. |
| 57 |
58 |
=== fitspipe-get fullheader=true === |
| 58 |
59 |
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. |
| 59 |
60 |
== Viewing the Frames == |
| 60 |
61 |
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: |
| 61 |
62 |
{{{ |
| 62 |
63 |
fitspipe-get server=localhost port=9999 feed=default | zimfits |
| 63 |
64 |
}}} |
| 64 |
65 |
Essentially, put '''zimfits''' in for the '''...''' in the fitspipe-get example above. Try '''zimfits -h''' for more information on its command line options: |
| 65 |
66 |
{{{ |
| 66 |
67 |
--help Display command line options |
| 67 |
68 |
-if F Read from file F instead of stdin |
| 68 |
69 |
-box NXxNY[:X0,Y0] Read only a subarray from a file centered at X0,Y0 |
| 69 |
70 |
-fzoom N Zoom/pan via prebinned files, start at extension .rN at 2^N bin |
| 70 |
71 |
-binx A Bin factor in x (default 1) |
| 71 |
72 |
-biny A Bin factor in y (default 1) |
| 72 |
73 |
-anax A Anamorphic display magnification factor in x (default 1) |
| 73 |
74 |
-anay A Anamorphic display magnification factor in y (default 1) |
| 74 |
75 |
-dt T Delay at least T sec between frames |
| 75 |
76 |
-xflip Flip images in x |
| 76 |
77 |
-yflip Flip images in y |
| 77 |
78 |
-rot R Rotate images by 90 deg CCW (R=+1) or CW (R=-1) |
| 78 |
79 |
-nstat N Size of statistics box (default 32) |
| 79 |
80 |
-stat X Start running statistics X |
| 80 |
81 |
-follow Follow PSF if persistent stats (default 1) |
| 81 |
82 |
-nofollow Do not follow PSF if persistent stats (default 1) |
| 82 |
83 |
-eofquit Quit upon EOF on input |
| 83 |
84 |
-novideo Suppress X video display (but do stats if requested) |
| 84 |
85 |
-pkbord N Border to ignore for PSF search (default 30) |
| 85 |
86 |
-psfwhm F Smoothing to apply for PSF search (default 0.0) |
| 86 |
87 |
-leak N Leaky average number of previous frames to subtract (default 0) |
| 87 |
88 |
-auto N Autoscale or not? (0/1, default 1) |
| 88 |
89 |
-z0 Z Set stretch threshold to Z |
| 89 |
90 |
-z1 Z Set stretch saturation to Z |
| 90 |
91 |
-slin S Stretch non-linearity: S = 0/1/2/3 for lin/log/sqrt/rtlog (0) |
| 91 |
92 |
-ignore N Ignore pixels valued N for autoscaling (0) |
| 92 |
93 |
-fmt N 0/1 for human/program stats output (0) |
| 93 |
94 |
-passthru Copy all input to stdout |
| 94 |
95 |
-v V Set verbosity level to V (default 0) |
| 95 |
96 |
}}} |
| 96 |
97 |
and mouse input and keystrokes accepted in the running window: |
| 97 |
98 |
{{{ |
| 98 |
99 |
left_mouse Zoom out by a factor of 2 |
| 99 |
100 |
mid_mouse Pan to center on mouse location |
| 100 |
101 |
right_mouse Zoom in by a factor of 2 |
| 101 |
102 |
@ Recenter and restore 1:1 zoom |
| 102 |
103 |
! Recenter and restore 1:1 zoom |
| 103 |
104 |
# zoom in by x64 and print data values on pixels |
| 104 |
105 |
$ Toggle between sampling and averaging when zoomed out |
| 105 |
106 |
(space) Pause the display of FITS images |
| 106 |
107 |
, Single step to the next FITS image |
| 107 |
108 |
- Set the stretch threshold at this pixel value |
| 108 |
109 |
+ Set the stretch saturation at this pixel value |
| 109 |
110 |
a Toggle autoscale on and off |
| 110 |
111 |
s Report on statistics in a box at mouse location |
| 111 |
112 |
S Persistent report on statistics in previous box |
| 112 |
113 |
b-b Report on statistics in a box defined by two b's |
| 113 |
114 |
B-B Persistent report on statistics in previous box |
| 114 |
115 |
x Report on psf statistics at mouse location |
| 115 |
116 |
X Persistent report on psf statistics at previous location |
| 116 |
117 |
p Report on JT psf statistics at mouse location |
| 117 |
118 |
P Persistent report on JT psf statistics at previous location |
| 118 |
119 |
j Auto-detect a star and report on JT psf statistics |
| 119 |
120 |
J Persistent version of 'j' |
| 120 |
121 |
o Auto-detect a star and report on donut psf statistics |
| 121 |
122 |
O Persistent version of 'o' |
| 122 |
123 |
m Auto-detect a star and provide psf moments |
| 123 |
124 |
M Persistent version of 'm' |
| 124 |
125 |
? Create the command menu window |
| 125 |
126 |
q Quit |
| 126 |
127 |
}}} |
