148 lines
3.9 KiB
Markdown
148 lines
3.9 KiB
Markdown
probe-image-size
|
|
================
|
|
|
|
[](https://travis-ci.org/nodeca/probe-image-size)
|
|
[](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.
|
|
|
|
Key features:
|
|
|
|
- small size, no heavy dependencies
|
|
- works with remote and local data
|
|
- effective with big images (speed/memory), download minimal data from remotes
|
|
- easy to browserify (splitted to components)
|
|
|
|
|
|
Install
|
|
-------
|
|
|
|
```bash
|
|
npm install probe-image-size --save
|
|
```
|
|
|
|
Example
|
|
-------
|
|
|
|
```js
|
|
var probe = require('probe-image-size');
|
|
|
|
// Get by URL
|
|
//
|
|
probe('http://example.com/image.jpg').then(result => {
|
|
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
|
|
//
|
|
probe('http://example.com/image.jpg', { timeout: 5000 }).then(function (result) {
|
|
console.log(result);
|
|
});
|
|
|
|
// With callback
|
|
//
|
|
probe('http://example.com/image.jpg', function (err, result) {
|
|
console.log(result);
|
|
});
|
|
|
|
// From the stream
|
|
//
|
|
var input = require('fs').createReadStream('image.jpg');
|
|
|
|
probe(input).then(result => {
|
|
console.log(result);
|
|
|
|
// terminate input, depends on stream type,
|
|
// this example is for fs streams only.
|
|
input.destroy();
|
|
});
|
|
|
|
// From a Buffer
|
|
//
|
|
var data = require('fs').readFileSync('image.jpg');
|
|
|
|
console.log(probe.sync(data));
|
|
```
|
|
|
|
|
|
API
|
|
---
|
|
|
|
### probe(src [, options, callback]) -> Promise
|
|
|
|
`src` can be of this types:
|
|
|
|
- __String__ - URL to fetch
|
|
- __Stream__ - readable stream
|
|
|
|
`options` - HTTP only. See [`got` documentation](https://github.com/sindresorhus/got).
|
|
Defaults changed to `{ retries: 1, timeout: 30000 }`
|
|
|
|
`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: ..., // last url for the image in chain of redirects (if no redirects, same as src) (HTTP only)
|
|
}
|
|
```
|
|
|
|
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.
|
|
|
|
If callback (legacy node style) provided, `Promise` will not be returned.
|
|
|
|
__Note 1.__ If you use `Stream` as source, it's your responsibility to close that
|
|
stream in callback. In other case you can get memory leak, because stream will
|
|
be left in paused state. With http requests that's not a problem - everything
|
|
is released automatically, as soon as possible.
|
|
|
|
__Note 2.__ We still support legacy v2.x signature for http probe (`src` is
|
|
Object as described in [request](https://github.com/request/request)). But it
|
|
will be deprecated in next versions.
|
|
|
|
|
|
### sync.probe(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)
|
|
- [imagesize](https://github.com/arnaud-lb/imagesize.js)
|
|
|
|
|
|
License
|
|
-------
|
|
|
|
[MIT](https://raw.github.com/nodeca/probe-image-size/master/LICENSE)
|