Skip to content
Command line application for generating static images of interactive plotly charts
Branch: master
Clone or download
Latest commit a2ce478 Feb 27, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Broaden CircleCI version number regex Jan 31, 2019
bin Merge remote-tracking branch 'origin/3.0-release' into 3.0.4-merge Feb 27, 2019
build Configure Project for Electron-Builder (#52) Feb 16, 2018
deployment Merge remote-tracking branch 'origin/3.0-release' into 3.0.4-merge Feb 27, 2019
recipe make recipe/ assume that `npm i` and `npm run pack` have been ran Sep 13, 2018
src Update docstring Feb 6, 2019
test Add unittest for the timeout Feb 6, 2019
.dockerignore Add Dockerfile to build server image Sep 18, 2017
.gitignore Enable CI platforms to build Linux, Windows and OS X releases (#63) Apr 13, 2018
.npmignore npm-ingore a few more things Aug 14, 2018
.travis.yml
CHANGELOG.md
CONTRIBUTING.md fix typo about `npm version` commit Jan 11, 2019
LICENSE Create LICENSE Mar 2, 2018
README.md Merge pull request #94 from cpsievert/orca-r Dec 28, 2018
appveyor.yml
orca_logo.png
package-lock.json 1.2.1 Feb 4, 2019
package.json
setup.py

README.md

Orca

orca logo

npm version MIT License

Orca is an Electron app that generates images and reports of Plotly things like plotly.js graphs, dash apps, dashboards from the command line. Additionally, Orca is the backbone of Plotly's Image Server. Orca is also an acronym for Open-source Report Creator App.

Visit plot.ly to learn more or visit the Plotly forum.

Follow @plotlygraphs on Twitter for Orca announcements.

Installation

Method 1: conda

If you have conda installed, you can easily install Orca from the plotly conda channel using:

$ conda install -c plotly plotly-orca

which makes the orca executable available on the path of current conda environment.

Method 2: npm

If you have Node.js installed (recommended v8.x), you can easily install Orca using npm as:

$ npm install -g electron@1.8.4 orca

which makes the orca executable available in your path.

Method 3: Standalone binaries

Alternatively, you can download the standalone Orca binaries corresponding to your operating system from the release page. Then, on

Mac OS

  • Unzip the mac-release.zip file.
  • Double-click on the orca-X.Y.Z.dmg file. This will open an installation window.
  • Drag the orca icon into the Applications folder.
  • Open finder and navigate to the Applications/ folder.
  • Right-click on the orca icon and select Open from the context menu.
  • A password dialog will appear asking for permission to add orca to your system PATH.
  • Enter you password and click OK.
  • This should open an Installation Succeeded window.
  • Open a new terminal and verify that the orca executable is available on your PATH.
$ which orca
/usr/local/bin/orca

$ orca --help
Plotly's image-exporting utilities

  Usage: orca [--version] [--help] <command> [<args>]
  ...

Windows

  • Extract the windows-release.zip file.
  • In the release folder, double-click on orca Setup X.Y.Z, this will create an orca icon on your Desktop.
  • Right-click on the orca icon and select Properties from the context menu.
  • From the Shortcut tab, copy the directory in the Start in field.
  • Add this Start in directory to you system PATH (see below).
  • Open a new Command Prompt and verify that the orca executable is available on your PATH.
> orca --help
Plotly's image-exporting utilities

  Usage: orca [--version] [--help] <command> [<args>]
  ...
Windows References

Linux

  • Make the orca AppImage executable.
$ chmod +x orca-X.Y.Z-x86_64.AppImage
  • Create a symbolic link named orca somewhere on your PATH that points to the AppImage.
$ ln -s /path/to/orca-X.Y.Z-x86_64.AppImage /somewhere/on/PATH/orca
  • Open a new terminal and verify that the orca executable is available on your PATH.
$ which orca
/somewhere/on/PATH/orca

$ orca --help
Plotly's image-exporting utilities

  Usage: orca [--version] [--help] <command> [<args>]
  ...
Linux Troubleshooting: Cannot open shared object

The Electron runtime depends a several common system libraries. These libraries are pre-installed in most desktop Linux distributions (e.g. Ubuntu), but are not pre-installed on some server Linux distributions (e.g. Ubuntu Server). If a shared library is missing, you will see an error message like:

$ orca --help
orca: error while loading shared libraries: libgtk-x11-2.0.so.0:
cannot open shared object file: No such file or directory

These additional dependencies can be satisfied by installing:

  • The libgtk2.0-0 and libgconf-2-4 packages from your distribution's software repository.
  • The google-chrome-stable package from the Google Linux Software Repository.
Linux Troubleshooting: Headless server configuration

The Electron runtime requires the presence of an active X11 display server, but many server Linux distributions (e.g. Ubuntu Server) do not include X11 by default. If you do not wish to install X11 on your server, you may install and run orca with Xvfb instead.

On Ubuntu Server, you can install Xvfb like this:

$ sudo apt-get install xvfb

To run orca under Xvfb, replace the symbolic link suggested above with a shell script that runs the orca AppImage executable using the xvfb-run command.

#!/bin/bash
xvfb-run -a /path/to/orca-X.Y.Z-x86_64.AppImage "$@"

Name this shell script orca and place it somewhere or your system PATH.

Linux References

Quick start

From the command line: Unix/MacOS:

$ orca graph '{ "data": [{"y": [1,2,1]}] }' -o fig.png

Windows:

orca graph "{ \"data\": [{\"y\": [1,2,1]}] }" -o fig.png

generates a PNG from the inputted plotly.js JSON attributes. Or,

$ orca graph https://plot.ly/~empet/14324.json --format svg

generates an SVG from a plotly.js JSON hosted on plot.ly.

When running

To print info about the supported arguments, run:

$ orca --help
$ orca <command> --help

To call orca from a Python script:

from subprocess import call
import json
import plotly

fig = {"data": [{"y": [1,2,1]}]}
call(['orca', 'graph', json.dumps(fig, cls=plotly.utils.PlotlyJSONEncoder)])

To call orca from an R script:

library(plotly)

p <- plot_ly(x = 1:10, y = 1:10, color = 1:10)
orca(p, "plot.svg")

API usage

Using the orca npm module allows developers to build their own Plotly exporting tool. We export two Electron app creator methods run and serve. Both methods return an Electron app object (which is an event listener/emitter).

To create a runner app:

// main.js

const orca = require('orca/src')

const app = orca.run({
  component: 'plotly-graph',
  input: 'path-to-file' || 'glob*' || url || '{data: [], layout: {}}' || [/* array of those */],
  debug: true
})

app.on('after-export', (info) => {
  fs.writeFile('output.png', info.body, (err) => console.warn(err))
})

// other available events:
app.on('after-export-all', () => {})
app.on('export-error', () => {})
app.on('renderer-error', () => {})

then launch it with electron main.js

Or, to create a server app:

// main.js

const orca = require('orca/src')

const app = orca.serve({
  port: 9090,
  component: 'component name ' || [{
    name: 'plotly-graph',
    path: /* path to module if none given, tries to resolve ${name} */,
    route: /* default to same as ${name} */,

    // other options passed to component methods
    options: {
      plotlyJS: '',
      mathjax: '',
      topojson: '',
      mapboxAccessToken: ''
    }
  }, {
    // other component
  }, {
    // other component ...
  }],

  debug: false || true
})

app.on('after-export', (info) => {
  console.log(info)
})

// other available events:
app.on('after-connect', () => {})
app.on('export-error', () => {})
app.on('renderer-error', () => {})

then launch it with electron main.js

Plotly's image server

Plotly's image server is dockerized and deployed here. See the deployment/ README for more info.

System dependencies

If you don't care about exporting EPS or EMF you can skip this section.

The environment you're installing this into may require Poppler for EPS exports and Inkscape for EMF exports.

Poppler installation via Aptitude (used by some *nix/BSD, e.g. Ubuntu)

$ apt-get install poppler-utils (requires `sudo` or root privileges)

Poppler installation via Homebrew (third-party package manager for Mac OS X)

$ brew install poppler

Inkscape installation via Aptitude (used by some *nix/BSD, e.g. Ubuntu)

$ apt-get install inkscape (requires `sudo` or root privileges)

Inkscape installation via Homebrew (third-party package manager for Mac OS X)

$ brew install inkscape

Contributing

See CONTRIBUTING.md. You can also contact us if you would like a specific feature added.

Tests and Linux builds Mac OS build Windows build
CircleCI Build Status AppVeyor

License

Code released under the MIT © License.

You can’t perform that action at this time.