Extension:Proofread Page/Afficheur de page

This page is a translated version of the page Extension:Proofread Page/Page viewer and the translation is 15% complete.

This page documents the latest version of the ProofreadPage extension. Some features may not be deployed yet.

Contexte

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.

Utiliser l'afficheur

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

From left to right:

Select a region of the image for OCR (not merged yet)
Add a moveable guide (not merged yet)
Zoom in, out and reset zoom to the full page
Rotate the image by 90 degrees left or right

Navigation à la souris

Some of these features are not merged yet:

Gerrit change 740369

You can scroll and zoom the image as follows:

Left 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
Left click: zoom in one step
Shift+Left click: zoom out one step

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.

Navigation au clavier

The default OpenSeadragon 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

Lignes de marquage

Not merged yet

The button can be used to add a moveable guide.

Click the button to add a guide to the image.
Drag a guide to move it
Double-click a guide to delete it

Guides will persist when you reload the page, so they can be used to help keep your place while previewing your changes.

Options de l'afficheur

There are some options for the page viewer in your preferences, in the Editing tab, under the Proofreading interface options heading.

Animation speed: This makes the panning and zoom feel smoother. The default is '0', which means there is zero lag and the zoom "snaps" from one level to the next. The OSD default used on many third-party image viewers is 1.2.
Zoom step of the viewer: This adjusts how "fast" the viewer zooms in and out. The default is 1.2. If you find the zoom too aggressive, you could try to lower it to, say, 1.1.

API JavaScript

Accroches MediaWiki

Version de MediaWiki :

≥ 1.40-wmf.12

Gerrit change 852322

The following mw.hooks are fired:

Hook	Description	Arguments
`ext.proofreadpage.osd-controller-availiable`	Fired when the OpenSeadragon controller has been initialized.	Argument 1: `osdController` the OpenSeadragon controller object (also available as `mw.proofreadpage.openseadragon`)
`ext.proofreadpage.osd-no-image-found`	Fired when the OpenSeadragon controller fails to initialized, can be used to show error messages.	No arguments

mw.proofreadpage

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

mw.proofreadpage.openseadragon

Version de MediaWiki :

≥ 1.40-wmf.12

Gerrit change 852322

This is a wrapper around the OpenSeadragon API. This object emits two events:

Event	Description	Arguments
`prp-osd-before-creation`	Fired just before the OpenSeadragon is initialized	Argument 1: `osdParams` the OpenSeadragon parameters object. This contains the configuration that will be sent to OpenSeadragon and can be modified by userscripts to customize how OpenSeadragon looks/feels. A list of all potential values can be found in the OpenSeadragon documentation.
`prp-osd-after-creation`	Fired when the OpenSeadragon viewer has initialized and the images loaded userscripts can use this event to hook into and listen for OpenSeadragon specific 'events', such as panning/zooming actions etc.	Argument 1: `viewer` the OpenSeadragon viewer object (also availiable as `mw.proofreadpage.openseadragon.viewer`)

mw.proofreadpage.openseadragon.viewer

Version de MediaWiki :

≥ 1.40-wmf.12

Gerrit change 852322

The OpenSeadragon viewer object. Only valid after prp-osd-after-creation.

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

mw.proofreadpage.openseadragon.forceInitialize()

Version de MediaWiki :

≥ 1.40-wmf.12

Gerrit change 852322

This will force OpenSeadragon to initialize, causing all the events to be fired and the hooks to be run.

For a userscript making changes to OpenSeadragon, this allows changes to be applied immediately.

For example:

function initialize( openseadragon ) {
    
    openseadragon.on( 'prp-osd-before-creation', function ( osdParams ) {
        // Make your changes here, for example, here we set the `showNavigator` parameter to true
        osdParams['showNavigator'] = true;
    } );

    openseadragon.on( 'prp-osd-after-creation', function ( viewer ) {
        // Do something
        // ....
        // ....
    } );
   
    // Force Openseadragon to update with the changes
    openseadragon.forceInitialize();
}

mw.proofreadpage.openseadragon.getCurrentImage()

Version de MediaWiki :

≥ 1.40-wmf.12

Gerrit change 859160

Get a URL to the current image being displayed on the OpenSeadragon canvas.

This function might error out if called before prp-osd-after-creation is fired.

mw.proofreadpage.getPageViewportControls()

Pending review: Gerrit change 736203

Returns a jQuery object that holds a <div> that contains controls for the viewer, which is placed in the WikiEditor toolbar. Scripts can add new controls to this area. Only valid after ext.proofreadpage.osd-viewer-ready.

Paramètres de configuration

The following mw.config variables are added to Page namespace pages. These can be used by gadgets and user scripts.

Variable	Content	Type	Example
`prpFormattedPageNumber`	The formatted page number (usually what's actually written on the page)	string	`"20"`
`prpImageFullSize`	The URL of the full-size page image (the largest image of the current page)	string	`"//upload.wikimedia.org/wikipedia/commons/thumb/a/a8/My_mortal_enemy_-_1926.djvu/page20-3893px-My_mortal_enemy_-_1926.djvu.jpg"`
`prpImageThumbnail`	The URL of the thumbnail page image (the size used in the page viewer)	string	`"//upload.wikimedia.org/wikipedia/commons/thumb/a/a8/My_mortal_enemy_-_1926.djvu/page20-1024px-My_mortal_enemy_-_1926.djvu.jpg"`
`prpIndexFields`	The values of any index fields in the index data config object marked `js: true`	object	`{ Progress: "C", Transclusion: "no", Footer: "\n", … }`
`prpIndexTitle`	The name of the associated index page	string	`"Index:My mortal enemy - 1926.djvu"`
`prpPageQuality`	The current quality level of the page (0-4, 1 if the page doesn't exist yet)	integer	`1`
`prpPageQualityUser`	The name of the last user to set the quality	string	`"SomeUser"`

Ressources pour OpenSeadragon

Utilisation par les scripts et les gadgets

Scripts and gadgets can use the API for anything supported by the OpenSeadragon API via the mw.proofreadpage.openseadragon.viewer object.

Modifier l'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):

mw.proofreadpage.openseadragon.on( 'prp-osd-before-creation', function ( osdParams ) {
    osdParams['tileSources'] = [{url: 'image_url_here'}];
} );
mw.proofreadpage.openseadragon.forceInitialize();

You can also directly add an IIIF tiled image source:

mw.proofreadpage.openseadragon.on( 'prp-osd-before-creation', function ( osdParams ) {
    osdParams['tileSources'] = iiif_json_source;
} );
mw.proofreadpage.openseadragon.forceInitialize();

Ajouter des boutons dans la barre d'outils controlant l'affichage

These can be directly added to the element returned by mw.proofreadpage.getPageViewportControls():

var button = new OO.ui.ButtonWidget( {
	icon: 'home', // choose an icon
	framed: false,
	classes: [ 'tool' ]
} );

mw.proofreadpage.getPageViewportControls().append( button );

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.

Sélectionner une région

This is not merged yet Gerrit change 741125

A region selection module (ext.proofreadpage.page.regionselection) is provided that allows scripts to add a simple rectangular region selection.

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

mw.loader.using( 'ext.proofreadpage.page.regionselection', function( require ) {
    var RegionSelection = require( 'ext.proofreadpage.page.regionselection' );
    var regionSelector = new RegionSelection();
    mw.hook( 'ext.proofreadpage.osd-viewer-ready' ).add( function ( viewer ) {
        regionSelector.register( viewer );
        
        regionSelector.connect( this, {
            [ regionSelector.events.selectionStart ]: [ 'onRegionToggle', true ],
            [ regionSelector.events.selectionEnd ]: [ 'onRegionToggle', false ]
	    } );
    } );
    
    // start a selection
    regionSelector.toggleSelection( true );
} );

In this case onRegionToggle is a handler that you should provide.

Events:

selectionStart emitted when a selection starts
selectionEnd emitted when a selection ends (the selection is cancelled somehow)

Methods on a RegionSelector:

isActive() if a selection is active now
getSelection() get the selection rectangle in a co-ordinate system from 0 to 1

Voir aussi

OpenSeadragon API reference: https://openseadragon.github.io/docs/