Overview
The NextDraw 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 NextDraw software. They can be used (for example) whether plotting from Bantam Tools NextDraw software for Inkscape, Bantam Tools Merge, or the CLI or Python APIs.
When printing multiple layers, layers print in the order from lowest to highest. You can preview the layers within Inkscape using the Layers and Objects panel, accessible from the menu at Layer > Layers and Objects.... Layers can be hidden. Since only visible layers will be printed, hiding layers is an effective method for controlling what will be plotted.
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 with the "Plot selected layers" option in the Bantam Tools NextDraw extension for Inkscape (or "layers" mode in the NextDraw 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 escape sequences are as follows:
-
+S
: Specify pen-down speed for the given layer. The+S
should be followed by an integer in the range 1 to 100 that gives the pen-down plotting speed for that layer. -
+H
: Specify pen-down height for the given layer. The+H
should be followed by an integer in the range 0 to 100 that gives the pen-down height for that layer. -
+D
: Specify a delay in milliseconds before the given layer. The+D
should be followed by an integer of at least 1, which gives the delay time. The delay will be executed when the NextDraw begins to plot that layer, before any other elements of that layer are processed — 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+D
escape sequence can be used with an otherwise empty layer. -
+G
: Specify plot optimization level for the given layer. The+G
should be followed by an integer in the range 0 to 4 that gives the optimization control code for the layer. The integer values are:- 0: Least; Only connect adjoining paths
- 1: Basic; Also reorder paths for speed
- 2: Full; Also allow path reversal
- 3: (Reserved for future use; currently same as 2)
- 4: None; Strictly preserve file order
+G
syntax was added in software version 1.3. -
+M
: (Coming soon): Specify a handling mode for the layer.
In addition to these escape sequences, two special escape characters are defined as follows:
-
%
: If the first non-whitespace character of the layer name is the percentage sign (%
), 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. When Preview mode is active, rendered path previews are placed on documentation layers so that they can be viewed, but will not plot.
-
!
: If the first non-whitespace character of the layer name is an exclamation point (!
), 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.
Sublayers
Layers may be created or placed inside of other layers. A layer inside another layer is called a "sublayer." However, only the names of top-level "outer" layers in the SVG document, and not sublayers, are considered for any Layer control features.
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 Bantam Tools NextDraw) and that the default pen-down speed is set at 30 (e.g., in the "Options > Speed" tab of Bantam Tools NextDraw).
2 forest floor
- 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).
45+S50_forest floor
- 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.
100+H5055forest floor
- 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.
0+s1+h100 Forest floor
- 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.
300+s1+h100+S50+G4 Forest floor
- 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. This layer has plot optimization strictly disabled (optimization value 4).
22+S0+H0 Forest floor
- 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.
223+D2500+H0 Forest floor
- The layer number is 223. It prints after a delay of 2.5 seconds (2500 ms) and pen-down height of 0.
99+S25_+H50 Forest floor
- 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".
+H50 Forest floor
- 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.)
%99+S25_+H50 Forest floor
- The layer will not be plotted, since it begins with a percentage sign.
!+H50 Forest floor
- 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 NextDraw 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
g
(group) element with attributeinkscape:groupmode="layer"
. - The layer name is specified by a second attribute,
inkscape:label
likeinkscape:label="1-Yellow"
.
You will also need to add the Inkscape namespace to the enclosing svg
element so that the inkscape
attributes are recognised. Something like this:
<svg viewBox="0 0 297 210" height="210mm" width="297mm" xmlns="http://www.w3.org/2000/svg" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" />
Examples of SVG documents with layers can be found in the NextDraw basic example set. You can open these SVG files in a text editor to examine the structure of the documents.