Difference between revisions of "Camogm"

Revision as of 21:33, 18 November 2007

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

xstatus

save_gp

exif

timescale

format

reset

debug

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.