|
| 1 | +[](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub) |
| 2 | +[](https://zenodo.org/badge/latestdoi/186020000) |
| 3 | + |
| 4 | +[](https://kotl.in/jsirsupported) |
| 5 | + |
| 6 | + |
| 7 | + |
| 8 | +## Artifact details |
| 9 | + |
| 10 | +**TBD** |
| 11 | + |
| 12 | +## Compatibility note |
| 13 | +The current `$version` version of the library is compatible with kotlin 1.4 with JS-IR and kotlinx-serialization 1.1.0. The JVM part requires JVM 11 to run. |
| 14 | + |
| 15 | +# TL;DR |
| 16 | +See [examples](./examples/src/main/kotlin). |
| 17 | +See [original library samples](https://plotly.com/javascript/) to understand capabilities. |
| 18 | + |
| 19 | +# Description |
| 20 | + |
| 21 | +This project is developed to allow simple access to plotly functionality from kotlin-multiplatform. The API allows to create plotly configuration and render it as a plotly chart. |
| 22 | + |
| 23 | +The library supports three drawable plot objects: |
| 24 | +* `Plot` itself stands for a stand-alone plot frame. It requires external infrastructure to load appropriate JavaScript libraries. |
| 25 | +* `PlotFragment` (JVM only) is an HTML fragment possibly including several plots. The API for html is provided by [kotlinx-html](https://github.com/Kotlin/kotlinx.html) library. |
| 26 | +* `PlotlyPage` (JVM only) is a complete page, including body fragment and page headers (needed to load JavaScript part of Plotly). |
| 27 | + |
| 28 | +The work with plotly graphs could be rendered in following modes: |
| 29 | + |
| 30 | +## HTML page export |
| 31 | +(JVM only) Export plot or a plot grid in a standalone html file, which |
| 32 | +uses CDN based plotly distribution. This mode does not support updates. |
| 33 | + |
| 34 | +See [staticPlot](./examples/src/main/kotlin/staticPlot.kt) and |
| 35 | +[customPage](./examples/src/main/kotlin/customPage.kt) for examples. |
| 36 | + |
| 37 | +## Ktor-based server with dynamic updates |
| 38 | +(JVM only) A Ktor CIO server with full multi-page and update capabilities. |
| 39 | + |
| 40 | +See [simpleServer](./examples/src/main/kotlin/simpleServer.kt) and |
| 41 | +[dynamicServer](./examples/src/main/kotlin/dynamicServer.kt) for examples. |
| 42 | + |
| 43 | +## Kotlin-JS |
| 44 | +Plotly is a JavaScript library, yet it is convenient to have a type-safe API when using in with Kotlin-JS. The sample application is available in [js-demo](./js-demo) module. One should node that Plotly.kt for JS is not a zero-cost wrapper like TypeScript definitions, it maintains its own object structure, could generate stand-alone models and some internal optimizations. |
| 45 | + |
| 46 | +## JavaFX browser |
| 47 | +Plotly.kt could be run in a JavaFX browser. An example project is presented in [fx-demo](./fx-demo). |
| 48 | + |
| 49 | +## Kotlin jupyter kernel (experimental) |
| 50 | +Plotly.kt comes with (beta-version) support for integration with [Kotlin Jupyter kernel](https://github.com/Kotlin/kotlin-jupyter). See details [here](./docs/tutorials/jupyter.md). |
| 51 | + |
| 52 | +The examples of the notebooks are shown in [notebooks](./examples/notebooks) directory. Plotly.kt uses Kotlin jupyter notebook API for integration (available in kernel version `0.8.3.236` and later). In order to load the library together with automatic imports one need to simply load a library in a following way: |
| 53 | + |
| 54 | +```kotlin |
| 55 | +@file:Repository("https://repo.kotlin.link") |
| 56 | +@file:DependsOn("space.kscience:plotlykt-jupyter:$version") |
| 57 | +//@file:DependsOn("space.kscience:plotlykt-server:$version") // Use this one for sever integration. |
| 58 | +``` |
| 59 | + |
| 60 | +The module `plotly` allows rendering static plots in Jupyter. Jupyter lab is currently supported. Jupyter notebook (classic) is able to render only `PlotlyPage` objects, so one must convert plots to pages to be able to use notebook (see [demo notebook](./notebooks/plotlykt-demo-classic.ipynb)). |
| 61 | + |
| 62 | +The module `plotly-server` adds server capabilities and allows to render dynamic plots in notebooks (see [demo notebook](./notebooks/plotlykt-server-demo.ipynb)). One must note that for dynamic pages, one must pass `renderer` parameter explicitly to plot like it is done in examples. |
| 63 | + |
| 64 | +## Direct image render via Orca (experimental) |
| 65 | +[Plotly Orca](https://github.com/plotly/orca) application allows direct rendering of plots (not fragments or pages) to raster of vector images. |
| 66 | +`Plot.export` extension could be used to call it. It requires for orca to be installed in the system and available on the system path. |
| 67 | + |
| 68 | +## Kotlin-scripting (experimental) |
| 69 | +It is possible to separate script logic into stand-alone `plotly.kts` script file and generate an html from the command line. See [plotlykt-script](./plotlykt-script) module for details. |
| 70 | + |
| 71 | +# The feature I need is not implemented! |
| 72 | + |
| 73 | +There are three ways to solve it: |
| 74 | +1. Contribute! It is easy! Just add a model you need. |
| 75 | +2. Create a model you need in your project or add an extension. Since the inner model is dynamic, you can add features on flight. |
| 76 | +3. You can dynamically add missing features directly into configuration |
| 77 | +like it done in [unsupportedFeature](./examples/src/main/kotlin/unsupportedFeature.kt) example. |
| 78 | + |
| 79 | +# Build and usage |
| 80 | + |
| 81 | +In order to use the library, one needs to use following `gradle.kts` configuration: |
| 82 | + |
| 83 | +```kotlin |
| 84 | +plugins { |
| 85 | + kotlin("jvm") |
| 86 | +} |
| 87 | + |
| 88 | +repositories { |
| 89 | + maven("https://repo.kotlin.link") |
| 90 | +} |
| 91 | + |
| 92 | +dependencies { |
| 93 | + implementation("kscience.plotlykt:plotlykt-server:$version") |
| 94 | +} |
| 95 | +``` |
| 96 | + |
| 97 | + |
| 98 | +If you do not need the server, then use plotlykt-core instead. |
| 99 | + |
| 100 | +# Naming |
| 101 | +The library keeps original Plotly API naming wherever it is possible. There are some usability shortcuts, usually provided via kotlin extensions, included in order to simplify user interaction. For example, `text` and `shape` extensions in the top level API. |
| 102 | + |
| 103 | +Keeping the original naming sometimes causes clashes with Kotlin code style. For example enum names are unorthodox. |
| 104 | + |
| 105 | +# Planned features |
| 106 | + |
| 107 | +* Table widgets |
| 108 | +* Serverside plot events |
| 109 | +* Online plot editor |
| 110 | +* Dynamic data |
| 111 | +* Mathjax and latex support |
| 112 | + |
| 113 | +# Contributions and thanks |
| 114 | +* [Vasily Chernov](https://research.jetbrains.org/researchers/vchernov) - initial project foundation |
| 115 | +* [Alexander Nozik](https://research.jetbrains.org/researchers/altavir) - dynamic core and server |
| 116 | +* [Mikhail Zeleniy](https://research.jetbrains.org/researchers/gama_sennin) - basic models |
| 117 | +* [Ekaterina Samorodova](https://github.com/ebsamorodova) (JBR-2020 summer internship) - Model refactoring, tutorials and `0.2` release. |
| 118 | + |
| 119 | +The project was partially founded by JetBrains Research grant. |
| 120 | + |
0 commit comments