Document all tools, and SelectedParallelWay.
authorSteve Bennett <stevagewp@gmail.com>
Fri, 24 Dec 2010 02:25:06 +0000 (02:25 +0000)
committerSteve Bennett <stevagewp@gmail.com>
Fri, 24 Dec 2010 02:25:06 +0000 (02:25 +0000)
net/systemeD/potlatch2/controller/SelectedParallelWay.as
net/systemeD/potlatch2/tools/Circularise.as
net/systemeD/potlatch2/tools/Parallelise.as
net/systemeD/potlatch2/tools/Quadrilateralise.as
net/systemeD/potlatch2/tools/Simplify.as
net/systemeD/potlatch2/tools/Straighten.as

index a8161f3..cd30446 100644 (file)
@@ -6,12 +6,15 @@ package net.systemeD.potlatch2.controller {
        import net.systemeD.potlatch2.tools.Parallelise;
        import net.systemeD.halcyon.Globals;
 
+    /** The state midway during the use of the "parallelise tool", where a parallel way has been created but is stuck to the 
+    * mouse cursor, allowing the user to choose how far from the original way it should go. This transforms it in the process. */
     public class SelectedParallelWay extends SelectedWay {
                private var startlon:Number;
                private var startlatp:Number;
                private var parallelise:Parallelise;
                private var originalWay:Way;
 
+        /** Initialises by parallelising the originalWay. */
         public function SelectedParallelWay(originalWay:Way) {
                        this.originalWay = originalWay;
                        parallelise = new Parallelise(originalWay);
@@ -29,6 +32,7 @@ package net.systemeD.potlatch2.controller {
                        return this;
         }
 
+               /** Cancel parallel way creation if ESC pressed. */
                override public function processKeyboardEvent(event:KeyboardEvent):ControllerState {
                        if (event.keyCode==27) {                        // Escape
                                Way(firstSelected).remove(MainUndoStack.getGlobalStack().addAction);
@@ -70,6 +74,7 @@ package net.systemeD.potlatch2.controller {
                        return furthdist*furthsgn;
                }
 
+               /** Creates the WayUI for the parallel way. */
                override public function enterState():void {
                        selection=[parallelise.parallelWay];
                        controller.map.paint.createWayUI(firstSelected as Way);
@@ -77,6 +82,7 @@ package net.systemeD.potlatch2.controller {
                        startlatp=controller.map.coord2latp(controller.map.mouseY);
                        Globals.vars.root.addDebug("**** -> "+this);
         }
+               /** Unselects. */
                override public function exitState(newState:ControllerState):void {
             clearSelection(newState);
                        Globals.vars.root.addDebug("**** <- "+this);
index 958a57c..9f52f65 100644 (file)
@@ -5,8 +5,14 @@ package net.systemeD.potlatch2.tools {
        import net.systemeD.halcyon.connection.Node;
        import net.systemeD.halcyon.connection.MainUndoStack;
 
+       /** Tool to transform a closed way of at least 3 distinct points into a circular shape, inserting more nodes as necessary. Call only the static function circularise(). */
        public class Circularise {
 
+               /** Carries out the circularisation of a way.
+                * @param way The way to be made round: must be closed, must have at least 3 distinct points.
+                * @param map The map that the way belongs to.
+                * @param performAction A function that will be passed a CompositeUndoableAction representing the transformation. In other words, a function that will push the result onto an undo stack.
+                * */ 
                public static function circularise(way:Way,map:Map,performAction:Function):void {
                        if (way.length<4) { return; }
 
index af0585f..ed49b96 100644 (file)
@@ -2,6 +2,10 @@ package net.systemeD.potlatch2.tools {
 
     import net.systemeD.halcyon.connection.*;
 
+         /** Tool to create a parallel copy of an existing way. First call the constructor Parallelise() passing it the 
+         * way that will be parallelised. This performs some initialisation. Then call draw(), passing it an offset,
+         * as many times as you like. Each time it recomputes the parallel way. There is no finalisation. 
+         * <p>This is intended to work with the SelectedParallelWay controller state.</p>*/
        public class Parallelise {
                private var originalWay:Way;
                public var parallelWay:Way;
@@ -11,6 +15,9 @@ package net.systemeD.potlatch2.tools {
                private var df:Array=[];
                private var nodes:Object={};
                
+               /** Initialises parallelisation process, adding an entry to global undo stack.
+                * @param way The way to be duplicated. 
+                * */
                public function Parallelise(way:Way) {
                        var a:Number, b:Number, h:Number, i:uint, j:uint, k:int;
                        connection  = Connection.getConnection();
@@ -44,6 +51,8 @@ package net.systemeD.potlatch2.tools {
 
                }
 
+               /** Compute the shape of the parallel way, implicitly causing it to be drawn if onscreen. Closed ways are ok. 
+                * @param offset How far, in lon/latp units, should the parallel way be. Can be negative. */
                public function draw(offset:Number):void {
                        var x:Number, y:Number;
                        var undo:CompositeUndoableAction = new CompositeUndoableAction("Draw parallel way");
@@ -81,6 +90,7 @@ package net.systemeD.potlatch2.tools {
                        undo.doAction();                // don't actually add it to the undo stack, just do it!
                }
                
+               /** Compute determinant. */
                private function det(a:Number,b:Number,c:Number,d:Number):Number { return a*d-b*c; }
 
        }
index f87b0ce..3ddeb22 100644 (file)
@@ -4,6 +4,7 @@ package net.systemeD.potlatch2.tools {
   import flash.geom.Point;
   import net.systemeD.halcyon.connection.*;
 
+  /** Tool to transform a closed way by making corners right-angled, if possible. Call the static function quadrilateralise(). */
   public class Quadrilateralise {
     private static const NUM_STEPS:uint = 1000;
     private static const TOLERANCE:Number = 1.0e-8;
@@ -12,26 +13,28 @@ package net.systemeD.potlatch2.tools {
      * Attempts to make all corners of a way right angles. Returns true if it
      * thought it was successful and false if it failed. If it fails it does not
      * modify the way.
+     * @param way Way to be transformed.
+     * @performAction Function that will be passed a CompositeUndoableAction parameter representing the transformation.
      */
     public static function quadrilateralise(way:Way,performAction:Function):Boolean {
       // needs a closed way to work properly.
       if (!way.isArea()) {
-       return false;
+        return false;
       }
 
       var functor:Quadrilateralise = new Quadrilateralise(way,performAction);
       var score:Number = functor.goodness;
       for (var i:uint = 0; i < NUM_STEPS; ++i) {
-       functor.step();
-       var newScore:Number = functor.goodness;
-       if (newScore > score) {
-         trace("Quadrilateralise blew up! " + newScore + " > " + score);
-         return false;
-       }
-       score = newScore;
-       if (score < TOLERANCE) {
-         break;
-       }
+        functor.step();
+        var newScore:Number = functor.goodness;
+        if (newScore > score) {
+          trace("Quadrilateralise blew up! " + newScore + " > " + score);
+          return false;
+           }
+        score = newScore;
+        if (score < TOLERANCE) {
+        break;
+        }
       }
 
       functor.updateWay();
@@ -42,7 +45,7 @@ package net.systemeD.potlatch2.tools {
     private var points:Array;
     private var performAction:Function;
     
-    // i wanted this to be private, but AS3 doesn't allow that. so please don't use it outside this package!
+    /** Private function that had to be declared public - do not call from outside this package. */
     public function Quadrilateralise(way_:Way, performAction_:Function) {
       way = way_;
       performAction = performAction_;
index 386f9e1..3732e25 100644 (file)
@@ -5,10 +5,17 @@ package net.systemeD.potlatch2.tools {
        import net.systemeD.halcyon.connection.Node;
        import net.systemeD.halcyon.connection.MainUndoStack;
 
+       /** Tool to reduce the number of nodes in a way by filtering out the "least important" ones, using the Douglas-Peucker algorithm. */
        public class Simplify {
 
                private static const TOLERANCE:Number=0.00005;
 
+               /** Carries out simplification on a way, adding an entry to global undo stack.
+                * @param way Way to be simplified.
+                * @param map Map it belongs to, for computing offscreen-ness.
+                * @param keepOffscreen If true, don't delete any nodes that are not currently visible. 
+                * */ 
+                 
                public static function simplify(way:Way, map:Map, keepOffscreen:Boolean):void {
                        if (way.length<3) { return; }
 
index ea798ea..a5a6f8a 100644 (file)
@@ -5,14 +5,21 @@ package net.systemeD.potlatch2.tools {
        import net.systemeD.halcyon.connection.Node;
        import net.systemeD.halcyon.connection.MainUndoStack;
 
+       /** Tool to transform a non-closed way into a straight line, by deleting any non-junction, untagged, on-screen nodes, and 
+        * moving the others to fit. Call only the static function <code>straighten()</code>*/
        public class Straighten {
 
+               /** Carries out the straightening.
+                * @param way Way to be straightened.
+                * @param map Map that it belongs to.
+                * @performAction Function that will be passed a CompositeUndoableAction parameter representing the transformation.
+                * */
                public static function straighten(way:Way,map:Map,performAction:Function):void {
                        if (way.length<3) { return; }
 
                        var a:Node=way.getNode(0);
                        var b:Node=way.getNode(way.length-1);
-                       if (a==b) { return; }
+                       if (way.isArea()) { return; }
                        
                        // ** could potentially do the 'too bendy?' check here as per Potlatch 1