Editing Inkscape and WaterColorBot

{{WaterColorBotDocs}}


== Introduction ==
 
There are three main [[WaterColorBot_Software|software interfaces]] for driving the WaterColorBot: [[RoboPaint]], [[RoboPaint RT]], and (as described on this page) the WaterColorBot extensions for Inkscape. 


Inkscape is a superb, free vector graphics editor, for which we have written an extension (a plugin) to control the WaterColorBot.  Our extension provides a fine grain level of control over exactly what will be painted, but more-or-less requires that you create the artwork within Inkscape to take full advantage of the features.  The most important thing to know is that the Inkscape extension will paint all of the paths (lines) within your drawing. It will not automatically fill in any regions; any region that you wish to fill with paint will have to have (for example) a hatch fill that consists of lines, in order for the area to be colored in.

Inkscape is also capable of importing artwork in PDF format (as well as tracing bitmap graphics to some extent), and saving as SVG graphics that can be used with RoboPaint.  Users who have experience with the Eggbot (and its Inkscape based driver) may wish to start with this application, before trying the others.


== Getting the software ==


Installing Inkscape: 
* Begin by downloading and installing Inkscape, version 0.91.  You can find Inkscape https://inkscape.org/en/release/0.91/platforms/ here].
* If you are using a Mac (MacOS version 10.6 or newer), download and install the latest release of  [http://xquartz.macosforge.org/landing/ XQuartz]
* If you are using a Linux version for which there is not a pre-compiled version of Inkscape,  [https://gist.github.com/jeffkayser/4637089d3c11546e6d4f this page] may be helpful in compiling Inkscape 0.91 source on Ubuntu / Debian]


Installing the extensions
* Make sure that you've already installed Inkscape
* Download the software from [https://github.com/evil-mad/wcb-ink/releases our github repository].
* Mac & Windows: Please use the dedicated installer for your platform.
* Linux: Please manually install the extensions


Manual installation of extensions for Linux:
* Download source code zip file from  [https://github.com/evil-mad/wcb-ink/releases our github repository] and unzip
* Move or copy the contents of the "extensions" directory into $HOME/.config/inkscape/extensions
* Move or copy the contents of the "templates" directory into $HOME/.config/inkscape/templates


USB Driver (Windows only):
* A USB driver is also required for Windows. The Windows installer now installs this driver (assuming that you grant it permission).

== Special information for Eggbot users ==

The WaterColorBot Control extension is based on our [[Eggbot Control]] extension that operates the Eggbot.  If you have had some experience with the Eggbot, you will find most controls to be the same. In particular, you may have had some experience with making a multi-color drawing with the Eggbot, by putting paths that you want to print in different colors on different layers.   

The biggest difference between the two machines is that since the WaterColorBot can perform automatic paint color changes-- unlike the Eggbot --it ''requires'' that you use multiple named layers when multicolor painting is enabled. 


== Setting up your file ==

=== The WaterColorBot Template / Making a new document ===

A WaterColorBot template is included with the software installation.  To create a new document pre-formatted for the WaterColorBot, select from the menu: File > Templates... and select WaterColorBot from the list there.

The template is pre-sized at 11" wide x 8" tall, matching the printable area of the WaterColorBot (that is, for a sheet of 9x12 paper, without the margins shown).  The template also comes pre-formatted with a layer structure that may help save you some time in preparing your document.

=== Default paint layers ===

The template comes with 9 (named but otherwise empty) layers that are intended to represent the 8 colors plus water wash.   

In accordance with the way that the [[Control_WaterColorBot|Control WaterColorBot]] extension works, the 9 default layers have names like "4-Yellow" and "1-Black" that represent both a paint position (4 and 1, respectively in those two cases) and the human-readable paint color (Yellow and Black, respectively in those two cases).   

While layers can easily be re-ordered, the default stackup of the layers is in approximate order of darkness, with 4-Yellow at the bottom (meaning that it will be printed first) and 1-Black is near the top (meaning that it will be printed near the end).  

If you will be using a painting mode that does not automatically change paint colors (e.g., pen/pencil mode), you can ignore the layer structure, and put your painting on any layer or combination of layers that you desire.


=== Working with layers   ===

If there are multiple layers in your Inkscape Drawing, they will be printed in the order from '''bottom to top'''.  

To paint with different colors (using either automatic or manual paint color changes), the different parts of your drawing that will be painted in different colors should be separated into layers as described below.


==== Preparing layers for automatic paint color changes ====

To paint with multiple colors, and have Inkscape automatically change the paint color as it goes, you need to do two things:
* Create one or more layers in Inkscape and assign them names that begin with integers, and
* Configure the WaterColorBot (in [[Control_WaterColorBot|Control WaterColorBot]]) for painting with automatic paint color changes. (See NOTE 1 below.)


The integer can be in the range from 0 - 100, and that integer can be followed by any name or description that you like.

Only layers that begin with an integer in the range 0-8 will be painted with AutoChange enabled, and for each of those layers, the paint color will be determined by that leading integer, as follows: 

: 0 - Water wash (no paint)
: 1 - Top paint pan (normally black)
: 2 - Second from top (red)
: 3 - 3rd from top (orange)
: 4 - 4th from top (yellow)
: 5 - 5th from top (green)
: 6 - 6th from top (blue)
: 7 - 7th from top (violet)
: 8 - bottom paint pan (brown)
: 9 or higher:  ignored

For example, if you create four layers with the names:
: 2 - circles
: 2 - rectangles
: 5 - triangles
: 62 - zigzags

Then, the two layers that start with the "2" (the circles and the rectangles) will be painted in red, the triangles will be painted in green, and layer 62 (zigzags) will not be painted.

The order in which the layers will be painted is from '''bottom to top'''.    You can add additional layers of any of the colors, and you can re-arrange the order of the layer to change the order in which the different colors are painted.   For example,  you can switch back and forth between two or more colors as desired.


NOTE 1: To configure the WaterColorBot to use automatic paint color changes:
* Select a painting mode in the "Modes" tab of [[Control_WaterColorBot|Control WaterColorBot]] that has "AutoChange" enabled (e.g., Watercolor, Tempera, or manual with AutoChange selected), and
* Start your painting from the "Paint" tab (not the "Layers" tab) of [[Control_WaterColorBot|Control WaterColorBot]].

==== Preparing layers for manual paint color changes ====

The same layer structure can be used with manual color changes, for example, switching to different colors of watercolor pencil or permanent marker.  

When doing so, select a painting mode in the "Modes" tab of [[Control_WaterColorBot|Control WaterColorBot]] that does not have "AutoChange" enabled (e.g., Dip Pen, Watercolor Pencil or Pen/Pencil).  Use the "Layers" tab in [[Control_WaterColorBot|Control WaterColorBot]] rather than the "Paint" tab, to paint one layer at a time, and manually change the color after each layer that you paint.


==== Preparing a file that does not need color changes ====

There are a number of ways to use the WaterColorBot that do not require paint color changes.  For example, if you are using the WaterColorBot to sketch or draw with a pen or pencil, or with a calligraphy brush that will only be dipped in black ink.   In cases like these, without color changes, you can ignore the layer structure, and put your drawing on any layer or combination or layers that you desire.  

To turn off automatic paint color changes, make sure that none of the "AutoChange" modes (e.g., Watercolor, Tempera, or manual with AutoChange selected) is enabled in the "Modes" tab.  Then, you can begin your painting from either the "Layers" tab (to draw only the contents of one layer) or from the "Paint" tab (to draw the contents of all layers).

== Extensions ==

<img src="http://evilmadscience.s3.amazonaws.com/wiki/watercolor/inkex/menu.jpg">

There are three Inkscape extensions installed as part of the WaterColorBot distribution.

=== Control WaterColorBot ===

[[Control_WaterColorBot|Control WaterColorBot]] is the primary Inkscape extension for WaterColorBot, and of the three, is the one that actually talks to and drives the WaterColorBot. 


=== Hatch Fill ===

The Hatch Fill extension (originally developed for the Eggbot project) is included in the WaterColorBot submenu, below Control WaterColorBot.  This version has been slightly modified to have calibration in terms of lines per inch, rather than pixel steps.

=== Snap Colors to Layers (beta) ===

This new extension (still in beta test) can automatically assign colored paths to layers, making it possible for the WaterColorBot to semi-automatically paint them.


== Performance issues ==

=== Pausing a plot in progress ===

The WaterColorBot has a useful feature which allows you to pause and resume your plots. By pressing the PRG button on the EBB (EiBotBoard), plotting is paused. You can then make adjustments including changing drawing speeds and pen up or down positions. After making any adjustments, you can resume the plot within the Resume tab. Note that you can even exit Inkscape. The Control WaterColorBot extension will automatically store plotting information in your drawing file. So, if you save the drawing file before exiting Inkscape, you can later resume your plot by relaunching Inkscape and re-opening your drawing.

There are actually two options in the Resume tab, to either resume the plot or only return the carriage to the home corner.  If you use that feature to return to the home corner, you can still resume your plot from there.


== For Developers ==

=== Repository ===
The WaterColorBot extensions for Inkscape are maintained at [https://github.com/evil-mad/wcb-ink/ our github repository].  

=== Bugs and feature requests ===

Please use the [https://github.com/evil-mad/wcb-ink/issues issues page] at our repository to report bugs and request new features for the WaterColorBot extensions for Inkscape.