core.dflic
Class FLIC

java.lang.Object
  core.dflic.FLIC

public class FLIC

extends java.lang.Object

Fast Line Integral Convolution algorithm. This class performs the Fast Line Integral Convolution algorithm on a given input image and vector field, producing an output image. A number of parameters that affect the execution of FLIC can be modified before the computation. Among these are changing the input image and vector field and the output image, independently changing the mapping between the vector field and both the input and output images, changing the convolution kernel width and sampling step, the maximum length to follow any particular streamline, the minimum and maximum sampling coverage of each output pixel, and an iterator specifying the order in which samples should be chosen. Most of these parameters have default values that will result in a good rendition of the LIC effect.

Version:

1.0

Author:

Andreas Sundquist

Field Summary

private Streamline	bstream
private boolean	clear
private double[][]	contrib
private int	contribsize
private double	contribtot
private double	fcurlen Private temporary variables
private Vec2Field	field
private double	fmaxlen Private temporary variables
private double	fstepsize Private temporary variables
private Streamline	fstream
private double	fstreamlen Private temporary variables
private Vec2Transform	ftoi
private Vec2Transform	ftoo
private ScalarImage	input
private double	istreamlen Private temporary variables
private Vec2Iterator	iterator
private Vec2Transform	itoo
private double	maxcoverage
private double	mincoverage
private boolean	normalize
private double	omaxlen
private Vec2	op
private double	ostepsize
private double	ostreamlen
private Vec2Transform	otof
private AccumImage	output
private Vec2	p
private double[]	sample
private int	sampleoffset
private Vec2[]	samplev
private java.util.Vector	singularities

Constructor Summary

FLIC(ScalarImage input, AccumImage output, Vec2Field field, Vec2Transform ftoi, Vec2Transform ftoo)
Constructs an instance of a FLIC with the given initial parameters.

Method Summary

void	AddSingularity(Vec2 v) Adds a singularity, where streamlines are always terminated.
private static int	ceil(double x)
void	ClearSingularities() Clears the list of singularities.
void	Compute() Executes the FLIC algorithm, filtering the input image using the given vector field to produce an output image.
private void	ComputeStream(Vec2 p0) Performs a FLIC (or LIC) streamline computation with the seed point "p0".
private void	ContribAccum(int x, int y, double a)
private void	ContribAdd(Vec2 p)
private void	ContribClear(Vec2 p)
private void	ContribDel(Vec2 p)
private double	ContribRescale(double total)
private static int	floor(double x)
private void	InitializeContrib(int size)
private static int	max(int x, int y)
private static int	min(int x, int y)
private static int	round(double x)
void	SetClear(boolean clear) Sets whether or not the output is cleared prior to rendering.
void	SetDefaultClear() By default, the output is cleared before rendering.
void	SetDefaultIterator() Sets the default ordering of streamline seed points, which is a pseudo- random sequence of points.
void	SetDefaultIterator(java.util.Random random) Sets the default ordering of streamline seed points, a pseudo-random sequence of points generated by the random-number generator "random".
void	SetDefaultMaxCoverage() 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	SetField(Vec2Field field) Sets the vector field to "field"
void	SetFtoITransform(Vec2Transform ftoi) Sets the vector field-to-input image transformation to "ftoi".
void	SetFtoOTransform(Vec2Transform ftoo) Sets the vector field-to-output image transformation to "ftoo".
void	SetInput(ScalarImage input) Sets the input image to "input"
void	SetIterator(Vec2Iterator iterator) Sets the order in which streamline seed points are chosen to that sequence produced by "iterator".
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), the length that FLIC will follow a particular streamline to compute successive convolutions.
void	SetMinCoverage(double mincoverage) Sets the minimum coverage of each output pixel.
void	SetNormalize(boolean normalize) Sets whether or not to normalize the output after rendering.
void	SetOutput(AccumImage output) Sets the output image to "output"
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".

Methods inherited from class java.lang.Object

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

Field Detail

input

private ScalarImage input

output

private AccumImage output

field

private Vec2Field field

ftoo

private Vec2Transform ftoo

otof

private Vec2Transform otof

ftoi

private Vec2Transform ftoi

itoo

private Vec2Transform itoo

ostreamlen

private double ostreamlen

ostepsize

private double ostepsize

omaxlen

private double omaxlen

mincoverage

private double mincoverage

maxcoverage

private double maxcoverage

iterator

private Vec2Iterator iterator

clear

private boolean clear

normalize

private boolean normalize

singularities

private java.util.Vector singularities

fstreamlen

private double fstreamlen

Private temporary variables

istreamlen

private double istreamlen

Private temporary variables

fstepsize

private double fstepsize

Private temporary variables

fmaxlen

private double fmaxlen

Private temporary variables

fcurlen

private double fcurlen

Private temporary variables

fstream

private Streamline fstream

bstream

private Streamline bstream

sampleoffset

private int sampleoffset

samplev

private Vec2[] samplev

sample

private double[] sample

contribsize

private int contribsize

contrib

private double[][] contrib

contribtot

private double contribtot

p

private Vec2 p

op

private Vec2 op

Constructor Detail

FLIC

public FLIC(ScalarImage input,
            AccumImage output,
            Vec2Field field,
            Vec2Transform ftoi,
            Vec2Transform ftoo)

Constructs an instance of a FLIC with the given initial parameters. Note that this does *not* actually perform the computation, but retains the state of the parameters over the course of potentially many similar FLIC computations. The "input" image must be a ScalarImage or derived type. Input samples are assumed to have a Gaussian distribution with an average of zero, and final sample values are rescaled to renormalize the variance. If this is not the desired effect, a post-processing step can be used to renormalize the entire output image. The "output" image must be an AccumImage or derived type since it will be accumulated to. The image is normalized at the end of the FLIC computation. Note that because the input is convolved along streamlines, the input image domain must be larger than the output image domain. In other words, for each output pixel, when mapped to the corresponding input pixel, there must be enough pixels around that input pixel to produce a set of samples for the convolution. The "field" can be any type of Vec2Field, but field lines will always be reparameterized by arc-length and is therefore independent of the magnitude of the vectors. "ftoi" defines the transformation from the vector field to the input image. This transformation *must* be rigid, although it can be scaled as well. "ftoo" defines the transformation from the vector field to the output image. This transformation *must* be rigid, although it can be scaled as well. All other parameters are set to reasonable, default values. Requires: "ftoi" and "ftoo" describe scaled, rigid transformations or are null

Method Detail

SetInput

public void SetInput(ScalarImage input)

Sets the input image to "input"

SetOutput

public void SetOutput(AccumImage output)

Sets the output image to "output"

SetField

public void SetField(Vec2Field field)

Sets the vector field to "field"

SetFtoITransform

public void SetFtoITransform(Vec2Transform ftoi)

Sets the vector field-to-input image transformation to "ftoi". Requires: "ftoi" must be a scaled, rigid transformation, or else null

SetFtoOTransform

public void SetFtoOTransform(Vec2Transform ftoo)

Sets the vector field-to-output image transformation to "ftoo". Requires: "ftoo" must be 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), the 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 doesn"t 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()

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.

SetIterator

public void SetIterator(Vec2Iterator iterator)

Sets the order in which streamline seed points are chosen to that sequence produced by "iterator". Generally, the more random the sequence of points, the better the results, though it may produce significantly different output images depending on the particular random sequence. Frame-to-frame coherence in an animation is particularly difficult to obtain without care. The iterator must be reset before every call to Compute(), or else the default iterator will be invoked.

SetDefaultIterator

public void SetDefaultIterator()

Sets the default ordering of streamline seed points, which is a pseudo- random sequence of points.

SetDefaultIterator

public void SetDefaultIterator(java.util.Random random)

Sets the default ordering of streamline seed points, a pseudo-random sequence of points generated by the random-number generator "random". By passing in a "random" object seeded with the same value, the set of streamline seed points becomes deterministic (but randomly distributed all the same).

SetNormalize

public void SetNormalize(boolean normalize)

Sets whether or not to normalize the output after rendering.

SetDefaultNormalize

public void SetDefaultNormalize()

By default, the output is normalized after rendering.

SetClear

public void SetClear(boolean clear)

Sets whether or not the output is cleared prior to rendering.

SetDefaultClear

public void SetDefaultClear()

By default, the output is cleared before rendering.

ClearSingularities

public void ClearSingularities()

Clears the list of singularities.

AddSingularity

public void AddSingularity(Vec2 v)

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

Compute

public void Compute()

Executes the FLIC algorithm, filtering the input image using the given vector field to produce an output image. The given iterator is used to sample the input image until the 95% of the output image pixels have achieved the minimum coverage requirement. Then, the remaining output pixels are filled in using the LIC algorithm. This results in improved performance since it becomes increasingly difficult to randomly select an uncovered pixel. Requires: all the parameters are valid

floor

private static int floor(double x)

ceil

private static int ceil(double x)

round

private static int round(double x)

min

private static int min(int x,
                       int y)

max

private static int max(int x,
                       int y)

ComputeStream

private void ComputeStream(Vec2 p0)

Performs a FLIC (or LIC) streamline computation with the seed point "p0". "p0" is not modified.

InitializeContrib

private void InitializeContrib(int size)

ContribAccum

private void ContribAccum(int x,
                          int y,
                          double a)

ContribAdd

private void ContribAdd(Vec2 p)

ContribDel

private void ContribDel(Vec2 p)

ContribClear

private void ContribClear(Vec2 p)

ContribRescale

private double ContribRescale(double total)