Jump to content

Extension:Layers

From mediawiki.org
MediaWiki extensions manual
Layers
Release status: stable
Implementation Media, Parser function , Special page , Page action , API
Description A professional-grade, non-destructive image annotation system with 17 drawing tools, 1,385 built-in shapes (ISO 7010, IEC 60417, ISO 7000, GHS, ECB, ANSI), Slide Mode for standalone graphics, curved arrows, live preview, layer folders, style presets, named layer sets, and full keyboard accessibility.
Author(s) Paul Vodrazka
Latest version 1.5.75 (2026-05-25)
MediaWiki >= 1.44.0
PHP >= 8.1
Database changes Yes
Tables
Parameters
  • $wgLayersEnable
  • $wgLayersDebug
  • $wgLayersMaxBytes
  • $wgLayersMaxImageBytes
  • $wgLayersMaxLayerCount
  • $wgLayersMaxNamedSets
  • $wgLayersMaxRevisionsPerSet
  • $wgLayersDefaultSetName
  • $wgLayersUseBinaryOverlays
  • $wgLayersDefaultFonts
  • $wgLayersMaxImageSize
  • $wgLayersThumbnailCache
  • $wgLayersImageMagickTimeout
  • $wgLayersMaxImageDimensions
  • $wgLayersSlidesEnable
  • $wgLayersSlideDefaultWidth
  • $wgLayersSlideDefaultHeight
  • $wgLayersSlideMaxWidth
  • $wgLayersSlideMaxHeight
  • $wgLayersSlideDefaultBackground
Tags
  • ‎<annotation>
  • ‎<canvas>
  • ‎<drawing>
  • ‎<image editor>
  • ‎<image markup>
  • ‎<non-destructive>
Added rights
  • editlayers
  • managelayerlibrary
Hooks used
Licence GNU General Public License 2.0 or later
Download
GitHub:

Note:
No localisation updates are
provided by translatewiki.net .


README
CHANGELOG

The Layers extension is a modern, non-destructive image annotation and editing tool for MediaWiki. It enables users to add captions, callouts, highlights, shapes, and freehand drawings to images without altering the original file.

All edits are stored as validated JSON and rendered client-side for precise positioning. The system fully integrates into MediaWiki's file pages and parser. Click the Edit layers tab on any image's File: page to access the editor.

Why Layers?

[edit]
  • Professional Tools: 17 drawing tools, style presets, live preview, industry-standard alignment, a rich selection of built-in shapes and emoji, and Slide Mode for standalone graphics—everything needed to annotate like a pro.
  • Non-Destructive: Original images are never modified. Annotations are stored separately and can be versioned or removed at any time.
  • Accessible: WCAG 2.1 compliant with full keyboard navigation, screen reader support, and high-contrast indicators.

Use Cases

[edit]
Use Case Example Features Used
Educational Content Label anatomy diagrams, annotate historical photos Callouts, arrows, text boxes, named sets for different topics
Technical Documentation Highlight UI elements, show click sequences Numbered labels, curved arrows, blur to de-emphasize
Step-by-Step Guides Multi-step tutorials on a single image Named layer sets ("Step 1", "Step 2"), revision history
Collaborative Review Multiple annotators on the same image Named layer sets per reviewer, revision tracking
Maps & Geography Mark locations, draw routes, highlight regions Shapes, arrows, polygon tool, opacity controls
Scientific Imagery Label specimens, mark measurement points Text boxes, arrows, style presets for consistency

Slide Mode (v1.5.22+)

[edit]

Create standalone canvas graphics without requiring a base image. Slides are perfect for diagrams, infographics, flowcharts, and presentations. Like images, slides support multiple named layer sets for different annotation variations.

Slide Syntax

[edit]
{{#Slide: MySlide}}
<!-- Render slide "MySlide" (default layer set) -->

{{#Slide: MySlide | layerset=annotations}}
<!-- Render specific named layer set -->

{{#Slide: MySlide | size=800x600}}
<!-- Render at specific display size -->

{{#Slide: MySlide | canvas=1920x1080}}
<!-- Create with specific canvas size -->

{{#Slide: MySlide | size=800x600 | noedit}}
<!-- no edit button overlay -->

Slide Parameters

[edit]
Parameter Description Example
layerset Named layer set to display (default: "default") layerset=anatomy
canvas Canvas size in pixels canvas=1920x1080
size Display size on page size=800x600
noedit disable edit button noedit

Slide Management

[edit]
Feature Description
Special:Slides Browse, search, create, and delete slides with a modern grid interface
Special:EditSlide/SlideName Direct editor access for a specific slide
Custom canvas sizes Any size from 100×100 to 4096×4096 pixels
Background colors Any CSS color or transparent
Instant refresh Changes appear immediately after saving (no page reload needed)

Installation

[edit]

Branch Selection

[edit]
MediaWiki 1.39 LTS reached end-of-life on December 31, 2025. The REL1_43 branch provides full feature parity with main and is recommended for MediaWiki 1.43 users.
MediaWiki Version Branch Current Version
1.44+ main 1.5.75
1.43.x (LTS) REL1_43 1.5.66
1.39 - 1.42 REL1_39 1.5.66
  • Download the suitable binary for your MediaWiki version (either main, REL1_43 or REL1_39) and place the file(s) in a directory called Layers in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php file: 
    wfLoadExtension( 'Layers' );
  • Run the update script which will automatically create the necessary database tables that this extension needs.
  • Developers considering running tests, linting, etc. should run composer install and npm install within the newly created Layers directory.
  • Yes Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Configuration

[edit]

Parameters

[edit]
Variable Type Default Description
$wgLayersEnable boolean true Master switch for Layers.
$wgLayersDebug boolean false Enable verbose debug logging.
$wgLayersMaxLayerCount integer 100 Max layers per set.
$wgLayersMaxNamedSets integer 15 Max named sets per image.
$wgLayersMaxRevisionsPerSet integer 50 Historical revisions to keep.
$wgLayersMaxImageBytes integer 1048576 Max size for imported image layers.
$wgLayersMaxBytes integer 2097152 Max JSON size for a single layer set.
$wgLayersDefaultSetName string "default" Default named set when none is specified.
$wgLayersUseBinaryOverlays boolean false Enable legacy binary overlay files.
$wgLayersDefaultFonts array (see extension.json) Allowed fonts list for the editor.
$wgLayersMaxImageSize integer 4096 Max image size for editing (px).
$wgLayersThumbnailCache boolean true Cache composite thumbnails.
$wgLayersImageMagickTimeout integer 30 ImageMagick timeout (seconds).
$wgLayersMaxImageDimensions integer 8192 Max width/height for processing.
$wgLayersSlidesEnable boolean true Enable Slide Mode for standalone graphics.
$wgLayersSlideDefaultWidth integer 800 Default slide width (px).
$wgLayersSlideDefaultHeight integer 600 Default slide height (px).
$wgLayersSlideMaxWidth integer 4096 Maximum allowed slide width (px).
$wgLayersSlideMaxHeight integer 4096 Maximum allowed slide height (px).
$wgLayersSlideDefaultBackground string "#ffffff" Default background color for slides.

Permissions

[edit]
Right Description Default Groups
editlayers Create and edit layer sets user
managelayerlibrary Manage global layer library sysop

Key Features

[edit]

Annotation Tools

[edit]
  • Callouts & Speech Bubbles: Professional callouts with draggable tail positioning, three tail styles (triangle, curved, line), and rounded corners—perfect for tutorials and explanations.
  • Curved Arrows: Arrows support curved paths via a draggable control point, with configurable head types (arrow, circle, diamond, triangle) and line styles (solid, dashed, dotted).
  • Text & Text Boxes: Simple click-to-place text or advanced text boxes with word wrap, vertical alignment, padding, and corner radius.
  • Shape Library (1,385 Shapes): Built-in library with 12 categories including arrows, basic shapes, callouts, flowchart, ISO 7010 safety symbols, IEC 60417, ISO 7000, GHS, ECB, math, and more. All shapes render as crisp SVG vectors.
  • Emoji Library (2,817 Emoji): Google Noto Color Emoji library with 19 categories (smileys, gestures, people, animals, food, travel, sports, and more). Lazy-loaded SVG thumbnails for fast browsing.

Visual Effects

[edit]
  • Blur Fill: Apply a "frosted glass" blur effect to any shape—blur what's beneath instead of using a solid fill.
  • Shadow & Glow: Add drop shadows with configurable blur, offset, and spread. Glow effects for emphasis.
  • Blend Modes: Standard blend modes (multiply, screen, overlay, etc.) for professional compositing.
  • Opacity Controls: Independent fill and stroke opacity for fine-tuned transparency.

Layer Management

[edit]
  • Layer Folders: Group layers into collapsible folders for organization. Visibility and lock states cascade to children.
  • Named Layer Sets: Create multiple annotation sets per image (e.g., "default", "anatomy-labels", "step-by-step").
  • Revision History: Automatically tracks up to 50 revisions per layer set with one-click restore.
  • Lock & Visibility: Lock layers to prevent accidental edits; toggle visibility for complex compositions.

Professional Workflow

[edit]
  • Style Presets: Save and reuse style configurations (colors, stroke width, fonts) per tool type.
  • Smart Guides: Snap to edges and centers of other objects with visual alignment guides.
  • Key Object Alignment: Industry-standard alignment matching Adobe Illustrator—last selected object becomes the alignment anchor.
  • Distribute Tools: Evenly space selected layers horizontally or vertically.

Real-Time Editing

[edit]
  • Live Color Preview: Canvas updates in real-time as colors are selected in the color picker.
  • Live Article Preview: Layer changes appear immediately on article pages after saving—no page reload needed.
  • Instant Feedback: All property changes (stroke width, font size, opacity) update the canvas immediately.
  • Hover Overlay Actions: Edit/View icons appear on hover over layered images—respects editlayers permission for edit button visibility.

Integration

[edit]
  • Import Images: Add external images as layers (PNG, JPG, GIF, WebP).
  • Export as PNG: Download the annotated image as a single PNG file.
  • InstantCommons Support: Works seamlessly with files from Wikimedia Commons and other foreign repositories.
  • Vector 2022 Dark Mode: Full support for MediaWiki's Vector 2022 skin night mode.
[edit]

Named layer sets work in galleries as well as inline file links.

Native <gallery> blocks (v1.5.75): 

<gallery mode="packed" widths=200>
File:Anatomy.jpg|layerset=anatomy|Anatomical labels
File:Physiology.jpg|layerset=physiology
</gallery>

Cargo format=gallery (v1.5.74): Include a layerset field in your Cargo query and the correct named set is shown per image automatically — no template changes required: 

{{#cargo_query:tables=MyImages|fields=Image,layerset|format=gallery|mode=packed|image width=200}}

If your column has a different name, add layerset field=yourfield to the query.

Manual hint registration (v1.5.73): For other gallery sources, call {{#layers_hint:Filename.jpg|setname}} before the gallery renders. Returns empty string (no visible output).

Deep Linking (v1.2.0+)

[edit]

Control how users interact with layered images using the layerslink parameter:

Parameter Behavior Use Case
layerslink=viewer Opens fullscreen lightbox viewer Enlarged view for detailed inspection
layerslink=editor Opens layer editor directly Quick access from article to editing
layerslink=editor-newtab Opens editor in new browser tab Edit without losing article context
layerslink=editor-modal Opens editor in iframe overlay Perfect for Page Forms integration
Please note that |layerslink=editor-modal requires $wgEditPageFrameOptions = 'SAMEORIGIN'; in LocalSettings.php .

Example usage: 

[[File:Anatomy.png|thumb|layerset=anatomy|layerslink=viewer]]
[[File:Diagram.png|thumb|layerset=labels|layerslink=editor]]
'layers=' was changed to 'layerset=' to be more consistent with the terminology used in the editor.
'layers=' is still supported for backwards compatibility.

Drawing Tools

[edit]
Tool Shortcut Purpose Key Features
Pointer V Select/manipulate Multi-select, resize, rotate, Key Object alignment
Text T Simple Text Click to place, inline editing
Text Box X Advanced Text Word wrap, alignment, padding, corner radius
Callout B Speech Bubbles Draggable tail, 3 tail styles, rounded corners
Pen P Freehand Smooth paths, adjustable stroke
Rectangle R Basic Shape Adjustable stroke, fill, corner radius
Circle C Basic Shape Perfect circles with stroke and fill
Ellipse E Basic Shape Oval shapes with independent radii
Polygon Y Complex Shape Configurable sides, rounded corners
Star S Complex Shape Configurable points and radii
Arrow A Annotations Configurable head types, curved paths, line styles
Line L Annotations Simple lines with adjustable stroke
Marker M Sequence Markers Numbered/lettered markers with optional leader lines
Dimension D Measurements Technical dimension annotations with tick marks
Custom Shape — Shape Library Arrows, symbols, flowchart shapes, and more
Emoji — Emoji Library 2,817 Noto Color Emoji in 19 categories
Image — Import Images Add PNG, JPG, GIF, WebP images as layers

Keyboard Shortcuts

[edit]

Full keyboard accessibility with over 20 shortcuts:

Action Shortcut Action Shortcut
Pointer Tool V Undo Ctrl+Z
Text Tool T Redo Ctrl+⇧ Shift+Z
Arrow Tool A Delete Layer Delete or ← Backspace
Rectangle Tool R Duplicate Ctrl+D
Circle Tool C Group Layers Ctrl+G
Ellipse Tool E Ungroup Ctrl+⇧ Shift+G
Polygon Tool Y Select All Ctrl+A
Star Tool S Toggle Smart Guides ;
Pen Tool P Save Ctrl+S
Marker Tool M Dimension Tool D

Technical Details

[edit]
  • Performance: Architecture splits the lightweight Viewer (~3,300 lines including overlay) from the Editor (~114k lines including generated shape/emoji data).
  • Stability: 14,001 Jest tests (172 suites) with 95.87% statement coverage and 87.20% branch coverage.
  • Security: Property whitelisting (50+ fields), CSRF protection, and strict text sanitization.
  • Accessibility: WCAG 2.1 compliant with prefers-reduced-motion support, ARIA live regions, and skip links.

See also

[edit]
Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:Layers&oldid=8391256"