From Create Wiki

Note: this is an early draft of the specification, do not take anything on this page for granted, pretty much everything is open for discution.

Contents 1 Introduction 2 Base line documents 3 The full syntax of the OpenRaster Layer stack 4 Example of OpenRaster layer stack xml 5 Description of each elements and attributes 5.1 Common attributes 5.2 Image element 5.3 stack element 5.4 layer element 5.5 filter element 5.6 params element 5.7 param element 5.8 text element

Introduction

This document specifies and describes what is a correct and valid OpenRaster Layer Stack. The main two goals of the specification is interoperability between applications and saving non destructrive pixels operations.

Note that this document do not define data source, and especially doesn't address the issue of how to store pixels, nor how OpenRasters file can be stored on the hard drive. This document doesn't address either the mathematics behind composite operations or behind filters. All of this part of the OpenRaster specification are described in other documents.

The first part of the document explain the concept of a BaseLine Layer Stack, then the document gives an exemple of a Layer Stack, followed by the full schema of the Layer Stack and then the last section contains a complete a description of each attribute and element.

Base line documents

To achieve interoperability, without restricting application to be clone of one other, or to have to use a different file format for extension, this specification will define a Baseline OpenRaster Layer Stack and allow extensions. We will refert to a BaseLine document as a document that can be opened and look similar on all applications and plateform. In other word, at the same time, Baseline define the minimum requirement to achieve interoperability and what is unsafe if the goal of the user is interoperability.

BaseLine is divided in two categories, some users will require full interoperability, to create files that can be edited on every application supporting OpenRaster, but some other will only need to give file for visualisation, that is why this document define two types of BaseLine:

• "Full BaseLine" which allow reading and editing
• "Viewing BaseLine" which offer the garantie for the vizualisation of the file, but edition might damage the result

The full syntax of the OpenRaster Layer stack

The complete syntax of the layer stack is given following the RelaxNG xml schema:

grammar {
 start = 
   element image {
     positionSizeAttributes,
     attribute name { text } ?,
     stackContent
     }
 
 stackContent =
   element stack {
     attribute x { xsd:int } ?,
     attribute y { xsd:int } ?,
     attribute name { text } ?,
     ( stackContent, layerContent, filterContent, textContent )+
   }
 
 layerContent =
   element layer {
     layerCommonAttributes,
     attribute src { text },
     attribute compositeop { text },
     element filters {
      ( filterContent ) +
     }
   }
 
 filterContent =
   element filter {
     layerCommonAttributes,
     attribute type { text },
     attribute output { text }
     paramsContent,
     stackContent
   }
 
 textContent =
   element text {
     layerCommonAttributes,
     text
   }
 
 positionSizeAttributes =
   attribute x { xsd:int } ?,
   attribute y { xsd:int } ?,
   attribute width { xsd:int } ?,
   attribute height { xsd:int } ?
 
 layerCommonAttributes =
     positionSizeAttributes,
     attribute name { text } ?
 
 paramsContent =
   element params {
     attribute version { xsd:int }
     element param {
       attribute name { text }
       (text | xsd:int)
     }+
   }
}

Example of OpenRaster layer stack xml

<image x=-10 y=2 w=300 h=177>
 <stack>
   <stack x="10">
     <filter name="invert" type="invert" />
     <stack>
       <layer name="OpenRaster Logo" src="hw.svg" x="5" y="5" width="40" height="20"/>
       <text x="50" y="10">Use a Rich Text XML Specification to write cool text in your OpenRaster File</text>
     </stack>
   </stack>
   <filter name="filter1" type="standard:gaussianblur">
     <params>
       <param name="radius">10</param>
     </params>
     <stack>
       <layer name="mask2" src="mask2.data" compositeOp="over" />
       <layer name="mask1" src="mask1.png" />
     </stack>
   </filter>
   <layer name="layer1" src="image1.png" />
 </stack>
</image>

Description of each elements and attributes

Common attributes

This section describes the legal value that can be taken by some common values, and the default value of each element if they are not given:

• position attributes, "x" and "y" are signed integer, their default value is 0 for layers, for an image, it's defined such as all the layers are visible (x_image and y_image are set to the minimum of respectively x_layer and y_layer).
• size attributes, "width" and "height" are positive integer, their default value is set to the value defined by the data source for a layer, for an image
• name attribute, it's an utf8 string

Image element

It's the root element of the file. TODO: tell more when all of the parts of the file are defined

stack element

This element describe a group of layers, wether it is an other group of layers, a layer, a filter or a text.

layer element

• "src" :the file name of the source of this layer
• "compositeOp" : the composite op used by (TODO: do a namespacing like for filters ? standard and application are most likely needed, but composite ?)

filter element

This elements define a layer which instead of containing pixel, apply an filter on the result of the layer composition for the layer below in the stack.

• type the type of the filter, they make use of namespaces, they must have the following form : "namespace:name", three namespaces are defined:
  • "standard" : for the list of filters and the associated mathematics, see the relevant OpenRaster specification
  • "composite" : composite are filters which are a composition of a list of stantard filters, the name must be the name of a filter defined in the same file
  • "applications" : non standard filters, the name is formed as followed "application:filtername"), for instance for an application called MyGraphApp, the full names is "application:MyGraphApp:MyFilter", the use of such a type of filter, prevent the file to be "Full BaseLine", the use of the output attribute allow file to be "Viewing BaseLine"
• output the filename of the data of the filter output, this attribute is only needed when the type of the filter is of the "application" namespace, and if the user want to create a "Viewing BaseLine" layer stack

params element

This elements is used to describe the parameters used for an filter layer. The standard filters has a defined list of parameters, range value and filters of the parameters on the end result.

• version : correspond to the version of the filter, either the version of the filter specification for standard filter, or any number defined by the application for the applications tag.

param element

Description of the attributes:

• name the name of the parameter

The value contains in the param element, is the value of the parameter associated with the name.

For "composite" filters, the params element allow to defined variables that are then used to parametrized the filters. For instance, lets consider the case of the "standard:blur" filter with the parameter "radius" and of the "standard:invert" filter, it is defined as follow in the composite section:

<compositefilter name="blurinvert" >
 <filter name="blur" >
  <params>
    <param name="radius">
    @R@
    </param>
  </params>
 </filter>
 <filter name="invert" />
</compositefilter>

Then the usuage would be:

<filter name="composite:blurinvert" >
<params>
<param name="R">10</param>
</params>
</filter>

TODO: reconsider this, is it useful ? it just come out of my mind that is the only usefull use of parameters for composite filter, but if it's useless, lets not allow any parameters for them !

text element

TODO: define it, more like include an other specification, a relevant subset of the OpenDocument Text specification would be the most logical.