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

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

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 ]

`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.