ImageTweak user guide

CAFxX edited this page Jun 30, 2012 · 18 revisions

ImageTweak is open source under the GPLv3, feel free to hack on the source code and send patches or pull requests. Found a bug? See Troubleshooting.

If you like ImageTweak please consider donating via or by sending bitcoins to 1265ciMoFwnX4y4gGxXNGkiD7Qu24oYSqw.

Status of this document

This guide is based on ImageTweak version 0.25. If you are using any other version you may find discrepancies between the contents of this guide and the behaviour or appearence of your version.


ImageTweak is a very narrowly targeted addon. As such, you will not see it active anywhere except when the current tab or window is displaying an image or video not embedded within a webpage (more precisely it will activate only when the URL of the currently active document points to a resource having a MIME-type that Firefox renders by instantiating an ImageDocument or VideoDocument).

When ImageTweak is active, it transforms the default view of the "direct" image/video (white background, image/video in the top-left corner, at most two zoom levels) setting a custom background color (by default a dark gray), centering the image/video and making it zoomable, roteable and draggable.

Many aspects of ImageTweak (such as its behaviour, input methods, etc.) can be configured from the Options dialog reachable from the Add-ons window (Tools > Add-ons) or from the context menu when ImageTweak is active. Depending on how the options are set, ImageTweak will behave differently: as such a complete discussion is not feasible, and we will only pinpoint the most common cases.

Basic usage

When an image or video is displayed, you can:

  • Zoom in or out the image by holding down ctrl and scrolling the mousewheel, or using the +/- keys. You can also hold ctrl+shift and move the mouse pointer to zoom the image (or ctrl+alt+shift and move the mouse pointer to zoom and rotate) .
  • Move the image by dragging it with the mouse (left-click), or using the arrow keys. The mouse wheel also performs vertical scrolling.
  • Rotate the image using ctrl+> and ctrl+<. You can also hold ctrl+alt and move the mouse pointer.
  • Switch zoom mode using the mouse (double left-click), using the space bar or the keys 1 (full view), 2 (fill view), 3 (unscaled view), 4 (free view).
  • Perform drag-and-drop to save the image on the desktop by dragging the image outside the browser window on the desktop.
  • Show the context menu by left clicking on the image/video. The context menu allows to perform many of the above actions and also allows you to configure ImageTweak.
  • Toggle between interpolation modes by pressing the 'p' key.
  • Toggle the custom background by pressing the 'b' key. This temporarily restores the background to the default one.

When a webpage is displayed, you can (if the corresponding options has been enabled in the Options window):

  • If you use ctrl + right-click when the pointer is over an image, it will be opened as a "direct" image in the current tab.
  • If you use ctrl + alt + right-click when the pointer is over an image, it will be opened as a "direct" image in a new tab.
  • If you use ctrl + alt + shift + right-click when the pointer is over an image, it will be opened as a "direct" image in a new window.


From the Options window, you can configure the following:

  • Background color: set the color used as background when viewing an image; the value entered here must be a valid CSS color declaration (examples include "red", "#FF0000", "rgb(255,0,0)"). You can also specify a percentage (0% being black and 100% being white) or use the colorpicker button.
  • Border color: set the color of the border displayed around the image. The same notes about the background color apply. Leave empty to have no border.
  • Zoom factor: this numeric parameter controls how fast the zoom is performed; the default value of 200 means that at each step the zoom is either doubled or halved
  • Clip image movement range: when enabled it prevents from moving the image outside of the window
  • Place image at top left: if enabled it places the image in the top left corner of the window when using zoom types fill and unscaled. By design this only works for images bigger than the window: if the image is smaller it will be shown centered regardless of this option.
  • Zoom on mouse pointer: when enabled, zoom operations will appear to use the mouse pointer as the pivoting point
  • Invert the mousewheel zoom direction: inverts the direction you have to scroll the mousewheel to zoom in/out
  • Invert keyboard navigation: inverts the direction the image is moved to when using the arrow keys
  • Enabled zoom types: sets which zoom types are enabled (see the "Zoom types" section for more information)
  • Default zoom type: sets which zoom type to use upon loading the image (see the "Zoom types" section for more information)
  • Enabled shortcuts: as a bonus, (ctrl/ctrl+alt/ctrl+alt+shift)+right-click on any image within a regular webpage may be used as shortcut for the "View image" context-menu command. The same happens when double-right-clicking
  • Notify websites: allow websites to detect that the browser has the capabilities of a decent image viewer (zoom, rotate, dark background, etc.)

Other rarely used preferences can only be accessed via about:config:

  • extensions.imagetweak.shadowcolor: if you set here a CSS color, a shadow will be drawn behind non-trasparent images

Zoom types

A zoom type is a common (dynamic) zoom level. Four zoom types are currently implemented:

  • Fit to window: the maximum zoom that allows the image to be completely inside the window (a.k.a. "touch from inside")
  • Fill window: the minimum zoom that allows the image to completely fill the window (a.k.a. "touch from outside")
  • 1:1: 100% (a.k.a. "unscaled")
  • Free mode: the last set zoom level and position (not taking into account the other three types).


For suggestions, corrections or further information please head over to the support thread on

If you think you found a bug, see this page for more information on how to report it.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.