Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

https://github.com/mooyoul/get-orientation

Get orientation from EXIF of image file. Supports both Browser and Node.js
https://github.com/mooyoul/get-orientation

exif image jpeg tiff

Last synced: 11 days ago
JSON representation

Get orientation from EXIF of image file. Supports both Browser and Node.js

Host: GitHub
URL: https://github.com/mooyoul/get-orientation
Owner: mooyoul
License: mit
Created: 2019-03-10T01:06:44.000Z (over 5 years ago)
Default Branch: master
Last Pushed: 2024-09-27T08:07:24.000Z (about 2 months ago)
Last Synced: 2024-10-16T02:02:42.824Z (29 days ago)
Topics: exif, image, jpeg, tiff
Language: TypeScript
Homepage: https://mooyoul.github.io/get-orientation/
Size: 7.44 MB
Stars: 117
Watchers: 3
Forks: 3
Open Issues: 32
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

README

        # get-orientation

[![Build Status](https://travis-ci.com/mooyoul/get-orientation.svg?branch=master)](https://travis-ci.com/mooyoul/get-orientation)

[![BrowserStack Status](https://automate.browserstack.com/badge.svg?badge_key=cFNiUHduTHZpVVFDKzJCTVFhQUtyUFhJVXRlRDRCYU1UdTlvRVZVUmhnMD0tLWIxZ1hkRWxpNjVGL09uUzdnYlMydlE9PQ==--7b310907b4d628c5942ccc11899b8df415cb2393)](https://automate.browserstack.com/public-build/cFNiUHduTHZpVVFDKzJCTVFhQUtyUFhJVXRlRDRCYU1UdTlvRVZVUmhnMD0tLWIxZ1hkRWxpNjVGL09uUzdnYlMydlE9PQ==--7b310907b4d628c5942ccc11899b8df415cb2393)

[![Semantic Release enabled](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)

![npm bundle size (minified)](https://img.shields.io/bundlephobia/min/get-orientation.svg)

[![Renovate enabled](https://img.shields.io/badge/renovate-enabled-brightgreen.svg)](https://renovatebot.com/)

[![MIT license](http://img.shields.io/badge/license-MIT-blue.svg)](http://mooyoul.mit-license.org/)

Get orientation from EXIF of image file. Supports both Browser and Server (Node.js) environment.

`get-orientation` has fast, efficient built-in EXIF parser. 

Built-in EXIF Parser is stream-based, and uses small memory footprint.

Also, Compatibility is the key. `get-orientation` was tested with 50+ test images.

## Sponsor

- [CATCH](https://www.catchfashion.com/) - 캐치패션 - 세상 쉬운 명품 직구 - [We're hiring!](https://www.wanted.co.kr/company/2378)

## Demo

https://mooyoul.github.io/get-orientation/

## Why?

![adaption stats of CSS3 Image Orientation](/docs/why-2.png)

Most Browsers don't rotate images automatically.

Hmm... How about adaption stats of CSS3 Image Orientation?

![missing auto rotation](/docs/why-1.png)

Well. Good luck. 

To rotate image by its orientation, you'll have to make a EXIF parser or install heavy EXIF related libraries.

That's why i made this.           

## Compatibility

get-orientation works in major environments, including IE 10.

#### Tested Platforms (Node.js) 

Platform | Environment | Build | Compatibility 

-------- | ----------- | ----- | -------------

macOS Mojave | Node.js 4 | Default | Compatible

macOS Mojave | Node.js 6 | Default | Compatible

Linux Ubuntu Trusty | Node.js 6 | Default | Compatible

macOS Mojave | Node.js 8 | Default | Compatible

Linux Ubuntu Trusty | Node.js 10 | Default | Compatible

macOS Mojave | Node.js 10 | Default | Compatible

#### Tested Platforms (Browser)

Platform | Environment | Build | Compatibility

-------- | ----------- | ----- | -------------

Windows XP/7 | ~ IE 9 | N/A | Incompatible due to missing FileReader/DataView support   

Windows 7 | IE 10 | Browser/ES5 | Compatible, Requires Promise and WeakMap polyfill

Windows 7| IE 11 | Browser/ES5 | Compatible, Requires Promise polyfill

Windows 10 | IE 11 | Browser/ES5 | Compatible, Requires Promise polyfill

macOS Mojave | Chrome 74 | Browser/ES6 (Default) | Compatible

macOS Mojave | Safari | Browser/ES6 (Default) | Compatible

macOS Mojave | Safari TP | Browser/ES6 (Default) | Compatible

macOS Mojave | Firefox Developer Edition 67 | Browser/ES6 (Default) | Compatible

macOS Mojave | Firefox 65 | Browser/ES6 (Default) | Compatible

iOS 12.0.1 | Safari | Browser/ES6 (Default) | Compatible

Android 5 | Mobile Chrome 74 | Browser/ES6 (Default) | Compatible

## Install

#### from NPM

```bash

$ npm install get-orientation

```

#### from unpkg

```html

```

## Supported Image Format

- JPEG/JFIF

- JPEG/EXIF

- TIFF/EXIF

    

 

## Usage

#### Node.js

```typescript

import * as fs from "fs";

import { getOrientation } from "get-orientation";

// using Readable File Stream as input

const stream = fs.createReadStream(imageFilePath);

const orientation = await getOrientation(stream);

// using Buffer as input

const bufFile = fs.readFileSync(imageFilePath);

const orientation = await getOrientation(bufFile);

// using HTTP Response body as input

import axios from "axios";

const response = await axios({ url, responseType: "stream" });

const orientation = await getOrientation(response.data);

// using Stream interface directly

import { EXIFOrientationParser, Orientation } from "get-orientation";

const parser = new EXIFOrientationParser();

parser.on("orientation", (orientation: Orientation) => {

  console.log("got orientation: ", orientation);

});

fs.createReadStream(imageFilePath).pipe(parser);

```

#### Browser

```javascript

import { getOrientation } from "get-orientation/browser";

async function onFileChanged() {

  const orientation = await getOrientation(fileInput.files[0]);

  // do stuff...

}

```

> *IMPORTANT NOTE*

>

> The ES5 target browser build does not include any Polyfills like Promise/A+.

> For example, To use this library from Microsoft Internet Explorer 11, You'll have to polyfill Promise.

 

## API (Node.js)

### `getOrientation(input: Buffer | ReadableStream)` => `Promise`

returns Orientation of given image.

If image is non-jpeg image, or non-image, `getOrientation` will return Orientation.TOP_LEFT (Horizontal - Default value).  

### `new EXIFOrientationParser()` => `WritableStream`

returns a parser stream instance that implements WritableStream interface.

Please note that EXIFOrientationParser won't emit any `orientation` event if stream doesn't have any Orientation tags.

also, Stream will be closed without any errors.

For example, Using non-EXIF images, non-JPEG images as input won't emit a `orientation` event.     

#### Stream Events

##### `orientation`

emitted after parsing orientation.

## API (Browser)

### `getOrientation(input: ArrayBuffer | Blob | File)` => `Promise` 

returns Orientation of given image.

If image is non-jpeg image, or non-image, `getOrientation` will return Orientation.TOP_LEFT (Horizontal - Default value).

## Types

### Orientation

```typescript

enum Orientation {

  TOP_LEFT = 1,         // Horizontal (Default)

  TOP_RIGHT = 2,        // Mirror Horizontal

  BOTTOM_RIGHT  = 3,    // Rotate 180

  BOTTOM_LEFT = 4,      // Mirror vertical

  LEFT_TOP = 5,         // Mirror horizontal and rotate 270 CW

  RIGHT_TOP = 6,        // Rotate 90 CW

  RIGHT_BOTTOM = 7,     // Mirror horizontal and rotate 90 CW

  LEFT_BOTTOM = 8,      // Rotate 270 CW

}

```

## Changelog

See [CHANGELOG](/CHANGELOG.md).

## Testing

```bash

$ npm run test

```

[![BrowserStack Logo](/docs/browserstack.png)](https://www.browserstack.com/)

get-orientation uses [BrowserStack](https://www.browserstack.com/) for compatibility testing.

## Build

```bash

$ npm run build

```

## Related

- [mooyoul/node-webpinfo](https://github.com/mooyoul/node-webpinfo) - Strongly typed, Stream based WebP Container Parser

## License

[MIT](LICENSE)

See full license on [mooyoul.mit-license.org](http://mooyoul.mit-license.org/)