core.dflic
Class DFLIC

java.lang.Object
  core.dflic.DFLIC

public class DFLIC

extends java.lang.Object

Dynamic Fast Line Integral Convolution algorithm. This class performs the Dynamic Line Integral Convolution algorithm with the FLIC performance enhancement (the F stands for fast LIC). It takes in two time-varying vector fields and produces an output image, with a given mapping between the fields and the image. Additionally, most of the parameters that can be set for the FLIC algorithm can also be specified here: the convolution kernel width, the sample spacing, the maximum streamline length, the minimum and "maximum" output pixel coverage. A DFLIC object is created once for an entire animation sequence. For each frame, Compute() is called in order to generate a FLIC image for the current frame based on the vector field "field". Next, Evolve() is called to update the object for the given time step using the vector field "dfield". This can be repeated as long as necessary. Note that the input samples are created so that their intensities have a uniform distribution over [-1, 1]. The output image will share the same statistics, with an average of 0 and a standard of deviation of Sqrt(1/12).

Version:

1.0

Author:

Andreas Sundquist

Nested Class Summary

private class

DFLIC.ElementIterator

Field Summary

private double[]	defaultkernel Sets the default kernel.
private Vec2Field	dfield privately stores the state of the DFLIC object from frame-to-frame.
private float[]	elc
private int[]	elcurrent
private int	elempty
private int	eliter
private int	eliterlast
private int	elmax
private int[]	elnew
private int[]	elnext
private Vec2	elp
private int[]	eltemp
private float[]	elx
private float[]	ely
private Vec2Field	field privately stores the state of the DFLIC object from frame-to-frame.
private FLIC	flic
private Vec2Transform	ftoi
private Vec2Transform	ftoo
private AccumImage	input
private double[]	inputfilterkernel
private int	inputfilterrepeat
private Vec2Transform	itof
private double	maxcoverage
private double	mincoverage
private double	omaxlen
private double	ostepsize
private double	ostreamlen
private Vec2Transform	otof
private AccumImage	output
private java.util.Random	random

Constructor Summary

DFLIC(Vec2Field field, Vec2Field dfield, AccumImage output, Vec2Transform ftoo)
DFLIC constructs a new DFLIC object with the given initial parameters.

Method Summary

void	AddSingularity(Vec2 v) Adds a singularity.
private int	ceil(double x)
void	ClearSingularities() Clears the list of singularities.
void	Compute() Computes the next FLIC image in the animation sequence using "field".
private int	ElementAdd(double x, double y, double c)
private void	ElementIterDelete()
private void	ElementIterInit()
private int	ElementIterNext()
private void	ElementMerge()
void	Evolve(double dt) Evolves the DFLIC state by a time step "dt".
void	Evolve(double dt, double maxStep) Evolves the DFLIC state by a time step "dt".
private void	InitializeElements()
private void	InitializeElements(int max)
private void	InitializeInput()
void	InitializeRandom() Initializes the random-number generator with a randomly-seeded Random object
private int	round(double x)
void	SetDefaultInputFilterKernel() Sets the default input filter kernel.
void	SetDefaultInputFilterRepeat() By default disables the input filtering.
void	SetDefaultMaxCoverage(double maxcoverage) Sets the default "maximum" coverage of each output pixel, which is 3.0.
void	SetDefaultMaxlen() Sets the default maximum streamline length, which is four times the width of the convolution kernel.
void	SetDefaultMinCoverage() Sets the default minimum coverage for output pixels, which is 1.0.
void	SetDefaultNormalize() By default, the output is normalized after rendering.
void	SetDefaultStepSize() Sets the convolution and streamline step size to the default value, which is one-half of an output pixel.
void	SetDefaultStreamLen() Sets the default convolution kernel width, which is one-eighth of the maximum distance in the output image.
void	SetDField(Vec2Field dfield) Sets the motion of the field line points to "dfield"
void	SetField(Vec2Field field) Sets the field we would like to visualize to "field"
void	SetFtoOTransform(Vec2Transform ftoo) Sets the mapping from the vector fields to the output image to "ftoo", and adjusts the inverse mapping accordingly.
void	SetInputFilterKernel(double[] kernel) Sets the input filter 3x3 kernel.
void	SetInputFilterRepeat(int repeat) Sets the number of times the input filtering is repeated.
void	SetMaxCoverage(double maxcoverage) Sets the "maximum" coverage of each output pixel.
void	SetMaxLen(double omaxlen) Sets the maximum streamline length (in output image units).
void	SetMinCoverage(double mincoverage) Sets the minimum coverage of each output pixel.
void	SetNormalize(boolean normalize) Sets whether or not the output is normalized after rendering.
void	SetOtoFTransform(Vec2Transform otof) Sets the mapping from the output image to the vector field to "otof", and adjusts the inverse mapping accordingly.
void	SetOutput(AccumImage output) Sets the target output image to "output"
void	SetRandom(java.util.Random random) Sets the pseudo-random number generator to "random".
void	SetStepSize(double ostepsize) Sets the convolution and streamline step size (in output image units) to "ostepsize".
void	SetStreamLen(double ostreamlen) Sets the convolution kernel width (in output image units) to "ostreamlen".
private int	sqr(int x)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

field

private Vec2Field field

privately stores the state of the DFLIC object from frame-to-frame. In order to modify them, the corresponding accessor methods should be called.

dfield

private Vec2Field dfield

privately stores the state of the DFLIC object from frame-to-frame. In order to modify them, the corresponding accessor methods should be called.

input

private AccumImage input

output

private AccumImage output

ftoo

private Vec2Transform ftoo

otof

private Vec2Transform otof

ftoi

private Vec2Transform ftoi

itof

private Vec2Transform itof

ostreamlen

private double ostreamlen

ostepsize

private double ostepsize

omaxlen

private double omaxlen

mincoverage

private double mincoverage

maxcoverage

private double maxcoverage

inputfilterkernel

private double[] inputfilterkernel

inputfilterrepeat

private int inputfilterrepeat

random

private java.util.Random random

flic

private FLIC flic

defaultkernel

private double[] defaultkernel

Sets the default kernel. The kernel is of type double[10], and the convolution computed is of the form: out(i,j) = c0 + c1*out(i-1,j-1) + c2*out( i ,j-1) + c3*out(i+1,j-1) + c4*out(i-1, j ) + c5*out( i , j ) + c6*out(i+1, j ) + c7*out(i-1,j+1) + c8*out( i ,j+1) + c9*out(i+1,j+1) where ci = kernel[i). See the method Convolve3x3 in core.image.ScalarImage.java

elmax

private int elmax

elempty

private int elempty

elx

private float[] elx

ely

private float[] ely

elc

private float[] elc

elnext

private int[] elnext

eltemp

private int[] eltemp

eliter

private int eliter

eliterlast

private int eliterlast

elp

private Vec2 elp

elcurrent

private int[] elcurrent

elnew

private int[] elnew

Constructor Detail

DFLIC

public DFLIC(Vec2Field field,
             Vec2Field dfield,
             AccumImage output,
             Vec2Transform ftoo)

DFLIC constructs a new DFLIC object with the given initial parameters. Note that this does *not* perform any sort of computation. "field" is a Vec2Field whose streamlines we want to visualize. It must be updated between frames to represent the vector field at different points in time. "dfield" is a Vec2Field that describes how points in "field" are moving over time. Currently, a simple Euler method is used to integrate the motion of points on the field lines, so "dfield" need only describe the instantaneous velocity of the points. Though it is possible to implement a higher-order integration method, the pay-off is not significant to warrant the extra computation. "output" must be an AccumImage since the output will be accumulated to by FLIC, though the resulting image will be normalized before returning. "ftoo" is the transformation from both "field" and "dfield" to "output". It must be a scaled, rigid transformation. Indeed, this means that both "field" and "dfield" must reside in the same coordinate system. All other parameters, including the FLIC parameters, will be set to reasonable default values, which will yield good results.

Method Detail

SetField

public void SetField(Vec2Field field)

Sets the field we would like to visualize to "field"

SetDField

public void SetDField(Vec2Field dfield)

Sets the motion of the field line points to "dfield"

SetOutput

public void SetOutput(AccumImage output)

Sets the target output image to "output"

SetFtoOTransform

public void SetFtoOTransform(Vec2Transform ftoo)

Sets the mapping from the vector fields to the output image to "ftoo", and adjusts the inverse mapping accordingly. Requires: "ftoo" is a scaled, rigid transformation, or else null

SetOtoFTransform

public void SetOtoFTransform(Vec2Transform otof)

Sets the mapping from the output image to the vector field to "otof", and adjusts the inverse mapping accordingly. Requires: "otof" is a scaled, rigid transformation, or else null

SetStreamLen

public void SetStreamLen(double ostreamlen)

Sets the convolution kernel width (in output image units) to "ostreamlen". The kernel is always uniform and symmetric. The maximum streamline length is reset to its default value.

SetDefaultStreamLen

public void SetDefaultStreamLen()

Sets the default convolution kernel width, which is one-eighth of the maximum distance in the output image.

SetStepSize

public void SetStepSize(double ostepsize)

Sets the convolution and streamline step size (in output image units) to "ostepsize".

SetDefaultStepSize

public void SetDefaultStepSize()

Sets the convolution and streamline step size to the default value, which is one-half of an output pixel.

SetMaxLen

public void SetMaxLen(double omaxlen)

Sets the maximum streamline length (in output image units). This is the maximum length that FLIC will follow a particular streamline to compute successive convolutions. Larger lengths generally speed up the FLIC algorithm, but may run into problems at singularities. If the length is set to less that the convolution kernel width, the length is reset to the width of the kernel.

SetDefaultMaxlen

public void SetDefaultMaxlen()

Sets the default maximum streamline length, which is four times the width of the convolution kernel.

SetMinCoverage

public void SetMinCoverage(double mincoverage)

Sets the minimum coverage of each output pixel. When the FLIC algorithm is complete, every output pixel will have been hit at least an amount "mincoverage". Note that because samples are accumulated using a box-filter, contributions are not necessarily in integer amounts. Larger values of "mincoverage" may reduce aliasing and improve the quality of the computation in general, but the extra computational cost usually does not warrant it.

SetDefaultMinCoverage

public void SetDefaultMinCoverage()

Sets the default minimum coverage for output pixels, which is 1.0. Experimentation has shown that higher values do not usually provide much added benefit.

SetMaxCoverage

public void SetMaxCoverage(double maxcoverage)

Sets the "maximum" coverage of each output pixel. This is not a maximum in a strict sense - indeed, when the FLIC algorithm is complete, there may be pixels that have been hit more than that. This value is instead used as a heuristic in order to determine when sets of pixels have been hit enough times so that it might be a better idea to try an altogether different streamline.

SetDefaultMaxCoverage

public void SetDefaultMaxCoverage(double maxcoverage)

Sets the default "maximum" coverage of each output pixel, which is 3.0. The heuristic is not used as extensively as it should be, so the setting of this value is not so critical, but 3.0 seems to be a reasonable number.

SetInputFilterKernel

public void SetInputFilterKernel(double[] kernel)

Sets the input filter 3x3 kernel.

SetDefaultInputFilterKernel

public void SetDefaultInputFilterKernel()

Sets the default input filter kernel.

SetInputFilterRepeat

public void SetInputFilterRepeat(int repeat)

Sets the number of times the input filtering is repeated. Zero disables it

SetDefaultInputFilterRepeat

public void SetDefaultInputFilterRepeat()

By default disables the input filtering.

SetNormalize

public void SetNormalize(boolean normalize)

Sets whether or not the output is normalized after rendering.

SetDefaultNormalize

public void SetDefaultNormalize()

By default, the output is normalized after rendering.

ClearSingularities

public void ClearSingularities()

Clears the list of singularities.

AddSingularity

public void AddSingularity(Vec2 v)

Adds a singularity. A singularity is where streamlines are always terminated. The point "v" is given in the coordinate system of the vector field.

SetRandom

public void SetRandom(java.util.Random random)

Sets the pseudo-random number generator to "random". By passing in a Random object seeded with the same value, the results of the DFLIC algorithm will be completely deterministic, and yet it will retain its random distribution.

InitializeRandom

public void InitializeRandom()

Initializes the random-number generator with a randomly-seeded Random object

Compute

public void Compute()

Computes the next FLIC image in the animation sequence using "field". The input image to FLIC is automatically computed in such a way to preserve the frame-to-frame coherence of the animation.

Evolve

public void Evolve(double dt,
                   double maxStep)

Evolves the DFLIC state by a time step "dt". The integrator takes time steps at most "maxStep" in size. The elements that comprise the input image to FLIC are evolved according to "dfield" using simple Euler integration. Other integration methods might yield slightly more accurate results, but added computational cost does not produce significant benefits.

Evolve

public void Evolve(double dt)

Evolves the DFLIC state by a time step "dt". The elements that comprise the input image to FLIC are evolved according to "dfield" using simple Euler integration. Other integration methods might yield slightly more accurate results, but added computational cost does not produce significant benefits.

sqr

private int sqr(int x)

ceil

private int ceil(double x)

round

private int round(double x)

InitializeInput

private void InitializeInput()

InitializeElements

private void InitializeElements()

InitializeElements

private void InitializeElements(int max)

ElementIterInit

private void ElementIterInit()

ElementIterNext

private int ElementIterNext()

ElementIterDelete

private void ElementIterDelete()

ElementAdd

private int ElementAdd(double x,
                       double y,
                       double c)

ElementMerge

private void ElementMerge()