The Leonardo XML File Format Version 1.0

Table of Contents

• The World According to Leonardo
  • Co-ordinates
  • Angles
  • Colors
    • 1 BPP Palette
    • 2 BPP Palette
    • 4 BPP Palette
    • 8 BPP Palette
  • Objects
• Leonardo's File Formats
  • XML Document Structure
  • Vertex, Size and Bounds Elements
    • The origin Element
    • The v Element
    • The points Element
    • The topLeft Element
    • The bottomRight Element
    • The extent Element
    • The radius Element
    • The bounds Element
  • Markers
  • Object Style
    • The stroke Element
    • The fill Element
      • The texture and pattern Elements
      • The gradient Element
  • An Important Note on Object Co-ordinates
  • The Objects Themselves
    • The arc Element
    • The ellipse Element
    • The bezier Element
    • The rectangle Element
    • The polyline Element
    • The polygon Element
    • The text Element
• The Future
• Footnotes

The World According to Leonardo

Co-ordinates

Leonardo's world is a two-dimensional plane. X co-ordinates are positive moving right and Y co-ordinates are positive moving down. Valid co-ordinates in both dimensions are integers in the range -32768 to 32767 inclusive. The center or origin of the image is at (0, 0). One Leonardo co-ordinate corresponds to one pixel on the screen if your image is zoomed to 100% (i.e.: zoom level 0).

Angles

As far as Leonardo is concerned, there are 256 "degrees" in a circle, as opposed to the more widely used 360 degrees. However, when using Leonardo itself, degrees are represented in their normal range (0 - 359) in the user interface, so users will understand what is going on. 0 - 255 is Leonardo's internal representation which has the advantage of only occupying one byte of memory. This provides lower memory consumption than would be possible with 360 degrees (which would require two bytes) and allows Leonardo to perform calculations on angles more efficiently than it would otherwise. Looking at a circle front-on, Leonardo angles start at 0 at the topmost point of the circle then move clockwise as shown in the diagram below.

If you need to convert a Leonardo angle to degrees, multiply by 1.40625. Here's a handy conversion table for common angles:

Colors

All colors are represented by a hexadecimal index in the range 0x00 to 0xe9 depending on the palette type of the image, which can be 1, 2, 4 or 8 bits per pixel. Following is a mapping of Leonardo color indices to HTML RGB values:

1 BPP Palette

2 BPP Palette

4 BPP Palette

8 BPP Palette

Note that the entire possible set of 256 palette entries is not visible in Leonardo - the palette display in Leonardo only goes up to 0xe9. The remaining 21 palette entries all map to black, but this may not necessarily be true in future.

Objects

There are seven different types of object (or shape) that Leonardo is aware of: arc, ellipse, bezier, rectangle, polyline, polygon and text. Following is a mapping of Leonardo drawing tools to actual Leonardo objects, to provide a point of reference. Some object flags are mentioned - the specifics of these are covered elsewhere in this document.

Leonardo's File Formats

If you have installed the conduit that comes with Leonardo's Workshop, when you hotsync your PDA, your Leonardo images will be converted to Leonardo image files in the c:\Palm\USERNAME\Leonardo folder. Likewise, any Leonardo image files in this folder will be synched back to your PDA. The images are in an XML format, described below. Because they are XML files, they can be edited by hand using a text editor. Programs can also be written relatively easily to manipulate and convert Leonardo images in this XML format.

For reasons of speed and size, Leonardo itself works directly with Palm databases, in a binary format. This binary format is not described in this document, although it is conceptually similar to the XML format. Note that this means the backup PDB files in your c:\Palm\USERNAME\Backup folder are not in the Leonardo XML format.

As you go through this document, it may be helpful to have a Leonardo image open in a text editor.

XML Document Structure

Because this is an XML file, the first line of the file must be the usual <?xml version="1.0"?> processing instruction. Following this, the root element is leonardoImage. Inside the leonardoImage element are the dbName, origin and objects elements. Finally, inside the objects element are the actual objects that make up the image, one after another.

The leonardoImage element has the following attributes:

The dbName element contains the name of the corresponding Leonardo image database on the PDA. Image database names are in the form "wLeoname", where name is the image name as displayed to the user. The name portion can be a maximum of 27 characters.

The origin element is an empty element (i.e.: it has no children) which specifies the current position of the center of the Leonardo viewport relative to the center of the image itself (the specifics of the attributes are defined below).

As mentioned previously, the objects element contains all the objects that make up the image, one after another. For display purposes, the first object listed in the file is the rear-most and the last object in the file is the front-most.

Here's an example snippet:

<?xml version="1.0"?>
<leonardoImage bgColor="0x04" lastModified="0xba23857f" paletteType="4"
  version="1.0" zoomFactor="-62">

 <dbName><![CDATA[wLeountitled]]></dbName>

 <origin x="0" y="0"/>

 <objects>

  <polyline freehand="false">

   <-- polyline data here -->

  </polyline>

  <-- more objects here -->

 </objects>

</leonardoImage>

Vertex, Size and Bounds Elements

In various places in Leonardo image files, there is a need to specify the co-ordinates of a vertex, or a size. The elements used for this have different names depending on their context, but they all share the same basic form; they are empty elements with an X and a Y attribute. These elements are:

The origin Element

The origin element specifies the center (origin) of an object. It has the following attributes:

The v Element

The v element specifies the position of an individual vertex in a polyline, polygon or bezier. It has the following attributes:

The points Element

The entire list of vertices that make up a polyline, polygon or bezier are defined in the points element as a list of v elements, for example:

   <points>
    <v x="-6" y="-13"/>
    <v x="-8" y="-12"/>
    <v x="-9" y="-9"/>
   </points>

The maximum number of points in any object is 500.

The topLeft Element

The topLeft element specifies the top left co-ordinate of a rectangular area. It has the following attributes:

The bottomRight Element

The bottomRight element specifies the bottom right co-ordinate of a rectangular area. It has the following attributes:

The extent Element

The extent element specifies the width and height of a rectangular area. It has the following attributes:

The radius Element

The radius element is effectively the same as extent but is used when defining the X and Y radius of an ellipse. It's attributes are:

The bounds Element

The bounds element defines a rectangular bounding box. It has no attributes, but instead includes a topLeft and an extent element. For example:

    <bounds>
     <topLeft x="-9" y="-13"/>
     <extent x="55" y="25"/>
    </bounds>

This defines an area 55 pixels by 25 pixels, whose top left corner is at (-9, -13).

Markers

Arcs, beziers and polylines can have markers attached to their ends. Each of these objects includes a marker element to specify the markers used. It is an empty element with the following attributes:

Object Style

Each object in a Leonardo image includes a style element which defines the stroke, fill and position of the object. It has the following attributes:

It includes as children origin, bounds, stroke and fill elements. Here's an example:

   <style visible="true">
    <origin x="-55" y="-41"/>
    <bounds>
     <topLeft x="-64" y="-54"/>
     <extent x="19" y="26"/>
    </bounds>
    <stroke color="0xe9" type="solid" width="1"/>
    <fill color="0x00"/>
   </style>

The stroke Element

The stroke element defines the stroke width, color and style for an object. It is an empty element with the following attributes:

If the stroke width is zero, the line is considered to be infinitely thin - it will always be rendered one pixel wide regardless of how far you zoom in. The idea is that these magic thin lines can be used for guides when drawing, for example.

The fill Element

The fill element defines the fill style of an object. Fills can be either solid, a texture or a gradient. The exact structure of the fill element varies depending on this type. For a solid fill, the fill element is empty, and has one attribute - color - specifying the color to use. Here's an example:

    <fill color="0x00"/>

For a texture fill, the fill element has no attributes, but includes a texture element as its only child.

For a gradient fill, the fill element has no attributes, but includes a gradient element as its only child.

The texture and pattern Elements

The texture element includes a pattern element which defines a bitmask for the texture as a long hexadecimal number. The texture element has the following attributes:

Here's an example texture fill:

    <fill>
     <texture bgColor="0x00" fgColor="0xe9">
      <pattern><![CDATA[0x004020100a060e00]]></pattern>
     </texture>
    </fill>

The hex number inside the pattern element defines an eight-byte bitmask (an 8x8 grid). In this case, the pattern is:

The gradient Element

The gradient element is an empty element with the following attributes:

Here's an example gradient fill:

    <fill>
     <gradient color2="0x00" type="linear" angle="32" color1="0xe9"/>
    </fill>

An Important Note on Object Co-ordinates

• The origin of an object specifies the position of the center of the object relative to the center of the image.
• All object vertices are specified relative to the origin of the object, not relative to the center of the image.
• The exception to this is the bounds of an object - this specifies the bounding rectangle for the object relative to the center of the image.

For example (using a rectangle):

  <rectangle angle="0">
   <style visible="true">
    <origin x="18" y="-1"/>
    <bounds>
     <topLeft x="-9" y="-13"/>
     <extent x="55" y="25"/>
    </bounds>
    <stroke color="0x4f" type="solid" width="1"/>
    <fill color="0x00"/>
   </style>
   <topLeft x="-27" y="-12"/>
   <bottomRight x="27" y="12"/>
  </rectangle>

• The origin (center) of the rectangle is at (18, -1), relative to the center of the image.
• The top left and bottom right corners of the rectangle are at (-27, -12) and (27, 12) respectively, relative to the origin of the rectangle.
• Therefore, the width of the rectangle is 55 pixels, being the number of pixels between -27 and 27; the height of the rectangle is 25 pixels, being the number of pixels between -12 and 12. These dimensions are stored as the extent of the bounds.
• The topLeft of the bounds is at (-9, -13), which is the position of the top left corner of the rectangle relative to the center of the image (18 + -27 = -9, -1 + -12 = -13)

It is very important that when manipulating object co-ordinates (relative to the object's origin) that the object bounds (relative to the center of the image) are kept up to date. The bounds must be the smallest image-relative rectangle that contains all the vertices that make up the object. If the bounds are set incorrectly, the image will not view correctly in Leonardo. The bounds element will ultimately be removed in a later version of Leonardo's Workshop, as it is technically redundant data, and because it can cause this problem if manipulated incorrectly. However, for now, it must be maintained. To sum up:

1. Always make sure the bounds are set correctly when creating version 1.0 Leonardo image files.
2. Do not assume that the bounds element will exist when reading Leonardo image files.

The Objects Themselves

The arc Element

The arc element defines an elliptical arc. It contains three children: style, radius for the X and Y radius of the arc and marker for the markes to use at the ends of the arc. It has the following attributes:

Here's an example:

  <arc angle="0" end="192" start="64">
   <style visible="true">
    <origin x="-21" y="-41"/>
    <bounds>
     <topLeft x="-29" y="-41"/>
     <extent x="17" y="18"/>
    </bounds>
    <stroke color="0xe9" type="solid" width="1"/>
    <fill color="0x00"/>
   </style>
   <radius x="8" y="17"/>
   <marker end="none" start="none"/>
  </arc>

The ellipse Element

The ellipse element has two children: style and radius for the X and Y radius of the ellipse. It has the following attributes:

Here's an example:

  <ellipse angle="0">
   <style visible="true">
    <origin x="46" y="18"/>
    <bounds>
     <topLeft x="25" y="4"/>
     <extent x="43" y="29"/>
    </bounds>
    <stroke color="0xe9" type="solid" width="1"/>
    <fill color="0x7d"/>
   </style>
   <radius x="21" y="14"/>
  </ellipse>

The bezier Element

The bezier element defines a cubic Bézier curve. It has no attributes, but has three children: style, marker and points. There must be exactly four points defined for the bezier - Leonardo won't draw beziers with more or less points than this. Here's an example:

  <bezier>
   <style visible="true">
    <origin x="-43" y="46"/>
    <bounds>
     <topLeft x="-56" y="27"/>
     <extent x="26" y="38"/>
    </bounds>
    <stroke color="0xe9" type="solid" width="1"/>
    <fill color="0x00"/>
   </style>
   <marker end="none" start="none"/>
   <points>
    <v x="-13" y="-7"/>
    <v x="-1" y="-19"/>
    <v x="0" y="18"/>
    <v x="12" y="6"/>
   </points>
  </bezier>

The rectangle Element

The ellipse element has three children: style, topLeft and bottomRight. The latter two children define the corners of the rectangle. It has the following attributes:

Here's an example:

  <rectangle angle="0">
   <style visible="true">
    <origin x="18" y="-1"/>
    <bounds>
     <topLeft x="-9" y="-13"/>
     <extent x="55" y="25"/>
    </bounds>
    <stroke color="0x4f" type="solid" width="1"/>
    <fill color="0x00"/>
   </style>
   <topLeft x="-27" y="-12"/>
   <bottomRight x="27" y="12"/>
  </rectangle>

The polyline Element

The polyline element has three children: style, marker and points. It can have between 2 and 500 points. It has the following attributes:

Here's an example:

The polygon Element

The polygon element has two children: style and points. It can have between 3 and 500 points. It has no attributes. Here's an example:

  <polygon>
   <style visible="true">
    <origin x="-3" y="24"/>
    <bounds>
     <topLeft x="-25" y="9"/>
     <extent x="45" y="30"/>
    </bounds>
    <stroke color="0xe9" type="solid" width="1"/>
    <fill color="0x7d"/>
   </style>
   <points>
    <v x="0" y="-15"/>
    <v x="-22" y="14"/>
    <v x="22" y="14"/>
   </points>
  </polygon>

The text Element

The text element has five children: style, topLeft, bottomRight, flags and string. It has the following attributes:

Note that the point size can in theory be from 1 - 255, but Leonardo will only render 8 or 10 point text as of this writing.

The topLeft and bottomRight elements specify the corners of the rectangle containing the text. The flags element specifies various font effects and has the following attributes:

The string element contains the text itself. Here's an example:

  <text angle="0" font="0x00" size="8">
   <style visible="true">
    <origin x="3" y="-4"/>
    <bounds>
     <topLeft x="-43" y="-49"/>
     <extent x="94" y="112"/>
    </bounds>
    <stroke color="0xe9" type="solid" width="1"/>
    <fill color="0x7d"/>
   </style>
   <topLeft x="-46" y="-45"/>
   <bottomRight x="47" y="66"/>
   <flags bold="true" hidden="false" italic="false" underlined="false"/>
   <string><![CDATA[This is a block of text consisting of a few paragraphs.

Here's the second paragraph.

Foo
Bar
Baz]]></string>
  </text>

The Future

The Leonardo XML format serves well to represent anything you can possibly create in Leonardo, and is reasonably human-readable. However there are some issues that will be addressed in a future version of the file format. These are:

• Rotation angles will almost certainly be removed from individual objects and added to the style element instead. Leonardo and Leonardo's Workshop will be updated to support rotation.
• The bounds element will be removed as it is both redundant and potentially error-prone.
• Currently, all elements and attributes described in this document must appear in each Leonardo file in order for Leonardo's Workshop to parse it correctly. This will be changed so that irrelevant elements (like fill on a polyline or arc) can be omitted.
• rectangle may be removed in favour of a four-point polygon.

Footnotes

• [N/I] This attribute exists (and is currently required) in the file format, but support for it has not been fully implemented in Leonardo as of this writing. This attribute may change in future.