FILE: NORMALFLOW\README.TXT

ACTIVEX NORMALFLOW V2.0

-----------------------------------------
0. Whats new ?

1. About NormalFlow ActiveX Server.

2. Known Limitations

3. Files

4. Installation

5. Functionality

6. Use in Matlab

7. Use in C++

------------------------------------------

0. What's new ?

Important changes from version 1.0:
- Only floating point arithmetic used.
- Input image is one channel floating point
- Renamed methods and member variables
- Does not require OpenCV and IPL libraries


1. About NormalFlow ActiveX Server.

NormalFlow is an ActiveX server object that computes the normal flow
on digital images, using differential methods.

The object exposes its internal functionality to most programming 
languages and environments in Windows platforms. It was 
designed to be accessed via Matlab and C++ clients, but 
can be used by other compiled/scripted languages.

2. Known Limitations

- Only allows grayscale images.

- Only allows floating point data type
	- "float *" in c++
	- "single" in matlab

- Image number of columns should be a multiple of 4

- MATLAB must be version 6.0 or later.


3. Files

NormalFlow is distributed in a zip file (NormalFLow.zip)
and includes the following files:

NormalFlow.dll
 - the binary code implementing the object functionality
NormalFlow.tlb
 - the type library required for use with compiled languages
README.TXT
 - this file
PROBLEMS.TXT
 - Description of some problems found in this release
INSTALL.BAT
 - The registration script required to install the object
UNINSTALL.BAT
 - The registration script required to uninstall the object
TEST1.M
TEST2.M
 - Matlab script files with examples of object usage 
TEST.EXE
 - compiled program to test the object; requires the Microsoft Vision SDK
IMAGE1.BMP
IMAGE2.BMP
HIGHWAY.AVI
 - Images for test programs.

4. Installation:

Installation of the NormalFlow object

- Unpack the "NormalFlow.zip" file to a new directory.

- Run the registration script "INSTALL.BAT"

- Run the TEST.EXE
  application to test the ActiveX object.

5. Functionality:

Object Properties (To be configured before object creation):

- lines  - number of lines of input images

- columns - number of columns of input images

- input_filter - boolean variable indicating if the object should perform spatial 
		 blurring in the input images. The implemented filted has small variance.
		 It is recommended that input images are previously blurred with filters 		 		 of variance on the range of flow values to detect.

- timederivative_mode - mode for computation of time derivatives:
	- 'recursive' -  temporal IIR causal first order filter
        - 'batch' - temporal FIR zero phase (non-causal) 5 order filter

- computation_mode - Kind of processing to be done:

	- 'changedetection'
	
		Computes the image Squared Time Derivative
  
		Method:	ComputeIt2()
		Result:				It2 = It*It	


	- 'normalflow'

		Computes image Space Derivatives
		Methods: ComputeIx(), ComputeIy()
		Results: Ix = d/dx(Is), Iy = d/dy(Is)

		Computes the image Squared Space Derivatives - requires Ix, Iy 
		Methods: ComputeIx2(), ComputeIy2() 
		Results: Ix2 = Ix*Ix, Iy2 = Iy*Iy 

		Computes the image Squared Gradient Magnitude
		Considers a regularization term lambda (can be zero)
		Methods: ComputeIg2(float lambda) 
		Results: Ig2 = Ix2 + Iy2 + lambda

		Computes image Space/Time Derivative Cross Products - requires Ix, Iy, It
		Methods: ComputeIxIy(), ComputeIxIt(), ComputeIyIt()
		Results: Ixy = Ix*Iy, Ixt = Ix*It, Iyt = Iy*It

		Computes the normal flow field
		Methods: ComputeUn(), ComputeVn(), ComputeFn2()
		Results: Un = -Ixt/Ig2, Vn = -Iyt/Ig2, Fn2 = ||(Un,Vn)||^2 = It2/Ig2 

- Object Methods

	- process_data(input_img) - feeds new image to the filter. 
		The input image should be spatially blurred with filter variance
		of about the flow values to detect.

- Returning values (object read-only properties)

- Is = The original image (blurred if input_filter == 1)
- It = The time derivative image
- Ix = The horizontal derivative image
- Iy = The vertical derivative image
- It2 = The squared It
- Ix2 = The squared Ix
- Iy2 = The squared Iy
- Ig2 = The squared gradient = Ix2 + Iy2
- Ixy = Ix*Iy
- Ixt = Ix*It
- Iyt = Iy*It
- Fn2 = The squared normal flow magnitude
- Un = The horizontal normal flow
- Vn = The vertical normal flow 


6. The NormalFLow object can be called by any ActiveX aware
scripting languages like Java, VisualBasic and Matlab. 

Check the matlab script files *.M to see examples of use in Matlab:

For more information check matlab help on integration with activex objects


7. C++ Example.

The NormalFLow object can also be used with compiled languages and takes 
advantage of their flexibility to create highly optimized code. It exposes
functions that allow the internal access to data structures, avoiding expensive
data transfers between the object and the client, but reducing the robustness 
against programming errors. These functions are not available to scripting 
languages due to reliability requirements.

Check file TEST.CPP to see an example of use in C++.

------------------------------------------------------------------------
Copyright (c) 2002, Alexandre Bernardino - ISR/IST.  All rights reserved.
alex@isr.ist.utl.pt