


Camwire configuration management
================================


Camwire needs hardware configuration information for each type of camera
it works with, or even for each individual camera if you would like to
configure cameras differently from one another.  It reads this
information from a configuration file ending in a .conf extension.

The information in the configuration file is bus-specific in that it is
stuff the general user need not know or care about if all they want to
do is run a correctly-configured camera.

The creation of new configuration files has been somewhat automated.
The first time you run Camwire with new camera, it will exit with an
error message saying that it could not find a hardware configuration
file.  It does however also query the camera and print a possible
hardware configuration to the standard output.

To create a configuration file, copy this suggested configuration
verbatim into a file (and edit as needed).  The filename must be
identical to one of the camera's ID strings (as may be obtained from
camwire_get_identifier()) appended by an extension of ".conf".  The
Camwire configuration message will prompt you with suitable filenames.

Camwire first looks in the current working directory for configuration
files and, if it does not find a suitable one, in a directory given by
the CAMWIRE_CONF environment variable.  Within each of these
directories, Camwire first looks for a filename containing the camera's
chip ID, then for a filename containing the camera's model, and lastly
for a filename containing the camera's vendor.

Although you may be able to get going with Camwire's best-guess
configuration, you probably will have to edit the configuration file to
supply some data that Camwire cannot get from the camera.  For example,
for IEEE 1394 cameras, Camwire has no way of knowing the meaning of the
shutter register.  It needs to be told by how many seconds the
integration time changes when the shutter register is incremented by
one, and what register value of 0 means.

These numbers are typically different for every make of camera.  The
values should be obtained from the camera's user's manual or the
manufacturer.  If you are lucky there may be a configuration file for
your camera in the etc/camwire directory of the Camwire distribution.

There is a tool in the examples directory called measureconf_1394.  It
automatically exercises you camera to estimate the best timestamp
parameters for the conf file.  Type `measureconf_1394 -h' for
documentation.

An example configuration file for an IEEE 1394 camera looks like this
(without the ----- lines):

----------------------------------------------------------------
Camwire IEEE 1394 IIDC DCAM hardware configuration:
  bus_speed:           400
  format:              7
  mode:                0
  max_packets:         4095
  min_pixels:          4096
  trig_setup_time:     2.2e-05
  exposure_quantum:    2e-05
  exposure_offset:     0
  line_transfer_time:  1.5672e-05
  transmit_setup_time: 0.000231
  transmit_overlap:    1
  drop_frames:         0
  dma_device_name:     
----------------------------------------------------------------

For the IEEE 1394 bus, the fields have the following meanings:

bus_speed:		The IEEE 1394 bus speed, one of 100, 200, 400,
			etc.
		      
format:			The IIDC DCAM format, one of 0, 1, 2 or 7, which
			mostly sets the frame size.  Each camera
			typically supports only one or two formats.

mode:			The IIDC DCAM mode which sets the camera's
			colour coding or number of bits per pixel.
			There are different sets of modes for each
			format.  Each camera typically supports only one
			or two modes in each format.

max_packets:		(Format 7 only.)  The maximum number of packets
			per frame the camera is capable of.  Since the
			frame rate is indirectly determined by the total
			number of packets per frame, this number sets a
			lower bound on the minimum frame rate.

min_pixels:		(Format 7 only.)  The minimum number of pixels
			per frame the camera is capable of.  Since the
			frame rate is indirectly determined by the total
			number of pixels per frame, this number sets an
			upper bound on the maximum frame rate.

trig_setup_time:	The delay in seconds between the trigger and the
			start of exposure (integration).  Used in
			timestamp calculation.

exposure_quantum:	The number of seconds by which the exposure
			(intergration) time increases when the shutter
			register increments by one.

exposure_offset:	The number of seconds of exposure (integration)
			time (positive or negative) when the shutter
			register is 0.

line_transfer_time:	The number of seconds by which frame
			transmission from the camera to the bus is
			delayed for each line (row) in the frame
			(assuming the number of frame lines equals the
			height of the frame).  This number is typically
			non-zero when frames are buffered in the camera
			prior to frame transmission.  If frame buffering
			and transmission happen simultaneously or if the
			frame buffering delay is independent of the
			frame height, then the line transfer time should
			be set to zero.  Used in timestamp calculation.

transmit_setup_time:	The number of seconds' delay before frame
			transmission starts.  This may be due to frame
			buffering in the camera which takes a constant
			time per frame.  The transmit setup time can be
			negative if line_transfer_time is positive and
			transmission starts before frame buffering from
			the sensor has finished.  This number can be
			used as a general-purpose frame timing offset
			which will be subtracted from the frame's
			timestamp.  Used in timestamp calculation.

transmit_overlap:	A flag which is true (1) when the camera reads
			out its image sensor to an internal buffer at
			the same time as transmitting the buffer to the
			computer, or false (0) if the two processes
			happen in tandem.  This information is used to
			calculate accurate timestamps.  You can set it
			either way if you are not interested in
			timestamps, or use measureconf_1394 to
			detect what your camera does.

drop_frames:		If this flag is set then any frames by which we
			are behind are dropped (flushed) and only the
			latest available frame is returned.

dma_device_name:	The name of the low-level driver.  If this is
			the empty string then a default driver name is
			used (something like "/dev/video1394/%d" where
			%d is the port (OHCI host chip or card) number).


Johann Schoonees
Industrial Research Limited, PO Box 2225, Auckland, New Zealand

$Id: CONFIGURATION,v 20.0 2011/02/17 02:07:38 johanns Exp $
