Docs for clip feature, as well as get and set

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

@@ -282,6 +282,7 @@ $.Drawer.prototype = /** @lends OpenSeadragon.Drawer.prototype */{
             return;
         }
 
+        this.context.beginPath();
         this.context.rect(rect.x, rect.y, rect.width, rect.height);
         this.context.clip();
     },

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}.
@@ -86,7 +89,10 @@ $.TiledImage = function( options ) {
     this._imageLoader = options.imageLoader;
     delete options.imageLoader;
 
-    this._clip = options.clip;
+    if (options.clip instanceof $.Rect) {
+        this._clip = options.clip.clone();
+    }
+
     delete options.clip;
 
     var x = options.x || 0;
@@ -448,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);

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.