119 lines
5.3 KiB
Markdown
119 lines
5.3 KiB
Markdown
### General usage
|
|
|
|
```sh
|
|
osr-media sw --src=(FOLDER||FILE)/GLOB --dst=EXPRESSION||FILE||FOLDER/GLOB
|
|
|
|
```
|
|
|
|
### Parameters
|
|
|
|
**src** : The source directory or file. This can be a glob pattern.
|
|
|
|
**dst** : The source directory or file. This can be a glob pattern with expressions.
|
|
|
|
**width** : The image's new width
|
|
|
|
**height** : The image's new height
|
|
|
|
**minWidth** : Perform only when the image's width exceeds this threshold
|
|
|
|
**minHeight** : Perform only when the image's height exceeds this threshold
|
|
|
|
**minSize** : Perform only when the image's size exceeds this threshold (bytes)
|
|
|
|
## [Sharp-JS resize options](https://sharp.pixelplumbing.com/api-resize)
|
|
|
|
| Param | Type | Default | Description |
|
|
| --- | --- | --- | --- |
|
|
| [width] | <code>number</code> | | How many pixels wide the resultant image should be. Use `null` or `undefined` to auto-scale the width to match the height. |
|
|
| [height] | <code>number</code> | | How many pixels high the resultant image should be. Use `null` or `undefined` to auto-scale the height to match the width. |
|
|
| [width] | <code>number</code> | | An alternative means of specifying `width`. If both are present this takes priority. |
|
|
| [height] | <code>number</code> | | An alternative means of specifying `height`. If both are present this takes priority. |
|
|
| [fit] | <code>String</code> | <code>'cover'</code> | How the image should be resized/cropped to fit the target dimension(s), one of `cover`, `contain`, `fill`, `inside` or `outside`. |
|
|
| [position] | <code>String</code> | <code>'centre'</code> | A position, gravity or strategy to use when `fit` is `cover` or `contain`. |
|
|
| [background] | <code>String</code> \| <code>Object</code> | <code>{r: 0, g: 0, b: 0, alpha: 1}</code> | background colour when `fit` is `contain`, parsed by the [color](https://www.npmjs.org/package/color) module, defaults to black without transparency. |
|
|
| [withoutEnlargement] | <code>Boolean</code> | <code>false</code> | Do not scale up if the width *or* height are already less than the target dimensions, equivalent to GraphicsMagick's `>` geometry option. This may result in output dimensions smaller than the target dimensions. |
|
|
| [withoutReduction] | <code>Boolean</code> | <code>false</code> | Do not scale down if the width *or* height are already greater than the target dimensions, equivalent to GraphicsMagick's `<` geometry option. This may still result in a crop to reach the target dimensions. |
|
|
| [fastShrinkOnLoad] | <code>Boolean</code> | <code>true</code> | Take greater advantage of the JPEG and WebP shrink-on-load feature, which can lead to a slight moiré pattern or round-down of an auto-scaled dimension. |
|
|
|
|
When both a `width` and `height` are provided, the possible methods by which the image should **fit** these are:
|
|
- `cover`: (default) Preserving aspect ratio, attempt to ensure the image covers both provided dimensions by cropping/clipping to fit.
|
|
- `contain`: Preserving aspect ratio, contain within both provided dimensions using "letterboxing" where necessary.
|
|
- `fill`: Ignore the aspect ratio of the input and stretch to both provided dimensions.
|
|
- `inside`: Preserving aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to both those specified.
|
|
- `outside`: Preserving aspect ratio, resize the image to be as small as possible while ensuring its dimensions are greater than or equal to both those specified.
|
|
|
|
|
|
|
|
### Variables
|
|
|
|
**SRC_DIR** : The directory of the current file being converted
|
|
|
|
**SRC_NAME** : The file name of the current file being converted
|
|
|
|
**SRC_FILE_EXT** : The file extension of the current file being converted
|
|
|
|
## Resize
|
|
|
|
#### Resize all JPGs by 80%
|
|
|
|
```sh
|
|
osr-media resize --src='./tests/images/in/*.+(jpg)' --dst='./tests/images/out/' --percent=80
|
|
```
|
|
|
|
#### Resize all JPGs by 80%, recursive
|
|
|
|
```sh
|
|
osr-media resize --src='./tests/images/in/**/*.+(jpg)' --dst='./tests/images/out/' --percent=80
|
|
```
|
|
|
|
#### Resize all JPGs by 80% and save as WEBP
|
|
|
|
```sh
|
|
osr-media resize --src='./tests/images/in/*.+(jpg)' --dst='./tests/images/out/*.+(webp)' --percent=80
|
|
```
|
|
|
|
#### Resize a JPG file by 80%, adding a filename suffix (`_medium`)
|
|
|
|
```sh
|
|
osr-media resize --src='./tests/images/in/DSC01177.JPG' --dst='&{SRC_DIR}/&{SRC_NAME}_medium.+(jpg)' --percent=80
|
|
```
|
|
|
|
#### Resize all JPG files to a 1000px square (eg: Instagram)
|
|
|
|
```sh
|
|
osr-media resize --src='./tests/images/in/*.+(jpg)' --dst='./tests/images/out_square/.+(jpg)' --fit=contain --width=1000 --height=1000
|
|
```
|
|
|
|
#### Resize all image types to width = 2000, in place & recursive
|
|
|
|
```sh
|
|
osr-media resize --src='./tests/images/in/**/*.+(${IMAGES})' --percent=80
|
|
```
|
|
|
|
### Resize all image types to width = 2000, only when the image's width is larger than 2000
|
|
|
|
```sh
|
|
osr-media resize --src='./tests/images/in/**/*.+(${IMAGES})' --width=2000 --minWidth=2000
|
|
```
|
|
|
|
## Convert
|
|
|
|
#### Convert all WEBPs to JPGs
|
|
|
|
```sh
|
|
osr-media convert --src='./tests/images/in_webp/*.+(webp)' --dst='./tests/images/out_jpg/*.+(jpg)'
|
|
```
|
|
|
|
#### Convert a WEBP to a JPG file
|
|
|
|
```sh
|
|
osr-media convert --src='./tests/images/in_webp/DSC01177.webp' --dst='./tests/images/out_jpg/DSC01177.jpg'
|
|
```
|
|
|
|
#### Convert a WEBP to a JPG and a PNG file
|
|
|
|
```sh
|
|
osr-media convert --src='./tests/images/in_webp/DSC01177.webp' --dst='${SRC_DIR}/${SRC_NAME}.+(jpg|png)'
|
|
```
|