Difference between revisions of "Imgsrv"

Revision as of 23:43, 2 October 2007

imgsrv - Simple and fast HTTP server to provide still images and metadata acquired by the camera

Overview

This server was developed to increase the transfer rate of individual images acquired by the Elphel 353 series cameras as the CGI (and even fastCGI applications) connected through the universal web servers (Boa, included with Axis SDK, currently on the default port 80 in camera and lighttpd - now used in Elphel cameras together with php in fast CGI mode, port 81) failed to reach the top speed of the 100mbps network. Specialized imgsrv is connected through a different port (currently listens to 8081) and writes GET responses directly to the socket (reading image data from the circbuf using zero-copy memory mapping mmap), reaching 9-10MB/sec - virtually the full bandwidth of the network. This server does not provide any control over the sensor or FPGA compressor operation, its only purpose is to get data acquired to the (currently 19 MB) circular buffer in the system RAM. It is intended to have the functionality similar to the camera video streamers that also deal with the data already being acquired to the system buffer to be used when individual images are needed rather than the continuous video stream .

The imgsrv makes use of the new functionality of the /dev/circbuf driver providing it with a convenient web front end. It serves JPEG images (with Exif data attached) as well as metadata and circbuf status formatting output as the xml files.

imgsrv usage

imgsrv listens to the camera http port (currently 8081) and parses the rest of the url string as a series of commands, i.e.:

http://<camera_ip>:8081/torp/wait/img/next/save , where <camera_ip> is the camera IP address 

The above command will be interpreted as the following sequence:

1. set the current image pointer to the global read pointer stored in teh driver;
2. wait for the image at that pointer to become available (it is possible that no waiting will actually take place if the image acquisition is ahead of the reading images out process. As far as the image readout process does not fall behind too far (by the size of the circbuf) it is OK.
3. transfer compressed image to the client
4. advance frame pointer to the next one
5. and finally - save the new pointer to the global read pointer, so that the same url can be used over and over each time providing the next acquired image

If issued with empty arguments (just http://<camera_ip>:8081/ ) imgsrv outputs a text file with the list of the valid commands.

Commands are separated from the server url and from each other by the slashes ("/"), "?" and "&" also work. Each command is interpreted sequentially, from the left to the right. First group of commands generates response data sent to the client, they are mutually exclusive and can appear only once in the command line (url). Each subsequent instances of such commands will be ignored. If none of the response-generating commands appear in the URL (but the url is not empty) the server will generate a minimalistic response - 1x1 pixel image. The commands of that group are the following:

• img - send image at the current pointer (if it is first command - use last acquired image, if none availabe - send 1x1 gif)
• bimg -same as above, but save the whole image in the memory before sending - useful to avoid overruns with slow connection
• meta - send XML-formated metadata of the current frame instead of the image
• pointers - send XML-formatted data about frames available in the camera circular buffer)

                     "Any of the 4 commands above can appear only once in the URL string, the second instance will be ignored. If none of the 3\n" \
                     "is present in the URL 1x1 pixel gif will be returned to the client after executing the URL command.\n\n" \
                     "torp -   set frame pointer to global read pointer, maintained by the camera driver. If frame at that pointer\n" \
                     "         is invalid, use scnd (see below)\n" \
                     "towp -   set frame pointer to hardware write pointer - position where next frame will be aquired\n" \
                     "prev -   move to previous frame in buffer, nop if there are none\n" \
                     "next -   move to the next frame in buffer (will stop at write pointer, see towp above)\n" \
                     "last -   move to the most recently acquired frame, or to write pointer if there are none.\n" \
                     "         this command is implied at the start of the url command sequence.\n" \
                     "first -  move to the oldest frame still available in the buffer. It is not safe to rely on it if\n" \
                     "         more frames are expected - data might be overwritten at any moment and the output will be corrupted.\n" \
                     "second - move to the second oldest frame in the buffer - somewhat safer than \"first\" - there will be time for\n" \
                     "         \"next\" command at least before frame data (and pointer structures) will be overwritten.\n" \
                     "save   - save current frame pointer as a global read pointer that holds it values between server requests.\n" \
                     "         This pointer is shared between all the clients and applications that use it.\n" \
                     "wait   - Wait until there will be a frame at current pointer ready\n";</nowiki>