From b60ccd11c3bc281df5afc5aef80c96ea671022d5 Mon Sep 17 00:00:00 2001 From: Jonathon Menz Date: Wed, 28 Jun 2017 14:40:18 -0700 Subject: [PATCH] DOCS clarify $force_resample behaviour Fixes https://github.com/silverstripe/silverstripe-assets/issues/21 --- .../02_Developer_Guides/14_Files/02_Images.md | 53 ++++++++++++------- 1 file changed, 34 insertions(+), 19 deletions(-) diff --git a/docs/en/02_Developer_Guides/14_Files/02_Images.md b/docs/en/02_Developer_Guides/14_Files/02_Images.md index f232b01bf..b159c2ad7 100644 --- a/docs/en/02_Developer_Guides/14_Files/02_Images.md +++ b/docs/en/02_Developer_Guides/14_Files/02_Images.md @@ -141,7 +141,40 @@ For usage on a website form, see [api:FileField]. ### Image Quality -To adjust the quality of the generated images when they are resized add the +#### Source images + +Whenever SilverStripe performs a manipulation on an image, it saves the output +as a new image file, and applies compression during the process. If the source +image already had lossy compression applied, this leads to the image being +compressed twice over which can produce a poor result. To ensure the best +quality output images, it's recommended to upload high quality source images +(minimal or no compression) in to your asset store, and let SilverStripe take +care of applying compression. + +Very high resolution images may cause GD to crash (especially on shared hosting +environments where resources are limited) so a good size for website images is +around 2000px on the longest edge. + +#### Forced resampling + +Since the 'master' images in your asset store may have a large file size, by +default SilverStripe will always apply compression to your images to save +bandwidth - even if no other manipulation (such as a crop or resize) is taking +place. If you expect the images in your asset store to already have +compression applied and want to serve up the original when no resampling is +necessary, you can add this to your mysite/config/config.yml file: + + :::yml + # Configure resampling for File dataobject + File: + force_resample: false + # DBFile can be configured independently + SilverStripe\Filesystem\Storage\DBFile: + force_resample: false + +#### Resampled image quality + +To adjust the quality of the generated images when they are resampled, add the following to your mysite/config/config.yml file: :::yml @@ -150,24 +183,6 @@ following to your mysite/config/config.yml file: properties: Quality: 90 -By default SilverStripe image functions will not resample an image if no -cropping or resizing is taking place. You can tell SilverStripe to always to -always produce resampled output by adding this to your -mysite/config/config.yml file: - - :::yml - # Configure resampling for File dataobject - File: - force_resample: true - # DBFile can be configured independently - SilverStripe\Filesystem\Storage\DBFile: - force_resample: true - -If you are intending to resample images with SilverStripe it is good practice -to upload high quality (minimal compression) images as these will produce -better results when resampled. Very high resolution images may cause GD to -crash so a good size for website images is around 2000px on the longest edge. - ## Changing the manipulation driver to Imagick If you want to change the image manipulation driver to use Imagick instead of GD, you'll need to change your config so