wiki:rp_xml_ele_field
Last modified 12 months ago Last modified on 07/11/14 15:59:33

<field>

A <field> object represents a set of values defined over a mesh. The mesh is usually a collection of points in space, but it can also represent points in energy, momentum, etc. The mesh is a separate <mesh> object. Meshes can be shared among several <field> objects.

    <field>
        <about>
            <label>3D Field</label>
        </about>
        <units>eV</units>
        <component>
            <mesh>output.mymesh</mesh>
            <association>pointdata</association>
            <elemtype>scalars</elemtype>
            <elemsize>1</elemsize>
            <values>
                0.143588 0.11341 0.104264 0.119749 0.148021 0.195553 
                0.209402 0.132308 0.0634601 0.0574183 0.0550705 0.0341862 
                0.0239724 0.0343367 0.0490282 0.0629045 0.0890553 0.135098 
                0.157703 0.144812 0.15334 0.192826 0.209467 0.199057 
                ...
            </values>
        </component>
    </field>
<about><label>
This is the label for the output.
<about><description>
This is the description of the output. It is revealed when the user hovers over the output in the drop-down list.
<about><xaxis><units>
Specify units for the X axis. This overrides any units present in the mesh.
<about><xaxis><label>
Specify a label for the X axis. This overrides any label present in the mesh.
<about><yaxis><units>
Specify units for the Y axis. This overrides any units present in the mesh.
<about><yaxis><label>
Specify a label for the Y axis. This overrides any label present in the mesh.
<about><zaxis><units>
Specify units for the Z axis. This overrides any units present in the mesh.
<about><zaxis><label>
Specify a label for the Z axis. This overrides any label present in the mesh.
<about><view>
Select a view other than the default view for the field type and dimension. The viewer must be compatible with the data type. See Views below.
<units>
Specify units for all field values.
<component><mesh>
The name of the mesh element. The mesh is a separate <mesh> object.
<component><association>
The association of the field values to the mesh: 'pointdata' or 'celldata'. Defaults to 'pointdata'.
<component><elemtype>
The type of field: 'colorscalars', 'normals', 'scalars', 'tcoords', 'tensors', 'vectors'. Defaults to 'scalars'.
<component><elemsize>
The number of components in each field value tuple. For example, a field of 3D vectors would have an elemsize of 3. The default is 1 which corresponds with the default <elemtype> of 'scalars'.
<component><values>
The values of the field. Each value is a tuple of one or more numbers. The number of tuples must match the number of points (for <association> of 'pointdata') or number of cells (for 'celldata') of the mesh, and the total number of values = (number of points or cells * elemsize).
<component><vtk>
As an alternative to the component elements above, you may include a whole VTK legacy format text file in this element. Note that, since VTK files may contain a mesh and multiple fields, we intend to move this whole VTK file option to a <dataset> element in the future.

Views

There are a variety of ways that fields can be viewed. Currently, the default view is selected by Rappture based on the data dimension (e.g. 2D vs. 3D mesh bounds) and number of components in each field value tuple (e.g. scalar vs. vector fields). If a different viewer is desired, a viewer can be specified using <about><view>, as long as the field type is compatible with the viewer. Be aware that these view types and view options are under development and subject to change. We anticipate that a future version of Rappture will include a notion of views that is more flexible. New view types may be added and existing view types may be removed or merged together in the future. In any case, if you don't select a specific view, a default view will be selected by Rappture.

Contour Plot

A contour plot gives you essentially a “topographic map” of a function. The contours join points on the surface that have the same height. By default contour plots are shaded, in such a way that regions with higher z values are lighter. Contour plots display a field with a 2D mesh. To select this view, use 'contour' in <about><view>.

Heightmap Plot

Heightmap plots are used to plot (x,y,z) points in three-dimensional space as a height field surface where the field value (z) is interpreted as the height above the xy-plane. Heightmap plots display a field with a 2D mesh. To select this view, use 'heightmap' in <about><view>.

Glyph Plot

The glyph plot places a glyph shape at each point in the mesh. The glyphs may be colored, sized, and/or oriented based on the field values. A common type of glyph plot shows oriented arrows at the points of a vector field, where the arrows point in the direction of the vector at that point in the field. The glyphs may be colored by vector magnitude or a scalar field. Glyph plots display a field with a 2D or 3D mesh. To select this view, use 'glyphs' in <about><view>.

Glyph Plot

Isosurface Plot

An isosurface plot draws a surface through all the points of the model that have the same value. Isosurfaces plots are surfaces that represent a constant scalar value in a 3D scalar distribution. They are an extension to 2D contour plots. Isosurface plots display a field with a 3D mesh. To select this view, use 'isosurface' in <about><view>.

Streamlines Plot

A streamline plot is a contour plot of the lines of constant value of the stream function, which represents the trajectories of particles in a steady flow. Streamline plots display a field with a 2D or 3D mesh. To select this view, use 'streamlines' in <about><view>.

Volume Plot

The volume plot allows the potential to visualize all the data within a three-dimensional volume by mapping scalar values to an opacity and color value. Volume plots display a field with a 3D mesh on a uniform grid. To select this view use either 'nanovis' or 'vtkvolume' in <about><view>. The former is the original nanoHUB volume viewer, the latter is a newer viewer that uses the VTK library.

Flow Plot

A flow plot can animate particles through a steady flow field. However, it is anticipated that this view will be deprecated in favor of an enhanced streamline view.

How to define a <field> object

There will be one value for each point in the mesh. The mesh defines the geometry and topology, the values the attributes. For example when displaying a heightmap, the field values will be displayed as the height of the surface at each point in the mesh.

The mesh is a separate <mesh> object. Meshes can be shared among several <field> objects.

<mesh id="m2d">
  <about>
    <label>2D Mesh</label>
  </about>
  <dim>2</dim>
  <units>um</units>
  <hide>yes</hide>
  <grid>
    <xaxis>
      <min>0.0</min>
      <max>1.0</max>
      <numpoints>20</numpoints>
    </xaxis>
    <yaxis>
      <min>-10.0</min>
      <max>10.0</max>
      <numpoints>50</numpoints>
    </yaxis>
  </grid>
</mesh>

<field id="f2d">
  <about>
    <label>2D Field</label>
  </about>
  <units>eV</units>
  <component>
    <mesh>output.mesh(m2d)</mesh>
    <values>0
0
0
0
...
    </values>
  </component>
</field>

In this example, the <mesh> is a 20 x 50 uniform 2D grid with bounds of [0,0um,1.0um] in the X axis and [-10.0um, 10.0um] in the Y axis. The <field> includes a <mesh> attribute pointing to output.mesh(m2d) as the underlying mesh. The values within the field correspond to the points defined in the grid. The first value represents the field at the first mesh point, the second value at the second mesh point, and so forth. In this case, the mesh points are implicitly defined by the grid axes rather than as a list of points. The order of implicit grid points follows the convention of X coordinates changing fastest, then Y coordinates, then Z coordinates. In this case, the mesh is 2D, so we would list point field values according to the grid order: (0,0), (1,0), (2,0)...(19,0), (0,1), (1,1), (2,1)... etc.

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

Attachments