Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/nodeca/probe-image-size

Get image size without full download. Supported image types: JPG, GIF, PNG, WebP, BMP, TIFF, SVG, PSD, ICO.
https://github.com/nodeca/probe-image-size

Last synced: about 18 hours ago
JSON representation

Get image size without full download. Supported image types: JPG, GIF, PNG, WebP, BMP, TIFF, SVG, PSD, ICO.

Awesome Lists containing this project

README 

        
probe-image-size

================



[![CI](https://github.com/nodeca/probe-image-size/workflows/CI/badge.svg?branch=master)](https://github.com/nodeca/probe-image-size/actions)

[![NPM version](https://img.shields.io/npm/v/probe-image-size.svg?style=flat)](https://www.npmjs.org/package/probe-image-size)

[![Coverage Status](https://coveralls.io/repos/github/nodeca/probe-image-size/badge.svg?branch=master)](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).