Camogm

Description

This program allows recording of the video/images acquired by Elphel 353/363 series cameras to the storage media. It is developed to use such media as hard disk drives, compact flash cards or USB storage devices (with reduced data rate as ETRAX FS processor currently supports only USB 1.1, not the fast USB 2). But it might work over the NFS and be useful even for the basic model 353 cameras that do not have any additional storage devices attached.

camogm is designed to run in the background and accept commands through a named pipe. It writes JPEG-encoded frames from the camera circbuf-circular video buffer in any of the 3 formats:

• ogm - MJPEG video in Xiph Ogg container
• jpeg - series of the individual JPEG files (1 file per frame)
• mov - MJPEG video in Apple QuickTime(R) container

As of today the last one (mov) is probably the fastest one in the camera as it uses the minimum of computational resources. Ogg is optimized for streaming and requires additional memory copying and checksum calculation for all of the recorded data, individual JPEG files grow large directories that can use system resources, while recording mov format simply merges FPGA-encoded frames (with JPEG and optional Exif headers added by the software) and the file header (with frame index) is calculated only once per file.

This program makes use of the circbuf that can hold several seconds of even high resolution/high frame rate video, so switching from file to file and/or waiting for the search operations on the HDD will not cause the frame loss - that can be verified if the Exif headers are enabled - regardless of the format selected each frame will have the exact timestamp (with 1 microsecond resolution).

Usage

Starting camogm

Eventually camogm will be started (and restarted if needed) automatically at boot time, now it is started manually with the command

camogm <named_pipe_name>

Where <named_pipe_name> is the filename that will be used to pass commands to the camogm. A good choice is "/var/state/camogm_cmd" and it is used in a camogmstate.php - a demo PHP script that can read the current status of the camogm recorder. Running camogm without any parameters or with "--help" will just output the short version of this page. So this is the example of the command that starts camogm as a background process from the shell prompt (i.e. telnet or Phpshell):

camogm /var/state/camogm_cmd &

Sending Commands to camogm

When the camogm is running you may verify that with the command:

ps | grep "camogm"

It is waiting fro the commands to be sent to the pipe (/var/state/camogm_cmd above) as text strings. Commands are separated with the new lines ("\n") and/or semicolons (";"), command names are separated from the optional parameters by spaces " " and/or equal signs "=". The following is an example of such command sent from the shell prompt using command "echo" and output redirection ">" to th camogm command pipe

echo "status; exif 1; format=jpeg;status=/var/tmp/camogm.status" > /var/state/camogm_cmd

That command will:

1. print current status information sending it to the standard output (may not be visible if the program was not started from the same session),
2. set exif mode ON (each frame will have the full Exif header including a precise time stamp),
3. set output format to a series of individual JPEG files, and then
4. send status information to a file /var/tmp/camogm.status in the camera file system.

The camogmstate.php script shows how to use a named pipe for the status information so the caller will wait until camogm returns that status info (the "echo" command by itself will not wait for the status, there can (and will) be a delay between finishing of echo (or equivalent) and the appearance of the status info in the output file. With the current state of the software that status info may never come if the camera frame capture process is stopped while camogm was recording video as it checks for the new commands once per frame if it is in the "running" state (in "stopped" state in checks for the incoming commands twice a second)

camogm Commands

start

No parameters - just start recording video/images. At least two frames in the buffer are needed to start recording (they will not be lost) - the time stamp difference is used to calculate the frame rate. In the case there are not enough frames in the buffer (i.e. video acquisition is not started) the state of the camogm (reported by status and xstatus) will be "starting" before it will become "running". The video will be recorded to the same file (may be a directory for .jpeg format) until explicitly stopped, or until the specified file size/duration/number of frames is exceeded or some critical parameters (like frame dimensions) are changed. In those cases (not explicitly stopped) camogm will restart recording into a new file (filenames are composed from the specified prefix and the timestamp) so that no frames will be lost (if it is not overwhelmed by the incoming frame rate) and the first frame of a new file segment will be the next one acquired after the last one in the previous file.

stop

Just stop the recording. If you the video acquisition is on and camogm is started again before the circbuf is overrun, there will be no gaps in the recording. But if the pause will be too long some frames will be lost and there will be a gap between the next file and the previous one.

exit

Terminate camogm program (it will execute implied "stop" command first to finish recording if any).

duration

duration=<time_in_seconds>

Specify the maximal duration of each individual file segment. The new file will be started if this time limit will be exceeded. The default duration is 60 seconds, current value is reported by status/xstatus commands.

length

length=<file_size_in_bytes>

Specify the maximal size of each individual file segment in bytes. The new file will be started if this limit will be exceeded. The limit is 100000000 bytes, current value is reported by status/xstatus commands.

prefix

prefix=<file_name_prefix>

prefix value is used by the camogm to generate file names/paths to store video content. Full paths will be generated from the specified prefix, timestamps of the first frame in the segment and appropriate extension (".ogm",".jpeg" or ".mov"). The prefix consists of directory path (everything before the last slash "/") and the file name prefix (what remains after the last "/"). In the case of video formats (".ogm",".mov") the directory prefix should point to an existent directory on the mounted writeable media - camogm will not try to create missing directories and will just fail to start recording. In the case of individual JPEG files camogm will try to create the last level in directory structure if it does not exist and place all the frame files there.

status

status
status=<status_output_file>

This command provides the current camogm state information and sends it to standard output (maybe invisible if camogm was started from different shell session or by other means) or to the specified output file in plain text format. The same information is available in XML format - see xstatus command below. The following is a commented sample output generated by the status command:

state              running                          // may be stopped, running and starting. Usually the last
                                                    // one can be only visible if there are no images coming to the buffer.
file               /tmp/z/qvid1195433980_662716.mov // full path toi the current file being recorded
frame              293                              // current frame number (starts from 0)
file duration      14.616060 sec                    // current duration of the video in this file segment
file length        13167561 B                       // current video file size
frame period       50055 (0xc387)                   // frame period in microseconds (this one is approximately 1/20 sec)
width              1024 (0x400)                     // frame width in pixels
height             768 (0x300)                      // frame height in pixels
                                                    // - blank line
output format      mov                              // output file format - one of "ogm", "jpeg" and "mov"
using exif         yes                              // frames are generated with Exif headers that include time stamps
path prefix:       /tmp/z/qvid                      // file prefix as specified in prefix command
max file duration: 60 sec                           // maximal file duration as specified in duration command
max file length:   100000000 B                      // maximal file length as specified in length command
max frames         16384                            // maximal number of frames as specified in ... none yet, uses default
timescale          1.000000                         // time scale as specified in timescale command
frames per chunk   10                               // "frames per chunk" used in "mov" format
                                                    // - blank line
buffer overruns    0                                // number of buffer overruns while recording since last status/xstatus
                                                    // (these commands zero the buffer overruns counter). If no overruns 
                                                    // are reported, no frames are lost, including between file segments.
buffer minimal     19748288                         // Minimal level of the buffer memory since last status/xstatus command.
buffer free        19748192                         // Current amount of free memory in the video buffer (actual value might
                                                    // be one frame less as the FPGA write pointer is reported only after
                                                    // the whole frame is stored
buffer used        43680                            // Amount of memory currently used in the video buffer.
circbuf_rp         10933536 (0xa6d520)              // Current location of the read pointer in the video buffer
                                                    // - blank line
debug output to    stderr                           // where the debug messages are sent to (as specified in debug command)
debug level        1                                // Debug verbosity level, the higher - the more "noisier". Set in
                                                    // debuglev command.
use global pointer no                               // As a debug feature camogm can set the camera global circbuf read pointer
                                                    // to the current value of camogm's read pointer. In that case it is possible
                                                    // to watch the progress by other programs, such as imgsrv

"-1" values that status/xstatus commands may return for some parameters mean "undefined", they are calculated only during video recording.

debuglev

This program does not control the process of acquisition of the video/images to the camera internal buffer, it only retrieves that data from the buffer (waiting when needed), packages it to selected format and stores the result files.