Extend Rect class to support rotation.

src/rectangle.js

@@ -36,42 +36,63 @@
 
 /**
  * @class Rect
- * @classdesc A Rectangle really represents a 2x2 matrix where each row represents a
+ * @classdesc A Rectangle is described by it top left coordinates (x, y), width,
- * 2 dimensional vector component, the first is (x,y) and the second is
+ * height and degrees of rotation around (x, y).
- * (width, height).  The latter component implies the equation of a simple
+ * Note that the coordinate system used is the one commonly used with images:
- * plane.
+ * x increases when going to the right
+ * y increases when going to the bottom
+ * degrees increases clockwise with 0 being the horizontal
  *
  * @memberof OpenSeadragon
- * @param {Number} x The vector component 'x'.
+ * @param {Object} options
- * @param {Number} y The vector component 'y'.
+ * @param {Number} options.x X coordinate of the top left corner of the rectangle.
- * @param {Number} width The vector component 'height'.
+ * @param {Number} options.y Y coordinate of the top left corner of the rectangle.
- * @param {Number} height The vector component 'width'.
+ * @param {Number} options.width Width of the rectangle.
+ * @param {Number} options.height Height of the rectangle.
+ * @param {Number} options.degrees Rotation of the rectangle around (x,y) in degrees.
+ * @param {Number} [x] Deprecated: The vector component 'x'.
+ * @param {Number} [y] Deprecated: The vector component 'y'.
+ * @param {Number} [width] Deprecated: The vector component 'width'.
+ * @param {Number} [height] Deprecated: The vector component 'height'.
  */
-$.Rect = function( x, y, width, height ) {
+$.Rect = function(x, y, width, height) {
+
+    var options = x;
+    if (!$.isPlainObject(options)) {
+        options = {
+            x: x,
+            y: y,
+            width: width,
+            height: height
+        };
+    }
+
     /**
      * The vector component 'x'.
      * @member {Number} x
      * @memberof OpenSeadragon.Rect#
      */
-    this.x = typeof ( x ) == "number" ? x : 0;
+    this.x = typeof(options.x) === "number" ? options.x : 0;
     /**
      * The vector component 'y'.
      * @member {Number} y
      * @memberof OpenSeadragon.Rect#
      */
-    this.y = typeof ( y ) == "number" ? y : 0;
+    this.y = typeof(options.y) === "number" ? options.y : 0;
     /**
      * The vector component 'width'.
      * @member {Number} width
      * @memberof OpenSeadragon.Rect#
      */
-    this.width  = typeof ( width )  == "number" ? width : 0;
+    this.width  = typeof(options.width) === "number" ? options.width : 0;
     /**
      * The vector component 'height'.
      * @member {Number} height
      * @memberof OpenSeadragon.Rect#
      */
-    this.height = typeof ( height ) == "number" ? height : 0;
+    this.height = typeof(options.height) === "number" ? options.height : 0;
+
+    this.degrees = typeof(options.degrees) === "number" ? options.degrees : 0;
 };
 
 $.Rect.prototype = /** @lends OpenSeadragon.Rect.prototype */{
@@ -80,7 +101,13 @@ $.Rect.prototype = /** @lends OpenSeadragon.Rect.prototype */{
      * @returns {OpenSeadragon.Rect} a duplicate of this Rect
      */
     clone: function() {
-        return new $.Rect(this.x, this.y, this.width, this.height);
+        return new $.Rect({
+            x: this.x,
+            y: this.y,
+            width: this.width,
+            height: this.height,
+            degrees: this.degrees
+        });
     },
 
     /**
@@ -114,10 +141,8 @@ $.Rect.prototype = /** @lends OpenSeadragon.Rect.prototype */{
      *  the rectangle.
      */
     getBottomRight: function() {
-        return new $.Point(
+        return new $.Point(this.x + this.width, this.y + this.height)
-            this.x + this.width,
+            .rotate(this.degrees, this.getTopLeft());
-            this.y + this.height
-        );
     },
 
     /**
@@ -128,10 +153,8 @@ $.Rect.prototype = /** @lends OpenSeadragon.Rect.prototype */{
      *  the rectangle.
      */
     getTopRight: function() {
-        return new $.Point(
+        return new $.Point(this.x + this.width, this.y)
-            this.x + this.width,
+            .rotate(this.degrees, this.getTopLeft());
-            this.y
-        );
     },
 
     /**
@@ -142,10 +165,8 @@ $.Rect.prototype = /** @lends OpenSeadragon.Rect.prototype */{
      *  the rectangle.
      */
     getBottomLeft: function() {
-        return new $.Point(
+        return new $.Point(this.x, this.y + this.height)
-            this.x,
+            .rotate(this.degrees, this.getTopLeft());
-            this.y + this.height
-        );
     },
 
     /**
@@ -158,7 +179,7 @@ $.Rect.prototype = /** @lends OpenSeadragon.Rect.prototype */{
         return new $.Point(
             this.x + this.width / 2.0,
             this.y + this.height / 2.0
-        );
+        ).rotate(this.degrees, this.getTopLeft());
     },
 
     /**
@@ -177,28 +198,31 @@ $.Rect.prototype = /** @lends OpenSeadragon.Rect.prototype */{
      * @param {OpenSeadragon.Rect} rectangle The Rectangle to compare to.
      * @return {Boolean} 'true' if all components are equal, otherwise 'false'.
      */
-    equals: function( other ) {
+    equals: function(other) {
-        return ( other instanceof $.Rect ) &&
+        return (other instanceof $.Rect) &&
-            ( this.x === other.x ) &&
+            this.x === other.x &&
-            ( this.y === other.y ) &&
+            this.y === other.y &&
-            ( this.width === other.width ) &&
+            this.width === other.width &&
-            ( this.height === other.height );
+            this.height === other.height &&
+            this.degrees === other.degrees;
     },
 
     /**
-    * Multiply all dimensions in this Rect by a factor and return a new Rect.
+    * Multiply all dimensions (except degrees) in this Rect by a factor and
+    * return a new Rect.
     * @function
     * @param {Number} factor The factor to multiply vector components.
     * @returns {OpenSeadragon.Rect} A new rect representing the multiplication
     *  of the vector components by the factor
     */
-    times: function( factor ) {
+    times: function(factor) {
-        return new OpenSeadragon.Rect(
+        return new $.Rect({
-            this.x * factor,
+            x: this.x * factor,
-            this.y * factor,
+            y: this.y * factor,
-            this.width * factor,
+            width: this.width * factor,
-            this.height * factor
+            height: this.height * factor,
-        );
+            degrees: this.degrees
+        });
     },
 
     /**
@@ -207,13 +231,14 @@ $.Rect.prototype = /** @lends OpenSeadragon.Rect.prototype */{
     * @param {OpenSeadragon.Point} delta The translation vector.
     * @returns {OpenSeadragon.Rect} A new rect with altered position
     */
-    translate: function( delta ) {
+    translate: function(delta) {
-        return new OpenSeadragon.Rect(
+        return new $.Rect({
-            this.x + delta.x,
+            x: this.x + delta.x,
-            this.y + delta.y,
+            y: this.y + delta.y,
-            this.width,
+            width: this.width,
-            this.height
+            height: this.height,
-        );
+            degrees: this.degrees
+        });
     },
 
     /**
@@ -223,67 +248,79 @@ $.Rect.prototype = /** @lends OpenSeadragon.Rect.prototype */{
      */
     // ----------
     union: function(rect) {
+        if (this.degrees !== 0 || rect.degrees !== 0) {
+            throw new Error('Only union of non rotated rectangles are supported.');
+        }
         var left = Math.min(this.x, rect.x);
         var top = Math.min(this.y, rect.y);
         var right = Math.max(this.x + this.width, rect.x + rect.width);
         var bottom = Math.max(this.y + this.height, rect.y + rect.height);
 
-        return new OpenSeadragon.Rect(left, top, right - left, bottom - top);
+        return new $.Rect({
+            left: left,
+            top: top,
+            width: right - left,
+            height: bottom - top
+        });
     },
 
     /**
-     * Rotates a rectangle around a point. Currently only 90, 180, and 270
+     * Rotates a rectangle around a point.
-     * degrees are supported.
      * @function
      * @param {Number} degrees The angle in degrees to rotate.
      * @param {OpenSeadragon.Point} pivot The point about which to rotate.
      * Defaults to the center of the rectangle.
      * @return {OpenSeadragon.Rect}
      */
-    rotate: function( degrees, pivot ) {
+    rotate: function(degrees, pivot) {
-        // TODO support arbitrary rotation
+        degrees = (degrees + 360) % 360;
-        var width = this.width,
+        if (degrees === 0) {
-            height = this.height,
+            return this.clone();
-            newTopLeft;
-
-        degrees = ( degrees + 360 ) % 360;
-        if (degrees % 90 !== 0) {
-            throw new Error('Currently only 0, 90, 180, and 270 degrees are supported.');
-        }
-
-        if( degrees === 0 ){
-            return new $.Rect(
-                this.x,
-                this.y,
-                this.width,
-                this.height
-            );
         }
 
         pivot = pivot || this.getCenter();
+        var newTopLeft = this.getTopLeft().rotate(degrees, pivot);
+        var newTopRight = this.getTopRight().rotate(degrees, pivot);
 
-        switch ( degrees ) {
+        var diff = newTopRight.minus(newTopLeft);
-            case 90:
+        var radians = Math.atan(diff.y / diff.x);
-                newTopLeft = this.getBottomLeft();
+        if (diff.x < 0) {
-                width = this.height;
+            radians += Math.PI;
-                height = this.width;
+        } else if (diff.y < 0) {
-                break;
+            radians += 2 * Math.PI;
-            case 180:
-                newTopLeft = this.getBottomRight();
-                break;
-            case 270:
-                newTopLeft = this.getTopRight();
-                width = this.height;
-                height = this.width;
-                break;
-            default:
-                newTopLeft = this.getTopLeft();
-                break;
         }
+        return new $.Rect({
+            x: newTopLeft.x,
+            y: newTopLeft.y,
+            width: this.width,
+            height: this.height,
+            degrees: radians / Math.PI * 180
+        });
+    },
 
-        newTopLeft = newTopLeft.rotate(degrees, pivot);
+    /**
-
+     * Retrieves the smallest horizontal (degrees=0) rectangle which contains
-        return new $.Rect(newTopLeft.x, newTopLeft.y, width, height);
+     * this rectangle.
+     * @returns {OpenSeadrayon.Rect}
+     */
+    getBoundingBox: function() {
+        if (this.degrees === 0) {
+            return this.clone();
+        }
+        var topLeft = this.getTopLeft();
+        var topRight = this.getTopRight();
+        var bottomLeft = this.getBottomLeft();
+        var bottomRight = this.getBottomRight();
+        var minX = Math.min(topLeft.x, topRight.x, bottomLeft.x, bottomRight.x);
+        var maxX = Math.max(topLeft.x, topRight.x, bottomLeft.x, bottomRight.x);
+        var minY = Math.min(topLeft.y, topRight.y, bottomLeft.y, bottomRight.y);
+        var maxY = Math.max(topLeft.y, topRight.y, bottomLeft.y, bottomRight.y);
+        return new $.Rect({
+            x: minX,
+            y: minY,
+            width: maxX - minX,
+            height: maxY - minY
+        });
     },
 
     /**
@@ -294,10 +331,11 @@ $.Rect.prototype = /** @lends OpenSeadragon.Rect.prototype */{
      */
     toString: function() {
         return "[" +
-            (Math.round(this.x*100) / 100) + "," +
+            (Math.round(this.x * 100) / 100) + "," +
-            (Math.round(this.y*100) / 100) + "," +
+            (Math.round(this.y * 100) / 100) + "," +
-            (Math.round(this.width*100) / 100) + "x" +
+            (Math.round(this.width * 100) / 100) + "x" +
-            (Math.round(this.height*100) / 100) +
+            (Math.round(this.height * 100) / 100) + "," +
+            (Math.round(this.degrees * 100) / 100) + "°" +
             "]";
     }
 };

test/coverage.html

@@ -75,6 +75,7 @@
     <script src="/test/modules/tilesource.js"></script>
     <script src="/test/modules/tilesourcecollection.js"></script>
     <script src="/test/modules/spring.js"></script>
+    <script src="/test/modules/rectangle.js"></script>
     <!-- The navigator tests are the slowest (for now; hopefully they can be sped up)
     so we put them last. -->
     <script src="/test/modules/navigator.js"></script>

test/modules/rectangle.js

@@ -0,0 +1,260 @@
+/* global module, asyncTest, $, ok, equal, notEqual, start, test, Util, testLog */
+
+(function() {
+
+    module('Rectangle', {});
+
+    var precision = 0.000000001;
+
+    function assertPointsEquals(pointA, pointB, message) {
+        Util.assessNumericValue(pointA.x, pointB.x, precision, message + " x: ");
+        Util.assessNumericValue(pointA.y, pointB.y, precision, message + " y: ");
+    }
+
+    function assertRectangleEquals(rectA, rectB, message) {
+        Util.assessNumericValue(rectA.x, rectB.x, precision, message + " x: ");
+        Util.assessNumericValue(rectA.y, rectB.y, precision, message + " y: ");
+        Util.assessNumericValue(rectA.width, rectB.width, precision,
+                message + " width: ");
+        Util.assessNumericValue(rectA.height, rectB.height, precision,
+                message + " height: ");
+        Util.assessNumericValue(rectA.degrees, rectB.degrees, precision,
+                message + " degrees: ");
+    }
+
+    test('Legacy constructor', function() {
+        var rect = new OpenSeadragon.Rect(1, 2, 3, 4);
+        strictEqual(rect.x, 1, 'rect.x should be 1');
+        strictEqual(rect.y, 2, 'rect.y should be 2');
+        strictEqual(rect.width, 3, 'rect.width should be 3');
+        strictEqual(rect.height, 4, 'rect.height should be 4');
+        strictEqual(rect.degrees, 0, 'rect.degrees should be 0');
+    });
+
+    test('Constructor', function() {
+        var rect = new OpenSeadragon.Rect({
+            x: 1,
+            y: 2,
+            width: 3,
+            height: 4,
+            degrees: 5
+        });
+        strictEqual(rect.x, 1, 'rect.x should be 1');
+        strictEqual(rect.y, 2, 'rect.y should be 2');
+        strictEqual(rect.width, 3, 'rect.width should be 3');
+        strictEqual(rect.height, 4, 'rect.height should be 4');
+        strictEqual(rect.degrees, 5, 'rect.degrees should be 5');
+
+        rect = new OpenSeadragon.Rect({});
+        strictEqual(rect.x, 0, 'rect.x should be 0');
+        strictEqual(rect.y, 0, 'rect.y should be 0');
+        strictEqual(rect.width, 0, 'rect.width should be 0');
+        strictEqual(rect.height, 0, 'rect.height should be 0');
+        strictEqual(rect.degrees, 0, 'rect.degrees should be 0');
+    });
+
+    test('getTopLeft', function() {
+        var rect = new OpenSeadragon.Rect({
+            x: 1,
+            y: 2,
+            width: 3,
+            height: 4,
+            degrees: 5
+        });
+        var expected = new OpenSeadragon.Point(1, 2);
+        ok(expected.equals(rect.getTopLeft()), "Incorrect top left point.");
+    });
+
+    test('getTopRight', function() {
+        var rect = new OpenSeadragon.Rect({
+            x: 0,
+            y: 0,
+            width: 1,
+            height: 3
+        });
+        var expected = new OpenSeadragon.Point(1, 0);
+        ok(expected.equals(rect.getTopRight()), "Incorrect top right point.");
+
+        rect.degrees = 45;
+        expected = new OpenSeadragon.Point(1 / Math.sqrt(2), 1 / Math.sqrt(2));
+        assertPointsEquals(expected, rect.getTopRight(),
+                "Incorrect top right point with rotation.");
+    });
+
+    test('getBottomLeft', function() {
+        var rect = new OpenSeadragon.Rect({
+            x: 0,
+            y: 0,
+            width: 3,
+            height: 1
+        });
+        var expected = new OpenSeadragon.Point(0, 1);
+        ok(expected.equals(rect.getBottomLeft()), "Incorrect bottom left point.");
+
+        rect.degrees = 45;
+        expected = new OpenSeadragon.Point(-1 / Math.sqrt(2), 1 / Math.sqrt(2));
+        assertPointsEquals(expected, rect.getBottomLeft(),
+                "Incorrect bottom left point with rotation.");
+    });
+
+    test('getBottomRight', function() {
+        var rect = new OpenSeadragon.Rect({
+            x: 0,
+            y: 0,
+            width: 1,
+            height: 1
+        });
+        var expected = new OpenSeadragon.Point(1, 1);
+        ok(expected.equals(rect.getBottomRight()), "Incorrect bottom right point.");
+
+        rect.degrees = 45;
+        expected = new OpenSeadragon.Point(0, Math.sqrt(2));
+        assertPointsEquals(expected, rect.getBottomRight(),
+                "Incorrect bottom right point with 45 rotation.");
+
+        rect.degrees = 90;
+        expected = new OpenSeadragon.Point(-1, 1);
+        assertPointsEquals(expected, rect.getBottomRight(),
+                "Incorrect bottom right point with 90 rotation.");
+
+        rect.degrees = 135;
+        expected = new OpenSeadragon.Point(-Math.sqrt(2), 0);
+        assertPointsEquals(expected, rect.getBottomRight(),
+                "Incorrect bottom right point with 135 rotation.");
+    });
+
+    test('getCenter', function() {
+        var rect = new OpenSeadragon.Rect({
+            x: 0,
+            y: 0,
+            width: 1,
+            height: 1
+        });
+        var expected = new OpenSeadragon.Point(0.5, 0.5);
+        ok(expected.equals(rect.getCenter()), "Incorrect center point.");
+
+        rect.degrees = 45;
+        expected = new OpenSeadragon.Point(0, 0.5 * Math.sqrt(2));
+        assertPointsEquals(expected, rect.getCenter(),
+                "Incorrect bottom right point with 45 rotation.");
+
+        rect.degrees = 90;
+        expected = new OpenSeadragon.Point(-0.5, 0.5);
+        assertPointsEquals(expected, rect.getCenter(),
+                "Incorrect bottom right point with 90 rotation.");
+
+        rect.degrees = 135;
+        expected = new OpenSeadragon.Point(-0.5 * Math.sqrt(2), 0);
+        assertPointsEquals(expected, rect.getCenter(),
+                "Incorrect bottom right point with 135 rotation.");
+    });
+
+    test('rotate', function() {
+        var rect = new OpenSeadragon.Rect({
+            x: 0,
+            y: 0,
+            width: 2,
+            height: 1
+        });
+
+        // Rotate 45deg around center.
+        var expected = new OpenSeadragon.Rect({
+            x: 1 - 1 / (2 * Math.sqrt(2)),
+            y: 0.5 - 3 / (2 * Math.sqrt(2)),
+            width: 2,
+            height: 1,
+            degrees: 45
+        });
+        var actual = rect.rotate(45);
+        assertRectangleEquals(expected, actual,
+                "Incorrect rectangle after rotation of 45deg around center.");
+
+        expected = new OpenSeadragon.Rect({
+            x: 0,
+            y: 0,
+            width: 2,
+            height: 1,
+            degrees: 33
+        });
+        actual = rect.rotate(33, rect.getTopLeft());
+        assertRectangleEquals(expected, actual,
+                "Incorrect rectangle after rotation of 33deg around topLeft.");
+
+        expected = new OpenSeadragon.Rect({
+            x: 0,
+            y: 0,
+            width: 2,
+            height: 1,
+            degrees: 101
+        });
+        actual = rect.rotate(101, rect.getTopLeft());
+        assertRectangleEquals(expected, actual,
+                "Incorrect rectangle after rotation of 187deg around topLeft.");
+
+        expected = new OpenSeadragon.Rect({
+            x: 0,
+            y: 0,
+            width: 2,
+            height: 1,
+            degrees: 187
+        });
+        actual = rect.rotate(187, rect.getTopLeft());
+        assertRectangleEquals(expected, actual,
+                "Incorrect rectangle after rotation of 187deg around topLeft.");
+
+        expected = new OpenSeadragon.Rect({
+            x: 0,
+            y: 0,
+            width: 2,
+            height: 1,
+            degrees: 300
+        });
+        actual = rect.rotate(300, rect.getTopLeft());
+        assertRectangleEquals(expected, actual,
+                "Incorrect rectangle after rotation of 300deg around topLeft.");
+    });
+
+    test('getBoundingBox', function() {
+        var rect = new OpenSeadragon.Rect({
+            x: 0,
+            y: 0,
+            width: 2,
+            height: 3
+        });
+
+        var bb = rect.getBoundingBox();
+        ok(rect.equals(bb), "Bounding box of horizontal rectangle should be " +
+                "identical to rectangle.");
+
+        rect.degrees = 90;
+        var expected = new OpenSeadragon.Rect({
+            x: -3,
+            y: 0,
+            width: 3,
+            height: 2
+        });
+        assertRectangleEquals(expected, rect.getBoundingBox(),
+                "Bounding box of rect rotated 90deg.");
+
+        rect.degrees = 180;
+        var expected = new OpenSeadragon.Rect({
+            x: -2,
+            y: -3,
+            width: 2,
+            height: 3
+        });
+        assertRectangleEquals(expected, rect.getBoundingBox(),
+                "Bounding box of rect rotated 180deg.");
+
+        rect.degrees = 270;
+        var expected = new OpenSeadragon.Rect({
+            x: 0,
+            y: -2,
+            width: 3,
+            height: 2
+        });
+        assertRectangleEquals(expected, rect.getBoundingBox(),
+                "Bounding box of rect rotated 270deg.");
+    });
+
+})();

test/test.html

@@ -39,6 +39,7 @@
     <script src="/test/modules/tilesource.js"></script>
     <script src="/test/modules/tilesourcecollection.js"></script>
     <script src="/test/modules/spring.js"></script>
+    <script src="/test/modules/rectangle.js"></script>
     <!-- The navigator tests are the slowest (for now; hopefully they can be sped up)
     so we put them last. -->
     <script src="/test/modules/navigator.js"></script>