README.html

<h1>CadInput</h1>

<p>CadInput is a <strong>PROTOTYPE</strong> QGIS Python plugin that allows to numerically constrain the cursor to achieve efficient and precise digitizing, as possible in CAD packages, with any QGIS tool.</p>

<p>A demo of an older version is available here : https://vimeo.com/85052231</p>

<p>It currently relies on too many hacks and may therefore be unstable. <strong>DO NOT USE THIS IN PRODUCTION !!!</strong></p>

<h2>How to use</h2>

<h3>Editfields</h3>

<p>Validating an editfield with Return will lock the value.
Setting a value to an empty string will unlock the value.</p>

<p>You can enter basic math operations in the editfields.</p>

<h3>Shortcuts</h3>

<p>Shortcuts are accessible if the MapCanvas or the CadInputWidget have focus :</p>

<ul>
<li><em>A</em> : angle</li>
<li><em>D</em> : distance</li>
<li><em>X</em> : x coordinate</li>
<li><em>Y</em> : y coordinate</li>
<li>Combine those with "shift" to toggle absolute/relative mode</li>
<li>Combine those with "alt" or "ctrl" to toggle locked mode.</li>
<li><em>C</em> : construction mode</li>
<li><em>P</em> : parralel / perpendicular to a segment</li>
<li><em>ESC</em> : unlock all locked parameters</li>
</ul>

<h2>Known issues</h2>

<ul>
<li>A CRS Prompt will appear at first use of the tool if "use default CRS for new layers" is not set in the options.</li>
<li>Changed snap settings will only have effect upon rescale or adding layers (will be solved with issue http://hub.qgis.org/issues/9465 )</li>
<li>The first point when activating is based upon the 0,0 point rather than last click (will be fixed when there's a CanvasClicked signal)</li>
<li>...</li>
</ul>

<h2>Feedback / Bugs / Contribute</h2>

<p>Please report bugs and ideas on the issue tracker : https://github.com/olivierdalang/CadInput/issues</p>

<p>Or send me some feedback at : olivier.dalang@gmail.com</p>

<h2>Roadmap</h2>

<h3>Features done</h3>

<ul>
<li>[x] available with all the QGIS map tools (probably)</li>
<li>[x] digitize using relative/absolute XY coordinates</li>
<li>[x] digitize using relative/absolute angular coordinates</li>
<li>[x] parralel/perpendicular from existing features</li>
<li>[x] extend/trim a line using segment's snapping</li>
<li>[x] mathematical input</li>
</ul>

<h3>Features planned</h3>

<ul>
<li>[ ] incremental values lock (for instance 30deg, or 10m grid)</li>
<li>[ ] set origin (for absolute mode with custom origin)</li>
<li>[ ] intersection of segments / having segments as a true constraint (not only for parralel/perpendicular)</li>
<li>[ ] intersection of arcs / having arcs as a true constraint (not only for parralel/perpendicular)</li>
<li>[ ] allow to use when not editing (useful to measures elements or angles)</li>
<li>[ ] input relative to north / other units</li>
</ul>

<h3>Features ideas</h3>

<p>Please submit your ideas on the tracker : https://github.com/olivierdalang/CadInput/issues</p>

<ul>
<li>[ ] one-click extend/trim a line (not directly linked to CadInput -> CadTools ?)</li>
<li>[ ] midpoints (can be achieved using D/2)</li>
</ul>

<h2>Version history</h2>

<ul>
<li>2014-01-29 - version 0.3 : intial experimental release</li>
<li>2014-01-31 - version 0.4 : 
<ul>
<li>improved performances on more complex files (thanks 3nids)</li>
<li>snapping preferences now taken into account)</li>
</ul></li>
<li>2014-02-09 - version 0.50 : better visuel feedback, several bugs fix and cleaner code</li>
<li>2014-03-22 - version 0.60 : several bug fixes</li>
</ul>

<h2>Technical notes</h2>

<p>The plugin relies on several hacks to work, since (afaik) the current QGIS API :
- does not allow to hook into MapCanvas mouse events
- does not allow numerical input for tools in scene coordinates
- does not allow to restrict background snapping on Vertexes or Segments only
- does not allow free drawing on the mapcanvas</p>

<h3>MapCanvas mouseEvents hack (improved since plugin's v0.2)</h3>

<p>To be able to capture the mouseEvents of the MapCanvas, the plugin installs an eventFilter on it.</p>

<h3>Tools numeric input hack</h3>

<p>Capturing and editing the mouseEvents is fine for graphical feedback, but does not allow for precise input (since mouseEvents are in pixels, and not in map units).
To workaround this limitation, the plugin creates a memory layer, in which a point is created each time a precise coordinate input is needed, to which the native tools will snap. Unfortunately, to snap to this layer only without possible interference from other regular layers snapping, the plugin must iterate through all layers and remove (temporarily) their snapping.</p>

<h3>Free drawing on QgsMapCanvas</h3>

<p>To be able to freely draw on the MapCanvas, the plugin adds a QWidget as child of the mapCanvas.
A drawback is that there is a "double cursor", the native QGIS cursor, and a CadInput-specific cursor, inducing a little bit of confusion.</p>

<h3>What API improvements would avoid the need of those hacks ?</h3>

<ul>
<li><strong>A. Have QgsMapCanvas emit signals on mouseEvents (not sure if usable for the plugin)</strong></li>
</ul>

<p>In current version, QgsMapCanvas emits xyCoordinates(const QgsPoint &amp;p) on mouseMoveEvent. The same could be done for mousePressEvent and mouseReleaseEvent (maybe with better names?).
I'm not sure this would be usable for the plugin though, since it needs to be able to modify those events too.</p>

<ul>
<li><strong>B. Allow to input scene coordinats to QgsMapTool (long term)</strong></li>
</ul>

<p>For instance by adding </p>

<pre><code>void QgsMapTool::scenePressEvent( QMouseEvent *e, QgsPoint *p ) // and the same for move and release events
</code></pre>

<p>Or by adding an optional <code>scenePos *pos=0</code> parameter to the existing <code>void QgsMapTool::canvasPressEvent( QMouseEvent *e )</code>
This could anyways be very useful for different uses (automation ?).</p>

<p>The problem is, it seems the snapping/coordinate translation is implemented by each Tool subclass... So it will be some work which would require anyway a more general MapTools refactoring !</p>

<ul>
<li><strong>C. Allow to snap to a specific layer (useless if F is done)</strong></li>
</ul>

<p>Add a QgsMapCanvasSnapper's snapToSpecificLayer method (exactly the same as snapToActiveLayer except it's not the active layer)</p>

<pre><code>int snapToSpecificLayers( const QPoint&amp; p, QList&lt;QgsSnappingResult&gt;&amp; results, QgsVectorLayer layer, QgsSnapper::SnappingType snap_to, double snappingTol = -1, const QList&lt;QgsPoint&gt;&amp; excludePoints = QList&lt;QgsPoint&gt;() );
</code></pre>

<ul>
<li><strong>D. Allow to restrict snapping for background layers, just as there is for the active layer (useless if F is done)</strong></li>
</ul>

<p>Modify QgsMapCanvasSnapper's snapToBackgroundLayers method to work like snapToCurrentLayer.</p>

<pre><code>int snapToBackgroundLayers( const QPoint&amp; p, QList&lt;QgsSnappingResult&gt;&amp; results, const QList&lt;QgsPoint&gt;&amp; excludePoints = QList&lt;QgsPoint&gt;() );
</code></pre>

<p>would become </p>

<pre><code>int snapToBackgroundLayers( const QPoint&amp; p, QList&lt;QgsSnappingResult&gt;&amp; results, QgsSnapper::SnappingType snap_to, double snappingTol = -1, const QList&lt;QgsPoint&gt;&amp; excludePoints = QList&lt;QgsPoint&gt;() );
</code></pre>

<p>Alternatively, QgsSnappingResult could have a field informing wheter it was a vertex or a segment snap.</p>

<h3>What other QGIS improvement woud make the plugin work better</h3>

<ul>
<li><strong>E. Click-drag tools should allow click-move-click input method</strong></li>
</ul>

<p>Some tools work in click-click mode (add feature...), but some other in click-drag mode (move vertex, ...). That second method is less common in CAD softwares, since it is less practical. Those click-drag tools work currently with the plugin, but the user must keep the mouse pressed, which is a bit annoying. Allowing click-move-click mode for those tool as well would be an improvement.</p>

<ul>
<li><em>*F. Improve snap priority *</em></li>
</ul>

<p>See http://hub.qgis.org/issues/7058</p>