The XML format

Groups
Object settings
Primitives
Surface
Triangles, tetrahedra and polygons
Including other scenes
Animations

Using the Callisto XML format, scenes can be easily defined. A DTD is provided in order to check the XML file for errors. If an error occurs when reading the file, the error string is send to the CAL_LoadScene return variable.
The header of the XML file should look the following example:

  <?xml version="1.0" encoding="utf-8" ?>
  <!DOCTYPE scene SYSTEM "callisto50.dtd">
Groups
Every scene description needs to be between <scene> and </scene>. Since in Callisto every object is contained within a group, the next tag will usually be <group>. Within the group, primitives can be defined. Groups have two properties: colCheck and name. Groups can optionally have tags setting their position, orientation and scaling.
<scene>
  <group colCheck="true" name="Test group">
    <pos x="0" y="0" z="0" />
    <or x="3.14" y="0" z="0" />
    <scale x="1" y="2" z="1" />
  </group>
</scene>

A group can also contain another group, each group can have its own separate settings and objects:

<scene>
  <group colCheck="true" name="Group 1">
    <pos x="10" y="0" z="0" />  
    <group colCheck="true" name="Group 2">
      <pos x="0" y="10" z="0" />
    </group>
  </group>
</scene>

If group 1 is manipulated (for example moved) then group 2 and all its objects will move along. If group 2 is moved, the only the objects of group 2 will move along.

Object settings
Within a group, objects can be defined. Every object needs to have its position defined (<pos>). The following example shows the creation of a box within a group. As can be seen, a box has three propertys: width, height and depth. Apart from the position, the orientation can be defined (orientation parameters must be within the range 0..2*PI):
<or z="3.14" y="0" z="0" />
Scaling can be set as follows:
<scale x="1" y="2" z="1" />
Setting position, orientation and scaling for a box within a group looks like this:
<scene>
  <group colCheck="true" name="Test group">
    <box width="10" height="1" depth="1">
      <pos x="0" y="0" z="0" />
      <or x="3.14" y="0" z="0" />
      <scale x="1" y="2" z="1" />
    </box>
  </group>
</scene>
Primitives
The following primitives resemble the box apart from their own properties. Remember that <pos>, <or> and <scale> are always optional:
<sphere radius="3" />
<cylinder radius="1" height="5" />
<cone radius="1" height="5" />

Surface
Apart from shape properties, the looks of the groups and objects can also be set using the <color> and <texture> tags. The following example shows seting the group color (and thus also the color of the box) to green.
<scene>
  <group colCheck="true" name="Test group">
    <box width="10" height="1" depth="1">
      <pos x="0" y="0" z="0" />
    </box>
    <color red="0" green="1" blue="0" />
  </group>
</scene>
If multiple color settings are present, the most inner color has the preference. The following example will cause the cyliner to be red and the box to be green:
<scene>
  <group colCheck="true" name="Test group">
    <group colCheck="true" name="Test group">
      <cylinder height="5" radius="1"/>
        <color red="1" green="0" blue="0" />
      </cylinder>
      <color red="0" green="0" blue="1" />
    </group>
    <box width="10" height="1" depth="1">
      <pos x="0" y="0" z="0" />
    </box>
    <color red="0" green="1" blue="0" />
  </group>
</scene>
Textures can be used in the same way as colors, but need to be pre-loaded. This can be achieved by adding a <defineTexture> tag to the scene and providing the texture with an ID for later reference. The texture files need to be in .ppm format:
<scene>
  <defineTexture fileName="d:\textures\tiles.ppm" ID="1" />
  <group colCheck="true" name="Test group">
      :
      :
      :
Later these textures can be used in groups or in objects. The tiling (number of repeations) can be set here as well. Also, since every object can have multiple surfaces, the surface ID can be set (default is 0). Surface's can be switched using CAL_SetGroupActiveSurface and CAL_SetObjectActiveSurface:
<scene>
  <group colCheck="true" name="Test group">
    <group colCheck="true" name="Test group">
      <cylinder height="5" radius="1">
        <pos x="3" y="0" z="0" />
        <texture ID="1" xTile="1" yTile="1" sID="0" />
      </cylinder>
            :
            :
            :

Triangles, tetrahedra and polygons
Creating triangles is quite straightforward, every <triangles> consists of a list of <triangle> which consists of three <point>'s:
<triangles>
  <triangle>
    <point x="0" y="0" z="0"/>
    <point x="10" y="0" z="0"/>
    <point x="0" y="10" z="0"/>
  </triangle>'
  <triangle>
    <point x="0" y="0" z="10"/>
    <point x="10" y="0" z="10"/>
    <point x="0" y="10" z="10"/>
  </triangle>
        :
        :
        :
</triangles>
A tetrahedron always consists of four points:
<tetrahedron>
  <point x="0" y="0" z="0"/>
  <point x="1" y="0" z="0"/>
  <point x="1" y="0" z="1"/>
  <point x="0" y="1" z="0"/>
</tetrahedron>
A polygon can consist of n points:
<polygon>
  <point x="0" y="0" z="0"/>
  <point x="10" y="0" z="0"/>
  <point x="10" y="10" z="0"/>
  <point x="0" y="10" z="0"/>
</polygon>
Just like the other primitives, orientations and colors can be defined.

Including other scenes
Instead of defining an object or another group in a group, another scene file can also be included. This can be a Callisto XML scene, but it can also be a VRML scene. Including a scene works like this:
  <include fileName="otherScene.wrl" />
Animations
Every object and every group can have a motion attached to it. Motions replace the position, orientation and scaling tags. Every <motion> tag consists of several <keyState>'s. Each key state has its own time interval. Motions are interpolated between the key states. The following example shows a box that moves along the y-axis up to y=10 and back:
<scene>
  <group colCheck="true" name="Test group">
    <box width="10" height="1" depth="1">
      <motion cyclic="true">
        <keyState time="0">
          <pos x="0" y="0" z="0" />
        </keyState>
        <keyState time="1">
          <pos x="0" y="10" z="0" />
        </keyState>
        <keyState time="2">
          <pos x="0" y="0" z="0" />
        </keyState>
      </motion>		    		    
    </box>
  </group>
</scene>
As can be seen from the example, the motion is cyclic. This means that it repeats itself for time stamps outside its range. If a motion is not cyclic and the current time lies outside the range, then the first or last configuration is shown, depending on the time. Changing the time interval using CAL_SetTime causes the box to move. Keystates can also contain orientations and scalings. Orientations are interpolated using quaternions. The next example shows a rotating cylinder, that also rotates about the y-axis because of the motion of its group.
<scene>
  <group colCheck="true" name="Test group">
    <motion cyclic="true">
      <keyState time="0">
        <or x="0" y="0" z="0" />
      </keyState>
      <keyState time="10">
        <or x="0" y="3.14" z="0" />
      </keyState>
      <keyState time="20">
        <or x="0" y="6.28" z="0" />
      </keyState>
    </motion>      
    <cylinder height="10" radius="1">
      <motion cyclic="true">
        <keyState time="0">
          <pos x="10" y ="0" z="0" />
          <or x="0" y="0" z="0" />
        </keyState>
        <keyState time="1">
          <pos x="10" y ="0" z="0" />      
          <or x="3.14" y="0" z="0" />
        </keyState>
        <keyState time="2">
          <pos x="10" y ="0" z="0" />      
          <or x="6.28" y="0" z="0" />
        </keyState>
      </motion>
    </cylinder>
  </group>
</scene>
Download Callisto (latest)
Version 5.2 (release notes)

Documentation
Callisto function reference

Examples
Getting started
The XML format of Callisto

Previous versions
Version 5.0
Version 4.1b
Version 4.00b
Version 3.05
Version 2.20
Version 2.11
Version 2.10
Version 2.00
Version 1.63
Version 1.5
Version 1.41
Version 1.3
Version 1.2
Version 1.11
Version 1.02
Version 1.0
Version 0.91
Version 0.9
Version 0.8
(c) 2003-2009 Dennis Nieuwenhuisen