@siteone/img-microservice
Advanced tools
Microservice for fast and awesome image manipulation microservice.
Img microservice can be installed in different ways, through docker or with npm. Depending on your needs you find here your way.
You can install img globally with
npm install -g @siteone/img
and then run it with
img
Pass --help to discover the available options
Img microservice try to meet the most common needs, so when you start it you already have a fully working system. Nonetheless Img microservice is highly customizable.
If you are a developer or run Img microservice directly from the source, the default configuration file contains a lot of instructions. You can read it in config/default.js.
When you install img globally, the cli accepts various configuration parameters. You can read the inline help running img --help.
Here a deeper look to the parameter
Img microservice listen to port 8565 by default. You can change it to the value you prefer:
> img --port 1234
Img microservice has different cache levels and any can be disabled and configured indipendently from the others
This cache store the resulting image. If you make a second request to get the same image with the same transformations, this cache will hit and the cached result will be returned. The image won't be processed again. By default this cache is set to memory.
If you change your transformation the original image will be downloaded again unless you activate the input cache. If this cache is activated the original image will be stored and therefore it won't be downloaded again. The image will be just re-processed to evaluate the new transformations to apply. This cache by default is disabled.
Each cache can use a different method to save/retrieve cached resources. All of those methods applies to any kind of cache.
This special cache doesn't store anything. Each request will be re-processed by Img microservice.
Output cache:
```bash
# enable
> img --cache none
```
Input cache:
bash # enable > img --inputcache none
The cached images will be stored on your local file system.
Output cache:
```bash
# enable
# note: The processed images will be saved on the operating system default temporary folder.
> img --cache file
# change cache path path
> img --cache file --cache-filepath "path/to/cache/folder/"
```
Input cache:
bash # enable # note: The processed images will be saved on the operating system default temporary folder. > img --inputcache file # change path > img --inputcache file --inputcache-filepath "path/to/cache/folder/"
In this case the cache will be stored in memory. It will be delete when the service is restarted.
Output cache:
```bash
# enable
# note: The processed images will be saved on the operating system default temporary folder.
> img --cache file
# change cache size limit (in MB)
> img --cache file --cache-limit 250
# disable cache size limit
> img --inputcache file --inputcache-limit false
```
Input cache:
bash # enable # note: The processed images will be saved on the operating system default temporary folder. > img --inputcache file # change cache size limit (in MB) > img --inputcache file --inputcache-limit 250 # disable cache size limit > img --inputcache file --inputcache-limit false
By default img transforms any image you feed him. If your service is publicly exposed you may want to restrict the list of domains from where the images can be taken. This can be a list of domains and it can contain wildcards.
> img --whitelist myapp.s3.amazon.com, *.myapp.com
Logger can be set to two levels.
## verbose logging
> img -v
## quiet
> img -q
Img microservice, by default, prints readable messages on stdout. You can, however, change output to JSON.
> img --json
Img microservice reads the file metadata to retrieve information about the file type. It can be configured to use the file extensions instead.
> img --guess-type-by-extension
In case the file extension is missing, img will fallback to metadata. For some transformation, reading the metadata is mandatory.
For the image formats where this is applicable, Img microservice produces progressive images. This is the best choice on the web since the images can start to render before being entirely downloaded. This behavior can be disabled
> img --progressive false
Img microservice can report error in several format. By default the errors are reported in a json format to help machine parsing. The other accepted values are plain, for a simple text report, and html for a pretty formatted report.
> img --errors plain
Img microservice can compress the response through deflate/gzip if the requester (the browser usually), asks for it through Accept-encoding header. By default this option is turned off.
img --compress
Demo instance: $MICROSERVICE_URL/$TRANSFORMS/$IMAGE_URL
$MICROSERVICE_URL - full URL of microservice (example instance runs on https://img.frontend.company)$TRANSFORMS - documented below$IMAGE_URL - full URL of imageExample: `https://img.frontend.company/rs_200x200/http://unsplash.it/2000/2000
Blur the image.
General syntax: blur_$VALUE
$VALUE can be 0.3 to 1000Result
Example URL: https://img.frontend.company/blur_100/https://picsum.photos/800/600/
Extract let you select an arbitrary portion of the input image specifying the coordinates and the size of the extraction.
General syntax: extract_$X_$Y_$W_$H
$X X coordinate$Y Y coordinate$W width$H heightAll values can be specified as pixel values or percentages.
Image URL: https://img.frontend.company/ex_95_35_0.5_100/https://picsum.photos/800/600/
Produces image with crop start at X 95px and Y 35px with width of 50% of original image and height 100px.
Fli the image horizontally or vertically.
General syntax: flip_$AXIS
$AXIS can be either - x for horizontal flipping - y for vertical flippingImage URL: https://img.frontend.company/flip_x/https://picsum.photos/800/600
Image URL: https://img.frontend.company/flip_y/https://picsum.photos/800/600
Returns your image in another format. Supports transforming jpeg, png webp and tiff into jpeg or webp formats.
General syntax: o_$FORMAT
$FORMAT output image format - webp for WEBP - jpeg for JPEGImage URL: https://img.frontend.company/o_jpeg/https://picsum.photos/800/600/
**Image URL: **
https://img.frontend.company/o_webp/https://picsum.photos/800/600/
Produce progressive images.
General syntax: progressive_$VALUE
$VALUE progressive option - true for progressive output - false for non-progressive outputImage URL: https://img.frontend.company/progressive_true/https://picsum.photos/800/600/
Image URL: https://img.frontend.company/progressive_false/https://picsum.photos/800/600/
Resize can be a very complex task in Img microservice. There are plenty of ways of resizing, cropping and extract portion of your images.
General syntax: rs_$SIZE_$MODE_$MODE_PARAMS
$SIZE - is the new size (it can be expressed in several ways as explaned here).$MODE - define how to resize. Maybe you want to stretch the image, or take just a portion;$MODE_PARAMS - are the parameters accepted by the specific mode and can also be empty.In scale mode the image will have the dimension of the size you specified. The aspect ratio is kept unless you pass iar (ignore aspect ratio) as additional parameter.
Since scale is the default resize mode, you can avoid specifiying it.
Scale the image to 200x300 px keeping the aspect ratio
Image URL: https://img.frontend.company/rs_200x300/https://picsum.photos/800/600/?image=1
Scale the image to 200 px width keeping the aspect ratio. The height is calculated automatically
Image URL: https://img.frontend.company/rs_200/https://picsum.photos/800/600/?image=1
Scale the image to 200x300 px width ignoring the aspect ratio.
Image URL: https://img.frontend.company/rs_200x300_scale_iar/https://picsum.photos/800/600/?image=1
The image will take the maximum available space up to the specified size, keeping the aspect ratio. For example this will resize the image up to 300x300 pixels and all the image will be visible.
NOTE: both width and height must be passed. Nonetheless they can be expressed in percentage
Like fit but only if the image is larger than the desired size (width or height), otherwise it will be left untouched.
NOTE: both width and height must be passed. Nonetheless they can be expressed in percentage
Like fit but only if the image is smaller than the desired size (both the width and height must be smaller), otherwise it will be left untouched.
NOTE: both width and height must be passed. Nonetheless they can be expressed in percentage
Produce a new image of specified width and height. The original image is then filled inside those dimensions. The excess part will be excluded.
You can specify a gravity to decide which part of the original image should be excluded. If nothing is specified the default gravity is center.
Fill also accept a special gravity parameter: auto. This let you automatically select a meaningfull region of the image.
Center gravity
North-east gravity
Gravity on center
Gravity auto
Same as fill but only if the image is larger than the target size (width and height).
Center downfill
West downfill
This embeds the image in the specified dimensions. The entire image is taken and aspect ratio is kept. If the image doesn't fit well in the dimension the output will be padded with a color of your choice (or black by default).
Simple embedding
RGB color
RGBA color
HEX color and optional alpha (6 digit + alpha)
Gravity
The size parameter can be specified in several format in each resize mode.
rs_200x300 is 200 x 300 px
rs_200 is 200 px width, height auto
rs_x300 is 200 px height, width auto
You can specify the width and height as percentage value of the input image
rs_0.2x0.3 is 20% of the width and 30% of the height
rs_0.2 is 20% of the width
rs_x0.3 is 30% of the height
Pixel and percentage can be mixed.
rs_200x0.3 is 200px of width and 30% of height
For those operations which support gravity, those value can be specified
center, north, northeast, northwest, east, west, south, southeast, southwest
and can be abbreviated in
c, n, ne, nw, e, w, s, se, sw.
Some operation, such as fill and downfill accept the auto gravity. This automatically focus on the most important region of the image.
Look here for an example
The colors accepted by some operations can be expressed as:
RGB 120230007 in this case the rgb(120, 230, 7)
The three values of red, green and blue must be put together and each must be of three digits, so 7 becomes 007 and 45 becomes 045.
Hexadecimal FF00AB is in the hex format. The short notation (3 digits only) is not accepted yet and # at the beginning must be removed.
To specify the opacity you can add .3 at the end. So to set an opacity of 0.4 the previouses become 120230007.4 and FF00AB.4
Omitting the opacity means it is 1, full opaque, while .0 means full transparent.
This paramter let you rotate the image.
Any angle multiple of 90° is accepted.
Result
FAQs
Image processing service
The npm package @siteone/img-microservice receives a total of 1 weekly downloads. As such, @siteone/img-microservice popularity was classified as not popular.
We found that @siteone/img-microservice demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
