[[PageOutline]]

= <drawing> =

A '''<drawing>''' output element lets you display a three dimensional drawing containing molecules, glyph plots and polygonal meshes.

'''NOTE:''' This element is under active development and there may be changes to the style elements and structure of the tags.

'''NOTE:''' This document describes the '''output''' drawing element.  For the '''input''' element, see [wiki:rp_xml_ele_drawing drawing (input)]

== Example ==

{{{
<output>
  <drawing>
    <about>
      <label>...</label>
      <description>...</description>
      <camera>...</camera>
    </about>
    <xaxis>
      <label>...</label>
      <units>...</units>
    </xaxis>
    <yaxis>
      <label>...</label>
      <units>...</units>
    </yaxis>
    <zaxis>
      <label>...</label>
      <units>...</units>
    </zaxis>
    <polydata>
      <about>
        <label>Polydata Example</label>
        <style>-color blue -opacity 0.9 -linewidth 2</style>
      </about>
      <vtk>..vtk file contents..</vtk>
    </polydata>
    <glyphs>
      <about>
        <label>Glyphs Example</label>
        <shape>sphere</shape>
        <style>-edges off -gscale 1</style>
      </about>
      <vtk>..vtk file contents..</vtk>
    </glyphs>
    <molecule>
      <about>
        <label>Molecule Example</label>
      </about>
      <pdb>..pdb file contents..</pdb>
    </molecule>
  </drawing>
</output>
}}}

 '''<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><camera>'''::
   This is an optional tag to specify the default camera orientation, pan and or zoom.  It contains a list of alternating flag names and values.  The set of flags are:
  * -qw,-qx,-qy,-qz: Quaternion describing camera orientation
  * -xpan,-ypan: X and Y panning in normalized screen coordinates (defaults to 0.0)
  * -zoom: Zoom ratio (default 1.0).

  Example of a "front" XY plane view: <about><camera>-qw 1 -qx 0 -qy 0 -qz 0</camera></about>
 '''<xaxis><units>'''::
   Specify units for the X axis.  This currently only affects the labelling of the axis with units.  It does not cause any scaling of objects to occur.
 '''<xaxis><label>'''::
   Specify a label for the X axis.  This label is displayed (plus any units) on the X axis line when enabled.
 '''<yaxis><units>'''::
   Specify units for the Y axis.  This currently only affects the labelling of the axis with units.  It does not cause any scaling of objects to occur.
 '''<yaxis><label>'''::
   Specify a label for the Y axis.  This label is displayed (plus any units) on the Y axis line when enabled.
 '''<zaxis><units>'''::
   Specify units for the Z axis.  This currently only affects the labelling of the axis with units.  It does not cause any scaling of objects to occur.
 '''<zaxis><label>'''::
   Specify a label for the Z axis.  This label is displayed (plus any units) on the Z axis line when enabled.

== Drawing Components ==

Currently, a drawing may include zero or one each of the following components in the scene.  Note that all components are drawn in a common coordinate system, so the points of all components need to be given in the same units.  For molecules, the units must be Angstroms, so any polydata meshes or glyphs must also have point geometry in Angstroms if a molecule is included in the drawing.

=== Glyphs ===
A glyphs component is a plot where a glyph shape is placed at each point location in a point cloud or mesh.

{{{
  <glyphs>
    <about>
      <label>Glyphs Example</label>
      <shape>sphere</shape>
      <style>-edges off -gscale 1</style>
    </about>
    <vtk>..vtk file contents..</vtk>
  </glyphs>
}}}

 '''<about><label>'''::
   This is the label for the glyph plot
 '''<about><shape>'''::
   This is the glyph shape to use.  Possible values are: 'arrow', 'cone', 'cube', 'cylinder', 'dodecahedron', 'icosahedron', 'line', 'octahedron', 'point', 'sphere', and 'tetrahedron'.  The default shape is a sphere.
 '''<about><style>'''::
   This element can be used to control the rendering options of the glyph plot.  The set of flags are as follows:
 * -color <colormap_name>
 * -constcolor <color>: color name or hexadecimal color
 * -edgecolor <color>: color name or hexadecimal color
 * -edges <bool>
 * -gscale <float>
 * -lighting <bool>
 * -linewidth <float>
 * -normscale <bool>
 * -opacity <float>
 * -orientglyphs <bool>
 * -outline <bool>
 * -ptsize <float>
 * -quality <float>
 * -scalemode <"scalar"|"vmag"|"vcomp"|"off">
 * -shape <"arrow"|"cone"|"cube"|"cylinder"|"dodecahedron"|"icosahedron"|"line"|"octahedron"|"point"|"sphere"|"tetrahedron">
 * -visible <bool>
 * -wireframe <bool>
 '''<vtk>'''::
   This is the contents of a VTK file with point geometry.  Scalar and vector fields can be included to color, scale and orient the glyphs.  See the <about><style> element.

=== Molecules ===
A molecule component is a representation of a chemical structure.

{{{
  <molecule>
    <about>
      <label>Molecule Example</label>
      <style>-labels on</style>
    </about>
    <pdb>..pdb file contents..</pdb>
      OR
    <vtk>...VTK file contents...</vtk>
  </molecule>
}}}

 '''<about><label>'''::
   This is the label for the molecule
 '''<about><style>'''::
   This element can be used to control the rendering options of the molecule.  The set of flags (NB: some of these are only available in a development build of Rappture) are as follows:
 * -atomscale <float>
 * -atomsvisible <bool>
 * -bondconstcolor <color>: Bond color if -bondcolormode is "constant" or -colormode is not "by_elements".  Color name or hexadecimal color.
 * -bondcolormode <"by_elements" | "constant">
 * -bondscale <float>
 * -bondstyle <"cylinder" | "line">
 * -bondsvisible <bool>
 * -color <colormap_name>
 * -colormode <"by_elements" | "constant" | "scalar" | "vmag" | "vx" | "vy" | "vz">
 * -colorfield <field_name>
 * -constcolor <color>: Atom color if -colormode is "constant".  Color name or hexadecimal color.
 * -edgecolor <color>: Color name or hexadecimal color.
 * -edges <bool>
 * -labels <bool>
 * -lighting <bool>
 * -linewidth <float>
 * -opacity <float: [0.0,1.0]>
 * -outline <bool>
 * -quality <float: [0.0,10.0]>
 * -representation <"ballandstick" | "balls" | "spheres" | "sticks" | "spacefilling" | "rods" | "wireframe" | "lines">: Setting this will override other settings such as "-rscale" and "-bondstyle".
 * -rscale <"covalent" | "van_der_waals" | "atomic" | "none">
 * -visible <bool>
 * -wireframe <bool>

 '''<pdb>'''::
   This is the contents of a PDB file specifying the molecule.  This is the recommended format.  To control the placement of bonds, include CONECT statements in the PDB file.
 '''<vtk>'''::
   This is an alternative to the PDB format above.  You may use <pdb> or <vtk> but not both.  The <vtk> element should include the contents of a VTK file (!PolyData dataset) with point geometry representing atom locations in Angstroms (you '''must''' use Angstroms, nanometers will result in scaling problems).  The element types should be encoded in an integer scalar field as atomic numbers, and the field must be called 'element'.  Single bonds may be added by including line cells in the VTK file to connect pairs of points (atoms).

=== Polydata ===
A polydata component is a polygonal surface mesh.

{{{
  <polydata>
    <about>
      <label>Polydata Example</label>
      <style>-color blue -opacity 0.9 -linewidth 2</style>
    </about>
    <vtk>..vtk file contents..</vtk>
  </polydata>
}}}

 '''<about><label>'''::
   This is the label for the polydata
 '''<about><style>'''::
   This element can be used to control the rendering options of the mesh.  The set of flags are as follows:
 * -cloudstyle <"mesh"|"points">
 * -color <colormap_name>
 * -constcolor <color>: Color name or hexadecimal color.
 * -edgecolor <color>: Color name or hexadecimal color.
 * -edges <bool>
 * -lighting <bool>
 * -linewidth <float>
 * -opacity <float>
 * -outline <bool>
 * -visible <bool>
 * -wireframe <bool>
 '''<vtk>'''::
   This element should be the contents of a VTK file with a !PolyData dataset.