Open Cross Stitch File Format (.OXS)


Author: Jeff Tullin 2020/21


Purpose of the new Format



Cross Stitch software has now been around for over 30 years.
During that time, suppliers have come and gone, and no doubt new software will be developed in the future.
Throughout the history of computers in the home, and their use in designing cross stitch (or similar) patterns, each software manufacturer has created a file format that was suitable for their individual needs.
Invariably, this file format was a binary one - sometimes using ‘standard’ routines from the development language, sometimes using custom developed routines.
The file formats were proprietary, and unless details of the algorithm used to create these was shared, one software product was unable to make use of data created in another.
Rather like having each product speak a different language without an interpreter.

This has meant that designs created in software packages such as EasyCross, or Myriacross, to name just 2, can no longer be opened or used in any software product that is still on sale - effectively that work is lost or needs to be created from scratch, which is a shame.
Similarly, anyone who wishes to use a new or additional software product will find that work created on one package cannot be used in another - it must be recreated.

The Open Cross Stitch file format is an attempt to break down the barriers that exist between these software packages, so that (if need be), any software package can create a file that can be understood by any other package. At a minimum, it will allow designs created using Ursa Software products to be understood by other products or suppliers in the future.

It is our hope that this format will be added to other suppliers products (it is not a big job), so that if/when a supplier goes out of business (which has happened many times over the years due to financial, health, or retirement reasons), designs created using package X will be usable in package Y

It will also allow new software to be developed quickly, and potentially new services to be developed, making use of the design work intended for cross stitch but with an application elsewhere, such as tiling, rugs, paving, lighting or more.

And a market / library of charts can be created that has a larger number of potential users, since every software product could ‘speak a common language’ even if they also continue to use their own format 'normally'



Overview


The Open Cross Stitch file format makes use of XML to record the data
XML is a text file at heart, where the data is held in what amounts to an almost self-documenting format for which it is easy to create a parser.
For example, a list of pets might look like this:

<pets>
<dog>name=“spot” age="6" color = “Brown”</dog>
<dog>name=“Rex” age="12" color = “Black”</dog>
<cat>name=“Fluffy” age="3" color = “White”</cat>
</pets>



This simple structure has an outer wrapper called pets, which ends at /pets
Inside that are a number of records. Two of them are of type dog, and one is a cat
Each ‘pet’ in the list has a number of attributes, such as name, age and color

So firstly, this data can be read by a human, (and in the worst scenario, could even be amended using a text editor!)
Secondly, a parser could open this file and do things with ‘just the dogs’
The great thing about an XML format is that extra information could be added for a special purpose, and it wouldn’t break any other persons program.
Imagine that some application that handled dogs also wanted to store whether the animal was chipped.

They could create a file that looked like this:
<pets>
<dog>name=“spot” age="6" color = “Brown” chipped = true</dog>
<dog>name=“Rex” age="12" color = “Black” chipped = false</dog>
<cat>name=“Fluffy” age="3" color = “White”</cat>
</pets>

Now, the file is quite different, and has become larger - but the original program could still read the file easily,
Adding extra information has happened in a way that a ‘binary file’ cannot do. (even adding one extra letter to an attribute could render a binary file unreadable afterwards)

Similarly, an application reading the file need only work with the parts it wants to handle.
‘Only dogs’ is one example.
‘Calculate the average age of all pets’ is another.. to do that the app doesn’t need to bother with the name or chipped status.




With cross stitch data, there is common data that all apps will have.
At the simplest, they have ‘information about the chart’ - this will include the dimensions, the stitches-per-inch, and perhaps the title, author, stitching instructions, copyright info..
They all need a ‘list of colors’ (the palette), and each color has a number/description/color value as a minimum.
That list of colors is used to make the chart, so in a grid of stitches, the cross at position 10 from the left and 2 from the top might be color 7 from the list.

After that, more specific items such as backstitches, and part stitches, knots, beads and other decorations may need to be stored.

This document sets out the base data originally defined in 2020 to handle Ursa Software’s file requirements.
Using this document, any other software supplier should have no difficulty understanding a chart in the OXS file format.
Other software products can also save in this format (and are encouraged to add this facility) , but with the benefit that they can add data which is specific to their software, and the output file can still be understood by any other product that implements this.
Any data items that are not known about are simply and safely ignored.
For example, a product that handles diamond painting has no interest in backstitches or half stitches - it would look at the ‘full crosses’ data only.



OXS V1.0 File Format Explained



The OXS file contains text which is UTF8, allowing for unicode characters such as ©

<?xml version="1.0" encoding=“UTF-8"?>

The file itself begins with an encompassing element called ‘chart’ - there is one of these
<chart>
..content..
</chart>


Within a chart, there are several sections,
properties, full stitches, and backstitches elements should be considered mandatory, even if they are empty.

The first section/element is purely informational - a brief format description

format

<format
comments01="Designed to allow interchange of basic pattern data between any cross stitch style software"
comments02="the 'properties' section establishes size, copyright, authorship and software used"
comments03="The features of each software package varies, but using XML each can pick out the things it can deal with, while ignoring others"
comments04="The basic items are :"
comments05="'palette'..a set of colors used in the design: palettecount excludes cloth color, which is item 0"
comments06="'fullstitches'.. simple crosses"
comments07="'backstitches'.. lines/objects with a start and end point"
comments08="(There is a wide variety of ways of treating part stitches, knos, beads and so on.)" comments09="Colors are expressed in hex RGB format."
comments10="Decimal numbers use US/UK format where '.' is the indicator - eg 0.5 is ‘half'"
comments11="For readability, please use words not enumerations"
comments12="The properties, fullstitches, and backstitches elements should be considered mandatory, even if empty"
comments13="element and attribute names are always lowercase”/>


or , in English

  • Designed to allow interchange of basic pattern data between any cross stitch style software.
  • The 'properties' section establishes size, copyright, authorship and software used
  • The features of each software package varies, but using XML each can pick out the things it can deal with, while ignoring others.
  • The basic items are :
  • 'palette'..a set of colors used in the design (palettecount excludes cloth color, which is item 0 )
  • 'fullstitches'.. simple crosses
  • 'backstitches'.. lines/objects with a start and end point
  • (There is a wide variety of ways of treating part stitches, knots, beads and so on.)
  • Colors are expressed in hex RGB format.
  • Decimal numbers use US/UK format where '.' is the indicator - eg 0.5 is ‘half'
  • For readability, best use words not enumerations / magic numbers where possible
  • The properties, fullstitches, and backstitches elements should be considered mandatory, even if empty
  • element and attribute names are always lowercase
  • All attributes are quoted strings - eg “100”


properties (occurs once)
This element has the following optional attributes:

  • oxs version eg “1.0"
  • software eg "Ursa Software" - can be used to indicate app-specific items
  • software_version eg “2021" - can be used to indicate app/version-specific items
  • chartheight eg “100”
  • chartwidth eg “100”
  • charttitle eg “My great chart”
  • author eg “Jenny Smith”
  • copyright eg “© J Smith Crafts 2021”
  • instructions eg “be careful”
  • stitchesperinch eg “14”
  • stitchesperinch_y eg “14” - not all apps vary the stitches vertically, this can be ignored for diamonds and similar
  • palettecount eg “20" - colors other than the cloth



example of the properties element:
<properties
software="Ursa Software"
software_version="2020"
chartheight="74" chartwidth="89"
charttitle="The Cottage"
author="" copyright="(c) Peter Bristow"
instructions="Cottage is based upon his own house."
stitchesperinch="14" stitchesperinch_y="14"
palettecount=“13" />





palette (occurs once)
This element holds <n> palette_item entries, one per color in the palette (see properties - arguably the palette count attribute in properties is not strictly needed, since the palette_item elements could be counted…)


palette_item (occurs <n> times as children of ‘palette’)

This element holds information about a color in the palette, which may represent a thread, bead or other color item.

  • index eg "1"
  • number eg "DMC 781"
  • name eg "Topaz V DK"
  • color eg "A26D20" -RGB hex value
  • printcolor eg "A26D20"
  • blendcolor eg "nil" -Ursa Specific
  • comments eg ""
  • strands eg "2"
  • symbol eg "21" - Ursa uses a symbol number, which is a sequence number. Others may specify a font and/or an actual character
  • dashpattern eg "" -Ursa Specific - used for backstitch line rendering
  • bsstrands eg "1" - where the strands used for backstitch differ from normal stitches
  • bscolor eg "A26D20" -RGB hex value can show backstitch with a different color from stitches, for clarity
  • misc1 eg “"

Examples (note that index 0 is the cloth color here)
<palette>
<palette_item index="0"
number="cloth"
name="cloth"
color="FFFFFF"
printcolor="FFFFFF"
blendcolor="nil"
comments=""
strands="2" symbol="100"
dashpattern=""
misc1=""/>
<palette_item index="1"
number="DMC 781"
name="Topaz V DK"
color="A26D20"
printcolor="A26D20"
bscolor="A2FFFF"
blendcolor="nil"
comments=""
strands="2"
bsstrands="1"
symbol="21"
dashpattern=""
misc1=“"/>
</palette>


full stitches (occurs once)
This element holds <n> stitches entries, and is cross stitch at the most basic.
It holds <n> entries, one for every full cross / tile/ tent stitch/ diamond in the design

stitch (occurs <n> times as children of ‘fullstitches’)

This element holds information about each stitch.
Only actual stitches need be recorded.. where a space on the cloth is empty, there is no need to store a stitch. If you choose to do so anyway, bare cloth is palette index 0


  • x eg "1"
  • y eg "47"
  • palindex eg “3"
  • marked eg "true" - if the chart is being used on screen, true if the square is marked as completed. May be omitted

examples:

<fullstitches>
<stitch x="1" y="47" palindex=“3"/>
<stitch x="1" y="48" palindex=“3"/>
<stitch x="1" y="49" palindex=“3" marked ="true"/>
</fullstitches>


partstitches (occurs once)
This element holds <n> partstitch entries.
In an Ursa Software file, these indicate that a square is actually filled with 2 stitches.

partstitch (occurs <n> times as children of ‘partstitches’)

This element holds information about each stitch.
Only actual stitches need be recorded.


  • x eg "38"
  • y eg "68"
  • palindex1 eg "2"
  • palindex2 eg “13"
  • direction=“1”


examples:

< partstitches >
<partstitch x="38" y="68" palindex1="2" palindex2="13" direction="1"/>
</partstitches >
palindex1 is the color on the left
palindex2 is the color on the right

When direction = 1, the result is Pasted Graphic

When direction = 2, the result is Pasted Graphic 1


From 2022, Ursa implemented half stitches which are tent stitches/ Gobelin.
For these, we started using direction 3 and 4 here.

When direction = 3, the result is Pasted Graphic 4

When direction = 4, the result is Pasted Graphic 5

backstitches (occurs once)
This element holds backstitch entries.

backstitch (occurs 0..n times as children of ‘backstitches’)

This element holds information about each backstitch.
An objecttype of ‘backstitch’ is a conventional straight line of stitching between two points.
In an Ursa Software file, this object could alternatively be a daisy stitch, or a bugle bead.
They are defined by the objecttype attribute. A rendering engine that doesn’t ‘handle’ daisy stitches or bugles could still render these items as lines.
Decimals are in UK/US format with a point as the decimal character

  • x1 eg "23"
  • x2 eg "27.5"
  • y1 eg "4"
  • y2 eg "8.5"
  • palindex eg "1"
  • objecttype eg "backstitch" , "daisy"
  • sequence eg “0” -can be used to determine drawing order

Example:
<backstitches>
<backstitch
x1="23" x2="27.5" y1="4" y2="8.5"
palindex="1"
objecttype="backstitch"
sequence=“0
"/>
<backstitch x1="31" x2="31" y1="7" y2="6" palindex="1" objecttype="daisy" sequence=“0"/>
<backstitch x1="32" x2="31" y1="7" y2="7" palindex="1" objecttype="daisy" sequence=“0"/>
<backstitch x1="27.5" x2="36" y1="11.5" y2="10" palindex="1" objecttype="bugle" sequence=“0"/>
</backstitches>







ornaments_inc_knots_and_beads (occurs once)
This element holds <n> object entries.
An object entry is pretty much ‘anything”. Some apps have buttons, charms, cutouts, beads, knots, special stitch shapes.. anything at all could occur here.
Most of these things will have an x,y position, plus optional other attributes.
Software could add a copyright label using something like this: (not a real object at this time)

<object x1="2" y1="3.5" width = “50” height = “20” words = “copyright by me 2021. Do not duplicate on pain of death” objecttype=“copylabel”/>

The possible values from an Ursa Software file (2021 edition onwards) are listed below

object (occurs '0…n' times as children of ‘ornaments_inc_knots_and_beads’)

<ornaments_inc_knots_and_beads>
<object x1="2" y1="3.5" palindex="1" objecttype=“fullcross"/>
<object x1="5" y1="6.5" palindex="1" objecttype=“4x4"/>
<object x1="8" y1="12" palindex="1" objecttype=“minikey”/>
</ornaments_inc_knots_and_beads>

In a file created by Ursa Software's MacStitch or WinStitch applications,, the current possible values of ‘objecttype’ are as follows:- all have a location, and the size and shape is determined by the object type.
Other software suppliers will have other object types that are not in this list.

  • “knot" - a french knot
  • “bead" - a simple bead of about 2.5 mm
  • “quarter" - a quarter stitch
  • “verticalhalf" - a half stitch which is taller than it is wide - half the width of a cross
  • “horizontalhalf" - a half stitch which is wider than it is tall - half the height of a cross
  • “fullcross" - a normal cross stitch, but placed anywhere
  • “3x2" - a cross stitch, but 1.5 times wider than a normal one
  • “2x3" - a cross stitch, but 1.5 times taller than a normal one
  • “3x3” - a cross stitch, but 1.5 times taller and wider than a normal one
  • "4x4" - a cross stitch, but 2 times taller and wider than a normal one
  • “minikey" - a color blob or symbol plus the thread number
  • "4x2" - a stitch, but 2 times wider than a normal one, used for knitting
  • "6x2" - a stitch, but 3 times wider than a normal one, used for knitting
  • "8x2"- a stitch, but 4 times wider than a normal one, used for knitting
  • “10x2" - a stitch, but 5 times wider than a normal one, used for knitting
  • “12x2" - a stitch, but 6 times wider than a normal one, used for knitting
  • “14x2" - a stitch, but 7 times wider than a normal one, used for knitting
  • “16x2" - a stitch, but 8 times wider than a normal one, used for knitting
  • “bead2mm" - a 2mm bead
  • "bead3mm" - a 3mm bead
  • "bead5mm" - a 5mm bead
  • "bead6mm"
  • "bead8mm"
  • "bead10mm"
  • “bead12mm"
  • "button6mm"
  • “button12mm" - buttons
  • "button8mm"
  • "button10mm"
  • "button20mm"
  • "sequin6mm"
  • “topleftlongtriangle" - a triangle 1 wide, 2 tall, at top left corner
  • “toprightlongtriangle" - a triangle 1 wide, 2 tall, at top right corner
  • “botleftlongtriangle" - a triangle 1 wide, 2 tall, at bottom left corner
  • “botrightlongtriangle" - a triangle 1 wide, 2 tall, at bottom right corner
  • “topleftwidetriangle" - a triangle 2 wide, 1 tall, at top left corner
  • “toprightwidetriangle" - a triangle 2 wide, 1 tall, at top right corner
  • “botleftwidetriangle" - a triangle 2 wide, 1 tall, at bottom left corner
  • “botrightwidetriangle" - a triangle 2 wide, 1 tall, at bottom right corner
  • "queen2x2" - a diamond shape , width 2 normal stitches
  • "queen3x3" - a diamond shape , width 3 normal stitches
  • "queen4x4" - a diamond shape , width 4 normal stitches
  • "queen5x5" - a diamond shape , width 5 normal stitches


commentboxes (occurs once)
This element holds <n> commentbox entries.


commentbox (occurs <n> times as children of ‘commentboxes’)


<commentboxes>
<commentbox
boxheight="2" boxwidth="34"
boxleft="18" boxtop="3"
boxwords=“This is a comment”
/>
</commentboxes>


Testing



A Sample chart can be downloaded from [HERE]

And it looks like this:

Pasted Graphic 1

© 2022 Ursa Software Ltd Contact Us