<h3>Install</h3>
Set the CLASSPATH to include all the .jars.
<pre>
Unix: 
  setenv CLASSPATH ./ovis.jar:gr.jar:gnu.jar:/home/zilla/zilla/Devl/Java/L/Jars/zlib.jar:zs.jar:cin.jar:GRserver.jar

Win: 
  set _CLASSPATH=c:\x\FlowUtil.jar;c:\x\ovis.jar;...
  java -classpath %_CLASSPATH% ...
</pre>

<h3>Programs</h3>
<pre>
FlowL		computes flow
FlowN		computes flow, older version
FlowSloMo	computes inbetween frames using flow
FlowMoBlur	fake 2d motion blur using flow
FlowPaint	warps an overlay painting according to the flow
FlowCompose	composes 2 flow files
FlowZoom	upres a flow file
FlowHacks	convert flow into visible ppm file
FlowUtil	convert flo file into Burkitt benchmark format

flowchase.py	script to compute frame-to-next-frame flow over a shot
flowchasenodrift.py  script to compute first-frame-to-every-other-frame flow
</pre>

<h3>Menu</h3>
<p>
To do slow motion, run flowchase, then run FlowSloMo.

<p>
To do fake motion blur, run flowchase, then run FlowMoBlur.

<p>
To warp an overlay to carry it along with part of the scene,
paint the overlay (it uses the overlay luminance as the matte),
run flowchasenodrift (not flowchase),
then run FlowPaint.

<h3>FlowL</h3>
java FlowL sourceimage targetimage warpimage flow [-v n] [-backwards] [-fnodrift] 
</pre>
Produces 
<br>*.flo  (single file format)  and
<br>flow_u.flt, flow_v.flt    (older split format, now obsolete) 
<br>
containing the x,y components
of vector that points from each pixel in the targetimage back to
the corresponding point in the source image. 
The warpimage is the result of warping the sourceimage through this
flow to make something roughly registered to the targetimage.
<p>
IMPORTANT, the vectors point from target back to source, and the warp is source
warped toward target.
If you want vectors that point from source to target, run in the opposite
order:
<pre>
  java FlowN targetimage sourceimage ... 
</pre>

<p>
-backwards runs the flow from the last frame back towards the first.

<pre>
 * Using standard backwards warp, think of target as pulling the source
 * towards it.  The result is put in warptmp, and then the warp
 * from target back to warptmp is computed.  This delta warp is added
 * to the warp, source is again pulled toward target and put into warptmp,
 * iterate.  Addtion of vectors is commutative so this should work.
 *
 * To compute the forward flow from source to target just reverse
 * the order: source pulls target back to it, this gives the forward flow.
 * When computing slowmo by flow the results are visibly MUCH better
 * when the flow is computed as java FlowL target source [-flipflow]
 * rather than in the source->target order.
</pre>

<h4>-fnodrift mode</h4>
-fnodrift mode operates on a sequence:
for each frame, it computes the flow from the last frame to this one,
then composes that with the previously composed flow from frame 1 to last
frame, then warps frame 1 to the current one through the composed flow, 
then recomputes a correction flow between the warped and the current 
and adds it to the composed flow...
so you end up with an attempt at
flow.0001.flo   0
flow.0002.flo   flow from 1 to 2
flow.0003.flo   flow from 1 to 3
The lambda should be high if using this, or the flow can end up
swirling and doing other wierd things.
<p>
flow.####.ppm contain the original frame warped to match frame n.
<p>
Look at the files _tmp_ff* while it is running, these give
an indication of how it is doing.
<br>
_tmp_fflow_1_0046_0047.ppm  contains frame 46 warped forward 1 frame to match
47, so view 46, this temp file, and 47.   After computing every frame
to the next, it moves to intervals of 2 frames, 4 frames, etc:
<br>
_tmp_fflow_8_0038_0046.ppm  contains frame 38 warped forward 8 frames to match
frame 46.

<h4>flow.props</h4>
This file sets all the flow parameters; it should be in the 
directory flow is run from.  Some important parameters:
<pre>
-flowgo Flowgo_z5 
-flowgo Flowgo_z7 
		_z7 tries to handle flow discontinuities and is more
		accurate, but Slow.  Use it for frame-to-frame computing.
		For -fnodrift try _z5 first.
-niter 3	number of iterations.  change to 2 or 1 for quick tests.
		has diminishing returns, but in ground-truth test it was
		still improving between 5 and 20 iterations!  
-pyrscale 0.75	scaling between pyramid levels
-criticalpoint true|false
		set to true for images where there are lots of traveling 
		shadows.  causes it to focus more on corner-like features.
-flow_z4_lambda 1.5
		controls smoothness.  Make this higher if the resulting
		warp is too wiggly, or if doing nodrift, make smaller
		if the flow does not capture details.
-flow_z4_nmembrane 250
		number of relaxation iterations per global iteration,
		set to 100 for quick tests
-flow_z7_disvel 0.05
		velocity discontinuity threshold - try not to smooth
		over a region where neighboring velocities are more than this.

<h3>Running it without a script</h3>
Typical usage should be like
<pre>
   java -mx200m FlowL source.ppm target.ppm warp.ppm flow
</pre>
where source,target are typically frames 1,2 or 2,3 or 3,4...;
warp is the resulting picture: source morphed to match target,
and flow is the binary flowfield.


<h3>Files</h3>
<pre>
_tmp*			temporary files
*.flo			file containing both x,y components of flow
flow_<nnnn>_u.flt, 	old format x component of flow field
flow_<nnnn>_v.flt	old format y component
*.flow			flow in Burkitt format( for ground truth), flow vector uses this,
			otherwise not needed.

<h3>FlowPaint</h3>
FlowPaint warps a single frame according to the flow.
<br>
Usage:
<pre>
java FlowPaint <plates.first-last.ext> <flowprefix> <artworkframe>
java FlowPaint ~me/xx.100-105.png flow Pics/xx.0100_Flowpaintart.ppm
</pre>
This expects files flow100_u.flt, etc. in the current directory and
writes art.*  (the warped artwork frame) and comp.* (the artwork comp'd
over the plates) also in the current directory.

<h3>FlowSloMo</h3>
Generates in-between frames using flow.
<pre>
java FlowSloMo /x/y/elephant.1-20.png flow 3
</pre>
First argument is the sequence of plates,
second is prefix for the flow files (must be in current directory),
so the command above reads flow.0001.flo, flow.0002....
Third argument is the number of output frames per input frame, so 3 = 
1/3 speed with 2 new frames per old frame.
<br>
The output is comp.####.ppm.

<h3>FlowMoBlur</h3>
<pre>
java FlowMoBlur /x/y/elephant.1-20.png flow 1.5
</pre>
Does 2d linear motion blur using the flow --
the current frame is blurred along the reverse of the flow vector at
each pixel.
The third argument scales the flow vectors, bigger = more motion blur.
<br>
The output is comp.####.ppm.
<br>
Beware of bug: something may be backwards here.
I got a much better looking result by running it on frames 2->1
than by on frames 1->2.  

<h3>FlowHacks</h3>
Temporary usage:
<pre>
java FlowHacks file.flo prefix
</pre>
Converts the .flo file into visible prefix_u.ppm and prefix_v.ppm.

<h3>Image formats</h3>
ppm, png, jpg, sgi 8bit verbatim.
Sometimes cineon, bmp.


<h3>Barron flow stuff</h3>
The test sequences are in sun raster format, convert to ppm with 
the linux 'convert' program.

<h4>Java FlowUtil in.flo out.flow</h4>
Converts new .flo format into Burkitt format, 
including flipping vector direction.

<h4>calc_error (C program)</h4>
If the reported error is e.g. 100percent the first thing to
check is flipping the flow direction.  Can do this in FlowUtil.
<pre>
  calc_error -A -B 0 25 5 ../_tmpqflow.flow -F G/yos_newcorrect.9.Gflow

<h4>psflow (C program)</h4>
-sN subsamples by N.
<br>
-mS scales magnitude of vectors by S.
<pre>
psflow -s5 -m2 ../_tmpqflow.flow flowplot.ps

<!-- ---------------------------------------------------------------- ->
<h4>parameter advice</h4>
<!-- ---------------------------------------------------------------- ->

With the new fnodrift, lambda=3 on pure horn-schunck (algorithm 5)
with iter=1,nmembrane=250 is too stiff to track the mouth on a 
warpainted face.  Even lambda=2 is too stiff, but it also scrambles
the mouth towards the end.  Suspect more stiffness is needed, but
with iter=2.
<p>
With algorithm 7, iter=1, lambda3/nmembrane400 failed to close the mouth sometimes,
and got scrambled later as well.  Suspect that more iterations needed.