Merge pull request #505 from openseadragon/margins

Viewport margins

src/drawer.js

@@ -324,6 +324,9 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{
         }
     },
 
+    /**
+     * @private
+     */
     drawDebugInfo: function( tile, count, i ){
         if ( this.useCanvas ) {
             this.context.save();
@@ -396,6 +399,30 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{
         }
     },
 
+    /**
+     * @private
+     */
+    debugRect: function(rect) {
+        if ( this.useCanvas ) {
+            this.context.save();
+            this.context.lineWidth = 2;
+            this.context.strokeStyle = this.debugGridColor;
+            this.context.fillStyle = this.debugGridColor;
+
+            this.context.strokeRect(
+                rect.x,
+                rect.y,
+                rect.width,
+                rect.height
+            );
+
+            this.context.restore();
+        }
+    },
+
+    /**
+     * @private
+     */
     _offsetForRotation: function( tile, degrees ){
         var cx = this.canvas.width / 2,
             cy = this.canvas.height / 2,
@@ -410,6 +437,9 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{
         tile.position.y = py;
     },
 
+    /**
+     * @private
+     */
     _restoreRotationChanges: function( tile ){
         var cx = this.canvas.width / 2,
             cy = this.canvas.height / 2,

src/openseadragon.js

@@ -262,6 +262,10 @@
   *     achieved.  Setting this to 0 and wrapHorizontal ( or wrapVertical ) to
   *     true will provide the effect of an infinitely scrolling viewport.
   *
+  * @property {Object} [viewportMargins={}]
+  *     Pushes the "home" region in from the sides by the specified amounts.
+  *     Possible subproperties (Numbers, in screen coordinates): left, top, right, bottom.
+  *
   * @property {Number} [imageLoaderLimit=0]
   *     The maximum number of image requests to make concurrently.  By default
   *     it is set to 0 allowing the browser to make the maximum number of

src/tiledimage.js

@@ -178,8 +178,7 @@ function updateViewport( tiledImage ) {
         best            = null,
         haveDrawn       = false,
         currentTime     = $.now(),
-        viewportSize    = tiledImage.viewport.getContainerSize(),
+        viewportBounds  = tiledImage.viewport.getBoundsWithMargins( true ),
-        viewportBounds  = tiledImage.viewport.getBounds( true ),
         viewportTL      = viewportBounds.getTopLeft(),
         viewportBR      = viewportBounds.getBottomRight(),
         zeroRatioC      = tiledImage.viewport.deltaPixelsFromPoints(

src/viewer.js

@@ -1907,7 +1907,8 @@ function openTileSource( viewer, source, options ) {
             viewer:             _this,
             degrees:            _this.degrees,
             navigatorRotate:    _this.navigatorRotate,
-            homeFillsViewer:    _this.homeFillsViewer
+            homeFillsViewer:    _this.homeFillsViewer,
+            margins:            _this.viewportMargins
         });
     }
 

src/viewport.js

@@ -63,6 +63,15 @@ $.Viewport = function( options ) {
         delete options.config;
     }
 
+    this._margins = $.extend({
+        left: 0,
+        top: 0,
+        right: 0,
+        bottom: 0
+    }, options.margins || {});
+
+    delete options.margins;
+
     $.extend( true, this, {
 
         //required settings
@@ -89,6 +98,11 @@ $.Viewport = function( options ) {
 
     }, options );
 
+    this._containerInnerSize = new $.Point(
+        Math.max(1, this.containerSize.x - (this._margins.left + this._margins.right)),
+        Math.max(1, this.containerSize.y - (this._margins.top + this._margins.bottom))
+    );
+
     this.centerSpringX = new $.Spring({
         initial: 0,
         springStiffness: this.springStiffness,
@@ -257,7 +271,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
     getMaxZoom: function() {
         var zoom = this.maxZoomLevel;
         if (!zoom) {
-            zoom = this.contentSize.x * this.maxZoomPixelRatio / this.containerSize.x;
+            zoom = this.contentSize.x * this.maxZoomPixelRatio / this._containerInnerSize.x;
             zoom /= this.homeBounds.width;
         }
 
@@ -268,11 +282,12 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
      * @function
      */
     getAspectRatio: function() {
-        return this.containerSize.x / this.containerSize.y;
+        return this._containerInnerSize.x / this._containerInnerSize.y;
     },
 
     /**
      * @function
+     * @returns {OpenSeadragon.Point} The size of the container, in screen coordinates.
      */
     getContainerSize: function() {
         return new $.Point(
@@ -284,6 +299,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
     /**
      * @function
      * @param {Boolean} current - Pass true for the current location; defaults to false (target location).
+     * @returns {OpenSeadragon.Rect} The location you are zoomed/panned to, in world coordinates.
      */
     getBounds: function( current ) {
         var center = this.getCenter( current ),
@@ -298,6 +314,22 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
         );
     },
 
+    /**
+     * @function
+     * @param {Boolean} current - Pass true for the current location; defaults to false (target location).
+     * @returns {OpenSeadragon.Rect} The location you are zoomed/panned to,
+     * including the space taken by margins, in world coordinates.
+     */
+    getBoundsWithMargins: function( current ) {
+        var bounds = this.getBounds(current);
+        var factor = this._containerInnerSize.x * this.getZoom(current);
+        bounds.x -= this._margins.left / factor;
+        bounds.y -= this._margins.top / factor;
+        bounds.width += (this._margins.left + this._margins.right) / factor;
+        bounds.height += (this._margins.top + this._margins.bottom) / factor;
+        return bounds;
+    },
+
     /**
      * @function
      * @param {Boolean} current - Pass true for the current location; defaults to false (target location).
@@ -338,13 +370,9 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
             height
         );
 
-        newZoomPixel    = this.zoomPoint.minus(
+        newZoomPixel = this._pixelFromPoint(this.zoomPoint, bounds);
-            bounds.getTopLeft()
-        ).times(
-            this.containerSize.x / bounds.width
-        );
         deltaZoomPixels = newZoomPixel.minus( oldZoomPixel );
-        deltaZoomPoints = deltaZoomPixels.divide( this.containerSize.x * zoom );
+        deltaZoomPoints = deltaZoomPixels.divide( this._containerInnerSize.x * zoom );
 
         return centerTarget.plus( deltaZoomPoints );
     },
@@ -550,14 +578,14 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
         }
 
         referencePoint = oldBounds.getTopLeft().times(
-            this.containerSize.x / oldBounds.width
+            this._containerInnerSize.x / oldBounds.width
         ).minus(
             newBounds.getTopLeft().times(
-                this.containerSize.x / newBounds.width
+                this._containerInnerSize.x / newBounds.width
             )
         ).divide(
-            this.containerSize.x / oldBounds.width -
+            this._containerInnerSize.x / oldBounds.width -
-            this.containerSize.x / newBounds.width
+            this._containerInnerSize.x / newBounds.width
         );
 
         return this.zoomTo( newZoom, referencePoint, immediately );
@@ -800,12 +828,16 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
             newBounds = oldBounds,
             widthDeltaFactor;
 
-        this.containerSize = new $.Point(
+        this.containerSize.x = newContainerSize.x;
-            newContainerSize.x,
+        this.containerSize.y = newContainerSize.y;
-            newContainerSize.y
+
+        this._containerInnerSize = new $.Point(
+            Math.max(1, newContainerSize.x - (this._margins.left + this._margins.right)),
+            Math.max(1, newContainerSize.y - (this._margins.top + this._margins.bottom))
         );
 
         if ( maintain ) {
+            // TODO: widthDeltaFactor will always be 1; probably not what's intended
             widthDeltaFactor = newContainerSize.x / this.containerSize.x;
             newBounds.width  = oldBounds.width * widthDeltaFactor;
             newBounds.height = newBounds.width / this.getAspectRatio();
@@ -877,7 +909,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
      */
     deltaPixelsFromPoints: function( deltaPoints, current ) {
         return deltaPoints.times(
-            this.containerSize.x * this.getZoom( current )
+            this._containerInnerSize.x * this.getZoom( current )
         );
     },
 
@@ -888,7 +920,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
      */
     deltaPointsFromPixels: function( deltaPixels, current ) {
         return deltaPixels.divide(
-            this.containerSize.x * this.getZoom( current )
+            this._containerInnerSize.x * this.getZoom( current )
         );
     },
 
@@ -898,11 +930,19 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
      * @param {Boolean} current - Pass true for the current location; defaults to false (target location).
      */
     pixelFromPoint: function( point, current ) {
-        var bounds = this.getBounds( current );
+        return this._pixelFromPoint(point, this.getBounds( current ));
+    },
+
+    /**
+     * @private
+     */
+    _pixelFromPoint: function( point, bounds ) {
         return point.minus(
             bounds.getTopLeft()
         ).times(
-            this.containerSize.x / bounds.width
+            this._containerInnerSize.x / bounds.width
+        ).plus(
+            new $.Point(this._margins.left, this._margins.top)
         );
     },
 
@@ -913,8 +953,10 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
      */
     pointFromPixel: function( pixel, current ) {
         var bounds = this.getBounds( current );
-        return pixel.divide(
+        return pixel.minus(
-            this.containerSize.x / bounds.width
+            new $.Point(this._margins.left, this._margins.top)
+        ).divide(
+            this._containerInnerSize.x / bounds.width
         ).plus(
             bounds.getTopLeft()
         );
@@ -1129,7 +1171,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
      */
     viewportToImageZoom: function( viewportZoom ) {
         var imageWidth = this.viewer.source.dimensions.x;
-        var containerWidth = this.getContainerSize().x;
+        var containerWidth = this._containerInnerSize.x;
         var viewportToImageZoomRatio = containerWidth / imageWidth;
         return viewportZoom * viewportToImageZoomRatio;
     },
@@ -1147,7 +1189,7 @@ $.Viewport.prototype = /** @lends OpenSeadragon.Viewport.prototype */{
      */
     imageToViewportZoom: function( imageZoom ) {
         var imageWidth = this.viewer.source.dimensions.x;
-        var containerWidth = this.getContainerSize().x;
+        var containerWidth = this._containerInnerSize.x;
         var viewportToImageZoomRatio = imageWidth / containerWidth;
         return imageZoom * viewportToImageZoomRatio;
     }

test/demo/collections/main.js

@@ -6,15 +6,52 @@
         init: function() {
             var self = this;
 
-            this.viewer = OpenSeadragon( {
+            var config = {
                 debugMode: true,
                 zoomPerScroll: 1.02,
                 showNavigator: true,
                 id: "contentDiv",
                 prefixUrl: "../../../build/openseadragon/images/"
+            };
+
+            var testMargins = false;
+
+            var margins;
+
+            if (testMargins) {
+                margins = {
+                    top: 250,
+                    left: 250,
+                    right: 250,
+                    bottom: 250
+                };
+
+                config.viewportMargins = margins;
+            }
+
+            this.viewer = OpenSeadragon(config);
+
+            if (testMargins) {
+                this.viewer.addHandler('animation', function() {
+                    var box = new OpenSeadragon.Rect(margins.left, margins.top,
+                        $('#contentDiv').width() - (margins.left + margins.right),
+                        $('#contentDiv').height() - (margins.top + margins.bottom));
+
+                    self.viewer.drawer.debugRect(box);
+                });
+            }
+
+            this.basicTest();
+        },
+
+        // ----------
+        basicTest: function() {
+            var self = this;
+
+            this.viewer.addHandler('open', function() {
             });
 
-            this.crossTest();
+            this.viewer.open("../../data/testpattern.dzi");
         },
 
         // ----------
@@ -96,6 +133,40 @@
                 y: -2,
                 width: 6
             });
+        },
+
+        // ----------
+        cjTest: function() {
+            var imageKey = "e-pluribus-unum";
+            var imageXML = '<?xml version="1.0" encoding="UTF-8"?><Image TileSize="254" Overlap="1" Format="png" xmlns="http://schemas.microsoft.com/deepzoom/2008"><Size Width="88560" Height="88560"/></Image>';
+            var $xml = $($.parseXML(imageXML));
+            var $image = $xml.find('Image');
+            var $size = $xml.find('Size');
+
+            var dzi = {
+                Image: {
+                    xmlns: $image.attr('xmlns'),
+                    Url: "http://chrisjordan.com/dzi/" + imageKey + '_files/',
+                    Format: $image.attr('Format'),
+                    Overlap: $image.attr('Overlap'),
+                    TileSize: $image.attr('TileSize'),
+                    Size: {
+                        Height: $size.attr('Height'),
+                        Width: $size.attr('Width')
+                    }
+                }
+            };
+
+            this.viewer.open(dzi, {
+                width: 100
+            });
+        },
+
+        // ----------
+        stanfordTest: function() {
+            var info = {"@context":"http://library.stanford.edu/iiif/image-api/1.1/context.json","@id":"http://ids.lib.harvard.edu/ids/iiif/48530377","width":6251,"height":109517,"scale_factors":[1,2,4,8,16,32],"tile_width":256,"tile_height":256,"formats":["jpg"],"qualities":["native"],"profile":"http://library.stanford.edu/iiif/image-api/1.1/compliance.html#level1"};
+
+            this.viewer.open(info);
         }
     };