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'

At the time of writing, the format is now in use by
Ursa Software (MacStitch/WinStitch/MobiStitch)
DP Software (Cross Stitch Professional)
Cross Stitch Saga
Krestic

With hopefully more to follow

This document updated 6 Feb 2022 with additional / proposed new attributes from DP Software.



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 “"
  • fontname (added by DPSoftware) - one of 3 possible font sets used for the symbol
  • metallic (added by DPSoftware) - eg "true". If metallic thread
  • fluorescent (added by DPSoftware) - eg "true". If fluorescent thread
  • locked (added by DPSoftware) - Set to “true” if the color has been locked by the user to prevent color changes (Cross Stitch Pro also uses this flag when editing a layered object to stop palette changes from affecting the base level design)
  • symbolcolor. (added by DPSoftware) - eg "F5A3A8". rgb hex value for the font color of the symbol. Since this is a Windows color there is no cmyk version.

There are optional properties to specify CMYK hex colors.

  • colorcmyk="F5A3A855"
  • bscolorcmyk="F5A3A855"
  • printcolorcmyk="F5A3A855"

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”
    • major. (added by DP Software) eg. major="1"
"major" is used to indicate if a ¾ stitch should show as equal parts or if one part should be shown larger than the other. If major=0 or the parameter is not present then the parts will be equal. If major=1 then palindex1 is the larger half of the stitch. If major=2 then palindex2 is the larger half of the stitch.


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 <n> backstitch entries.

backstitch (occurs <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"
      • thickness. Eg "2" .. multiplies the number of strands by the thickness when it would otherwise be the default number of strands. If there is a non-default strand value set for the palette entry then this property is ignored.
      • 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>


DP Software notes:
Cross Stitch Pro will process backstitches at the time of printing or exporting to a flat design by chopping them into single stitch lengths, removing hidden lines, aligning directions and chaining them into continuous straight lengths.
This means it will not respect a sequence number assigned to a backstitch when opening an oxs file but will read them in the order they appear in the file.
When saving to oxs as a flat (non layered) design,
Cross Stitch Pro will assign an ascending sequence number which represents the order in which they were added to the design but it does not require or use this information.





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 <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
  • "tent" eg direction="1" objecttype = "tent">

A new objecttype='tent' is added that represents a diagonal stitch top left to bottom right or top right to bottom left.
Direction=1 represents \
Direction=2 represents /



Additional info from DP Software files:
objecttype='quarter' gets an optional property petit which can be “true” or “false”.
A value of true specifies that programs able to differentiate between ¼ stitches and petit-point should treat the stitch as petit-point.
Cross Stitch Pro treats each square in the design as either regular stitches (cross, ¼, ¾, tent) or petit-point (petit, half cross vertical or horizontal, off grid cross).
It is not possible to mix stitches from both groups in a single grid square.
If the property is missing then Cross Stitch Pro treats the stitch as a standard ¼ stitch.


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>


Schemes (optional - occurs once only)
This is a new section suggested by DP software that allows different color schemes to be defined for a design, like colorways from Ursa Software
Each color scheme is contained in a scheme_item.
Each scheme_item contains a new palette, name of the scheme and name of the color range.
When Cross Stitch Pro adds an alternative color scheme it always adds a master scheme plus the new alternative.
So either there are no schemes or there are at least 2.
The main palette is the one currently in view and the master and alternates are the ones available for selection.
Contains <n> scheme_item entries.
(occur once for each color scheme as child of ) • name -
for example “My alternate color scheme” as shown in the design software. • rangename – for example “dmc” or “anchor tapestry” used to show entire range.
In Cross Stitch Pro, the extension .clr is added to this name to get the filename of the thread definitions.
These files could be made by the user so cannot be guaranteed standard.
Children: same as in the main chart containing palette_items



Layers (coming soon)


Testing



A Sample chart can be downloaded from
[HERE]

And it looks like this:

Pasted Graphic 1