update readme related to kaleido usage and kaleido_download feature

Signed-off-by: Andrei Gherghescu <[email protected]>

Author: andrei-ng

README.md

@@ -40,7 +40,7 @@
 * [Introduction](#introduction)
 * [Basic Usage](#basic-usage)
     * [Exporting an Interactive Plot](#exporting-an-interactive-plot)
-    * [Exporting a Static Image](#exporting-a-static-image)
+    * [Exporting Static Images with Kaleido](#exporting-static-images-with-kaleido)
     * [Usage Within a Wasm Environment](#usage-within-a-wasm-environment)
 * [Crate Feature Flags](#crate-feature-flags)
 * [Contributing](#contributing)
@@ -96,18 +96,38 @@ If you only want to view the plot in the browser quickly, use the `Plot.show()`
 plot.show(); // The default web browser will open, displaying an interactive plot
 ```
 
-## Exporting a Static Image
+## Exporting Static Images with Kaleido
 
-To save a plot as a static image, the `kaleido` feature is required:
+To save a plot as a static image, the `kaleido` feature is required as well as installing an **external dependency**.
 
+### Kaleido external dependency
+
+When developing applications for your host, enabling both `kaleido` and `kaleido_download` features will ensure that the `kaleido` binary is downloaded for your system's architecture at compile time. After download, it is unpacked into a specific path, e.g., on Linux this is `/home/USERNAME/.config/kaleido`. With these two features enabled, static images can be exported as described in the next section as long as the application run on the same host where where this crate was compiled on.
+
+When the applications developed with `plotly.rs` are intended for other targets or when the user wants to control where the `kaleido` binary is installed then Kaleido must be manually downloaded and installed. Setting the environment variable `KALEIDO_PATH=/path/installed/kaleido/` will ensure that applications that were built with the `kaleido` feature enabled can locate the `kaleido` executable and use it to generate static images.
+
+Kaleido binaries are available on Github [release page](https://github.com/plotly/Kaleido/releases). It currently supports Linux(`x86_64`), Windows(`x86_64`) and MacOS(`x86_64`/`aarch64`).
+
+## Exporting a Static Images
+
+Enable the `kaleido` feature and opt in for automatic downloading of the `kaleido` binaries by doing the following
+
+```toml
+# Cargo.toml
+
+[dependencies]
+plotly = { version = "0.11", features = ["kaleido", "kaleido_download"] }
+```
+
+Alternatively, enable only the `kaleido` feature and manually install Kaleido.
 ```toml
 # Cargo.toml
 
 [dependencies]
 plotly = { version = "0.11", features = ["kaleido"] }
 ```
 
-With this feature enabled, plots can be saved as any of `png`, `jpeg`, `webp`, `svg`, `pdf` and `eps`. Note that the plot will be a static image, i.e. they will be non-interactive.
+With the feature enabled, plots can be saved as any of `png`, `jpeg`, `webp`, `svg`, `pdf` and `eps`. Note that the plot will be a static image, i.e. they will be non-interactive.
 
 Exporting a simple plot looks like this:
 
@@ -121,12 +141,6 @@ plot.add_trace(trace);
 plot.write_image("out.png", ImageFormat::PNG, 800, 600, 1.0);
 ```
 
-### _Kaleido dependency_
-
-On your host, when building this project with the `kaleido` feature enabled the Kaleido binary is downloaded automatically for your system's architecture at compile time from the official Kaleido [release page](https://github.com/plotly/Kaleido/releases). This library currently supports `x86_64` on Linux and Windows, and both `x86_64` and `aarch64` on macOS.
-
-When building application for other targets that depend on this feature, the `Kaleido` binary will need to be installed manually on the target machine. Currently, the location where the binary is expected is hardcoded depending on the target OS. E.g., on Linux this defaults to `~/.config/kaleido`. This is defined in source code [here](https://github.com/plotly/plotly.rs/blob/1405731b5121c1343b491e307222a21ef4becc5e/plotly_kaleido/src/lib.rs#L89)
-
 ## Usage Within a Wasm Environment
 
 Using `Plotly.rs` in a Wasm-based frontend framework is possible by enabling the `wasm` feature:
@@ -198,6 +212,13 @@ The following feature flags are available:
 
 Adds plot save functionality to the following formats: `png`, `jpeg`, `webp`, `svg`, `pdf` and `eps`.
 
+Requires `Kaleido` to have been previously installed on the host machine. See the following feature flag and [Kaleido external dependency](#kaleido-external-dependency).
+
+### `kaleido_download`
+
+Enable download and install of Kaleido binary at build time from [Kaleido releases](https://github.com/plotly/Kaleido/releases/) on the host machine.
+See [Kaleido external dependency](#kaleido-external-dependency) for more details.
+
 ### `plotly_image`
 
 Adds trait implementations so that `image::RgbImage` and `image::RgbaImage` can be used more directly with the `plotly::Image` trace.

examples/kaleido/Cargo.toml

@@ -8,4 +8,4 @@ authors = [
 edition = "2021"
 
 [dependencies]
-plotly = { path = "../../plotly", features = ["kaleido", "kaleido_fetch"] }
+plotly = { path = "../../plotly", features = ["kaleido", "kaleido_download"] }

examples/kaleido/src/main.rs

@@ -5,15 +5,21 @@ fn main() {
     let trace = Scatter::new(vec![0, 1, 2], vec![2, 1, 0]);
     plot.add_trace(trace);
 
-    // Adjust these arguments to set the image format, width and height of the
+    // Adjust these arguments to set the width and height of the
     // output image.
     let filename = "out";
-    let image_format = ImageFormat::PNG;
     let width = 800;
     let height = 600;
     let scale = 1.0;
 
     // The image will be saved to format!("{filename}.{image_format}") relative to
     // the current working directory.
-    plot.write_image(filename, image_format, width, height, scale);
+    plot.write_image(filename, ImageFormat::EPS, width, height, scale);
+    plot.write_image(filename, ImageFormat::JPEG, width, height, scale);
+    plot.write_image(filename, ImageFormat::PDF, width, height, scale);
+    plot.write_image(filename, ImageFormat::PNG, width, height, scale);
+    plot.write_image(filename, ImageFormat::SVG, width, height, scale);
+    plot.write_image(filename, ImageFormat::WEBP, width, height, scale);
+
+    let _svg_string = plot.to_svg(width, height, scale);
 }

plotly/Cargo.toml

@@ -15,7 +15,7 @@ exclude = ["target/*"]
 
 [features]
 kaleido = ["plotly_kaleido"]
-kaleido_fetch = ["plotly_kaleido/download"]
+kaleido_download = ["plotly_kaleido/download"]
 
 plotly_ndarray = ["ndarray"]
 plotly_image = ["image"]

plotly/src/plot.rs

@@ -809,7 +809,7 @@ mod tests {
         assert!(!dst.exists());
     }
 
-    #[cfg(target_os = "linux")]
+    #[cfg(not(target_os = "macos"))]
     #[test]
     #[cfg(feature = "kaleido")]
     fn test_save_to_webp() {

plotly_kaleido/src/lib.rs

@@ -87,7 +87,7 @@ impl Kaleido {
                 Some(compile_time_path) => compile_time_path.to_string(),
                 None => {
                     println!("{}: {}", Self::KALEIDO_PATH_ENV, runtime_env_err);
-                    println!("Use `kaleido_fetch` feature to automatically download, install and use Kaleido when targeting applications that run on the host machine.");
+                    println!("Use `kaleido_download` feature to automatically download, install and use Kaleido when targeting applications that run on the host machine.");
                     println!("Use `{}` environment variable when targeting applications intended to run on different machines. Manually install Kaleido on the target machine and point {} to the installation location.", Self::KALEIDO_PATH_ENV, Self::KALEIDO_PATH_ENV
                     );
                     std::process::exit(1);
@@ -227,22 +227,19 @@ impl Kaleido {
         let output_lines = BufReader::new(process.stdout.take().unwrap()).lines();
         for line in output_lines.map_while(Result::ok) {
             let res = KaleidoResult::from(line.as_str());
-            match res.result {
-                Some(image_data) => {
-                    // TODO: this should be refactored
-                    // The assumption is that  KaleidoResult contains a single image.
-                    // We should end the loop on the first valid one.
-                    // If that is not the case, prior implementation would have returned the last
-                    // valid image
-                    return Ok(image_data);
-                }
-                None => {
-                    println!("empty line from Kaleido stdout");
-                }
+            if let Some(image_data) = res.result {
+                // TODO: this should be refactored
+                // The assumption is that  KaleidoResult contains a single image.
+                // We should end the loop on the first valid one.
+                // If that is not the case, prior implementation would have returned the last
+                // valid image
+                return Ok(image_data);
             }
         }
 
-        // Don't eat up Kaleido/Chromiu erros but show them in the terminal
+        // Don't eat up Kaleido/Chromium errors but show them in the terminal
+        println!("Kaleido failed to generate static image for format: {format}.");
+        println!("Kaleido stderr output:");
         let stderr = process.stderr.take().unwrap();
         let stderr_lines = BufReader::new(stderr).lines();
         for line in stderr_lines {