|
| 1 | +# image-size |
| 2 | + |
| 3 | +[](https://circleci.com/gh/image-size/image-size) |
| 4 | +[](https://www.npmjs.com/package/image-size) |
| 5 | +[](http://npm-stat.com/charts.html?package=image-size&author=netroy&from=&to=) |
| 6 | + |
| 7 | +Fast, lightweight NodeJS package to get dimensions of any image file or buffer. |
| 8 | + |
| 9 | +## Key Features |
| 10 | +- Zero dependencies |
| 11 | +- Supports all major image formats |
| 12 | +- Works with both files and buffers |
| 13 | +- Minimal memory footprint - reads only image headers |
| 14 | +- ESM and CommonJS support |
| 15 | +- TypeScript types included |
| 16 | + |
| 17 | +## Supported formats |
| 18 | + |
| 19 | +- BMP |
| 20 | +- CUR |
| 21 | +- DDS |
| 22 | +- GIF |
| 23 | +- HEIC (HEIF, AVCI, AVIF) |
| 24 | +- ICNS |
| 25 | +- ICO |
| 26 | +- J2C |
| 27 | +- JPEG-2000 (JP2) |
| 28 | +- JPEG |
| 29 | +- JPEG-XL |
| 30 | +- KTX (1 and 2) |
| 31 | +- PNG |
| 32 | +- PNM (PAM, PBM, PFM, PGM, PPM) |
| 33 | +- PSD |
| 34 | +- SVG |
| 35 | +- TGA |
| 36 | +- TIFF |
| 37 | +- WebP |
| 38 | + |
| 39 | +## Installation |
| 40 | + |
| 41 | +```shell |
| 42 | +npm install image-size |
| 43 | +# or |
| 44 | +yarn add image-size |
| 45 | +# or |
| 46 | +pnpm add image-size |
| 47 | +``` |
| 48 | + |
| 49 | +## Usage |
| 50 | + |
| 51 | +### Passing in a Buffer/Uint8Array |
| 52 | +Best for streams, network requests, or when you already have the image data in memory. |
| 53 | + |
| 54 | +```javascript |
| 55 | +import { imageSize } from 'image-size' |
| 56 | +// or |
| 57 | +const { imageSize } = require('image-size') |
| 58 | + |
| 59 | +const dimensions = imageSize(buffer) |
| 60 | +console.log(dimensions.width, dimensions.height) |
| 61 | +``` |
| 62 | + |
| 63 | +### Reading from a file |
| 64 | +Best for local files. Returns a promise. |
| 65 | + |
| 66 | +```javascript |
| 67 | +import { imageSizeFromFile } from 'image-size/fromFile' |
| 68 | +// or |
| 69 | +const { imageSizeFromFile } = require('image-size/fromFile') |
| 70 | + |
| 71 | +const dimensions = await imageSizeFromFile('photos/image.jpg') |
| 72 | +console.log(dimensions.width, dimensions.height) |
| 73 | +``` |
| 74 | + |
| 75 | +Note: Reading from files has a default concurrency limit of **100** |
| 76 | +To change this limit, you can call the `setConcurrency` function like this: |
| 77 | + |
| 78 | +```javascript |
| 79 | +import { setConcurrency } from 'image-size/fromFile' |
| 80 | +// or |
| 81 | +const { setConcurrency } = require('image-size/fromFile') |
| 82 | +setConcurrency(123456) |
| 83 | +``` |
| 84 | + |
| 85 | +### Reading from a file Syncronously (not recommended) ⚠️ |
| 86 | +v1.x of this library had a sync API, that internally used sync file reads. |
| 87 | + |
| 88 | +This isn't recommended because this blocks the node.js main thread, which reduces the performance, and prevents this library from being used concurrently. |
| 89 | + |
| 90 | +However if you still need to use this package syncronously, you can read the file syncronously into a buffer, and then pass the buffer to this library. |
| 91 | + |
| 92 | +```javascript |
| 93 | +import { readFileSync } from 'node:fs' |
| 94 | +import { imageSize } from 'image-size' |
| 95 | + |
| 96 | +const buffer = readFileSync('photos/image.jpg') |
| 97 | +const dimensions = imageSize(buffer) |
| 98 | +console.log(dimensions.width, dimensions.height) |
| 99 | +``` |
| 100 | + |
| 101 | +### 3. Command Line |
| 102 | +Useful for quick checks. |
| 103 | + |
| 104 | +```shell |
| 105 | +npx image-size image1.jpg image2.png |
| 106 | +``` |
| 107 | + |
| 108 | +### Multi-size |
| 109 | + |
| 110 | +If the target file/buffer is an HEIF, an ICO, or a CUR file, the `width` and `height` will be the ones of the largest image in the set. |
| 111 | + |
| 112 | +An additional `images` array is available and returns the dimensions of all the available images |
| 113 | + |
| 114 | +```javascript |
| 115 | +import { imageSizeFromFile } from 'image-size/fromFile' |
| 116 | +// or |
| 117 | +const { imageSizeFromFile } = require('image-size/fromFile') |
| 118 | + |
| 119 | +const { images } = await imageSizeFromFile('images/multi-size.ico') |
| 120 | +for (const dimensions of images) { |
| 121 | + console.log(dimensions.width, dimensions.height) |
| 122 | +} |
| 123 | +``` |
| 124 | + |
| 125 | +### Using a URL |
| 126 | + |
| 127 | +```javascript |
| 128 | +import url from 'node:url' |
| 129 | +import http from 'node:http' |
| 130 | +import { imageSize } from 'image-size' |
| 131 | + |
| 132 | +const imgUrl = 'http://my-amazing-website.com/image.jpeg' |
| 133 | +const options = url.parse(imgUrl) |
| 134 | + |
| 135 | +http.get(options, function (response) { |
| 136 | + const chunks = [] |
| 137 | + response |
| 138 | + .on('data', function (chunk) { |
| 139 | + chunks.push(chunk) |
| 140 | + }) |
| 141 | + .on('end', function () { |
| 142 | + const buffer = Buffer.concat(chunks) |
| 143 | + console.log(imageSize(buffer)) |
| 144 | + }) |
| 145 | +}) |
| 146 | +``` |
| 147 | + |
| 148 | +### Disabling certain image types |
| 149 | + |
| 150 | +```javascript |
| 151 | +import { disableTypes } from 'image-size' |
| 152 | +// or |
| 153 | +const { disableTypes } = require('image-size') |
| 154 | + |
| 155 | +disableTypes(['tiff', 'ico']) |
| 156 | +``` |
| 157 | + |
| 158 | +### JPEG image orientation |
| 159 | + |
| 160 | +If the orientation is present in the JPEG EXIF metadata, it will be returned by the function. The orientation value is a [number between 1 and 8](https://exiftool.org/TagNames/EXIF.html#:~:text=0x0112,8%20=%20Rotate%20270%20CW) representing a type of orientation. |
| 161 | + |
| 162 | +```javascript |
| 163 | +import { imageSizeFromFile } from 'image-size/fromFile' |
| 164 | +// or |
| 165 | +const { imageSizeFromFile } = require('image-size/fromFile') |
| 166 | + |
| 167 | +const { width, height, orientation } = await imageSizeFromFile('images/photo.jpeg') |
| 168 | +console.log(width, height, orientation) |
| 169 | +``` |
| 170 | + |
| 171 | +# Limitations |
| 172 | + |
| 173 | +1. **Partial File Reading** |
| 174 | + - Only reads image headers, not full files |
| 175 | + - Some corrupted images might still report dimensions |
| 176 | + |
| 177 | +2. **SVG Limitations** |
| 178 | + - Only supports pixel dimensions and viewBox |
| 179 | + - Percentage values not supported |
| 180 | + |
| 181 | +3. **File Access** |
| 182 | + - Reading from files has a default concurrency limit of 100 |
| 183 | + - Can be adjusted using `setConcurrency()` |
| 184 | + |
| 185 | +4. **Buffer Requirements** |
| 186 | + - Some formats (like TIFF) require the full header in buffer |
| 187 | + - Streaming partial buffers may not work for all formats |
| 188 | + |
| 189 | +## License |
| 190 | + |
| 191 | +MIT |
| 192 | + |
| 193 | +## Credits |
| 194 | + |
| 195 | +not a direct port, but an attempt to have something like |
| 196 | +[dabble's imagesize](https://github.com/dabble/imagesize/blob/master/lib/image_size.rb) as a node module. |
| 197 | + |
| 198 | +## [Contributors](Contributors.md) |
0 commit comments