<!--
  wm3d XML data format:
  List of all available elements and attributes

  This XML format is not completely compatible with Watermelon's one.
-->

<!--
  XML element structure,
  details of the elements and available attributes are shown below.
-->

<WMXML>
  <!-- setting and default values -->
  <SETTING>
     <ATOM />
     <BOND />
     <RIBBON />
     <COIL />
     <SHAPE />
     <OBJ3D />
     <LABEL />
     <CAMERA />
     <PROTECT />
     <RADIUS />
     <WHEEL />
     <MATRIX />
     <AUTOSCALE />
  </SETTING>
  <CHAIN>
    <POINT />
    <!-- several POINTs are necessary to construct a chain -->
    <POINT />
    <COIL />
    <RIBBON />
  </CHAIN>
  <ATOM />
  ...
  <BOND />
  ...
  <SHAPE>
    <TRI />
    ...
  </SHAPE>
  <OBJ3D />
  <LABEL />
</WMXML>

<!--
Elements and Attributes ++++++++++++++++++++++++++++++++++++++++++++++++++

##########################################################################
<WMXML> element: (WMXML)

Description:
  Top level element of Watermelon XML

Child Elements:
  <SETTING>
  <ATOM>
  <BOND>
  <LABEL>
  <SHAPE>
  <OBJ3D>
  <CHAIN>

Attributes:

##########################################################################
<SETTING> element: (WMXML/SETTING)

Description:
  Default values and settings can be modified by the child elements of
  <SETTING>. The default radius of atoms, default colors of objects,
  default view point are involved in <SETTING>

Child Elements:
  <ATOM>          : default values related with <ATOM>
  <BOND>          : default values related with <BOND>
  <RIBBON>        : default values related with <RIBBON>
  <COIL>          : default values related with <COIL>
  <SHAPE>         : default values related with <SHAPE>
  <OBJ3D>         : default values related with <OBJ3D>
  <LABEL>         : default values related with <LABEL>
  <CAMERA>        : initial position of camera
  <LIGHT>         : direction of light
  <AR>            : auto-rotation related settings
  <PROTECT>       : hide structure data from users
  <FRAMERATE>     : framerate of flash movie
  <RADIUS>        : radius scale method
  <WHEEL>         : default mouse mode for WHEEL
  <MATRIX>        : apply rotation, translation to the object
  <AUTOSCALE>     : autoscale setting

Attributes:
  light(Point3D)  : direction of light (default="-1 1 -1")
  arrate(Float)   : autorotation rate (default="1.5")
  framerate(Int)  : framerate (default depends on the compilation flag)
  origin(Point3D) : predefined geometric center of the system (default=null)
  bg(Int)         : background color (default="0xFFFFFF"; white )

##########################################################################
<ATOM> element: (WMXML/SETTING/ATOM)

Description:
  Default setting of <ATOM>(WMXML/ATOM) elements.
  The default values can be overrided by specifing the attributes in
  the registration of each <ATOM>s.
  
  In the default setting, 3D sphere created by polygons are drawn where
  the number of polygons are determined by the quality attributes.
  
  See also another <ATOM> element (WMXML/ATOM).

Child Elements:

Attributes:
  radius(Float)   : radius of the sphere (default="2.0")
                    (abbr.: r, width, w )
  color(Int)      : color of the sphere (default="0x00FF00" (green) )
                    (abbr.: c )
  alpha(Float)    : alpha coefficient ranging 0-1.0 (default="1.0" (opaque))
                    (abbr.: a )
  shader(String)  : shading method (default="Phong").
                    "Simple", "Gouraud", and "Phong" are available.
                    (abbr.: shade, shading )
  quality(Int)    : quality of the sphere (default="3")
                    (abbr.: q, qua )
  ambient(Float)  : ambient intensity (default=0.35)
                    (abbr.: am, amb )
  diffuse(Float)  : diffuse intensity (default=0.7)
                    (abbr.: d, dif )
  specular(Float) : intensity of phong specular (default=0.8)
                    (abbr.: s, spe )
  gloss(Float)    : gloss of specular (default=20.0)
                    (abbr.: g )

##########################################################################
<BOND> element: (WMXML/SETTING/BOND)

Description:
  Default setting of <BOND>(WMXML/BOND) elements.
  The default values can be overrided by specifing the attributes in
  the registration of each <BOND>s.

  If the color0 and color1 are set and these values are not the same,
  The BOND (cylinder) will be colored in these two colors.
  
Child Elements:

Attributes (see ATOM above for abbreviations of attributes):
  radius(Float)   : radius of the bond(cylinder) (default="0.6")
  color(Int)      : color of the bond (default="0x00FF00" (green) )
  alpha(Float)    : alpha coefficient ranging 0-1.0 (default="1.0" (opaque))
  offset(Float)   : bond length offset (default="0.0")
                    (abbr.: o )
  shader(String)  : shading method (default="Gouraud")
  quality(Int)    : quality of the bond (default="0", triangle pole)
  ambient(Float)  : ambient intensity (default=0.3)
  diffuse(Float)  : diffuse intensity (default=1.0)
  specular(Float) : intensity of phong specular (default=0.6)
  gloss(Float)    : gloss of specular (default=20.0)
  color0(Int)     : first color (default="0x00FF00")
                    (abbr.: c0, col0 )
  color1(Int)     : second color (default="0x00FF00")
                    (abbr.: c1, col1 )
  rounded(Int)    : if value greater than 0 is given, the bottom and top
                    faces are drawn in sphere (default="0")
  exc(Int)        : if value greater than 0 is given, the bottom and top
                    faces are not drawn. (default="0")
  dash(Int)       : dashed line. (default="0"; plain line)
                    A line is drawn in specified number + 1 dashes.

##########################################################################
<RIBBON> element: (WMXML/SETTING/RIBBON)

Description:
  Default setting for <RIBBON>s (WMXML/CHAIN/RIBBON).
  The direction of the ribbon plane is automatically defined.
  There are no ways for users to give the plane direction.

Child Elements:

Attributes( see ATOM above for the abbreviations of attributes ):
  radius(Float)   : width of the ribbon (default="1.5")
  color(Int)      : color of the ribbon (default="0xFF0000" (red) )
  alpha(Float)    : alpha coefficient ranging 0-1.0 (default="1.0" (opaque))
  shader(String)  : shading method (default="Phong")
  ambient(Float)  : ambient intensity (default=0.3)
  diffuse(Float)  : diffuse intensity (default=0.7)
  specular(Float) : intensity of phong specular (default=0.8)
  gloss(Float)    : gloss of specular (default=10.0)

##########################################################################
<COIL> element: (WMXML/SETTING/COIL)

Description:
  Default setting for <COIL>s (WMXML/CHAIN/COIL).

Child Elements:

Attributes( see ATOM above for the abbreviations of attributes ):
  radius(Float)   : width of the coil (default="0.6")
  color(Int)      : color of the coil (default="0x00FF00" (green) )
  alpha(Float)    : alpha coefficient ranging 0-1.0 (default="1.0" (opaque))
  shader(String)  : shading method (default="Phong")
  ambient(Float)  : ambient intensity (default=0.3)
  diffuse(Float)  : diffuse intensity (default=0.7)
  specular(Float) : intensity of phong specular (default=0.8)
  gloss(Float)    : gloss of specular (default=10.0)

##########################################################################
<SHAPE> element: (WMXML/SETTING/SHAPE)

Description:
  Default setting for <SHAPE>s (WMXML/SHAPE).

Child Elements:

Attributes( see ATOM above for the abbreviations of attributes ):
  color(Int)      : color of the shape (default="0x00FF00" (green) )
  alpha(Float)    : alpha coefficient ranging 0-1.0 (default="1.0" (opaque))
  shader(String)  : shading method (default="Phong")
  ambient(Float)  : ambient intensity (default=0.3)
  diffuse(Float)  : diffuse intensity (default=0.5)
  specular(Float) : intensity of phong specular (default=0.2)
  gloss(Float)    : gloss of specular (default=20.0)

##########################################################################
<OBJ3D> element: (WMXML/SETTING/OBJ3D)

Description:
  Default setting for <OBJ3D>s (WMXML/OBJ3D).

Child Elements:

Attributes( see ATOM above for the abbreviations of attributes ):
  type(String)    : object type. Valid values are "cone", "cube",
                    "cylinder", and "square". (default="cone")
  radius(Float)   : radius used in cones and cylinders.(default="1.0")
                    If "x" is defined (see WMXML/OBJ3D), radius is ignored.
  color(Int)      : color of the object (default="0x00FF00" (green) )
  alpha(Float)    : alpha coefficient ranging 0-1.0 (default="1.0" (opaque))
  shader(String)  : shading method (default="Phong")
  ambient(Float)  : ambient intensity (default=0.35)
  diffuse(Float)  : diffuse intensity (default=0.7)
  specular(Float) : intensity of phong specular (default=0.8)
  gloss(Float)    : gloss of specular (default=20.0)

##########################################################################
<LABEL> element: (WMXML/SETTING/LABEL)

Description:
  Default setting for <LABEL>s (WMXML/LABEL).

Child Elements:

Attributes( see ATOM above for the abbreviations of attributes ):
  radius(Float)   : font size. (default=130.0)
  color(Int)      : color of the text (default="0x000000" (black) )
  font(String)    : font name. (default="Arial")

##########################################################################
<CAMERA> element: (WMXML/SETTING/CAMERA)

Description:
  Default position of the camera.
  Only the z position can be modified for simplicity.

Child Elements:

Attributes:
  x(Float) : z position of the camera
             (default=-max(stageWidth,stageHeight)*3)

##########################################################################
<PROTECT> element: (WMXML/SETTING/PROTECT)

Description:
  A flag to protect structure data from the user.
  If this element is added, users cannot edit and save XML data.
  This protection way is, as you know, far from the perfect.
  Use it at your own risk.

Child Elements:

Attributes:

##########################################################################
<RADIUS> element: (WMXML/SETTING/RADIUS)

Description:
  Framerate of the flash.
  This parameter can be assigned in compilation phase. Normal users
  may not have reasons to use this element. If you want to use wm3d
  on web-pages, this element can be useful in some situations.

Child Elements:

Attributes:
  method(String) : the way to determine radius
                   "absolute" : use given value without scaling
                   "relative" : scale the value using stage size (default)
  scale(Float)   : scaling factor in the case of "relative" (see above)
                   default is 0.005; actual radius is calculated by
                   radius * min( stageWidth, stageHeight ) * scale

##########################################################################
<WHEEL> element: (WMXML/SETTING/WHEEL)

Description:
  Default coefficient for wheel actions.
  The extent of the scale/depth modifications can be reassigned by this
  element and its attributes.

  Note: scaling is applied by means of diagonal elements of the
        transformation matrix. Depth change is performed by changing
        the camera position.

Child Elements:

Attributes:
  scale(Float) : extent of scaling (default="0.01")
  depth(Float) : extent of depth change (default="5.0")

##########################################################################
<MATRIX> element: (WMXML/SETTING/MATRIX)

Description:
  4x4 matrix of rotation/translation/scaling of affine transformation
  matrix. Usually, this element is used to save/reconstruct the view.
  To write this data manullay is not recommended.

Child Elements:

Attributes:
  data( 16 Floats ) : transformation matrix

##########################################################################
<AUTOSCALE> element: (WMXML/SETTING/AUTOSCALE)

Description:
  Auto-scale handler. Usually, the position of atoms are scaled so as to
  fit the window size. Users can disable the automatic scaling and can
  apply user-defined scaling factor using this option.

Child Elements:

Attributes:
  manual(Int)        : values <= 0 to activate auto-scaling(default)
                       values >  0 to disable auto-scaling
  autoscale(Float)   : scaling factor in automatic scaling. (default=0.3)
                       actual scaling is done by the following formula.
                       stageWidth * autoscale / (largest abs(x) in xml )
  manualscale(Float) : scaling factor of manual scaling. (default=100.0)
                       RADIUS(SETTING/RADIUS) will also be important for
                       manual scaling mode.

##########################################################################
<ATOM> element: (WMXML/ATOM)

Description:
  Draw an sphere.
  See another ATOM element (WMXML/SETTING/ATOM) for default values,
  all the attributes there can be used in this element.

  NOTE: X, Y, and Z positions must be in space-separated format.
  (ex. "1.0 2.0 3.0" )

Child Elements:

Required Attributes:
  pos(Point3D) : position of the atom

Optional Attributes: see another ATOM element (WMXML/SETTING/ATOM)

##########################################################################
<BOND> element: (WMXML/BOND)

Description:
  Draw a bond.
  See another BOND element (WMXML/SETTING/BOND) for default values,
  all the attributes there can be used in this element.

  Sample xml/swf files (src/samples/*.{xml,swf}) will help your
  understanding.

Child Elements:

Required Attributes:
  pos0(Point3D) : position of an atom
  pos1(Point3D) : position of the other atom

Optional Attributes: see another BOND element (WMXML/SETTING/BOND)

##########################################################################
<SHAPE> element: (WMXML/SHAPE)

Description:
  Base element of a shape, which is an object consists of triangles.
  This element is intended to be used in drawing mathematical functions,
  atomic orbitals, molecular orbitals.

  See src/samples/surface.*, where function f(x,z) = exp(-(x^2+z^2)) is
  drawin (range of -1<x<1, -1<z<1).

Child Elements:
  <TRI>

Optional Attributes: see another SHAPE element (WMXML/SETTING/SHAPE)

##########################################################################
<TRI> element: (WMXML/SHAPE/TRI)

Description:
  A triangle, constituent of a SHAPE.
  Front and back faces are created from a <TRI> element.
  Color, alpha value of triangles are determined in parent <SHAPE> element.

Required Attributes:
  p0(Point3D) :
  p1(Point3D) : vertex of this triangle
  p2(Point3D) :

##########################################################################
<CHAIN> element: (WMXML/CHAIN)

Description:
  Base data to draw COILs and RIBBONs. A <CHAIN> consists of <POINT>s.
  In addition to the given <POINT>s, wm3d add several points
  between <POINT>s to construct a smoother chain.

  Note that the attribute of this element, N, is used as the default value
  of N in its children, <POINT>s.

Child Elements:
  <POINT>
  <COIL>
  <RIBBON>

Attributes:
  N(Int) : # of points to be inserted between adjacent <POINT>s (default="3")

##########################################################################
<POINT> element: (WMXML/CHAIN/POINT)

Description:
  Constituent of a <CHAIN>. The position of this element is used as a
  control point for Catmull-rom interpolation.

Parent Element: <CHAIN>

Child Elements:

Required Attributes:
  pos(Point3D) : position of this control point
  index(Int)   : index in chain; which is used to alignment

Optional Attributes:
  N(Int) : # of points to be inserted (default depends on "N" of parent)
  dir(Point3D) : predefined face direction used in ribbons (default:null)
                 in case of null, direction is automatically determined.

##########################################################################
<COIL> element: (WMXML/CHAIN/COIL)

Description:
  Draw a coil.
  See the other COIL element (WMXML/SETTING/COIL) for parameters.

Parent Element: <CHAIN>

Child Elements:

Required Attributes:
  init(Int) : init position in CHAIN (corresponds to "index" of <POINT>)
  last(Int) : last position in CHAIN (corresponds to "index" of <POINT>)

Optional Attributes: see another COIL element (WMXML/SETTING/COIL)

##########################################################################
<RIBBON> element: (WMXML/CHAIN/RIBBON)

Description:
  Draw a ribbon.
  See the other RIBBON element (WMXML/SETTING/RIBBON) for params.

Parent Element: <CHAIN>

Child Elements:

Required Attributes:
  init(Int) : init position in CHAIN (corresponds to "index" of <POINT>)
  last(Int) : last position in CHAIN (corresponds to "index" of <POINT>)

Optional Attributes: See the other RIBBON element (WMXML/SETTING/RIBBON)

##########################################################################
<OBJ3D> element: (WMXML/OBJ3D)

Description:
  Draw an object such as Cube, Cylinder, Cone.
  See the other OBJ3D element (WMXML/SETTING/OBJ3D) for params.

Child Elements:

Required Attributes:
  pos(Point3D)  : position of the object

Optional Attributes: See the other OBJ3D element (WMXML/SETTING/OBJ3D)
  dir(Point3D)  : object direction(default=null)
  x(Float)      : width used in Cube, Cylinder, Cone, Square (default=0.0)
  y(Float)      : height used in Cube, Cylinder, Cone, Square (default=0.0)
  z(Float)      : z-width used in Cube (default=0.0)

##########################################################################
<LABEL> element: (WMXML/LABEL)

Description:
  Draw a text.
  See another LABEL element (WMXML/SETTING/LABEL) for default values,
  all the attributes there can be used in this element.

  Label text is created with TextField first, and then it is converted to
  bitmap data. The quality of label texts might be not so good.

Child Elements:

Required Attributes:
  pos(Point3D) : position of the label
  text(String) : label text

Optional Attributes: see another LABEL element (WMXML/SETTING/LABEL)

-->
