Repository files navigation

Orca support in Plotly.py is deprecated and will be removed after September 2025. UseKaleido instead.

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

Visitplot.ly to learn more or visit thePlotly forum.

Follow@plotlygraphs on Twitter for Orca announcements.

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

$ conda install -c plotly plotly-orca

which makes theorca executable available on the path of current condaenvironment.

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

$ npm install -g electron@6.1.4 orca

which makes theorca 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 isgraph,it executes the command line applicationorca graph:

$ docker run -i quay.io/plotly/orca graph --help

Alternatively, you can download the standalone Orca binaries corresponding toyour operating system from therelease page. Then, on

• Unzip themac-release.zip file.
• Double-click on theorca-X.Y.Z.dmg file. This will open an installation window.
• Drag the orca icon into theApplications folder.
• Open finder and navigate to theApplications/ folder.
• Right-click on the orca icon and selectOpen from the context menu.
• A password dialog will appear asking for permission to add orca to your systemPATH.
• Enter you password and clickOK.
• This should open anInstallation Succeeded window.
• Open a new terminal and verify that the orca executable is available on yourPATH.

$ which orca/usr/local/bin/orca$ orca --helpPlotly's image-exporting utilities  Usage: orca [--version] [--help] <command> [<args>]  ...

• Extract thewindows-release.zip file.
• In therelease folder, double-click onorca Setup X.Y.Z, this will create an orca icon on your Desktop.
• Right-click on the orca icon and selectProperties from the context menu.
• From theShortcut tab, copy the directory in theStart in field.
• Add thisStart in directory to you systemPATH (see below).
• Open a new Command Prompt and verify that the orca executable is available on yourPATH.

> orca --helpPlotly's image-exporting utilities  Usage: orca [--version] [--help] <command> [<args>]  ...

• How to set the path and environment variables in Windows:https://www.computerhope.com/issues/ch000549.htm

• Make the orca AppImage executable.

$ chmod +x orca-X.Y.Z-x86_64.AppImage

• Create a symbolic link namedorca somewhere on yourPATH that pointsto 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 yourPATH.

$ which orca/somewhere/on/PATH/orca$ orca --helpPlotly's image-exporting utilities  Usage: orca [--version] [--help] <command> [<args>]  ...

The Electron runtime depends a several common system libraries. Theselibraries 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 errormessage like:

$ orca --helporca: 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:

• Thelibgtk2.0-0 andlibgconf-2-4 packages from your distribution'ssoftware repository.
• Thechromium-browser package from your distribution'ssoftware 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 X11by default. If you do not wish to install X11 on your server, you mayinstall 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 shellscript that runs the orca AppImage executable using thexvfb-run command.

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

Name this shell scriptorca and place it somewhere on your systemPATH.

• How to add directory to system path in Linux:https://www.computerhope.com/issues/ch001647.htm
• AppImage:https://appimage.org/
• Xvfb:https://en.wikipedia.org/wiki/Xvfb

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 onplot.ly.

When running

To print info about the supported arguments, run:

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

To callorca from a Python script:

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

To callorca from an R script:

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

Using theorca npm module allows developers to build their ownPlotly exporting tool. We export two Electron app creator methodsrun andserve. Both methods return an Electronapp object (which is an eventlistener/emitter).

To create arunner app:

// main.jsconstorca=require('orca/src')constapp=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 withelectron main.js

Or, to create aserver app:

// main.jsconstorca=require('orca/src')constapp=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 methodsoptions:{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 withelectron main.js

Plotly's image server is dockerized and deployed here. See thedeployment/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

SeeCONTRIBUTING.md.You can alsocontact us if youwould like a specific feature added.

Tests and Linux builds	Mac OS build	Windows build	Docker build

Code released under the MIT ©License.