User's Reference - Streakline

### Streakline

Category

Realization

Function

Computes streaklines to represent the movement of particles through changing vector fields.

Syntax

    line = Streakline(name, data, start, time, head, curl, flag, stepscale);

Inputs

Name | Type | Default | Description
--- | --- | --- | ---
`name` | string or object | no default | name of streakline
`data` | vector field or vector field series | none | vector series time-step or vector field series
`start` | vector list or geometric field | center of the boundary box of the first series member | starting point(s)
`time` | scalar list | series start time(s) | starting time(s)
`head` | integer | final series frame number | series time-step at which the streaklines end
`frame` | integer | current frame | current frame
`curl` | vector field or vector field series | no curl | vorticity of vector field(s)
`flag` | flag | input dependent | 0: curl not used 1: curl used to generate twist of streakline(s)
`stepscale` | value | 0.1 | step length as a fraction of the size of the connection element

Outputs

Name | Type | Description
--- | --- | ---
`line` | field or group | one or more streaklines

Functional Details

This module traces the path of a particle through a changing vector field in discrete steps. The visual form of this trace is a streakline, which starts at a specified time and continues until the particle it represents exits from the field or until the field "expires."

`name` | is required only if more than one invocation of Streakline in the same visual program uses the same `start`, `time`, `head`, `curl`, and `flag` arguments with different vector fields (`data`). The reason for this requirement is that, in order to function efficiently in movie applications, Streakline saves intermediate results from frame to frame. This information is stored internally in association with a key. Each invocation of the Streakline module in the same graph receives a unique name, which is constructed from the `name`, `start`, `time`, `head`, `curl`, and `flag` arguments. Thus, if more than one invocation of Streakline in the same graph uses the same arguments, varying only the vector field, a unique `name` string must be assigned to each. If you have only one Streakline module or if any of the inputs to the module other than `data` are different between the two modules, you do not need to specify `name`.
`data` | specifies a vector field or vector field series. Vector fields are limited to n-D vectors defined in n space; for example, 2-D vectors on a 2-D sheet or 3-D vectors defined in a 3-D volume. The individual time-step vector fields are passed to Streakline as `data`, either combined in a single series object or one at a time in successive executions of the graph containing the Streakline module, as fields. Times are associated with each vector field by the "series position" attached to each member of the series group. Vector values in between these times are interpolated linearly from the prior and subsequent vector fields. The times associated with each field should increase monotonically as they are encountered by the Streakline module, either as the individual series members are indexed or as the individual series members are encountered in successive executions of the graph. Vector fields encountered out of order are ignored. If `data` is a single field rather than a series group, then it must have a "series position" attribute for Streakline to accept it. This attribute is attached when a series member is selected with the Select module. The individual members of the series group can be extracted using the Select module or by requesting a single member of the series when using the Import module.
`start` | specifies a set of points at which streaklines originate. It can be either a list of positions or a geometric field (e.g., the output of a Grid module).
`time` | specifies a set of times at which streaklines begin to be traced. The units of time correspond to the units of the vector field. That is, a particle travelling at a unit velocity moves one unit of distance in one unit of time. Both `time` and `start` can contain single or multiple elements. If either parameter contains a single element, that element is associated with each element of the other list. If both parameters contain multiple elements, they must contain the same number of elements, which are then matched in pairs. This allows either a single starting point to be associated with several different starting times, several starting points to be associated with a single starting time, or several starting points to be associated with individual starting times. If no `time` parameter is given, the series position of the first member of the vector field series (either the first series member or the first individual vector field encountered) is used. If no `start` parameter is given, the center point of the first member of the vector field series is used.
`head` | specifies an expiration time for streaklines that have not otherwise terminated. The streakline points are computed iteratively, and the spacing between the points depends on the element size of the connections.
`frame` | allows the Streakline module to incrementally generate streaklines when the entire series is input as `data`. For example, you could attach the Sequencer to `frame`, and as `frame` advanced, the streaklines would grow longer.
`flag` | specifies whether the normals of the streaklines produced rotate according to the vorticity of the vector field or do not rotate at all.
`curl` | specifies the curl of the vector field (see DivCurl). If the vorticity of the vector field is supplied by this parameter, the curl is interpolated from it. In that case, the field must correspond to the vector field in type (either both must be a series or both must be a single field) and they should correspond in time. If `curl` is specified, the default value for the `flag` parameter is 1. If `curl` is not specified, the vorticity can be computed within Streakline, but at a considerable cost in time. In this case the default value for `flag` is 0, and if you want Streakline to compute the curl of the field, you must set `flag` to 1.
`stepscale` | specifies the accuracy of the interpolation. Streakline traces the path of a particle through the vector field in discrete steps. These steps are determined by interpolating vectors from the prior and subsequent vector fields at the geometric position of the current end of the streakline, and then linearly interpolating between the results to produce a vector for the current position and time. A segment is then appended to the current streakline, which continues it in the direction of the resulting vector. The length of the new segment is determined by two factors. First, the length of the projection of the segment along the edges of the cells of the prior and subsequent vector fields in which the starting point of the segment is found does not exceed a proportion (specified by the `stepscale` parameter) of the length of the edge. Second, if grid is irregular, the segment is truncated at the boundary of the element in which it begins. This allows the segment length to be determined anew for the next element. Thus the `stepscale` parameter offers the user control over the accuracy of the streakline. If `stepscale` is a small value (perhaps in the range of 0.01 to 0.05), the resulting streakline contains a relatively large number of segments that closely trace small variations in the vector field. If `stepscale` is assigned a large number (0.5 to 1), the steps are larger and less accurate, but require less execution time. Note, however, that since the step is determined as a proportion of the size of the grid cell in which it is contained, the segments are small in areas in which the grid elements are small, and proportionally larger in areas in which the grid elements are large.

Streaklines trace particles through time. Associated with the streakline is a "time" component that indicates, for each position of the streakline, the time at which the particle reached that position. The initial value in this component, therefore, is equal to the starting time for that streak, which is by default the first series position, or settable by the user using the `time` parameter. The final value in the time component is equal to the time at which the particle exits from the vector field, either geometrically or for one of the following reasons:

- It has reached the time associated with the final member of the vector field series.

- It has reached the time associated with the current frame.

- It has reached the time associated with the series member indicated by the `head` parameter.

The output streaklines also contain a "data" component that indicates the velocity of the data field at each position along the streakline.

Note: | Unlike other modules in the system, the Streakline module maintains information about previous executions. If errors occur during the execution of the visual program, it may be necessary to use the `Reset Server` option to reinitialize the system.

Components

Creates new "positions," "connections," "data," "time," and "colors" components. If the flag argument is set, "normals" and "binormals" components are also created.

Example Visual Programs

    UsingCompute3.net
    UsingStreakline.net

See Also

DivCurl, Ribbon, Streamline, Tube

[ OpenDX Home at IBM | OpenDX.org ]