<h1>MagicWand</h1>

<h6>The plugin is available in the QGis public repository:
    <a href="http://plugins.qgis.org/plugins/MagicWand/">
    http://plugins.qgis.org/plugins/MagicWand/</a>
</h6>

<p>MagicWand is a QGis plugin written in python. The plugin adds a toolbar
that contains three actions.</p>

<h2>Magic wand tool <img src="icons/magic_wand.png"/></h2>
This action activates a map tool that allows the user to extract a
polygon from an image with just one click, looking at the pixel colors.
<br/>
<b>Required:</b>
<ul>
<li>Active layer in the legend must be a <b>raster layer</b></li>
</ul>
<b>Usage:</b><br/>
Click a specific element int the raster layer (i.e. click on a red roof
of a building that is surrounded by a green field). The tool generate a
polygon that represent the clicked element (the roof) and store it in a
temporary layer.

The created polygon is automatically selected on the temporary layer.
If the user is satisfied he can just <b>press enter</b> and the polygon
 will lose the selction.

If a generated polygon result incorrect it can be <b>edited</b>. In order to edit an existing polygon
just select it (if it is the last thing that was created than
it is already selected by defalut) and press a point close to the polygon. <br/>
Now if the user pressed with the <b>left click</b> the new area of pixels with
similar colors is going to be <b>added</b> to the already existing and selected polygon.
Instead if the the user pressed with the <b>right click</b> the area is
going to be <b>subtracted</b>.

<h2>Magic hat tool <img src="icons/magic_hat.png"/></h2>
This action activates a map tool that allows the user to edit an existing
polygon on a vector layer.<br/>
<b>Required:</b>
<ul>
<li>Active layer in the legend must be a <b>vector layer</b></li>
<li>One and only one feature <b>must be selected</b> in the vector active layer</li>
</ul>
<b>Usage:</b><br/>
Click and hold in the map to draw an outline that represent the part of the polygon
that you want to add or delete. <br/>
Use <b>left click</b> in order to add a part to the existing polygon. A <b style="color:green">green</b>
outline will be displayed.
Use <b>right click</b> in order to delete a part of the existing polygon. A <b style="color:red">red</b>
outline will be generated.

<h2>Settings <img src="icons/settings.png"/></h2>
This action open a settings dialog. The following properties can
be setted: <br/>

<b>Tolerance</b><br/>
Tolerance is used to understand if 2 blocks of pixels have similar colors by the
Magic Wand tool. <br/>
<b>Examples:</b>
If a light green filed surrounded by dark green trees wants to
be extracted probably a low value of tolerance must be setted.
Conversly if a filed that has different tones of yellow wants to be extracted
all at once, the tolerance must be setted to a high value. <br/>

<b>Approximation</b><br/>
Approximation is used by both the MagicWand and the MagicHat.

In the <b>MagicHat</b> it determines simply the brush thickness.

Instead in the <b>MagicWand</b> it determines how many pixels must be merged togheter
in order to speed up the process. If approximation is increased you will
immidiatly notice that the trasparent white area that follows your cursor
is increased. <br/>
<b>Examples (MagicWand):</b>
Increase approximation if you are working on a big scale, if you want
to extract a huge element in relation to the pixel size in the raster layer
or if the process becomes slow. <br/>

<b>Timeout</b><br/>
A <b>MagicWand</b> task can last at most the time indicated in the
timeout properties. If a task is taking more then the timeout value
(by default 15 sec), it will be interrupted.

<b>ViewSteps</b><br/>
Is a boolean that is used mainly in debbug mode but can be used also
in order to understand how the <b>MagicWand</b> tool works. If it is
setted, the algorithm's process is shown.
<p>

<h2></h2>
Tested on Windows, QGis minimum version tested 2.9.
</p>
<p>
Credits to: Ginaluca Silvestri
</p>