Help:ImageAnnotator

ImageAnnotator is a JavaScript extension of the MediaWiki user interface, allowing users to place comments onto images shown on file description pages, similar to the "photo notes" on Flickr. This works on all image files for which the MediaWiki software displays a preview image on the file description page, i.e., PNG, JPG, GIF, and SVG files.

Trying it out
If you want to make test edits using this feature but don't want to do so on live pages, you can create here a personal "sandbox" page in your user space where you can play around as you like. Just click the button below, and then save the page you're being taken to.

How to add informative notes
The ultimate goal of the tool is to improve information content of the image description. Annotation can add information that can't be included in descriptions easily. If used correctly annotation can be a great help, but other uses might just add to the clutter. Viewing individual annotations takes more effort on the user part than reading description, so lets make sure users that go into the trouble are rewarded and not disappointed.

In general, images that can benefit most from annotations are busy images like: group portraits, panoramas, aerial photographs, satellite images, maps and diagrams. The type of images that likely will not be improved by notes are simple images lacking enough detail to need notes. For example: flags, coats of arms, computer icons, single person portraits, etc. Of course one can find many exceptions from this general rule. Text of the note should be relevant to the region of the image outlined by it's box and as with other descriptions, "neutrality of description should be aimed at wherever possible" (see NPOV). Use of links to categories, and articles is encouraged.

Examples of informative notes:
 * 1) identification of people in group photographs or paintings. Examples: 1, 2, 3, 4
 * 2) identification of places/objects/locations in panoramic/aerial photographs. Examples: 1, 2, 3, 4
 * 3) highlighting important hard to notice details of the image. Examples: 1, 2
 * 4) identify the various elements of a composition. Examples: 1, 2
 * 5) zoom into more detailed images or show another angle of view. Example: 1
 * 6) transcribing inscriptions, signs, or words in the image. Examples: 1, 2. If the entire image is a sign or an inscription, this should be done in the information template only.

Examples of inappropriate and not-informative notes: Note: adding clearly inappropriate notes to images is considered vandalism and, if repeated, will get the user adding these notes blocked.
 * 1) talking ("I like this", "This photo is underexposed", "Hot!", "Lousy reproduction", etc.), or in general making comments about the image instead of neutrally describing features in the image. Use the file discussion page for commenting about the image (there is a "discussion" link at the top of every file description page).
 * 2) notes containing derogatory comments of any kind, or containing any text that is not neutral. Such notes are considered vandalism.
 * 3) notes too small to see easily. Bear in mind that you might be looking at a scaled-down version of an image though.
 * 4) notes covering most of the image with text relevant to the whole image. For example single person portraits. Such explanations are better written on the file page, typically in the "description" section of the information table. Edit the file page directly (click on the "edit" link at the top of the page), locate a line starting with "description=", and add your text after that.
 * 5) notes with information plainly visible in the image, like: ear (on a portrait), car (on a street scene), head (on a full shot).
 * 6) notes on animated files where note is correctly placed only in a single frame. This type of notes are more likely to be confusing and should be used with caution.

Another consideration is a choice of language:
 * If possible notes should be brief and language independent, like people/place names
 * Otherwise notes should use
 * language templates, like en or fr, to show all language versions on a single note, or the
 * language switch mechanism, see LangSwitch, to show user's preferred language


 * Links should be to articles and categories in the language most related to the image.
 * If links lead to Wikipedia, language templates (e.g. wikipedia:) should be used.

User interface
On image description pages, the script adds a button "Add an annotation" below the preview image. If the image already has annotations, it also shows a message indicating such. The button is only present if Ajax is enabled.

Display of image annotations
An annotation is shown on the preview image as a yellow rectangle. The note is supposed to explain some feature in the image at the location of that rectangle. These yellow rectangles are only shown if the user moves the mouse cursor over the preview image, otherwise they're hidden.

If the yellow rectangles are visible, the note text will appear in a small popup when the user moves the mouse cursor over such a rectangle. This popup is hidden again when the mouse leaves area of the rectangle combined with the area of the popup. While the popup is visible, its rectangle will be highlighted.

Adding a new annotation
When the "Add an annotation" button is clicked, the script enters definition mode. The preview image gets a green border, and the rectangles of all existing notes are shown. The user can now draw a new rectangle (shown in red) onto the preview image by clicking within the image, dragging the mouse cursor, and then releasing the mouse cursor. If the resulting rectangle has non-zero width and height, the note editor will pop up. When the note text is saved from that editor, a new note will be placed onto the preview image.

If the full image is much larger than the preview image, the script provides a floating zoom to make it easier to position the new rectangle. By default, this zoom is activated when the full image size is eight times larger than the preview, but this can be configured by the user to his or her liking. The zoomed image is initially just the preview image scaled up by the browser, but the script loads an image at the correct zoomed size from the server in the background, and once that truly zoomed image has arrived, it replaces the browser's upscaled image.

Editing a note
If Ajax is enabled, notes can be edited. The note editor appears in a popup in the vicinity of the note's yellow rectangle, and is pre-filled with the current text of the note (or empty, if the user is editing a newly defined note). It fully supports a preview function, just like the standard edit pages. Clearing the text and saving will delete an existing note (or cancel the definition of a new note). The "Revert" button will discard all changes made by the user and fill the editor again with the current text of the note. The "Cancel" button will close the editor without applying the changes. Clicking the "Save" button will edit the current page in the background and add the note text plus the coordinates of its rectangle to the page.

Deleting a note
An existing note can be deleted in two ways: The first method prompts the user whether the note shall be really deleted to catch mis-clicks.
 * by clicking the "Delete" link in the note's popup, or
 * by editing it, clearing the text, and then saving.

User rights
The ability to edit, add, or delete notes is available only on pages the user is actually allowed to edit. On protected pages, non-admin users can only view existing notes. On files stored non-locally, only viewing of notes is possible.

Local annotations
Normally, the gadget is used on file description pages. On such pages, it is activated automatically.

Sometimes, one might use image notes for an image on other pages, though. An example is nominations for featured pictures, where notes that are local to the nomination, but that are not shown on the file description pages, could be used to point out problems in an image.

This is possible through the use of template ImageWithNotes. Any file link that actually displays an image that is wrapped with a substitution of that template also activates the gadget. Notes added for such images are stored on the page that includes the substitution of the ImageWithNotes template, not on the file description page.

If a page contains more than one substitution of ImageWithNotes, either directly or though transclusions, as on , the gadget only allows viewing notes. Editing notes is possible only on the page that directly contains the template substitution. A nomination page that uses this feature is .

This mechanism is also used on the personal image note sandbox pages.

User configurations
Users can customize some few aspects of ImageAnnotator.

Setting the edit box width
By default, ImageAnnotator uses a textbox for modifying notes that is 50 characters wide. Although notes may contain arbitrary WikiText, they should typically be rather short. The somewhat small edit box helps avoid that people write whole sermons in a note. If you often create notes containing long links, though, you might want a slightly larger box. In that case you can define the text box width by adding the following line to your monobook.js or other skin-specific JS file (such as vector.js for the Vector skin):



This specifies the width of the textbox in characters. If the value set is not a number or outside the range of 30 to 100, the gadget reverts to its default behavior and uses a box 50 characters wide.

Note that on some browsers, notably Firefox, the textbox may be slightly wider than specified. Firefox, for instance, always adds space for a potential vertical scrollbar up front, even when it doesn't show a scrollbar yet. As a result, an empty textbox with 50 columns may on Firefox actually provide an input area that is 52 characters wide, until a vertical scrollbar appears.

Setting the zoom activation
When the full image is much larger than the preview image, the script activates a floating zoom to make positioning new rectangles easier. How much larger the full image needs to be than the preview image to activate this zoom is governed by the zoom threshold. By default, this threshold s set to 8.0: the zoom is activated only if the full image is eight times larger than the preview. This threshold ratio can be changed, though:



Setting the threshold to very high values will in practice disable zooming for most images. Setting it to zero enables the zoom on all images where the full image is at least twice the size of the preview. (In other words, the lower bound of ImageAnnotator_zoom_threshold is 2.0 in practice.)

Whatever the setting of this variable, zooming is enabled automatically for users who have set a very small preview size in their preferences (smaller than 600 pixels wide), and for images that are more than twice as wide as high, but only if the full image is at least twice the size of the preview image.

User interface texts
ImageAnnotator uses a small number of texts in its user interface. If Ajax is enabled, the script loads localized strings for these interface messages.

These interface texts can be defined on-wiki in pages in the protected MediaWiki namespace, just like the standard interface texts of MediaWiki. The script uses the following interface texts:

To localize these texts, just place the translations in subpages of these pages. The French texts, for instance, reside at "/fr" subpages:

If there is no translation for a particular text, the script falls back to the English texts.

The help button is a bit special. MediaWiki:ImageAnnotatorHelp can be one of the following: The third possibility is actually only useful if you really specify more than one image to create an animated button, or if you are running on an older MediaWiki installation that doesn't support the "link=" parameter for images. Otherwise, you can achieve the same effect (a clickable image linked to some page) by just defining MediaWiki:ImageAnnotatorHelp as e.g.
 * A simple link, e.g.  Get help . This will insert the link as is.
 * A span containing some simple text, followed by a link. This will insert a button with the text from the span, linking to the page given in the link.
 * A sequence of one to three images, followed by a link. This will insert the image, linked to the page given in the link. If more than one image are given, the second is displayed when the mouse hovers over the resulting help button, and the third is displayed on a mouse click.

The button labels are supposed to be simple texts. Those for the "Edit"/"Delete" links and for the "Preview", "Revert", and "Cancel" buttons are optional; if they're not defined, already existing MediaWiki messages that provide sensible default texts are used. Those for the "Save" and "Add a note" button do not have this fallback mechanism because there are no suitable pre-defined MediaWiki messages that could be used.


 * Getting the localizations through Ajax means that there will be one additional request to the servers for each and every image description page visited with ImageAnnotator active. If this ever becomes a problem, one can either switch off localizations, or make the developers implement an image page footer system message that could be used to transport the interface strings on the page itself when it loads, like it was done for the upload form. However, thanks to caching in the browser and also in the Squids on the server side, this additional request should not be problematic. The only drawback is that localizations for MediaWiki:ImageAnnotatorHasNotesMsg are ignored if Ajax is switched off. On the other hand, the Ajax mechanism works without server-side changes.

Here at the Familypedia, the script adds small "translate"-links at various places in the interface if there are no interface texts in the user's language. Clicking such a link opens the page MediaWiki talk:ImageAnnotatorTexts for editing in preview mode; users can enter their translations and save them there so an administrator can later verify them and move them to the correct messages in the protected MediaWiki namespace.

Browser compatibility
ImageAnnotator has been tested and is known to work on the following browsers:

The script has also been tested with RTL ("right-to-left") languages, here at the Familypedia using "uselang=he" (Hebrew) and also locally at the Arabic Wikipedia. Both tests were run using Firefox 3.0.11 and IE6.

Like for many other scripts at WikiMedia projects, a DOM Level 2 compatible browser is a prerequisite. Ajax is used to get localized interface texts, to save or delete notes, and for the preview feature of the note editor.

If JavaScript is disabled, the script will of course not do anything. If JavaScript is enabled but Ajax is disabled, the script still displays existing notes on the image, but the user cannot modify or delete them, and it's also not possible to add new notes.

Although modifying notes (automatically editing the image description page) works without the MediaWiki API, the API is used for previews and for getting localized interface texts. On wikis where the API is disabled, the script may not work at all, or fail to show previews and localized interface texts. (The public WMF wikis, including the Wikipedias and the Commons, have the API enabled.) The script does not use the write API. Enabling the read API is sufficient.

Installing ImageAnnotator on another Wiki
Image notes are only visible when the ImageAnnotator gadget is installed and activated (either by default for all users, or the viewing user has the gadget enabled). This means that notes added here at Familypedia are not visible at other Wikis unless the gadget is installed there, too.

To install the gadget on another Wiki, follow these steps. From Wikimedia Commons
 * 1) Copy the following files from the Commons onto your own Wiki:
 * 2) *MediaWiki:Gadget-ImageAnnotator.js
 * 3) *MediaWiki:LAPI.js
 * 4) *MediaWiki:TextCleaner.js
 * 5) *MediaWiki:Tooltips.js
 * 6) *MediaWiki:UIElements.js
 * 7) *MediaWiki:AjaxSubmit.js
 * 8) *MediaWiki:Gadget-DisableImageAnnotator.js
 * 9) Set up MediaWiki:Gadget-DisableImageAnnotator.js as a gadget on your Wiki: copy MediaWiki:Gadget-DisableImageAnnotator to your Wiki and add the line "DisableImageAnnotator|DisableImageAnnotator.js" to MediaWiki:Gadgets-definition on your Wiki.
 * 10) To set it up ImageAnnotator as a gadget, write a description of it at MediaWiki:Gadget-ImageAnnotator on your Wiki, and add the line "ImageAnnotator|ImageAnnotator.js" to MediaWiki:Gadgets-definition (also on your Wiki).
 * 11) To enable the gadget for everyone, you may skip step 3 and instead add the line "if (wgNamespaceNumber != -1) importScript ('MediaWiki:Gadget-ImageAnnotator.js');" to MediaWiki:Common.js on your Wiki. (Or take a look at our MediaWiki:Common.js to see how we do this and copy that code over to your Wiki.)
 * 12) Copy the templates Template:ImageNote, Template:ImageNoteEnd, and Template:ImageWithNotes to your Wiki and protect them.
 * 13) Copy the templates MediaWiki:ImageAnnotatorTexts and MediaWiki:ImageAnnotatorUITexts to your Wiki.
 * 14) Modify MediaWiki:ImageAnnotatorTexts to adapt it to your Wiki's default language. Replace the string lang="en" (one occurrence) as appropriate; e.g. at the Arabic Wikipedia, use lang="ar"</tt>.
 * 15) If you want, also create user interface texts in your language in the MediaWiki-messages noted above. The messages in the default language of the Wiki always go into the pages without suffix. For other languages, use suffixes. On the Arabic Wikipedia, for instance, you'd put Arabic text at MediaWiki:ImageAnnotatorEditorLabel and the English text at MediaWiki:ImageAnnotatorEditorLabel/en.

The gadget will work for files uploaded locally on your Wiki exactly as it does for files here at Familypedia. For non-local files (files hosted here at Familypedia, but viewed on your Wiki), the script will enable viewing of the notes (if there are any), but will not allow modifying them. Modification of notes is possible only if the user views the file at the Wiki where the file actually resides.

Note: the above instructions assume that you want to install the gadget on another WMF project. If you are using a MediaWiki installation that does not serve wikibits.js, you are on your own. You will have to modify the scripts to use whatever environment your Wiki provides (in particular script loading and getElementsByClassName</tt>).

Limitations

 * If an image that has annotations is overwritten by a new version, existing annotations are only displayed if the size of the full version of the top image matches the size of the full image on which the notes were defined. To recover annotations, one will need to edit the image description page manually, adjusting image sizes and rectangle coordinates, or re-enter annotations.


 * Editing and deleting notes only works on modern browsers if the XHTML of the edit page is valid. Normally, this should not be a problem, but during alpha testing, people were updating MediaWiki:Copyrightwarning, and sometimes that message generated invalid XHTML (improper nesting of tags, or spurious unclosed tags). When that happened, edits failed to save automatically.


 * Internet Explorer (all versions) is a bit sluggish in displaying the note popups showing a note's contents. This is related to my using the IE-specific mouseenter/mouseleave events on IE (on other browsers, mouseover/mouseout are used). This is not a problem in the ImageAnnotator script but more a problem in MediaWiki:Tooltips.js, which is used by the ImageAnnotator. A fix is in the works, but any event-related changes need extra careful testing, so don't hold your breath for this to be fixed.

Frequently asked questions

 * 1) Can't image notes be put on a subpage of the image page?
 * No, they cannot. This was considered as an option when this feature was developed, but the idea was given up because
 * edits to notes wouldn't show up on watchlists unless people also watched these subpages (currently, editing notes generate edits to the image description page itself, so they show up on watchlists if the image is watched);
 * it would be technically much harder to detect edit conflicts and keep things in synch between the notes displayed and the notes stored;
 * the script would need to load the subpage just to display the notes, and we'd like to keep the number of calls to the server at a minimum; and
 * it would be harder to keep things in synch if and when image moves are (re-)enabled.
 * 1) Can we have note regions with other shapes than rectangles?
 * No. JavaScript does not offer convenient drawing primitives. Rectangles are easy because HTML elements are all rectangular boxes, but anything else is either not possible at all in JavaScript or only with considerable difficulty using the &lt;canvas> element of HTML5, but HTML5 is not supported by older browsers, and our pages are "XHTML 1.0 transitional" anyway. Internet Explorer (all versions including IE8!) does not support &lt;canvas> out-of-the-box, though there are special extensions for it.
 * 1) Can we run ImageAnnotator script in Wikipedias in order to see annotations there?
 * Not yet. The tool is still in testing stage. Also a new version is being developed which will allow viewing notes on images directly in the articles. Afterwards the tool will be deployed and tested on a single Wikipedia before it is ready for release on other projects.
 * 1) Where can I test this feature?
 * On your personal image note sandbox page.

Problems?
Despite having been tested on a wide array of browsers, it is not impossible that this script has still errors or that it doesn't work as it should on some browsers. If you have any problems with this script, report them at MediaWiki talk:Gadget-ImageAnnotator.js.

When reporting an error, always include the following information:
 * Which browser are you using? What version?
 * Which other gadgets have you enabled?
 * Which skin are you using (Monobook, Modern, Vector, other...)?
 * What's your user interface language setting?
 * What exactly did you do?
 * If the error occurred when you were trying to save a note: were there any error messages in the editor's window?
 * Were there any error messages displayed at the top of the page?
 * If you have a modern browser that does have an "error console" of some sort: were there any errors reported there?

For the last three points: we of course also need to know what these messages said exactly.

Emergency switch-off
If you encounter severe problems, you can switch off ImageAnnotator completetly by logging in and then enabling in Special:Preferences&rarr;Gadgets the disable image annotations gadget. If you do so, you won't be able to see any image notes anymore. In fact, the script will not be loaded at all.

If you feel the need to do this, please also make sure that you do report your problem at MediaWiki talk:Gadget-ImageAnnotator.js, so that we have a chance of fixing it. We cannot fix problems that we don't even know about!