From Create Wiki

Current revision as of 13:57, 31 October 2009

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.

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 destructive 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 example 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

A Baseline document is a document that can be opened and look similar on all applications and platform. Baseline defines the minimum requirement to achieve interoperability and what is unsafe if the goal of the user is interoperability. This specification will define a Baseline OpenRaster Layer Stack and allow extensions.

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 visualization, 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 visualization of the file, but edition might damage the result

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 {
     attribute w { xsd:int },
     attribute h { xsd:int },
     attribute name { text } ?,
     stackContent
     }
 
 stackContent =
   element stack {
     layerCommonAttributes,
     ( stackContent, layerContent, filterContent, textContent )+
   }
 
 layerContent =
   element layer {
     layerCommonAttributes,
     attribute src { text },
     attribute compositeop { text } ?,
     attribute opacity { xsd:float } ?,
     element filters {
      ( filterContent ) +
     }
   }
 
 filterContent =
   element filter {
     layerCommonAttributes,
     attribute type { text },
     attribute output { text }
     paramsContent,
     stackContent
   }
 
 textContent =
   element text {
     layerCommonAttributes,
     text
   }
 
 positionAttributes =
   attribute x { xsd:int } ?,
   attribute y { xsd:int } ?
 
 layerCommonAttributes =
     positionAttributes,
     attribute name { text } ?
 
 paramsContent =
   element params {
     attribute version { xsd:int }
     element param {
       attribute name { text }
       (text | xsd:int)
     }+
   }
}

Example

<image w=300 h=177>
 <stack>
   <stack x="10">
     <filter name="invert" type="invert" />
     <stack>
       <layer name="OpenRaster Logo" src="data/hw.svg" x="5" y="5" />
       <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="data/mask2.data" compositeOp="over" />
       <layer name="mask1" src="data/mask1.png" />
     </stack>
   </filter>
   <layer name="layer1" src="data/image1.png" />
 </stack>
</image>

Description of each elements and attributes

Common attributes

• position attribute: "x" and "y" are signed integers, their default value is 0
• name attribute: it's an utf8 string

Image element

This is the root element of the file.

• The size of the image is given by the mandatory "w" and "h" attributes, which are positive integers. The content below the image element can be smaller or bigger and should be cropped at (0,0,w,h) for displaying, printing, exporting, etc.

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 ?)
• "opacity" : 0.0 for fully transparent, 1.0 for fully opaque

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.