Content:

- Introduction
- Directory structure
- Dependencies
- Compile
- Execute
- Libraries
- Testing
- Implementation Guidelines
- LICENSE


Introduction
============

This is the base directory of the Fib project.

The Fib project consists of the following components:
- the Fib multimedia description language
- the genetic algorithm to encode and optimize of Fib objects
- the converters for converting to, from and between the Fib formats


Directory structure
===================

Documentation of the project:
docu/: directory containing the documentation for the Fib project
gpl/: directory containing the copyright texts, which are used for the project

Implementation of the Fib project:
*/incl/: directories for the header / declaration files
*/src/: directories for the source code files
*/test/: directories for the source files to test the implementation
*/testruns/: directories for scripts to run complete test runs for the subsystem
*/testruns/basicMemtest.sh: A test run to check for memory leaks in the system.
	To execute this test run, ther have to be the LeakTracer program in the
	directory "~/tools/LeakTracer/LeakCheck"  by Erwin Andreasen and Henner
	Zeller (http://www.andreasen.org/LeakTracer/)
fib/: root directory of the Fib multimedia description language
	- here the files to generate the Fib library can be found
fib/incl/: directory for the header / declaration files of the Fib implementation
fib/src/: directory for source files of the Fib implementation
enviroment/: This directory contains the abstract version of the genetic
	algorithm, on which the genetic algorithm for Fib is build
enviroment.fib/: This directory contains the genetic algorithm for Fib
fib.algorithms/: This directory contains algorithms for Fib objects;
	with these Fib objects can be analyzed, edited and changed
TinyXML/: a utility library for reading xml data by Andrew Ellerton
add_ons/: root directory for additional programs of the Fib project
add_ons/converter/: programs to convert from, to and between the
	Fib multimedia formats
add_ons/converter/FreeImage/: A support library for reading image data by
	Herve Drolon.
other_packages /: other packages from outside vendors, which the
	Fib project needs
*/version.h: the version files for each component;
	in them you can find (among others) switches, with which various
	features can be switched
*/makefile: makefile to generate the respective component (see section Compile)


Dependencies
============

fib/ depends on: tinyxml/; other_packages/zlib/
add_ons/converter/ depends on: fib/; fib.algorithms/; add_ons/converter/FreeImage/
add_ons/creator/ depends on: fib/
enviroment/ depends on: tinyxml/
enviroment.fib/ depends on: fib/; enviroment/; enviroment.fib/operators/;
	tinyxml/
enviroment.fib/operators/ depends on: fib/; fib.algorithms/; enviroment.fib/
fib.algorithms/ depends on: fib/; tinyxml/


Compile
=======

The subsystems can be generated by calling make from the respective
subsystem folder.  (e.g. ">cd add_ons/converter/; make test" to generate
the converter test programs)


Linux
-----

For generating the program system:
>make

For generating the test program system:
>make test



Windows
-------
(NOTE: The system was developed under Linux. So far it dos not work
completely under Windows.
Some subsystems may not work yet (e.g. enviroment/). )

The system can be generated using MinGW (www.mingw.org).

For generating the program system:
>make win

For generating the test program system:
>make win_test


Requirements
------------

In order to generate the system only the "g++" C++ compiler with the
Standard C library is required.

The g++ compiler can be installed via the package management system.
(Or, for example, on Ubuntu ">sudo aptitude install g++" on the
shell command line)

When make is executed before the installation of "g++":
	>make clean
should be called to delete the dependency files.


Execute
=======

The Fib system contains various programs that can be executed.


The genetic algorithm
---------------------

The algorithm is used to generate Fib objects that represent a
multimedia object as well possible. For that the algorithm is
given a particular multimedia object, for which it generates new
Fib objects / individuals, of which good will be selected.

path: enviroment.fib/bin/

call: runEnviroment FILE_FIB_OBJECT FOLDER_OUTPUT [MAX_ITERATIONS]

parameters:
	FILE_FIB_OBJECT
		The path to the to load Fib multimedia data / object
	FOLDER_OUTPUT
		The path of the folder, where the evaluated best / result Fib objects
		should be stored.
	MAX_ITERATIONS (optional)
		The maximal number of iterations / operations the environment
		should perform.


converter
---------

There are currently three converter programs for Fib:
- for converting image data into the Fib format: convertToFib
- for converting image data in Fib into another image format: convertFromFib
- to convert objects in a Fib format to the other Fib format: convertFibToFib


Libraries
=========


Fib language elements
---------------------

In the subdirectory "fib/lib/" with "make" a library with classes for the
Fib elements will be generated. With objects of these classes Fib objects
can be created and it can be worked on these Fib objects.
These form the basis of the Fib system.


Fib-algorithms
--------------

In the subdirectory "fib/fib.algorithms/lib/" with "make" a library of
algorithms (and classes) for the Fib system will be crated.
These algorithms provide various functionality about the Fib system.
The source code for these algorithms can be found in the subdirectories of
the "fib.algorithms/" directory.


General genetic algorithm
-------------------------

In the subdirectory "enviroment/lib/" with "make" a library will be created,
with the classes for the basic genetic algorithm.
On this basic genetic algorithm the genetic algorithm for Fib
(enviroment.fib/) is build.


Testing
=======

For most components of the Fib systems automatic tests are available.
The individual test runs are respectively located in the "testcase/" directories.
In the "testruns/" directories are combined test, that execute the mostly
all the test runs that are available in the directory "testcase/".


Implementation guidelines
=========================

- The code should be written understandable and clean.
- The code is comment with doxygen in the Java style so that an automatic
	documentation can be created for it.
- For all aspects (methods, functions, ...) of the Fib program system
	automatic test routines should be created and automatic test runs (see
	"*/testruns/) should be build.
- All resources that are not part of standard C++ system and are needed by
	the Fib program system, are delivered with the system.
- The implementation should be compilable and running on both Linux and Windows.
	However, Linux is the main implementation system. For the automated test
	runs, it is enough if they only run on Linux.
- The implementation should compile and run without any extra costs (e. g.
	licenses).


LICENSE
=======

Fib multimedia library: LESSER GENERAL PUBLIC LICENSE 3.0
Remaining parts of the program system: GNU GENERAL PUBLIC LICENSE 3.0
Documentation: GNU Free Documentation License 1.2

A copy of the GNU LICENSE can be found in the subdirectory "gpl/".