README for aglaia 0.1

25.02.2002
Benjamin Hummel <benjamin@datamaze.de>


What is this?
~~~~~~~~~~~~~

aglaia is a tool for IEEE1394 cameras. Actually it's more a toy than a tool.
It takes images from the camera optionally applies some filters and displays
the result. Optionally you can save these images to disk (JPEG).


Prerequisites
~~~~~~~~~~~~~

* Obviously a working IEEE1394 subsystem (especially raw1394 module).
  I've tested it with a 2.4.17 kernel, but other kernels might work as well.
  (You might use gscanbus and coriander (see below) to test your IEEE1394 setup)

* libraw1394

* libdc1394

* libjpeg from the Independent JPEG Group (www.ijg.org)

* SDL (www.libsdl.org)

* And of course gcc, make, etc. to compile.


How to compile
~~~~~~~~~~~~~~

Compilation is as simple as typing
	make
in the aglaia source directory


Commandline options
~~~~~~~~~~~~~~~~~~~

aglaia understands the following options:

 -a, --autocapture
	Starts aglaia with capturing started (see also -t)

 -c <value>
	Tell aglaia which camera to use (default is 0). <value> is a number
	that identifies your camera. 0 is the first, 1 the second, ...

 -c1 <color>
 -c2 <color>
	Set primary/secondary color. These colors might have different effects
	depending on the used filter. <color> is a six digit hex number of RGB order
	(similar to HTML color numbers). E.g. 00FF00 is pure green.
	Note: always type leading zeros.
	Defaults are white (ffffff) and black (000000).

 -d, --dma
	Use video1394 (DMA) to get the image data. This is usually faster, but does
	not always work in the correct way.

 -e <effect>
	Set initial filter effect. For a list of filters see the according section.

 -f, --fullscreen
	Start in fullscreen mode

 -g, --grayscale
	Start in grayscale mode.

 -h, --help
	Display short help screen

 -n, --nowindow
	Runs aglaia without window. Key input is disabled with this. So to stop
	it use CTRL-C or the kill command.

 -o <file>
	Set the filename base for the captured files. A number and ".jpg" will be appended.
	So "-o img" produces images named "img000000.jgp", "img000001.jpg" and so on.
	Existing files will be overwritten. Default is "img".

 -p <value>
	Set the parameter for the filter. The meaning depends on the filter used.
	<value> is a number between 0 and 255. Default is 0x30 = 48

 -s, --statistics
	Prints some runtime statistics on exit. Useful for checking where your processor
	time is wasted.

 -t <timing>
	Set the capture timing. Possible values are:
	+ "manual"
		Captures one images and disables capturing.
	+ "single"
		Just like "manual", but exits after the first capture.
	+ "###m"
		Capture one image every ### milliseconds. Of course "-t 2m" won't
		give you video at 500 frames per second, but the maximum speed is
		bound at the framerate
	+ "###s"
		Like "###m" but using seconds instead of milliseconds.
	+ "###f"
		Gives you one image every ### frames. Depends on the framerate on your machine.

 -v, --verbose
	Generates some more output as usual. Especially what commands of libdc1394 it
	is actually calling. Useful for debugging.


Key commands
~~~~~~~~~~~~

While the aglaia window is open you can use the following keys:

 escape or q
	quit aglaia

 space or c
	toggle capturing. This means produce one image if in "single" or "manual"
	capture mode and turn on/off if in "###f", "###s" or "###m" mode.

 g
 	toggle grayscale mode

 F1 to F12
	direct filter selection

 leftarrow, rightarrow
	select next/previous filter

 uparrow, downarrow
	modify the filter parameter. Holding CTRL allows finer tuning.

 1 to 8
	sets the primary color to red, green, blue, cyan, magenta, yellow, black
	or white. Holding shift will set the secondary color.

 u, i, o, j, k, l
	these are used for color tuning. u,j are for the red part, i,k for the green
	and o,l for the blue part. u,i,o will increase while j,k,l decrease the color
	component. Holding shift affects the secondary color, otherwise the primary color
	is affected. Holding CTRL uses smaller steps.
	It is easier to understand these keys if you look at how they are arranged on
	your keyboard.

 x
	exchange primary and secondary color values


Effects
~~~~~~~

none
	This does exactly what you think: nothing.

delta
	This only displays the difference between the last two frames. This means you
	get only some kind of movement image. If nothing is moving you get blackness.
	Parameters and colors are not used.

sobel
	This is some kind of edge detection filter. It fills the images with the secondary
	color and uses the primary color for the lines. The parameter is used to adjust the
	sensitivity of the filter. Lower value will result in more "noise".

and
	This simply performs a logical and between each pixel and the primary color.
	Have a look on the web site (http://www.datamaze.de/aglaia) to see some of
	the effects you can achiev with this.

xor
	Basically the same as and, but performs xor.

colorize
	Uses a palette on the gray channel of the image. This palette is a blending from
	black to the primary color to white. This way you get a "colored" image.

colinv
	The same as colorize, but the palette goes from white to black. This has the same
	effect as inverting the image before applying colorize (if it was possible ;-)).

colblend
	Again similar to colorize, but the palette is created as a blend from the primary
	color to the secondary color (without the use of black or white).


Examples
~~~~~~~~

Example 1  - Basic usage

	The most simple way to use aglaia is the following:
		aglaia
	This will simply start aglaia for the first camera, no effect, capturing is manual.
	(Hitting space will create a "screenshot"). You can still change most of the
	settings (filters, colors, ...) using the key commands (e.g. hit F3 to switch to sobel).

Example 2  - More advanced usage

	To get the most out of aglaia use some commandline switches:
		 aglaia -e colblend -c 1 -c1 0000ff -c2 eeee00 -g -f
	This will start aglaia using camera 2 (-c 1), set the primary color to blue (-c1 0000ff)
	the secondary color to some shade of yellow (-c2 eeee00) and use the "colblend"
	filter (-e colblend). This way the image will be blue-yellow shaded. Additionally it's
	using grayscale mode (which doesn't matter as colblend only uses the gray channel) and
	running fullscreen.

Example 3  - Capturing

	To capture many sequential images (perhaps to convert them to some MPEG) you should call
	aglaia with the -t <timing> option.
		aglaia -t 200m
	This will create an image every 200 millisecond resulting in a framerate of 5 frames per
	second as soon as you press space. There are some other values for <timing>. See above.

Example 4  - Use in shell scripts

	Aglaia might even be useful in shell scripts or executed from other programs.
		aglaia -a -t single -n -o image13_
	This will run aglaia without window (-n) creating one image (-a -t single) and exiting.
	The image is named "image13_000000.jpg" (-o image13_).
	This could be used to create an image everytime somebody logs on as root or something
	similar. Be careful to create unique image names, as these might overwrite each other.


Troubleshooting
~~~~~~~~~~~~~~~

First note:
	aglaia is not for camcorders or USB cameras. It only works with IEEE1394 cameras supported
	by libdc1394.

At first you should check if your IEEE1394 system is running correctly. To ensure this use
gscanbus (http://www.ivistar.de/0500opensource.php3?lang=en) for general IEEE1394 testing
and coriander (http://sourceforge.net/projects/coriander) to test your camera.

Note: aglaia only supports the 640*480 YUV (4:1:1) format. Ensure your camera supports it.

General problems with IEEE1394 or your camera can't be solved with aglaia. Check the following
sites for answers:
	http://sourceforge.net/projects/linux1394
	http://linux1394.sourceforge.net
		These are the development sites for the linux IEEE1394 subsytem

	http://sourceforge.net/projects/libraw1394
		This is the development home for libraw1394, which is heavily used by most
		IEEE1394 apps.

	http://sourceforge.net/projects/libdc1394
		Here libdc1394 is developed. This is the lib used for cameras.

If this doesn't address your problem or even aglaia doesn't compile on your system although
all libraries are in place you should have a look on the aglaia home (http://www.datamaze.de/aglaia/)
or write an email to <aglaia@datamaze.de>.

One last note: If you are using a big endian machine, don't expect aglaia to work correctly.
Especially the colors could look somewhat wrong. I'm sorry for this, but I don't have access to
a big endian machine to test and adjust my code :-(


Bugs
~~~~

If you find any bugs not listed here, please report them to <aglaia@datamaze.de>.


Updates
~~~~~~~

The newest version of aglaia (as well as older versions) should always be
available at http://www.datamaze.de/aglaia
