Skip to content

Commit 6dd0ec4

Browse files
altaviraltavir
committed
0.7.1.1 release
1 parent 3ac2a23 commit 6dd0ec4

File tree

1 file changed

+126
-0
lines changed

1 file changed

+126
-0
lines changed

‎README.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
[![JetBrains Research](https://jb.gg/badges/research.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub)
2+
[![DOI](https://zenodo.org/badge/186020000.svg)](https://zenodo.org/badge/latestdoi/186020000)
3+
![Gradle build](https://github.com/mipt-npm/plotly.kt/workflows/Gradle%20build/badge.svg)
4+
[![Kotlin JS IR supported](https://img.shields.io/badge/Kotlin%2FJS-IR%20supported-yellow)](https://kotl.in/jsirsupported)
5+
6+
![Plotlykt logo](./docs/logo_text.svg)
7+
8+
## Artifact details
9+
10+
[![Maven Central](https://img.shields.io/maven-central/v/space.kscience/plotlykt-core.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22space.kscience%22%20AND%20a:%22plotlykt-core%22)
11+
12+
Dev builds and intermediate artifacts are available via `https://repo.kotlin.link` maven repository.
13+
14+
## Compatibility note
15+
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.
16+
17+
# TL;DR
18+
See [examples](./examples/src/main/kotlin).
19+
See [original library samples](https://plotly.com/javascript/) to understand capabilities.
20+
21+
# Description
22+
23+
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.
24+
25+
The library supports three drawable plot objects:
26+
* `Plot` itself stands for a stand-alone plot frame. It requires external infrastructure to load appropriate JavaScript libraries.
27+
* `PlotFragment` is an HTML fragment possibly including several plots. The API for html is provided by [kotlinx-html](https://github.com/Kotlin/kotlinx.html) library.
28+
* `PlotlyPage` is a complete page, including body fragment and page headers (needed to load JavaScript part of Plotly).
29+
30+
The work with plotly graphs could be rendered in following modes:
31+
32+
## HTML page export
33+
(JVM and native) Export plot or page in a standalone html file, using CDN distribution or local JS file (JVM only). This mode does not support updates.
34+
35+
See [staticPlot](./examples/src/main/kotlin/staticPlot.kt) and
36+
[customPage](./examples/src/main/kotlin/customPage.kt) for examples.
37+
38+
## Ktor-based server with dynamic updates
39+
(JVM only) A Ktor CIO server with full multi-page and update capabilities.
40+
41+
See [simpleServer](./examples/src/main/kotlin/simpleServer.kt) and
42+
[dynamicServer](./examples/src/main/kotlin/dynamicServer.kt) for examples.
43+
44+
## Kotlin-JS
45+
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.
46+
47+
## JavaFX browser
48+
Plotly.kt could be run in a JavaFX browser. An example project is presented in [fx-demo](./fx-demo).
49+
50+
## Kotlin jupyter kernel
51+
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).
52+
53+
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:
54+
55+
```kotlin
56+
@file:Repository("https://repo.kotlin.link")
57+
@file:DependsOn("space.kscience:plotlykt-jupyter:$version")
58+
//@file:DependsOn("space.kscience:plotlykt-server:$version") // Use this one for sever integration.
59+
```
60+
61+
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)).
62+
63+
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.
64+
65+
**IMPORTANT:** By default, Plotly-kt jupyter integration is configured to work with Jupyter Lab frontend, which renders all cells in the same page. Jupyter classic notebook and DataLore use cell isolation with iframes, so you will see blanks instead of plots. It could be fixed by switching into a notebook mode by running `Plotly.jupyter.notebook()` in a cell after plotly library is loaded.
66+
67+
## Direct image render via Orca (experimental)
68+
[Plotly Orca](https://github.com/plotly/orca) application allows direct rendering of plots (not fragments or pages) to raster of vector images.
69+
`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.
70+
71+
## Kotlin-scripting (experimental)
72+
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.
73+
74+
## Kotlin/Native (experimental)
75+
Plotly model now fully supports Kotlin/Native. It means that you can use it to create a proper Plotly-based HTML file. You will still need browser to view it. You can use [native-demo](./examples/native-demo) example.
76+
77+
# The feature I need is not implemented!
78+
79+
There are three ways to solve it:
80+
1. Contribute! It is easy! Just add a model you need.
81+
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.
82+
3. You can dynamically add missing features directly into configuration
83+
like it done in [unsupportedFeature](./examples/src/main/kotlin/unsupportedFeature.kt) example.
84+
85+
# Build and usage
86+
87+
In order to use the library, one needs to use following `gradle.kts` configuration:
88+
89+
```kotlin
90+
plugins {
91+
kotlin("jvm")
92+
}
93+
94+
repositories {
95+
maven("https://repo.kotlin.link")
96+
}
97+
98+
dependencies {
99+
implementation("space.kscience:plotlykt-server:$version")
100+
}
101+
```
102+
103+
104+
If you do not need the server, then use plotlykt-core instead.
105+
106+
# Naming
107+
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.
108+
109+
Keeping the original naming sometimes causes clashes with Kotlin code style. For example enum names are unorthodox.
110+
111+
# Planned features
112+
113+
* Table widgets
114+
* Serverside plot events
115+
* Online plot editor
116+
* Dynamic data
117+
* Mathjax and latex support
118+
119+
# Contributions and thanks
120+
* [Vasily Chernov](https://research.jetbrains.org/researchers/vchernov) - initial project foundation
121+
* [Alexander Nozik](https://research.jetbrains.org/researchers/altavir) - dynamic core and server
122+
* [Mikhail Zeleniy](https://research.jetbrains.org/researchers/gama_sennin) - basic models
123+
* [Ekaterina Samorodova](https://github.com/ebsamorodova) (JBR-2020 summer internship) - Model refactoring, tutorials and `0.2` release.
124+
125+
The project was partially founded by JetBrains Research grant.
126+

0 commit comments

Comments
 (0)