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.
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.
If you have Node.js installed (recommended v8.x), you can easily install Orca using npm as:
$ npm install -g electron@6.1.4 orca
which makes the orca
executable available in your path.
$ docker pull quay.io/plotly/orca
If no arguments are specified, it starts an Orca server on port 9091. You can publish the port to the outside world the usual way:
$ docker run -d -p 9091:9091 quay.io/plotly/orca
If the first argument is graph
,
it executes the command line application orca graph
:
$ docker run -i quay.io/plotly/orca graph --help
Alternatively, you can download the standalone Orca binaries corresponding to your operating system from the release page. Then, on
mac-release.zip
file.orca-X.Y.Z.dmg
file. This will open an installation window.Applications
folder.Applications/
folder.PATH
.PATH
.$ which orca
/usr/local/bin/orca
$ orca --help
Plotly's image-exporting utilities
Usage: orca [--version] [--help] <command> [<args>]
...
windows-release.zip
file.release
folder, double-click on orca Setup X.Y.Z
, this will create an orca icon on your Desktop.PATH
(see below).PATH
.> orca --help
Plotly's image-exporting utilities
Usage: orca [--version] [--help] <command> [<args>]
...
$ chmod +x orca-X.Y.Z-x86_64.AppImage
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
PATH
.$ which orca
/somewhere/on/PATH/orca
$ orca --help
Plotly's image-exporting utilities
Usage: orca [--version] [--help] <command> [<args>]
...
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:
libgtk2.0-0
and libgconf-2-4
packages from your distribution's
software repository.chromium-browser
package from your distribution's
software repository.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 on your system PATH
.
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")
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 is dockerized and deployed here. See the deployment/
README for more info.
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.
$ apt-get install poppler-utils (requires `sudo` or root privileges)
$ brew install poppler
$ apt-get install inkscape (requires `sudo` or root privileges)
$ brew install inkscape
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 | Docker build |
---|---|---|---|
Code released under the MIT © License.