Editing AxiDraw Layer Control

{{AxiDrawDocs}}


== Overview ==

The AxiDraw layer-numbering syntax, as described in the user guide, shows you how to print only one layer (or a set of layers) in your document, by numbering your layer names. However, there are additional parameters that can be controlled through the layer name. You can use properly formatted codes to specify the pen-down height and the speed for printing that layer alone. There are also special codes that can introduce a delay while plotting, force a programmatic pause (an operation that halts plotting -- not simply a delay), or label a layer as one that should not be plotted.  These features are always active when plotting SVG files from the AxiDraw software. They can be used (for example) whether plotting from the Plot or Layers tab of AxiDraw Control, when plotting with AxiDraw Merge, when plotting with the [https://axidraw.com/doc/cli_api/ AxiDraw CLI] (command-line interface), or plotting SVG files from [https://axidraw.com/doc/py_api/ AxiDraw Python API].

When printing multiple layers, layers print in the order from lowest to highest. You can preview the layers within Inkscape using the Layers panel, accessible from the menu at '''Layer > Layers...'''. Layers can be hidden, and only visible layers will be printed.


== Syntax ==

The basic syntax (again, as described in the user guide) requires only that the layer name begins with an integer in the range of 0 to 1000. Then, by printing from the "Layers" tab in AxiDraw Control (or "layers" mode in the AxiDraw CLI or Python API), we can select which layer (or set of layers) to print. 

We have extended this by detecting that layer-name integer, followed by a specific escape sequence, followed by another integer.  When printing a document where one or more of the layers contain parameters like this, the layer-specified pen-down height or pen-down speed will override the defaults given in the extension, for that layer only.  The escape sequences are not case sensitive. Escape sequences need to be given at the start of a layer or immediately following the layer number or other escape sequences. (One exception to this is that whitespace-- one or more spaces at the start of a layer name --  will be ignored. If more than one valid parameter of a given type is found (say, more than one valid speed command for a given layer), only the last one detected will have an effect. 

The three escape sequences that are as follows:

* <code>+S</code>: Specify pen-down speed for the given layer.  The <code>+S</code> should be followed by an integer in the range 1 to 100 that gives the pen-down plotting speed for that layer.


* <code>+H</code>: Specify pen-down height for the given layer. The <code>+H</code> should be followed by an integer in the range 0 to 100 that gives the pen-down height for that layer. 


* <code>+D</code>: Specify a delay in milliseconds before the given layer.  The <code>+D</code> should be followed by an integer of at least 1, which gives the delay time. The delay will be executed when the AxiDraw begins to plot that layer, ''before any other elements of that layer are processed'' &mdash; including the pen-up move to the first location on the layer. That means that in a multi-layer plot, the delay will typically be executed with the pen up, at the last XY position of the previous layer plotted.  The <code>+D</code> escape sequence can be used with an otherwise empty layer. (This feature was added in AxiDraw software version 1.6.1. Prior to version 3.1, the pen was not automatically raised at the end of each path, so the delay could be added with the pen still down.) 


In addition to these escape sequences, two special escape characters are defined as follows:

* <code>%</code>: If the first non-whitespace character of the layer name is the percentage sign (<code>%</code>), it specifies that the layer is a ''documentation layer'' and should not be plotted. This can be used for setup marks, instructions (including editable text and pictures), or other uses as needed. Documentation layers are skipped outright, so objects such as editable text and bitmap images (which would otherwise necessitate a warning) will simply be ignored if they occur on documentation layers. Sublayers within a documentation layer are skipped as well. The Preview function (available in AxiDraw software version 1.5 and newer) places its output on documentation layers so that they can be viewed, but will not plot. (This feature was added in AxiDraw software version 1.3.0.)


* <code>!</code>: If the first non-whitespace character of the layer name is an exclamation point (<code>!</code>), it forces a ''pause'' to occur before plotting the layer, just as though one had pressed the physical pause button. The pause operation raises the pen but does not return it to the home position. The plot can then be resumed from that point. This feature may be used to introduce a pause that requires a human's attention (e.g., paper swap, check ink levels, have a human wait for adhesive to set) or various programmatic operations-- such as beginning a plot even when the full plot data is not yet available. The pause will occur regardless of the layer's contents; the layer may even be completely empty other than the name. Note that if two or more pauses occur without plotting between them, they will be treated as a single pause when resuming. Note also that a pause at the beginning of the plot, before any motion occurs may abort the plot entirely. (This feature was added in AxiDraw software version 1.7.1.)


=== Sublayers ===

Layers may be created or placed inside of other layers. A layer inside another layer is called a "sublayer." 

In AxiDraw software version 3.0 and above, sublayer names are not parsed for layer control codes. If you wish to use layer control sequences, they need to be on top-level "outer" layers, not sublayers, in the SVG document.

Prior to version 3.0, parameter overrides apply to the given layer only. Sublayers '''do not''' inherit these overrides from layers that contain them. For example, if a layer specifies a given speed, sublayers of that layer will be plotted with the default speed unless the sublayers have overrides of their own. An exception to this is documentation layers, for which the entire layer is skipped, whether or not it contains sublayers.

The AxiDraw software that parses the SVG file may in some circumstances "flatten" nested layers into a linear list of layers to plot. The flattening process can in some cases lead to unexpected behavior if there are sublayers within a layer that starts with a coded delay (<code>+D</code>) or pause (<code>!</code>). To avoid this possibility, always avoid using sublayers within layers that also encode a pause or delay.


== Examples ==

The following examples show a number of different possible layer names, and what the expected behavior would be.  Let us assume that the default pen-down height is specified as 20 (e.g., in the "Setup" tab of AxiDraw Control) and that the default pen-down speed is set at 30 (e.g., in the "Options > Speed" tab of AxiDraw Control).


: <code>2 forest floor</code>

: The layer number is 2, and it is labeled as "forest floor". It prints with the default pen height and speed (in the case described here, a pen-down height of 20, and a pen-down speed of 30).


: <code>45+S50_forest floor</code>

: The layer number is 45, and it is labeled as "_forest floor". It prints with the default pen height, but with pen-down speed of 50, regardless of the value specified in the extension.


: <code>100+H5055forest floor</code>

: An invalid declaration, since the requested height is 5055 (which is outside of the range 0 to 100). The layer number is 100. It prints with the default pen height and speed, since there are not any valid override codes.


: <code>0+s1+h100 Forest floor</code>

: The layer number is 0. It prints with the pen-down height of 100, and with pen-down speed of 1, regardless of the value specified in the extension.


: <code>300+s1+h100+S50 Forest floor</code>

: The layer number is 300. It prints with the pen-down height of 100, and with pen-down speed of 50, regardless of the value specified in the extension. While there are two pen speed escape codes given, recall that only the last one has an effect.


: <code>22+S0+H0 Forest floor</code>

: The layer number is 22. It prints with the pen-down height of 0, and with the default pen-down speed 1, since the speed value of 0 is not valid.


: <code>223+D2500+H0 Forest floor</code>

: The layer number is 223. It prints after a delay of 2.5 seconds (2500 ms) and pen-down height of 0. 


: <code>99+S25_+H50 Forest floor</code>

: The layer number is 99. It prints with the default pen-down height, but with a pen-down speed of 25. The height parameter is not valid, since it does not directly follow the other parameter but is interrupted by an underscore. The layer name is "_+H50 Forest floor".


: <code>+H50 Forest floor</code>

: No layer number given. It prints with the default pen-down speed, but with a pen-down height of 50. (Layer numbers are not required.) 


: <code>%99+S25_+H50 Forest floor</code>

: The layer will not be plotted, since it begins with a percentage sign.



: <code>!+H50 Forest floor</code>

: No layer number given. It prints with the default pen-down speed, but with a pen-down height of 50. (Layer numbers are not required.) A pause will be forced when this layer is encountered-- nothing on the layer will be plotted until one uses the Resume feature to continue plotting.



== Adding layers outside of Inkscape ==

If you are generating your own SVG from scratch, it may be helpful to know what the AxiDraw software interprets as a "layer" in the SVG file.  The software follows the same convention as Inkscape, which is as follows:
* An Inkscape layer is a <code>g</code> (group) element with attribute <code>inkscape:groupmode="layer"</code>.
* The layer name is specified by a second attribute, <code>inkscape:label</code> like <code>inkscape:label="1-Yellow"</code>.

You will also need to add the Inkscape namespace to the enclosing <code>svg</code> element so that the <code>inkscape</code> attributes are recognised. Something like this:

 <svg viewBox="0 0 297 210" height="210mm" width="297mm" 
     xmlns="<nowiki>http://www.w3.org/2000/svg</nowiki>"
     xmlns:inkscape="<nowiki>http://www.inkscape.org/namespaces/inkscape</nowiki>"
 />

Examples of SVG documents with layers can be found in the [[Axidraw_Examples|AxiDraw basic example set]]. You can open these SVG files in a text editor to examine the structure of the documents.