<<<<<<<<<<<<<<<<<

ribbon_filter(display) Display Classes ribbon_filter(display)

NAME

ribbon_filter -- creates a triangle-mesh ribbon from lines, normals, and possibly vectors.

DESCRIPTION

ribbon_filter creates a display_data object that contains a triangle mesh describing a ribbon. It takes lines data and normals data from its input display_data object and puts a ribbon on each line, oriented in the direction of the normal at each point.

The ribbons created by this filter can be classified as one of two types: regular and offset.

Regular ribbons are centered on their corresponding lines and have a width specified by the instance variable <scale_factor>.

Offset ribbons are displaced from the line by a certain distance in the direction of the normal vector, optionally rotated by a specified angle. A ribbon is an offset ribbon when either of the instance variables <start_offset_distance> or <end_offset_distance> is non- zero. The width of an offset ribbon is specified in terms of the angle it subtends from the offset point. One of the main uses for an offset ribbon is the creation of "tubes". The "tube_filter" (q.v.) acts as a front end to the ribbon_filter to construct a tube from multiple ribbons.

Normally, the offset distance, or "radius", of a ribbon varies linearly from the <start_offset_distance> to the <end_offset_distance>. (Here, "linearly" means with respect to display_data points, not world coordinates.) However, when the vary_radius_direct!: r = <start_offset_distance> * sqrt( |V| / |V|max )

where: r = the radius of the ribbon at the current point |V| = the magnitude of the vector data at the current point |V|min = the minimum |V| over all points in the ribbon |V|max = the maximum |V| over all points in the ribbon

The result is that the radius varies in inverse or direct proportion to the square root of the vector magnitude. The former is useful for creating stream tubes whose cross section at any point represents an area of constant flux.

Offset ribbons can also be stretched in a given direction. This capability is probably not directly useful to the user, but is intended to be used by the tube filter in generating tubes whose cross sections are non-regular polygons.

SUPERCLASS

filter

INSTANCE VARIABLES

scale_factor The width of a regular ribbon.

stretch_factor The factor by which a ribbon is stretched in the direction specified by the stretch_angle. (Used by tube_filter.)

stretch_angle specifies the direction of stretching relative to the normal data. (Used by tube_filter.)

start_offset_distance, end_offset_distance The offset distances for an offset ribbon at the first and last (respectively) points in the ribbon.

width_angle The angle subtended by the ribbon from the corresponding line. (E.g., a hexagonal tube could be created using six ribbons each with a width_angle of 60 degrees.)

offset_angle The angle by which to rotate the entire ribbon about its corresponding line.

vary_radius A value indicating whether (and how) to vary the radius (offset_distance) using the vector data.

MESSAGES

generate_data! Generates the proper data and sends it to the display_data object indicated by data_out. Generally, the user won't need to use this message, since it is sent implicitly in response to a "data?" sent by a subsequent filter or display_feature.

start_offset_distance[=+?],start_radius[=+?] Set, increment, or query the start_offset_distance.

end_offset_distance[=+?],end_radius[=+?] Set, increment, or query the end_offset_distance.

offset_distance[=+?],radius[=+?] Set, increment, or query both the starting and ending offset distances. (In the case of query, only the starting offset distance.)

scale_factor[=+?] Set, increment, or query the scale factor.

width_angle[=+?] Set, increment, or query the width angle.

offset_angle[=+?] Set, increment, or query the offset angle.

vary_radius[=?] Set or query the vary_radius method..

vary_radius_off! Turn the vary_radius indicator off.

vary_radius_{inverse!,direct!} Sets the vary_radius mode to either inverse or direct. The former is equivalent to "vary_radius=1" and the latter is equivalent to "vary_radius=2".

EXAMPLE

grid_deometry new:case1_geo data_in=case1_gridset01 extent=(15,15,1,18,1,16);

contour_filter new:cf range=(.01,.03) data_in=case1_geo num_divisions=10;

ribbon_filter new:rf scale_factor=.2 data_in=cf;

surface new:surf1 data_in=rf;

BUGS

If the normal data is colinear with the ribbon direction at any point, or if the normal data is zero at any point, two degenerate triangles will be created.

Please send comments and suggestions to

consult@rpi.edu