Voltools
------
Contact : Alexis Guillaume :  <aguillau@liris.univ-lyon2.fr>
Voltools is free software. See file COPYING for details.

0. Contents
-----------

	1. Presentation
	2. Compilation and installation
	3. Supported file formats
	4. Where to find documentation

1. Presentation
---------------

	Voltools are small program for .vol files (files generated by the LibVol library).
	
	- volheader :
		a little shell script that display the header of a .vol file.
	Example :
		% volheader toto.vol
	- vol2raw : 
		convert a .vol file in a raw file (see file formats below)
	Example : 
		% ls
		toto.vol
		% vol2raw toto
		% ls
		toto.raw toto.vol
	- vol2geom :
		convert a .vol file in a geomview file.
	Exemple :
		% ls
		toto.vol
		% vol2geom toto
		% ls
		toto.geom toto.vol
	- raw2vol :
		convert a raw file into a vol file. (see the manual page for help)
	- volarith :
		performs operations between two .vol files. (see the manual page for help)
	- volboundary : 
		extract boundaries of .vol files by removing invisible voxels. (see the manual page for help)
		

2. Compilation and installation
-------------------------------

	Just type :
		% ./configure && make && sudo make install
	Librairies and binaries will be installed in /usr/local/.
	Of course, you can set up a few things like prefix. To see what, juste type :
		% ./configure --help

	You MUST have installed libvol before. If libvol was installed in an unusual path, you should use --libvol-prefix=/some/path/to/libvol option of the configure script.

	Uninstall :
		% make uninstall

3. Supported file formats
-------------------------

Two formats are available directly with the libvol library :
	
- .raw files : all data is written in binary :
	| int SizeX         | int SizeY         | int SizeZ      |\n
	| 3D raw data [...] |
	The 3D raw data is just the dump of the matrix of voxel. 
	In fact, raw data format depends of the machine where it is generated. So it's not very portable. 
	
- .vol files : they consist of the concation of a header and a raw file.
	
	o A header is made of fields
	
	o A field looks like :
	Type: Value\n (notice the blank after the colon)
	It's really similar to news or mail header in fact.
	
	Here is an example of a .vol file :
	X: 100
	Y: 100
	Z: 10
	Voxel-Size: 1
	Author: Dave Null
	foo: bar
	.						<-- (a dot followed by a new line indicateis the end of the header) 
	[ raw data ]
	
	Currently, there's a limitation of 64 lines in header, and each line is
	limited to 127 characters, including '\n'.
	
	A few fields are required in vol files : 
		- X, Y, Z (the dimensions of the picture)
		- Voxel-Size (size in bytes of a voxel)
	Some other fields can be useful :
		- Alpha-Color : the color of an "empty" voxel
		- Int-Endian : the endianess of an integer (e.g : DCBA, BACD, HGFEDCBA (64 bits int), ...)
		- Voxel-Endian : the endianess of a voxel

4. Documentation
----------------

	There are manual pages for most of the programs that are shipped with voltools.