# rxpan

> Panorama Editor

Latest version **0.1.34** (published 2021-04-28) · MIT license · 0 weekly downloads

## Install

```sh
npm install rxpan
pnpm add rxpan
yarn add rxpan
bun add rxpan
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; large bundle; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.34 |
| Published | 2021-04-28 |
| First published | 2021-01-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 16.4 MB |
| Known vulnerabilities | 0 (+12 in 2 direct dependencies) |
| Install scripts | no |
| Author | Dave Seidman |
| Maintainers | daveseidman |

## Links

- npm: https://www.npmjs.com/package/rxpan
- npm.io page: https://npm.io/package/rxpan

## Dependencies (4)

- [three](https://npm.io/package/three.md) ^0.115.0
- [multer](https://npm.io/package/multer.md) ^1.4.2
- [auto-bind](https://npm.io/package/auto-bind.md) ^4.0.0
- [@tweenjs/tween.js](https://npm.io/package/@tweenjs/tween.js.md) ^18.6.4

## Recent versions

- 0.1.34 (latest) — 2021-04-28
- 0.1.33 — 2021-04-26
- 0.1.32 — 2021-04-26
- 0.1.31 — 2021-04-26
- 0.1.3 — 2021-04-22
- 0.1.29 — 2021-04-22
- 0.1.28 — 2021-04-20
- 0.1.27 — 2021-04-16
- 0.1.25 — 2021-04-15
- 0.1.24 — 2021-04-15
- 0.1.23 — 2021-04-15
- 0.1.22 — 2021-04-14
- 0.1.21 — 2021-04-14
- 0.1.2 — 2021-04-08
- 0.1.1 — 2021-04-05
- … 112 more at https://npm.io/package/rxpan/versions

## README

# RxPan

A 360 panorama **viewer** and **editor** that works in modern browsers including mobile.<br>  
#### Viewer:
![RxPan viewer](https://rx-co.de/rxpan/viewer-example.gif)

#### Editor:
![RxPan editor](https://rx-co.de/rxpan/editor-example.gif)
---

## <b>Viewer</b>

#### Structure:
The RxPan editor allows you to create **tours** which are saved as .json files or can be embedded in your markup.  


A **tour** consists of one or more **locations**.<br>
A **location** can be rotated and zoomed and may contain **portals** and **hotspots**.<br>
A **portal** allows the user to go from one **location** to another.<br>
A **hotspot** dispatches events that you can listen to and use to show popups or take other actions.


#### Usage:

```
const rxpan = new RxPan(element, config, options);
```

<details>
<summary>Create an RxPan Viewer using the module:</summary>

```
import RxPan from 'rxpan';                     // import the module  
import config from 'config.json';              // import the config file

const element = document.createElement('div'); // create a container
document.body.appendChild(element);            // add it to the DOM

const viewer = new RxPan(element, config);      // create a viewer inside the container

```

</details><br>

<details>
<summary>Create an RxPan Viewer using script tags:</summary>

```
<script src='node_modules/rxpan/viewer.js'></script>        <!-- import the module -->

<script>
  const element = document.createElement('div');            // create a container
  document.body.appendChild(element);                       // add it to the DOM

  fetch('config.json').then(e => e.json()).then(config => { // fetch the config file
    const viewer = new RxPan(element, config);         // create the viewer inside the container
  });
</script>

```

</details><br>

<details>
<summary>Alternate method (config in markup):</summary>

```
<!-- tour config as markup -->
<rxpan id='example1' imagesDirectory='/editor/client/example-images' initialLocation='home'>
  <location id='home' image='center.png' rotation='0' />
    <portal id='back-left' angle='224.691' distance='7.086' />
  </location>
  <location id='back-left' image='back-left.png' rotation='0' />
    <hotspot id='popup' angle='66.550' height='-13.114' />
    <portal id='home' angle='45.447' distance='7.070' />
  </location>
</rxpan>

<script src='node_modules/rxpan/viewer.js'></script>   <!-- import the module -->

<script>
  const element = document.getElementById('example1'); // select the container
  const viewer = new RxPan(element, config);      // create the viewer inside the container
</script>

```

</details>

#### Config

```
tour  
├─ imagesDirectory <string> where the panorama images are located
├─ initialLocation <string> the location to display on load
└─ location <object>
   ├─ id <string> the name of the location (referenced by portals)
   ├─ image <string> the image file relative to imagesDirectory
   ├─ rotation <number> an initial rotaion offset for this location
   ├─ portal  
   |  ├─ id <string> the name of the location the portal should link to
   |  ├─ angle <number> the longitudinal angle of the portal 0-360 degrees. 0 = directly in front of camera
   │  └─ distance <number> the distance from the camera (0 - 50) 0 = directly under the camera, 50 = at the horizon
   └─ hotspot
      ├─ id <string> the name of the hotspot
      ├─ angle <number> the longitudinal angle of the hotspot 0-360 degrees. 0 = directly in front of camera
      └─ height <number> the latitudinal angle of the hotspot (-90 = directly above camera, 90 = directly below)
```


#### Options

**autoResize** - viewer resizes as it's containing DOM element's dimensions change. If _false_, call `viewer.resize()` to manually update its dimensions. Default is _true._  
**hideRxPanLogo** - hide the default RxPan background while panorama images load. Default is _false._   
**preload** - viewer will load the panorama images for each location in the tour before showing the initialLocation. Default is _false._  
**debug** - log all viewer events to the console. Default is _false._  
**hideProgress** - hide the progress bar while images are loading. Default is _false._  

#### Methods  

**viewer.goto(locationName)** - goes to a new location in the tour.   
**viewer.lookat({ x, y, z })**  - points the camera at a position in 3d space.  
**viewer.resize()** - resizes the webgl canvas to fit it's container.  
**viewer.destroy()** - removes the viewer's DOM element and all listeners attached to it.  

#### Events

**viewer.addEventListener('portal', portalClicked)**  - get notified when user moves to a new location.   
**viewer.addEventListener('hotspot', hotspotClicked)**  - get notified when a user clicks a hotspot.

---

# <b>Editor</b>

RxPan comes pre-packaged with an example tour to help get you started.  

In a terminal, run:
```
npm install rxpan  
cd node_modules/rxpan  
npm start
```  
In a browser, visit:  
**http://localhost:9000/example.html** - the example tour embedded within a page.  
**http://localhost:9000**  - the editor  

There are instructions within the editor that will guide you through the process of creating a tour from scratch, modifying or deleting an existing tour.

---


# <b>Development</b>  

If you'd like to work on the viewer or editor, this is the preferred method:  

Clone the [rxpan repo](https://git.fcb.io/studiorx/rx-pan)      
Within that folder run `npm link` to create a global symlink.   
Within the folder of a project that uses RxPan run `npm link rxpan`   
This will then use your local RxPan folder as the module so you can update and see the effects without having to publish to npm and reinstall.   

From within the rxpan folder run the editor's server: `npm start`  
From within the rxpan folder build and watch the viewer: `npm run viewer-dev`  
From within the rxpan folder build and watch the editor: `npm run editor-dev`  

You can now edit the files within `rxpan/editor/` and `rxpan/viewer/`  

To publish, run `npm publish` or better: `npm run build-and-publish` which will first bundle the viewer and editor before publishing.

Make sure to increment the version number in the package.json when publishing as well. Follow [semver](http://semver.org) standards.

---
_Source: https://npm.io/package/rxpan · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._