Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

https://github.com/mattdesl/google-panorama-equirectangular

gets equirectangular images from Google StreetView
https://github.com/mattdesl/google-panorama-equirectangular

Last synced: 17 days ago
JSON representation

gets equirectangular images from Google StreetView

Awesome Lists containing this project

README

        

# google-panorama-equirectangular

[![experimental](http://badges.github.io/stability-badges/dist/experimental.svg)](http://github.com/badges/stability-badges)

[![2d](http://i.imgur.com/AukW6Mv.png)](http://mattdesl.github.io/google-panorama-equirectangular/demo/)

[webgl demo](http://mattdesl.github.io/google-panorama-equirectangular/demo/) - [source](./demo/gpu.js)

Stitches Google Street View and Photo Sphere tiles into an equirectangular image. For use in the browser, with Webpack or Browserify.

Also includes an [intermediate mode](#intermediate-mode) for higher quality WebGL rendering on low-end devices.

## Install

```sh
npm install google-panorama-equirectangular
```

## Example

For full examples, see the [demo/](demo/) folder, or [running from source](#running-from-source) for details.

Make sure to include the Google Client library first:

```html

```

Then, in JavaScript:

```js
var load = require('google-panorama-equirectangular')
var panoID = 'dXZfBMex9_L7jO2JW3FTdA'

load(panoID, { zoom: 2 })
.on('start', function (data) {
console.log('canvas size: ', data.width, data.height)
})
.on('progress', function (ev) {
console.log('progress: ', ev.count / ev.total)
})
.on('complete', function (image) {
document.body.appendChild(image)
console.log('canvas image: ', image)
})
```

## Usage

[![NPM](https://nodei.co/npm/google-panorama-equirectangular.png)](https://www.npmjs.com/package/google-panorama-equirectangular)

#### `emitter = load(id, [opt])`

Creates a new StreetView stitcher with `id` and optional settings. `opt` can be:

- `zoom` an integer between 0 and 5 (inclusive), defaults to 1
- `canvas` a HTMLCanvasElement to re-use, defaults to creating a new element
- `tiles` is the tile dimensions from `getPanoramaByLocation` or `getPanoramaById`, defaults to assuming StreetView image dimensions
- `crossOrigin` crossOrigin String for image loading, defaults to `undefined`
- `width` some new StreetView IDs can be fetched by size; if the ID falls into this category, the returned image will ignore the `zoom` parameter and instead try to find something by `width*(width / 2)` dimensions
- `protocol` the protocol to use when requesting images; defaults to undefined which will load a protocol-relative URL (`//foo.com/`) but you can specify an exact protocol if desired (which may be necessary in some environments like CocoonJS), such as `'http'` or `'https'`

Here is an example using [google-panorama-by-id](https://github.com/Jam3/google-panorama-by-id).

It's recommended you specify `tiles` for an accurate result across different image types (panorama, photo sphere, etc).

```js
var load = require('google-panorama-equirectangular')
var panoData = require('google-panorama-by-id')
var id = 'dXZfBMex9_L7jO2JW3FTdA'

panoData(id, function (err, result) {
var tiles = result.tiles
load(id, { tiles: tiles, zoom: 2, canvas: myCanvas })
})
```

### events

#### `emitter.on('start', fn)`

Called when the stitching process begins, with `data` parameter that includes the output of [google-panorama-tiles](https://github.com/Jam3/google-panorama-tiles):

```js
{
columns: Number, // x tile count
rows: Number, // y tile count
tileWidth: Number, // tile size
tileHeight: Number, // tile size
width: Number, // canvas size
height: Number, // canvas size
legacy: Boolean // false if this is from the new API
}
```

#### `emitter.on('progress', fn)`

Called after a new tile has been loaded and drawn to the canvas.

```js
{
count: Number, // current # of tiles loaded
total: Number, // total number of tiles
image: Image, // an image for this tile, might be null
position: [x, y], // the pixel position of the tile in the full image
}
```

In [intermediate mode](#intermediate-mode), the `image` might be an Image or a Canvas, depending on crop.

#### `emitter.on('not-found', fn)`

Called when an image is skipped due to it not being found. The `url` is passed.

#### `emitter.on('complete', fn)`

Called when the stitching is complete. The resulting `canvas` is passed as the parameter.

In [intermediate mode](#intermediate-mode), the passed `canvas` is the one used during cropping.

## Intermediate Mode

The default export stitches all tiles into a single Canvas element. This is convenient, but not ideal for low-end devices like iOS Safari. In some browsers, there is a maximum size for canvas elements, and no way to query this value.

For example, in a 256MB RAM iPhone, the full canvas size must be less than `1024 * 1024 * 3` (3 MP).

WebGL applications can leverage "intermediate rendering" mode which keeps no more than a single 512x512 canvas in memory at a time. This allows higher quality panoramas to be stitched on low-end devices. The interface is the same, and can be required like this:

```js
var equirect = require('google-panorama-equirectangular/intermediate')
```

Each `'progress'` event simply returned a cropped image for that tile. You will need to stitch and upload sub-images yourself to WebGL. See [demo/gpu.js](demo/gpu.js) for an example.

In intermediate mode, the `imgage` field of `'progress'` events might be a canvas or image, depending on whether a crop was necessary. The `originalImage` is provided to allow access to the HTMLImageElement, so the event data is:

```js
{
count: Number,
total: Number,
image: Canvas|Image,
position: [x, y],
originalImage: Image
}
```

## Running From Source

To run the demos from source:

```sh
git clone https://github.com/mattdesl/google-panorama-equirectangular.git
cd google-panorama-equirectangular
npm install
```

Now run one of the demos:

```sh
# the simple WebGL demo
npm run webgl

# the simple 2D DOM demo
npm run 2d

# the GPU stitching demo
npm run gpu
```

And open [http://localhost:9966/](http://localhost:9966/). Changing the source will re-load the browser page.

## Also See

- [google-panorama-zoom-level](https://github.com/Jam3/google-panorama-zoom-level)
- [google-panorama-by-id](https://github.com/Jam3/google-panorama-by-id)
- [google-panorama-by-location](https://github.com/Jam3/google-panorama-by-location)
- [google-panorama-tiles](https://github.com/Jam3/google-panorama-tiles)
- [awesome-streetview](https://github.com/Jam3/awesome-streetview)

## Credits

Thanks to @thespite's prior work on [PanomNom.js](https://github.com/spite/PanomNom.js/), which was used as a reference while building these modules.

## License

MIT, see [LICENSE.md](http://github.com/mattdesl/google-panorama-equirectangular/blob/master/LICENSE.md) for details.