Documentation Manipulating Images

Manipulating Images

Overview #

WordPress.com automatically handles images in ways that should help minimize the need to manually perform image resizing, cropping, and optimization:

  • For high-DPI (aka Retina) devices, we automatically serve higher resolution versions of images in most cases; you should not need to upload or reference separate higher-resolution images. (This does not take effect for graphics defined by CSS, canvas, SVG, etc.)
  • In theme images, we perform automatic lossless compression on PNG and JPEG images that can be losslessly compressed, and automatically commit the compressed version to your theme’s subversion repository.
  • Images uploaded directly through WordPress are also compressed using lossless methods by default. You can optionally specify lossy compression methods as well.

We have a few different solutions for resizing and cropping available if you need to create thumbnail versions of your images. Which method you should use depends on where the image is hosted and where the image will be displayed:

↑ Top ↑

For Posts And Pages #

This is the most common situation, where you want to have an image that is representative of the post or page.

To do this, you’ll want to use WordPress’s built-in Featured Image functionality. Setting the image is really easy. After having done so, you can access and display this image from within your theme. You can even use a different sized thumbnail depending on where you are (single post view, multi-post view, etc.).

You can also define additional image sizes by using the add_image_size function:

add_action( 'after_setup_theme', 'x_setup_image_sizes' );

function x_setup_image_sizes() {
    add_image_size( 'article-image', 300, 300 );
    add_image_size( 'article-image-cropped', 300, 300, true ); // this will force the image size to 300x300 by cropping it
}

Unlike a self-hosted WordPress install, WordPress.com will generate these images on-the-fly.

↑ Top ↑

Multiple Post Thumbnails #

If you’ve ever wanted more than one Featured Image on a post, check out the Multiple Post Thumbnails plugin.

↑ Top ↑

Custom Cropping / Editing Thumbnails #

If your editorial team needs complete control over the crops for images, you can use the WP.com Thumbnail Editor plugin

↑ Top ↑

For Other Uploaded Images #

If the image file is hosted on our websevers, i.e. yourblog.files.wordpress.com, then you can do some on-the-fly resizing and cropping using some query string parameters.

Set a w value to control the width, a h if you want to control the height, and/or crop=1 if you want to crop to those exact width and heights. We have a helper function that can handle this for you.

Example:

wpcom_vip_get_resized_attachment_url( $attachment_id, 100, 50, true );

That will get you the following URL:

https://vip.files.wordpress.com/2010/09/wpcomlogo.png?w=100&h=50&crop=1

↑ Top ↑

For Other Locations #

We also have functionality for resizing and cropping images that are hosted anywhere (both on our servers and elsewhere). Here’s some example code:

echo '<img src="' . wpcom_vip_get_resized_remote_image_url( $url, $width, $height ) . '" alt="Image" />';

This function will return the URL to a resized and then cropped version of $url, served off of our CDN and escaped of all HTML entities. If you want the raw URL (with no HTML escaping), pass false as a fourth parameter.

This is powered by our own Photon service which we use to “edit” images. It’s important to not call this RESTful API directly, but to use the function described above. If you are looking to edit the image in another way, give us a holler.

Note that this function will only work on WordPress.com or on a self-hosted test site which is public, and not your local test environment, since the images need to be publicly accessible.

↑ Top ↑

Image Compression #

As mentioned above, we automatically perform lossless compression on images included in your theme and plugins, as well as images that you’ve uploaded through WordPress directly.

If you’d like to further optimize your uploaded images with lossy compression methods, we have a function you can use to enable that:

wpcom_vip_set_image_quality( $quality, $strip )

$quality can be a value between 0 and 100, where 100 is the original image quality.

$strip refers to meta data embedded in the file and has the following options:

info: will remove all Exif, IPTC and comment data from the image.
color: will remove any ICC color profiles present in the image.
all: will remove all of the above.

Note that these settings apply to images at the time they are displayed via our CDN; the original uncompressed image is still retained, allowing you to change quality settings later.

This function can be called direction in functions.php, or elsewhere in your theme code where you’re defining image display settings for a particular feature on your site.