Jump to content

Requests for comment/Square bounding boxes

From mediawiki.org
Request for comment (RFC)
Square bounding boxes
Component General
Creation date
Author(s) cscott
Document status accepted
See Phabricator.

Implemented in 1.24wmf6

The current mediawiki syntax for image thumbnails and resizing works poorly for images which are taller than they are wide. The upright option attempts to remedy this, but properly scaling a thumbnail to fit a square bounding box requires the user to manually compute the aspect ratio of the image. There is no way to directly obtain a thumbnail whose height is limited by the user's thumb size preference.

This was discussed in RFC review meetings on 2014-04-02 and 2014-05-21.


There are several proposals for remedying this situation:

  1. Change mediawiki to use square bounding boxes by default (opt-out).
    • Alternatively, only change the default bounding box used by thumb to be square.
  2. Add a new image option to request a square bounding box (opt-in).
  3. Add a new "upright=auto" option (minimalist, opt-in)
  4. Add a new "scale=N" option (adds new functionality, opt-in)

In an RFC review meeting on 2014-04-02 the following alternative was agreed upon:

  • Use square bounding boxes for thumbnails without an explicit size specification. (bug 63903)
  • Use square bounding boxes for thumbnails scaled using "upright" (bug 63904) pending investigation on the number of pages that would be affected.

Consensus proposal[edit]

Assuming a 220px default thumbnail size:

[[File:Foobar.jpg|200px]]              (unchanged, uses width-based scaling)
[[File:Foobar.jpg|thumb]]              (scales to 220 x 220 bounding box)
[[File:Foobar.jpg|thumb|upright]]      (scales to 220 x 220 bounding box?)
[[File:Foobar.jpg|thumb|upright=0.5]]  (scales to 110 x 110 bounding box?)

Currently the default 'upright' scale factor is 0.75. Assuming that the 'upright' option with the default scale is usually applied to 3:4 portrait-aspect-ratio images, it is possible that changing the default scale factor to 1.00 at the same time upright is changed to use a square bounding box will result in fewer images changing size. We are currently gathering statistics on this point.

Square bounding boxes by default[edit]

In this version of the proposal, the existing width-only restrictions on image size would be the exception, not the rule. Assuming a 220px default thumbnail size:

[[File:Foobar.jpg|200px]]              (scales to 200 x 200 bounding box)
[[File:Foobar.jpg|thumb]]              (scales to 220 x 220 bounding box)
[[File:Foobar.jpg|thumb|upright=0.5]]  (scales to 110 x 110 bounding box)
[[File:Foobar.jpg|x200px]]             legacy syntax, restricts height only
[[File:Foobar.jpg|150x200px]]          legacy syntax, uses specified non-square bounding box
[[File:Foobar.jpg|200xpx]]             new syntax, restricts width only?
                                         no way to have a thumbnail scaled by default width only

New "square" option[edit]

In this version of the proposal, a new "square" image option opts-in to square bounding boxes. Again assuming a 220px default thumbnail size:

[[File:Foobar.jpg|200px|square]]              (resizes to 200x200px)
[[File:Foobar.jpg|x200px|square]]             (resizes to 200x200px)
[[File:Foobar.jpg|150x200px|square]]          (resizes to 200x200px, using max dimension)
[[File:Foobar.jpg|thumb|square]]              (resizes to 220x220px)
[[File:Foobar.jpg|thumb|upright=0.5|square]]  (resizes to 110x110px)


In this version of the proposal, we narrowly solve the specific "thumbnail with a square bounding box of the default size" issue by adding a new "auto" value to the existing "upright" image option. Assuming a 220px default thumbnail size:

[[File:Foobar.jpg|thumb|upright=auto]]  (resizes to 220x220px)

The user must use the existing syntax for square bounding boxes of an explicit size:


There is no support for combining the 'auto' option with other uses of upright. That is, there is no way to get a square thumbnail of "half the default size", which would involve combining "upright=0.5" and "upright=auto".


In this version of the proposal, we add a new "scale" option, which is a better replacement for "upright" and uses a square bounding box by default. Assuming a 220px default thumbnail size:

[[File:Foobar.jpg|thumb|scale=1]]   (resizes to 220x220px)
[[File:Foobar.jpg|thumb|scale=0.5]] (resizes to 110x110px)
[[File:Foobar.jpg|scale=0.5]]       (resizes to half of Foobar.jpg's "natural size")

The "scale" option allows scaling thumbnails like "upright" does, but it also allows scaling images based on the image's natural size. Using "thumb" and "scale" together has the side effect of upgrading the default thumbnail size specification to a square bounding box.


Another hacky way to get a square bounding box for a thumbnail with current wikitext is:


where the XXX is the computed current aspect ratio of Foobar.jpg. This will give unintended results if a new version of Foobar.jpg is uploaded with a different aspect ratio. However, this is what Parsoid will likely implement as the default serialization in the short term. —The preceding unsigned comment was added by Cscott (talkcontribs16:11, 27 March 2014 (UTC)[reply]

Option 1 would be a torches-and-pitchforks change, as it breaks changes in an incompatible and likely unappealing manner any existing usages of "portrait"-oriented images. -2 from me on this. Anomie (talk) 17:09, 27 March 2014 (UTC)[reply]

As for option 2, we already have a syntax for specifying a square bounding box with explicit pixel dimensions, that being "200x200px". So just like 'upright', IMO this should only have an effect if pixel dimensions are not given. "|upright=0.5|square" probably also deserves more thought, as I doubt that the user really intends to bound it to 110x110px rather than something like 110x220px. Anomie (talk) 17:09, 27 March 2014 (UTC)[reply]


  • The "square" image option is implemented by https://gerrit.wikimedia.org/r/120856
  • The first part of the consensus proposal, which uses square bounding boxes for thumbnails without explicit size specifications, is implemented in https://gerrit.wikimedia.org/r/123683
  • Changing "upright" to use square bounding boxes and a default aspect ratio of 1.0 is not yet implemented.

See also[edit]

  • bug 62666 related Parsoid bug
  • bug 62671 related VE bug
  • bug 24763 unfortunately, height scaling isn't exact
  • bug 65945 related to problems with this change, and requests to roll it back