Merge pull request #627 from openseadragon/m2

Clip feature

changelog.txt

@@ -36,6 +36,7 @@ OPENSEADRAGON CHANGELOG
     * New Viewport method for managing homeBounds as well as constraints: setHomeBounds
     * Viewport.open supports positioning config properties
     * For multi-image open, drawing isn't started until all tileSources have been opened
+    * You can specify a clip area for each image (only works on browsers that support the HTML5 canvas) (#594)
 * Margins option to push the home region in from the edges of the Viewer (#505)
 * Rect and Point toString() functions are now consistent: rounding values to nearest hundredth
 * Overlays appear in the DOM immediately on open or addOverlay (#507)

src/drawer.js

@@ -258,6 +258,35 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{
         }
     },
 
+    // private
+    saveContext: function() {
+        if (!this.useCanvas) {
+            return;
+        }
+
+        this.context.save();
+    },
+
+    // private
+    restoreContext: function() {
+        if (!this.useCanvas) {
+            return;
+        }
+
+        this.context.restore();
+    },
+
+    // private
+    setClip: function(rect) {
+        if (!this.useCanvas) {
+            return;
+        }
+
+        this.context.beginPath();
+        this.context.rect(rect.x, rect.y, rect.width, rect.height);
+        this.context.clip();
+    },
+
     // private
     drawDebugInfo: function( tile, count, i ){
         if ( this.useCanvas ) {

src/tiledimage.js

@@ -52,6 +52,9 @@
  * @param {Number} [options.y=0] - Top position, in viewport coordinates.
  * @param {Number} [options.width=1] - Width, in viewport coordinates.
  * @param {Number} [options.height] - Height, in viewport coordinates.
+ * @param {OpenSeadragon.Rect} [options.clip] - An area, in image pixels, to clip to
+ * (portions of the image outside of this area will not be visible). Only works on
+ * browsers that support the HTML5 canvas.
  * @param {Number} [options.springStiffness] - See {@link OpenSeadragon.Options}.
  * @param {Boolean} [options.animationTime] - See {@link OpenSeadragon.Options}.
  * @param {Number} [options.minZoomImageRatio] - See {@link OpenSeadragon.Options}.
@@ -72,6 +75,8 @@ $.TiledImage = function( options ) {
     $.console.assert( options.viewer, "[TiledImage] options.viewer is required" );
     $.console.assert( options.imageLoader, "[TiledImage] options.imageLoader is required" );
     $.console.assert( options.source, "[TiledImage] options.source is required" );
+    $.console.assert(!options.clip || options.clip instanceof $.Rect,
+        "[TiledImage] options.clip must be an OpenSeadragon.Rect if present");
 
     $.EventSource.call( this );
 
@@ -84,6 +89,12 @@ $.TiledImage = function( options ) {
     this._imageLoader = options.imageLoader;
     delete options.imageLoader;
 
+    if (options.clip instanceof $.Rect) {
+        this._clip = options.clip.clone();
+    }
+
+    delete options.clip;
+
     var x = options.x || 0;
     delete options.x;
     var y = options.y || 0;
@@ -443,6 +454,36 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag
         this._setScale(height / this.normHeight, immediately);
     },
 
+    /**
+     * @returns {OpenSeadragon.Rect|null} The TiledImage's current clip rectangle,
+     * in image pixels, or null if none.
+     */
+    getClip: function() {
+        if (this._clip) {
+            return this._clip.clone();
+        }
+
+        return null;
+    },
+
+    /**
+     * @param {OpenSeadragon.Rect|null} newClip - An area, in image pixels, to clip to
+     * (portions of the image outside of this area will not be visible). Only works on
+     * browsers that support the HTML5 canvas.
+     */
+    setClip: function(newClip) {
+        $.console.assert(!newClip || newClip instanceof $.Rect,
+            "[TiledImage.setClip] newClip must be an OpenSeadragon.Rect or null");
+
+        if (newClip instanceof $.Rect) {
+            this._clip = newClip.clone();
+        } else {
+            this._clip = null;
+        }
+
+        this._needsDraw = true;
+    },
+
     // private
     _setScale: function(scale, immediately) {
         var sameTarget = (this._scaleSpring.target.value === scale);
@@ -1116,6 +1157,20 @@ function drawTiles( tiledImage, lastDrawn ){
         position,
         tileSource;
 
+    var usedClip = false;
+    if (tiledImage._clip) {
+        tiledImage._drawer.saveContext();
+        var box = tiledImage.imageToViewportRectangle(tiledImage._clip, true);
+        var topLeft = tiledImage.viewport.pixelFromPoint(box.getTopLeft(), true);
+        var size = tiledImage.viewport.deltaPixelsFromPoints(box.getSize(), true);
+        box = new OpenSeadragon.Rect(topLeft.x * $.pixelDensityRatio,
+            topLeft.y * $.pixelDensityRatio,
+            size.x * $.pixelDensityRatio,
+            size.y * $.pixelDensityRatio);
+        tiledImage._drawer.setClip(box);
+        usedClip = true;
+    }
+
     for ( i = lastDrawn.length - 1; i >= 0; i-- ) {
         tile = lastDrawn[ i ];
         tiledImage._drawer.drawTile( tile, tiledImage._drawingHandler );
@@ -1147,6 +1202,10 @@ function drawTiles( tiledImage, lastDrawn ){
             });
         }
     }
+
+    if (usedClip) {
+        tiledImage._drawer.restoreContext();
+    }
 }
 
 }( OpenSeadragon ));

src/viewer.js

@@ -1195,6 +1195,9 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
      * @param {Number} [options.y=0] The Y position for the image in viewport coordinates.
      * @param {Number} [options.width=1] The width for the image in viewport coordinates.
      * @param {Number} [options.height] The height for the image in viewport coordinates.
+     * @param {OpenSeadragon.Rect} [options.clip] - An area, in image pixels, to clip to
+     * (portions of the image outside of this area will not be visible). Only works on
+     * browsers that support the HTML5 canvas.
      * @param {Function} [options.success] A function that gets called when the image is
      * successfully added. It's passed the event object which contains a single property:
      * "item", the resulting TiledImage.
@@ -1280,6 +1283,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype,
                     y: queueItem.options.y,
                     width: queueItem.options.width,
                     height: queueItem.options.height,
+                    clip: queueItem.options.clip,
                     springStiffness: _this.springStiffness,
                     animationTime: _this.animationTime,
                     minZoomImageRatio: _this.minZoomImageRatio,

test/demo/m2/index.html

@@ -7,7 +7,7 @@
         <script src="//d3js.org/d3.v3.min.js" charset="utf-8"></script>
         <script src="js/main.js"></script>
         <script src="js/page.js"></script>
-        <script src="js/harvard-tilesources.js"></script>
+        <!-- <script src="js/harvard-tilesources.js"></script> -->
         <script src="js/openseadragon-svg-overlay.js"></script>
         <style type="text/css">
 

test/demo/m2/js/main.js

@@ -22,7 +22,10 @@
             this.pages = this.createPages();
 
             var tileSources = $.map(this.pages, function(v, i) {
-                return v.starter.tileSource;
+                return {
+                    tileSource: v.starter.tileSource,
+                    clip: v.starter.clip
+                };
             });
 
             this.viewer = OpenSeadragon({
@@ -543,11 +546,11 @@
                 }
             }
 
+            this.panBounds = null;
+
             box = new OpenSeadragon.Rect(x, y, width, height);
             this.viewer.viewport.fitBounds(box, config.immediately);
 
-            this.panBounds = null;
-
             var setPanBounds = function() {
                 if (self.mode === 'page' || self.mode === 'book') {
                     self.panBounds = box;
@@ -818,6 +821,16 @@
                 ]
             }));
 
+            pages.push(new this.Page({
+                tileSource: highsmith,
+                clip: {
+                    x: 1000,
+                    y: 1000,
+                    width: 5026,
+                    height: 7221
+                }
+            }));
+
             var inputs = [
                 highsmith,
                 duomo,

test/demo/m2/js/page.js

@@ -19,6 +19,11 @@
             tileSource: config.tileSource
         };
 
+        if (config.clip) {
+            this.starter.clip = new OpenSeadragon.Rect(config.clip.x, config.clip.y,
+                config.clip.width, config.clip.height);
+        }
+
         this.main = {};
 
         this.alternateIndex = -1;
@@ -56,6 +61,7 @@
             App.viewer.world.removeItem(this.main.tiledImage);
             App.viewer.addTiledImage({
                 tileSource: itemInfo.tileSource,
+                clip: itemInfo.clip,
                 index: this.pageIndex,
                 success: function(event) {
                     self.setDetail(self.main, itemInfo, event.item);
@@ -81,6 +87,7 @@
 
                 App.viewer.addTiledImage({
                     tileSource: v.tileSource,
+                    clip: v.clip,
                     success: function(event) {
                         v.tiledImage = event.item;
                         self.placeDetail(v, true);

test/modules/tiledimage.js

@@ -191,4 +191,33 @@
         viewer.open('/test/data/testpattern.dzi');
     });
 
+    // ----------
+    asyncTest('clip', function() {
+        var clip = new OpenSeadragon.Rect(100, 100, 800, 800);
+
+        viewer.addHandler('open', function() {
+            var image = viewer.world.getItemAt(0);
+            propEqual(image.getClip(), clip, 'image has correct clip');
+
+            image.setClip(null);
+            equal(image.getClip(), null, 'clip is cleared');
+
+            image.setClip(clip);
+            propEqual(image.getClip(), clip, 'clip is set correctly');
+
+            Util.spyOnce(viewer.drawer, 'setClip', function(rect) {
+                ok(true, 'drawer.setClip is called');
+                var pixelRatio = viewer.viewport.getContainerSize().x / image.getContentSize().x;
+                var canvasClip = clip.times(pixelRatio * OpenSeadragon.pixelDensityRatio);
+                propEqual(rect, canvasClip, 'clipping to correct rect');
+                start();
+            });
+        });
+
+        viewer.open({
+            tileSource: '/test/data/testpattern.dzi',
+            clip: clip
+        });
+    });
+
 })();