Respizer
A Responsive Images build tool: Resize your images into multiple breakpoint versions on the fly and generate corresponding picture/img srcset code
Version: 0.0.1
Dependencies
Respizer relies on graphicsmagick, so you'll need that installed on your system. With ubuntu it's as simple as
sudo apt-get install graphicsmagick
If you need help installing graphicsmagick see http://www.graphicsmagick.org/.
Installation
sudo npm install -g respizer
Configuration
Respizer uses a configuration file called respizer.conf.js
, this must be available in your
current working directory for respizer to work.
Here's a sample configuration file with comments:
module.exports = {
breakpoints: {
'1x': [
1680,
1366,
1024,
480,
320,
260
],
'2x': [480, 1024] //landscape widths of iphone/ipad
},
areas : [ //area refers to a space constraint on the web page that the image fits into
{
name: 'Gallery', //optional
dirs: ['test'], //required, array of directories to be referenced from web page area
width: '61.803398875%', //the percentage of viewport estate taken up by the image
minWidths: { //the percentage of viewport estate taken up by the image *at different minimum breakpoints*
'768' : '61.803398875%',
'0' : '80.901699437%'
}, //if minWidths is available it will trump width
//alternative to minWidths (mobile first) is maxWidths (desktop first)
maxWidths: { //the percentage of viewport estate taken up by the image *at different minimum breakpoints*
'768': '80.901699437%',
Infinity: '61.803398875%' //use infinity for normative desktop width
} //maxWidths will cause minWidth to be discarded
}
],
options: {
dirPrefix: __dirname, //absolute path to be prefixed to each areas and breakpoint root
processImages: true, //if false, we simply generateCode unless generateCode is false.. then we do nothing
noUpscaling: true, //if target size is higher than original image, uses original image instead of upscaling
artisticDirection: { //object or false
breakpoint: 480,
zoom: '112.5%',
method: 'zoom'
},
generateCode: { //generatedCode will be loaded onto the area[n].code property, which can then be output in anyway neccessary
implementation: 'picture',
defaultBreakpoint: 1024, //what size is the fallback
minOrMax: 'min-width', //min-width (mobile first) or max-width (desktop first) approach
className: false //add a class attribute to each element
}
}
}
Explanation
breakpoints
breakpoints
is an object, with properties defining the targetted device pixel ratio.
1x is normal screens, 2x is retina screens. Some devices are 1.5x, and who knows in
the future maybe for some crazy reason there will be a 3x or a 4x.
Each device pixel ratio property holds an array of targetted screen widths.
areas
area
referrs to a designated (by percentage) piece of viewport estate that will be holding
an image (or images, in the case of a slider or such).
You can give it a name to make Respizer's output more obvious but this optional.
You must provide a least one directory to the dirs
property, all images in the given
directory will be resized and converted to the given breakpoints. The breakpoint folders
will also be set up in the directory specified, you can specify more than one directory.
The width
property specifies how much of the viewport the image will take up. For instance
if you have a wrapper element set to 61.803398875% of the body, and have an image within the
wrapper element set to 100% of the wrapper, you're images ultimate width is 61.803398875%.
The minWidths
property overrides the width
property. You can use this to accompany any
media query breakpoints you have set that effect the width of the designated image area.
The maxWidths
property overrides the minWidths
property and is for exactly the same purpose,
except it comes from a desktop first approach instead of mobile first.
options
Focussing on the less obvious properties:
Respizer can generate images and/or code according to the configuration inputs.
processImages
allows you to turn off the image generation functionality in order to just
grab the generated code.
noUpscaling
should probably be left the same, it stops respizer from scaling the original
images up if they are smaller than the defined breakpoint and instead copies them straight accross.
Resizing detailed images down to fit on small screens can sometimes mean that the intended focal of the image (say a person in the middle of a room) becomes too small.
artisticDirection
allows you to set a breakpoint at which instead of just resizing
you can apply an alternative image processing method (currently only zoom
is implemented)
to better adapt images to smaller screen sizes. The zoom method will resize the image
to 112.5% of the specified breakpoint size, and then crop it to the breakpoint size, effectively
enlarging the focal point of the image (assuming the focal point is central).
generateCode
provides settings for the generate code feature which currently outputs
HTML in the responsive picture
element format which could then be used in browsers
with the help of Respondu
Usage
Once you have your configuration file setup, usage is very simple.
respizer
Plans
- A Respizer Grunt task so that it can be part of the overall build process
- A modification time cache, to avoid rerunning resize code unneccessarily
- Speed improvements
- More finite control over how and where images are created
- More artisticDirection methods, zoomLeft zoomRight etc.
Tests
Clone this repository and simply run ./index.js
,
the example configuration file runs respizer on the test folder which holds test.jpg
It should create eight sub-directories named after the breakpoints and resize test.jpg to 61.803398875% of each breakpoint size for breakpoints greater than 768 and it should resize and crop to 80.901699437% of breakpoint sizes for breakpoints less than 768 - as specified by the area.maxWidths object in the respizer.conf.js file.
No unit tests as yet :D