== <flow> ==

A '''{{{<flow>}}}''' is a subelement of a [wiki:rp_xml_ele_field <field>] element's
'''{{{<component>}}}''' element that describes how the component data is 
to be displayed as a flow.  

{{{
<output>
  <field>
    <component>
       <flow>
         <label>Flow label</label>
         <description>Flow label</description>
           ...more...
       </flow>
       <elemtype>vectors</elemtype>
       <elemsize>3</elemsize>
       <mesh>output.mesh(mygrid)</mesh>
       <values>...more...</values>
    <component>
  </field>
</output>
}}}

The component's <values> element is a list of 3 component (x,y,z) vectors.

The component's mesh must be a [wiki:rp_xml_ele_mesh <mesh>] element.
Each vector in <values> is associated with a point on the mesh.  The order of values must match the order of <mesh> points.  For uniform <grid> meshes, the order is the X mesh coordinate running fastest.

{{{
<output>
  <mesh id="mygrid">
    <dim>3</dim>
    <hide>yes</hide>
    <grid>
      <xaxis>
        <min>0</min>
        <max>6300</max>
        <numpoints>126</numpoints>
      </xaxis>
      <yaxis>
        <min>0</min>
        <max>1500</max>
        <numpoints>30</numpoints>
      </yaxis>
      <zaxis>
        <min>0</min>
        <max>1519.05</max>
        <numpoints>22</numpoints>
      </zaxis>
    </grid>
  </mesh>
  <field>
    <component>
      <flow>
        <label>Flow label</label>
        <description>Flow label</description>
           ...more...
      </flow>
      <elemtype>vectors</elemtype>
      <elemsize>3</elemsize>
      <mesh>output.mesh(mygrid)</mesh>
      <values>...more...</values>
    <component>
  </field>
</output>
}}}

A flow may contain one or more particle injection planes.  The injection
plane is where particles enter the flow.  The injection planes are
axis-aligned and may be positioned anywhere along the flow.

The '''{{{<particles>}}}''' element 
lets you define the particle color, size and default visibility. You can also define the 
axis and position of the plane along the axis.

Example of flow with two particle planes:
{{{
<flow>
  <label>Flow label</label>
  <description>Flow label</description>
  <particles id="left">
    <label>Left particle plane</label>
    <description>Description of the left particle plane.</description>
    <axis>x</axis>
    <color>lightgreen</color>
    <position>10%</position>
    <size>2.0</size>
    <hide>no</hide>
  </particles>
  <particles id="right">
    <label>Right particle plane</label>
    <description>Description for the right particle plane.</description>
    <axis>x</axis>
    <color>khaki</color>
    <position>90%</position>
    <size>1.0</size>
    <hide>yes</hide>
  </particles>
</flow>
}}}

Flows may also contain boxes that define a rectangular region.
A flow can have any number of boxes.  The '''{{{<box>}}}''' element 
lets you define the color, corner positions, line width and default visibility of the box.

Example of flow with a box:
{{{
<flow>
  <label>Flow label</label>
  <description>Flow label</description>
  <box id="box1">
    <label>Region of flow</label>
    <description>Description of the region.</description>
    <corner id="1">0 0 0</corner>
    <corner id="2">10 10 10</corner>
    <color>lightgreen</color>
    <linewidth>2</linewidth>
    <hide>no</hide>
  </box>
</flow>
}}}

Flows themselves have a number of elements that modify how the flow
is displayed.  You can define a streams plane that displays vector glyphs and a stream texture (using Line Integral Convolution or LIC) along that plane.  A volume rendering of the magnitude of 
the flow vector field can also be displayed along with its outline.

Example of flow options:
{{{
<flow>
  <label>Flow label</label>
  <description>Flow label</description>
  <axis>z</axis>
  <position>50%</position>
  <streams>yes</streams>
  <arrows>yes</arrows>
  <volume>yes</volume>
  <outline>no</outline>
  ...more...
</flow>
}}}

Descriptions of each <flow> element:

 '''{{{field.component.flow.label}}}''':: 
 is the text displayed along the x-axis.  
 '''{{{field.component.flow.description}}}''':: 
 is the text displayed when the user hovers over the flow.
 '''{{{field.component.flow.axis}}}'''::
 is the axis where the streams plane is positioned. 
 '''{{{field.component.flow.position}}}'''::
 is the position of the streams plane along the defined axis as a percentage.
 '''{{{field.component.flow.streams}}}'''::
 is a boolean indicating if the streams plane should be displayed. The default is no.
 '''{{{field.component.flow.arrows}}}'''::
 is a boolean indicating if arrow glyphs should be displayed. The default is no.
 '''{{{field.component.flow.volume}}}'''::
 is a boolean indicating if the vector field volume should be displayed. The default is yes.
 '''{{{field.component.flow.outline}}}'''::
 is a boolean indicating if the outline around the vector field should be displayed. The default is no.
 '''{{{field.component.flow.duration}}}'''::
 is the length of the flow animation.  The default is '1:00'.
 '''{{{field.component.flow.speed}}}'''::
 is the speed of the flow animation.  The default is '1x'.

You can see working code in the [browser:trunk/examples examples] in the [browser:trunk/examples/flow flow example] or on the hub in the directory /apps/rappture/examples/flow.