Extension:Proofread Page/Page viewer

Background
The ProofreadPage extension uses the popular OpenSeadragon (OSD) library to provide a zoomable image viewer in the Page namespace and the Pagelist editor. This provides various useful features:


 * A well-known and robust JS API for script and gadget extensibility
 * Zoom and panning that works on desktop and mobile
 * A well-maintained upstream codebase

OpenSeadragon replaced the previous home-made jQuery implementation in release 1.38.0-wmf.9.

Using the viewer
The main viewport controls are found on the top right of the image viewer:



From left to right:


 * [[File:OOjs UI icon crop.svg]] Select a region of the image for OCR (not merged yet)
 * [[File:OOjs UI icon guide-h.svg]] Add a moveable guide (not merged yet)
 * Zoom in, out and reset zoom to the full page
 * [[File:OOjs UI icon arched-arrow-rtl.svg]] [[File:OOjs UI icon arched-arrow-ltr.svg]] Rotate the image by 90 degrees left or right

Mouse navigation
Some of these features are not merged yet: 

You can scroll and zoom the image as follows:


 * Click and drag: pan the image
 * Scroll wheel : zoom the image in and out
 * Ctrl + scroll : pan the image up and down
 * Shift + scroll : pan the image side to side

The middle mouse button switches the normal and Ctrl-key modes (so Ctrl-scroll becomes zoom and normal scroll becomes pan). The cursor changes to identify which mode you are in.

Keyboard navigation
The default OpenSeadraon keyboard bindings are used:


 * w, up arrow — move viewport up
 * s, down arrow — move viewport down
 * a, left arrow — move viewport left
 * d, right arrow — move viewport right
 * 0 — zoom / move viewport home
 * - _, Shift + W , Shift + up arrow — zoom viewport out
 * =, + , Shift + S , Shift + down arrow — zoom viewport in
 * r — rotate clockwise
 * R — rotate counterclockwise

mw.hook
The following mw.hooks are fired:

mw.proofreadpage
The following objects are presented in the  global object:

mw.proofreadpage.viewer
The OpenSeadragon viewer object. Only valid after.

This can change, e.g. after the viewer is swapped from horizontal to vertical mode.

mw.proofreadpage.getPageViewportControls
Pending review: 

Returns a jQuery object that holds a  that contains controls for the viewer, which is placed in the WikiEditor toolbar. Scripts can add new controls to this area. Only valid after.

Use by scripts and gadgets
Scripts and gadgets can use the API for anything supported by the OpenSeadragon API via the  object.

Changing the image
The image can be changed by adding an image to the viewer.

For "simple" images (i.e. where you have just an image URL):

You can also directly add an IIIF tiled image source:

Adding buttons to the viewport control toolbar
These can be directly added to the element returned by :

Tools do not have to go in this toolbar to interact with the OpenSeadragon viewer; they can also go in the sidebar, the normal toolbar (for which the WikiEditor toolbar configuration system can be used) or anywhere else in the DOM.

Region selection
This is not merged yet

A region selection module is provided that allows scripts to add a simple rectangular region selection.

The region selection is communicated by OOUI events. Intantiate a region selector and bind handlers like this:

In this case  and   are handlers that you should provide.

Events:
 * emitted when a selection starts
 * emitted when a selection ends (the selection is cancelled somehow)
 * emitted when a selection starts
 * Parameter 1: the region, as an object of,  ,  ,  , all of which are in terms of the OpenSeadragon image size in pixels.

Methods on a :
 * if a selection is active now