Liblongvol
------
Contact : David Coeurjolly:  <dcoeurjo@liris.cnrs.fr>
Liblongvol is free software. See file COPYING for details.

Based on LibVol by Alexis Guillaume

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

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

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

	LibLongvol is a library designed to deal with 3D voxel pictures (a voxel is a 3D pixel).

	It provides features such reading a voxel file, writing a voxel file and dealing with it in a C++ program. It implements its own documented-and-easy file formats.

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

	Creating the doxygen documentation (for developers only)
		Use option --doc=yes of configure script.

	Uninstall :
		% make uninstall

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

Two formats are available directly with the liblongvol 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. 
	
- .longvol 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 .longvol 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 longvol 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
----------------

	You can read the man page : 
		% man longvol

	But you should read the tutorial (see tutorial directory).
