139 lines
4.3 KiB
Plaintext
139 lines
4.3 KiB
Plaintext
probe-image-size
|
|
================
|
|
|
|
[](https://github.com/nodeca/probe-image-size/actions)
|
|
[](https://www.npmjs.org/package/probe-image-size)
|
|
[](https://coveralls.io/github/nodeca/probe-image-size?branch=master)
|
|
|
|
> Get image size without full download. Supported image types:
|
|
> JPG, GIF, PNG, WebP, BMP, TIFF, SVG, PSD, ICO, AVIF, HEIC, HEIF.
|
|
|
|
Key features:
|
|
|
|
- small size, no heavy dependencies
|
|
- works with remote and local data
|
|
- effective with big images (speed/memory), download minimal data from remotes
|
|
- extracts orientation value when available
|
|
- easy to browserify (splitted to components)
|
|
|
|
|
|
Install
|
|
-------
|
|
|
|
```bash
|
|
npm install probe-image-size
|
|
```
|
|
|
|
Example
|
|
-------
|
|
|
|
```js
|
|
const probe = require('probe-image-size');
|
|
|
|
// Get by URL
|
|
let result = await probe('http://example.com/image.jpg');
|
|
console.log(result); // =>
|
|
/*
|
|
{
|
|
width: xx,
|
|
height: yy,
|
|
type: 'jpg',
|
|
mime: 'image/jpeg',
|
|
wUnits: 'px',
|
|
hUnits: 'px',
|
|
url: 'http://example.com/image.jpg'
|
|
}
|
|
*/
|
|
|
|
|
|
// By URL with options
|
|
let result = await probe('http://example.com/image.jpg', { rejectUnauthorized: false });
|
|
console.log(result);
|
|
|
|
|
|
// From the stream
|
|
let result = await probe(require('fs').createReadStream('image.jpg'));
|
|
console.log(result);
|
|
|
|
|
|
// From a Buffer (sync)
|
|
let data = require('fs').readFileSync('image.jpg');
|
|
console.log(probe.sync(data));
|
|
```
|
|
|
|
|
|
API
|
|
---
|
|
|
|
Note:
|
|
|
|
- You can access/browserify `stream.js` / `http.js` / `sync.js` directly.
|
|
- If you don't like `http.js` dependencies, you can create your own wrapper
|
|
for `stream.js`.
|
|
|
|
### probe(src [, options|keepOpen]) -> Promise
|
|
|
|
- `src` can be of this types:
|
|
- _String_ - URL to fetch
|
|
- _Stream_ - readable stream
|
|
- `options` - HTTP only. See [`needle` documentation](https://github.com/tomas/needle#request-options), and customized [defaults](https://github.com/nodeca/probe-image-size/blob/master/http.js#L13).
|
|
- `keepOpen` (Boolean) - stream only. Keep stream open after parser finishes
|
|
(input stream will be closed by default)
|
|
|
|
`result` (Promise) contains:
|
|
|
|
```js
|
|
{
|
|
width: XX,
|
|
height: YY,
|
|
length: ZZ, // byte length of the file (if available, HTTP only)
|
|
type: ..., // image 'type' (usual file name extention)
|
|
mime: ..., // mime type
|
|
wUnits: 'px', // width units type ('px' by default, can be different for SVG)
|
|
hUnits: 'px', // height units type ('px' by default, can be different for SVG)
|
|
url: ..., // HTTP only, last url for the image in chain of redirects
|
|
// (if no redirects, same as src)
|
|
|
|
// optional, image orientation (from Exif), number from 1 to 8;
|
|
// you may wish to swap width and height if orientation is >= 5
|
|
orientation: X,
|
|
|
|
// optional, full list of sizes for ICO (always) and AVIF (if multiple images)
|
|
variants: [ { width, height }, ... ] | undefined
|
|
}
|
|
```
|
|
|
|
Width and height in the output object represent image size *before* any transformations
|
|
(orientation, cropping) are applied. Orientation is returned separately, which you may
|
|
wish to apply afterwards depending on browser support (browsers
|
|
[only support JPEG](https://zpl.fi/exif-orientation-in-different-formats/) orientation for now).
|
|
See [known issues](known_issues.md) for details.
|
|
|
|
Returned errors can be extended with 2 fields:
|
|
|
|
- `code` - equals to `ECONTENT` if the library failed to parse the file;
|
|
- `status` - equals to a HTTP status code if it receives a non-200 response.
|
|
|
|
|
|
### probe.sync(src) -> result|null
|
|
|
|
Sync version can eat arrays, typed arrays and buffers. On success it returns
|
|
the same result as async version. On fail it returns null.
|
|
|
|
__Note.__ Formats like JPEG & TIFF can store size anywhere (far from the head).
|
|
That usually does not happens, but if you need guarantees - always provide full
|
|
file content to sync methods. We strongly recommend to use async version
|
|
as memory-friendly.
|
|
|
|
|
|
Similar projects
|
|
----------------
|
|
|
|
- [image-size](https://github.com/netroy/image-size)
|
|
|
|
|
|
Support probe-image-size
|
|
------------------------
|
|
|
|
You can support this project via [Tidelift subscription](https://tidelift.com/subscription/pkg/npm-probe-image-size?utm_source=npm-probe-image-size&utm_medium=referral&utm_campaign=readme).
|