[vtkusers] Streamlines Debugging tips?

[Berk Geveci]

> StreamLine? vtkStreamLine is deprecated, you should be using
> vtkStreamTracer instead. This bit me as well, it seems the only place
> to find out currently is this mailing list =). 

I apologize for the poor documentation. I am afraid of removing 
vtkStreamer and sub-classes for two reasons: 1. it would break backwards
compatibility 2. vtkStreamTracer does not support a few things the
others support: dashed streamlines, controlling the size of the output
lines independently (i.e. have different integration step and output
step). Still, I recommend switching at least because you are likely
to get more response from me and other developers on vtkStreamTracer :-)

> >Will randomly-generated points landing in a region of zero velocity
> >cause the streamline generator to puke? (Cannot generate normals on 
> >zero-length segments)
> 
> Looking through the code, it appears this is correct.

This sometimes happens (although it is less frequent with
vtkStreamTracer) and is not necessarily a show stopper.


> >Are there any published rules-of-thumb for setting integration 
> >parameters appropriate to the data fields under observation?

vtkStreamTracer gives you much better control of the integration
parameters. You can set the integration step based on absolute length,
cell length or time (or more precisely the integration parameter s).
The same thing is true for maximum propagation and similar parameters.
Furthermore, you can use adaptive integration (with Runge Kutta 4-5),
the advantage of which being that you only have to assign an initial
step length and a maximum relative error. Unfortunately, it is mainly
a matter of gaining experience through trial and error.

> >Are there any resommended methods of debugging the integrator/streamline 
> >generator?

One quick way of figuring out why a streamline terminated is to look at
the ReasonForTermination array in the output. This is a cell based array
(each streamline being a polyline cell) and will tell you why a
streamline was terminated. The values are:
    OUT_OF_DOMAIN = 1,
    NOT_INITIALIZED = 2,
    UNEXPECTED_VALUE = 3,
    OUT_OF_TIME = 4,
    OUT_OF_STEPS = 5,
    STAGNATION = 6
I routinely use ParaView for streamline integration. It makes debugging
very easy because you can place streamline seeds interactively,
immediately see why a streamline terminated, quickly change parameters
and re-try. Beyond that, it is reading the code, using a debugger and
asking developers.