|
1 | | -# UploadCompressImage |
| 1 | +# transform-image-js |
2 | 2 |
|
3 | | -### Upload files with resizing to a specified dimension using javascript |
| 3 | +[](https://travis-ci.org/github/shellophobia/transform-image-js) |
| 4 | +[](https://www.npmjs.com/package/@shellophobia/transform-image-js) |
| 5 | +[](https://www.npmjs.com/package/@shellophobia/transform-image-js) |
| 6 | +[](https://www.npmjs.com/package/@shellophobia/transform-image-js) |
4 | 7 |
|
5 | | -Demo [demo] |
| 8 | +> [transform-image-js](https://github.com/shellophobia/transform-image-js) is a library that resizes the image within defined constraints and also allows to adjust the quality of image. One of the use cases is when you want to perform a size optimization on the image before uploading. |
6 | 9 |
|
7 | | -A plugin that enables you upload image files to the server with a front-end side compression. So basically the image that you upload gets redrawn on the canvas with new dimension that you specify in the options and a compressed base64 encoded string is obtained from it. Now most of us these days have a phone with a fancy camera, that clicks the images of sizes of around 8-13 MB. So uploading that kind of size onto the server is totally not acceptable. So you wish to either compress on front end side or the server side. Android has some libraries that allows you to compress the files before sending onto the server, but on the other hand there is no such solid lead available on the browser side. |
| 10 | +## Getting started |
8 | 11 |
|
9 | | -So here's a plugin that comes to the rescue. |
| 12 | +### Installing |
10 | 13 |
|
11 | | -I have listed out the events, methods and params for incorporating the plugin at my gist. |
12 | | -Gist for jquery plugin - [jquerygist] |
13 | | -Gist for npm module - [npmgist] |
| 14 | +Using npm: |
14 | 15 |
|
15 | | -The logic behind compression is that the larger size images have ample amount of resolution to them, but most of the time that kind of resolution is not needed. So this plugin is basically resizing the higher resolution image to the specified dimensions that you will provide or it is going to use the default dimensions as specified inside the plugin. To use the compression algorithm on the front end especially with the current browser specs is quite a heavy task and it will slow down your page with high CPU usage, so resizing on the other hand helps. |
| 16 | +```bash |
| 17 | +npm i @shellophobia/transform-image-js |
| 18 | +``` |
16 | 19 |
|
17 | | -This repository contains both jquery plugin as well as a npm module code. You can use it as per your convenience. |
| 20 | +Using yarn: |
18 | 21 |
|
19 | | -I haven't done anything on the styling part, because I guess most of you would want to do it on your side, since everybody wants a custom thing. So you can go through the IDs of the element that I have created and style it on your own. This repo only contains a simple JS file. |
| 22 | +```bash |
| 23 | +yarn add @shellophobia/transform-image-js |
| 24 | +``` |
20 | 25 |
|
21 | | -So feel free to write any suggestions. |
| 26 | +Using jsDelivr CDN: |
22 | 27 |
|
23 | | -[jquerygist]: https://gist.github.com/shellophobia/547a13696996eebbcf20b19f1bfffca4 |
24 | | -[npmgist]: https://gist.github.com/shellophobia/7480afeda989bdd7fa93af6147ddd14d |
25 | | -[demo]: https://shellophobia.github.io/uploadresizeimage.html |
| 28 | +```html |
| 29 | +<script src="https://cdn.jsdelivr.net/npm/@shellophobia/transform-image-js/lib/transform-image-js.min.js"></script> |
| 30 | +``` |
| 31 | + |
| 32 | +Using unpkg CDN: |
| 33 | + |
| 34 | +```html |
| 35 | +<script src="https://unpkg.com/@shellophobia/transform-image-js/lib/transform-image-js.min.js"></script> |
| 36 | +``` |
| 37 | + |
| 38 | +### Usage |
| 39 | + |
| 40 | +#### Import |
| 41 | + |
| 42 | +in CommonJS: |
| 43 | +```js |
| 44 | +const transformImage = require("@shellophobia/transform-image-js") |
| 45 | +``` |
| 46 | + |
| 47 | +in ES6: |
| 48 | + |
| 49 | +```js |
| 50 | +import transformImage from '@shellophobia/transform-image-js'; |
| 51 | +``` |
| 52 | + |
| 53 | +#### Resize image to max 500x500 with quality as 0.9: |
| 54 | + |
| 55 | +##### Vanilla JS and HTML |
| 56 | +```html |
| 57 | +<input id="demo" type="file" onchange="handleUpload"> |
| 58 | +``` |
| 59 | +```js |
| 60 | +function handleUpload(e){ |
| 61 | + const file = e.target.files[0]; |
| 62 | + // The library will add a property `transformImageJS` on window once you import it |
| 63 | + const transformImage = new transformImageJS.TransformImage({maxHeight: 500, maxWidth:500, quality:0.9}); |
| 64 | + transformImage.resizeImage(file).then(res=>{ |
| 65 | + //The response returns an object that has the output blob in output attribute and has metadata for image sizes before and after transformation |
| 66 | + console.log(res); |
| 67 | + }).catch(err => { |
| 68 | + // handle error |
| 69 | + }); |
| 70 | +} |
| 71 | + |
| 72 | +// using async function |
| 73 | +async function handleUpload(e) { |
| 74 | + const file = e.target.files[0]; |
| 75 | + const transformImage = new transformImageJS.TransformImage({maxHeight: 500, maxWidth:500, quality:0.9}); |
| 76 | + try { |
| 77 | + const res = await transformImage.resizeImage(file); |
| 78 | + console.log(res); |
| 79 | + } catch(e) { |
| 80 | + // handle error |
| 81 | + } |
| 82 | +} |
| 83 | +``` |
| 84 | + |
| 85 | +##### React JSX |
| 86 | +```js |
| 87 | +import React from "react"; |
| 88 | +import transformImage from "@shellophobia/transform-image-js"; |
| 89 | + |
| 90 | +const handleUpload = async (e) => { |
| 91 | + const file = e.target.files[0]; |
| 92 | + console.log(file); |
| 93 | + const transformImage = new transformImage({maxHeight: 500, maxWidth:500, quality:0.9}); |
| 94 | + try { |
| 95 | + const res = await transformImage.resizeImage(file); |
| 96 | + console.log(res); |
| 97 | + } catch (e) { |
| 98 | + console.log(e); |
| 99 | + } |
| 100 | +} |
| 101 | + |
| 102 | +export default function App() { |
| 103 | + return ( |
| 104 | + <div className="App"> |
| 105 | + <input type="file" onChange={handleUpload} /> |
| 106 | + </div> |
| 107 | + ); |
| 108 | +} |
| 109 | +``` |
| 110 | + |
| 111 | +## API |
| 112 | + |
| 113 | +### Initialization options |
| 114 | + |
| 115 | +#### Description |
| 116 | +Following options can be passed during initialization of transformImage that returns an object on which methods can be called |
| 117 | + |
| 118 | +#### `transformImage(options)` |
| 119 | + |
| 120 | +| Name | Type | Description | Default | |
| 121 | +|------------------|----------|------------------------------------------------------------------------------------------------------------|------------------------| |
| 122 | +| sizeLimit | int | Byte size limit of the output | 16777216 // 16MB | |
| 123 | +| maxWidth | int | Max width of the output | 500 | |
| 124 | +| maxHeight | int | Max height of the output | 500 | |
| 125 | +| quality | float | A Number between 0 and 1 indicating the image quality to use for image formats that use lossy compression | 0.92 | |
| 126 | +| base64OutputType | bool | Return base64 output string in response | false | |
| 127 | +| blobOutputType | bool | Return blob output in response | true | |
| 128 | +| allowedFileTypes | []string | Array of allowed file types for uploaded file | ["jpg", "png", "jpeg"] | |
| 129 | + |
| 130 | + |
| 131 | +### Methods |
| 132 | + |
| 133 | +### `resizeImage(imageFile) => {Promise}` |
| 134 | + |
| 135 | +#### Description: |
| 136 | +Resize an image file with the configuration provided in the initialization options |
| 137 | + |
| 138 | +#### Parameters: |
| 139 | +| Name | Type | Description | |
| 140 | +|---------------|------|--------------------------| |
| 141 | +| imageFile | file | The image file to resize | |
| 142 | + |
| 143 | +#### Returns: |
| 144 | +Promise that resolves to the output object |
| 145 | + |
| 146 | +| Name | Type | Description | |
| 147 | +|----------|--------------------|--------------------------------------------------------------------| |
| 148 | +| output | blob/base64 string | Blob or base64 string based on configuration | |
| 149 | +| metadata | object | Metadata about initial image dimensions and final image dimensions | |
| 150 | + |
| 151 | +##### Metadata |
| 152 | +| Name | Type | Description | |
| 153 | +|----------------|------|-----------------------| |
| 154 | +| originalHeight | int | Original image height | |
| 155 | +| originalWidth | int | Original image width | |
| 156 | +| resizedHeight | int | Resized image height | |
| 157 | +| resizedWidth | int | Resized image width | |
| 158 | + |
| 159 | +## License |
| 160 | + |
| 161 | +[MIT](http://opensource.org/licenses/MIT) |
0 commit comments