wiki:rp_xml_ele_flow
Last modified 20 months ago Last modified on 09/12/13 18:59:23

<flow>

A <flow> is a subelement of a <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>
       <extents>3</extents>
       <mesh>unirect3d(mygrid)</mesh>
       <values>...more...</values>
    <component>
  </field>
</output>

The component's <values> element contains vectors of 2 or 3 numbers that describe the motion of particles.

The component's mesh must be a <unirect3d> element. The unirect3d is a uniform rectangular mesh in 3 dimensions. Each vector in <values> is associated with a point on the mesh. The order is "x1,y1,z1, x1,y1,z2, ... x1,y2,z1, x1,y2,z2, ..." where z varies quickest.

<output>
  <field>
    <component>
      <flow>
        <label>Flow label</label>
        <description>Flow label</description>
           ...more...
      </flow>
      <extents>3</extents>
      <mesh>unirect3d(mygrid)</mesh>
      <values>...more...</values>
    <component>
  </field>
</output>
<unirect3d id="mygrid">
  <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>
</unirect3d>

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 element that modify how the flow is displayed. You can define a stream plane that displayed the path of any particle along that plane. The volume associated with the flow vector field can be displayed along with its outline.

Example of flow options:

<flow>
  <label>Flow label</label>
  <description>Flow label</description>
  <axis>z</axis>
  <position>0%</position>
  <volume>yes</volume>
  <streams>no</streams>
  <outline>no</outline>
  ...more...
</flow>

Descriptions of each <flow> element:

field.component.flow.axis
is the axis where the streams plane is positioned.
field.component.flow.description
is the text displayed when the user hovers over the flow.
field.compoennt.flow.label
is the text displayed along the x-axis.
field.component.flow.position
is the position of the streams plane along the defined axis as a percentage.
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.streams
is a boolean indicating if the streams planes 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.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'.

The elements within the <unirect3d> mesh are as follows:

<xaxis><label>
is the text displayed along the x-axis.
<xaxis><min>
is the minimum x-coordinate.
<xaxis><max>
is the maximum x-coordinate.
<xaxis><numpoints>
is the number of uniformly spaced points on the x-axis.
<xaxis><units>
are the units used on the x-axis.
<yaxis><label>
is the text displayed along the y-axis.
<yaxis><min>
is the minimum y-coordinate.
<yaxis><max>
is the maximum y-coordinate.
<yaxis><numpoints>
is the number of uniformly spaced points on the y-axis.
<yaxis><units>
are the units used on the y-axis.
<zaxis><label>
is the text displayed along the z-axis.
<zaxis><min>
is the minimum z-coordinate.
<zaxis><max>
is the maximum z-coordinate.
<zaxis><numpoints>
is the number of uniformly spaced points on the z-axis.
<zaxis><units>
are the units used on the z-axis.

You can see working code in the examples in the flow example or on the hub in the directory /apps/rappture/examples/flow.