plotly · andrei-ng · Jun 29, 2025 · Jul 5, 2025 · Jul 5, 2025
diff --git a/.github/scripts/setup-windows-static-export.ps1 b/.github/scripts/setup-windows-static-export.ps1
@@ -0,0 +1,104 @@
+# Windows environment setup for plotly static export tests
+# This script sets up Chrome, chromedriver, and environment variables for Windows CI
+
+param(
+    [string]$ChromeVersion,
+    [string]$ChromePath,
+    [string]$ChromeDriverPath
+)
+
+Write-Host "=== Setting up Windows environment for static export ==="
+
+# Find chromedriver path
+$chromedriverPath = $ChromeDriverPath
+if (-not (Test-Path $chromedriverPath)) {
+    Write-Host "Action output chromedriver path not found, searching for alternatives..."
+
+    $commonPaths = @(
+        "C:\Program Files\Google\Chrome\Application\chromedriver.exe",
+        "C:\Program Files (x86)\Google\Chrome\Application\chromedriver.exe",
+        "$env:USERPROFILE\AppData\Local\Google\Chrome\Application\chromedriver.exe",
+        "$env:PROGRAMFILES\Google\Chrome\Application\chromedriver.exe",
+        "$env:PROGRAMFILES(X86)\Google\Chrome\Application\chromedriver.exe"
+    )
+
+    foreach ($path in $commonPaths) {
+        if (Test-Path $path) {
+            Write-Host "Using chromedriver from: $path"
+            $chromedriverPath = $path
+            break
+        }
+    }
+}
+
+# Find Chrome path
+$chromePath = $ChromePath
+if (-not (Test-Path $chromePath)) {
+    # Try the tool cache path first
+    $toolCachePath = "C:\hostedtoolcache\windows\setup-chrome\chromium\$ChromeVersion\x64\chrome.exe"
+    if (Test-Path $toolCachePath) {
+        $chromePath = $toolCachePath
+        Write-Host "Using Chrome from setup-chrome installation: $chromePath"
+    } else {
+        # Fallback: search for Chrome in the tool cache
+        $toolCacheDir = "C:\hostedtoolcache\windows\setup-chrome\chromium"
+        if (Test-Path $toolCacheDir) {
+            $chromeExe = Get-ChildItem -Path $toolCacheDir -Recurse -Name "chrome.exe" | Select-Object -First 1
+            if ($chromeExe) {
+                $chromePath = Join-Path $toolCacheDir $chromeExe
+                Write-Host "Using Chrome from tool cache search: $chromePath"
+            } else {
+                $chromePath = "C:\Program Files\Google\Chrome\Application\chrome.exe"
+                Write-Host "Using system Chrome: $chromePath"
+            }
+        } else {
+            $chromePath = "C:\Program Files\Google\Chrome\Application\chrome.exe"
+            Write-Host "Using system Chrome: $chromePath"
+        }
+    }
+}
+
+# Set environment variables
+$env:WEBDRIVER_PATH = $chromedriverPath
+$env:BROWSER_PATH = $chromePath
+$env:RUST_LOG = "debug"
+$env:RUST_BACKTRACE = "1"
+$env:ANGLE_DEFAULT_PLATFORM = "swiftshader"
+
+Write-Host "Environment variables set:"
+Write-Host "WEBDRIVER_PATH: $env:WEBDRIVER_PATH"
+Write-Host "BROWSER_PATH: $env:BROWSER_PATH"
+Write-Host "RUST_LOG: $env:RUST_LOG"
+Write-Host "RUST_BACKTRACE: $env:RUST_BACKTRACE"
+
+# Verify paths exist
+if (-not (Test-Path $env:WEBDRIVER_PATH)) {
+    Write-Error "Chromedriver executable not found at: $env:WEBDRIVER_PATH"
+    Write-Host "Available chromedriver locations:"
+    Get-ChildItem -Path "C:\Program Files\Google\Chrome\Application\" -Name "chromedriver*" -ErrorAction SilentlyContinue
+    Get-ChildItem -Path "C:\Program Files (x86)\Google\Chrome\Application\" -Name "chromedriver*" -ErrorAction SilentlyContinue
+    exit 1
+}
+
+if (-not (Test-Path $env:BROWSER_PATH)) {
+    Write-Error "Chrome not found at: $env:BROWSER_PATH"
+    exit 1
+}
+
+# Test Chrome version
+try {
+    $chromeVersion = & "$env:BROWSER_PATH" --version 2>&1
+    Write-Host "Chrome version: $chromeVersion"
+} catch {
+    Write-Host "Failed to get Chrome version: $_"
+}
+
+# Test chromedriver version
+try {
+    $chromedriverVersion = & "$env:WEBDRIVER_PATH" --version 2>&1
+    Write-Host "Chromedriver version: $chromedriverVersion"
+} catch {
+    Write-Host "Failed to get chromedriver version: $_"
+}
+
+Write-Host "=== Windows environment setup completed ==="
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -33,14 +33,22 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - name: Setup Chrome
+        uses: browser-actions/setup-chrome@v1
+        with:
+          chrome-version: 'latest'
+          install-chromedriver: true
       - uses: dtolnay/rust-toolchain@stable
         with:
           components: clippy
           targets: wasm32-unknown-unknown
+      # lint plotly_static for all features
+      - run: cargo clippy -p plotly_static --features geckodriver,webdriver_download -- -D warnings -A deprecated
+      - run: cargo clippy -p plotly_static --features chromedriver,webdriver_download -- -D warnings -A deprecated
       # lint the main library workspace for non-wasm target
-      - run: cargo clippy --all-features -- -D warnings
+      - run: cargo clippy --features all -- -D warnings -A deprecated
       # lint the non-wasm examples
-      - run: cd ${{ github.workspace }}/examples && cargo clippy --workspace --exclude "wasm*" -- -D warnings
+      - run: cd ${{ github.workspace }}/examples && cargo clippy --workspace --exclude "wasm*" --exclude "kaleido" -- -D warnings
       # lint the plotly library for wasm target
       - run: cargo clippy --package plotly --target wasm32-unknown-unknown -- -D warnings
       # lint the wasm examples
@@ -65,14 +73,121 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, windows-latest, macos-latest]
+        include:
+          - os: ubuntu-latest
+            browser: chrome
+            features: plotly_ndarray,plotly_image,static_export_default,debug
+          - os: ubuntu-latest
+            browser: firefox
+            features: plotly_ndarray,plotly_image,static_export_geckodriver,static_export_wd_download,debug
+          - os: windows-latest
+            browser: chrome
+            features: plotly_ndarray,plotly_image,static_export_chromedriver,debug
+          - os: macos-latest
+            browser: chrome
+            features: plotly_ndarray,plotly_image,static_export_default,debug
     runs-on: ${{ matrix.os }}
+    timeout-minutes: ${{ matrix.os == 'windows-latest' && 30 || 10 }}
     steps:
+      - name: Setup Chrome
+        if: matrix.browser == 'chrome'
+        uses: browser-actions/setup-chrome@v1
+        with:
+          chrome-version: 'latest'
+          install-chromedriver: true
+        id: setup-chrome
+
+      - name: Setup Firefox
+        if: matrix.browser == 'firefox'
+        uses: browser-actions/setup-firefox@v1
+        with:
+          firefox-version: 'latest'
+        id: setup-firefox
+
       - uses: actions/checkout@v4
+
       - uses: dtolnay/rust-toolchain@stable
-      - run: cargo test --features plotly_ndarray,plotly_image,kaleido
-      - if: ${{ matrix.os == 'windows-latest' }}
-        run: gci -recurse -filter "*example*"
+
+      # Cache cargo registry for all platforms
+      - name: Cache cargo registry
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+          key: ${{ runner.os }}-cargo-registry-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-registry-
+
+      # Windows-specific environment setup for static export tests
+      - name: Setup Windows environment for static export
+        if: matrix.os == 'windows-latest'
+        run: |
+          .\.github\scripts\setup-windows-static-export.ps1 `
+            -ChromeVersion "${{ steps.setup-chrome.outputs.chrome-version }}" `
+            -ChromePath "${{ steps.setup-chrome.outputs.chrome-path }}" `
+            -ChromeDriverPath "${{ steps.setup-chrome.outputs.chromedriver-path }}"
+
+      # Run tests on Ubuntu with Chrome
+      - name: Run tests (${{ matrix.os }} - Chrome)
+        if: matrix.os == 'ubuntu-latest' && matrix.browser == 'chrome'
+        run: cargo test --workspace --features ${{ matrix.features }} --exclude plotly_kaleido
+
+      # Install xvfb for Firefox WebGL support
+      - name: Install xvfb
+        if: matrix.os == 'ubuntu-latest' && matrix.browser == 'firefox'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y xvfb
+
+      # Run tests on Ubuntu with Firefox
+      - name: Run tests (${{ matrix.os }} - Firefox)
+        if: matrix.os == 'ubuntu-latest' && matrix.browser == 'firefox'
+        run: |
+          # Set environment variables for Firefox WebDriver
+          export BROWSER_PATH="${{ steps.setup-firefox.outputs.firefox-path }}"
+          export RUST_LOG="debug"
+          export RUST_BACKTRACE="1"
+
+          echo "Environment variables set:"
+          echo "BROWSER_PATH: $BROWSER_PATH"
+          echo "RUST_LOG: $RUST_LOG"
+
+          xvfb-run -s "-screen 0 1920x1080x24" cargo test --workspace --features ${{ matrix.features }} --exclude plotly_kaleido
+
+      # Run tests on macOS with Chrome
+      - name: Run tests (${{ matrix.os }} - Chrome)
+        if: matrix.os == 'macos-latest' && matrix.browser == 'chrome'
+        run: cargo test --workspace --features ${{ matrix.features }} --exclude plotly_kaleido
+
+      # Run tests on Windows with Chrome WebDriver
+      - name: Run tests (${{ matrix.os }} - Chrome)
+        if: matrix.os == 'windows-latest' && matrix.browser == 'chrome'
+        shell: pwsh
+        run: |
+          # Set environment variables for WebDriver
+          $env:WEBDRIVER_PATH = "${{ steps.setup-chrome.outputs.chromedriver-path }}"
+          $env:BROWSER_PATH = "${{ steps.setup-chrome.outputs.chrome-path }}"
+          $env:RUST_LOG = "debug"
+          $env:RUST_BACKTRACE = "1"
+          $env:ANGLE_DEFAULT_PLATFORM = "swiftshader"
+
+          Write-Host "Environment variables set:"
+          Write-Host "WEBDRIVER_PATH: $env:WEBDRIVER_PATH"
+          Write-Host "BROWSER_PATH: $env:BROWSER_PATH"
+
+          cargo test --workspace --features ${{ matrix.features }} --exclude plotly_kaleido          
+
+      - name: Upload static image(s) artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: example-pdf-${{ matrix.os }}-${{ matrix.browser }}
+          path: |
+            ${{ github.workspace }}/plotly_static/static_example.*
+            ${{ github.workspace }}/plotly/plotly_example.*
+            ${{ github.workspace }}/plotly/plotly_example_surface.*
+          retention-days: 30
 
   code-coverage:
     name: Code Coverage
@@ -112,6 +227,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+
+      - name: Setup Chrome (for static_export)
+        if: matrix.example == 'static_export'
+        uses: browser-actions/setup-chrome@v1
+        with:
+          chrome-version: 'latest'
+          install-chromedriver: true
+
       - uses: dtolnay/rust-toolchain@stable
       - run: cd ${{ github.workspace }}/examples/${{ matrix.example }} && cargo build
 
@@ -129,11 +252,21 @@ jobs:
           targets: wasm32-unknown-unknown
       - run: cd ${{ github.workspace }}/examples/wasm-yew/${{ matrix.example }} && cargo build --target wasm32-unknown-unknown
 
+
+
   build_book:
     name: Build Book 
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+
+      - name: Setup Chrome (for static_export)
+        uses: browser-actions/setup-chrome@v1
+        with:
+          chrome-version: 'latest'
+          install-chromedriver: true
+        id: setup-chrome
+
       - uses: dtolnay/rust-toolchain@stable
       - run: cargo install mdbook --no-default-features --features search --vers "^0.4" --locked --quiet
       - name: Build examples to generate needed html files
@@ -146,5 +279,6 @@ jobs:
           cd ${{ github.workspace }}/examples/subplots && cargo run
           cd ${{ github.workspace }}/examples/shapes && cargo run
           cd ${{ github.workspace }}/examples/themes && cargo run
+          cd ${{ github.workspace }}/examples/static_export && cargo run
       - name: Build book 
-        run: mdbook build docs/book
+        run: mdbook build docs/book
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,3 +1,3 @@
 [workspace]
 resolver = "2"
-members = ["plotly", "plotly_derive", "plotly_kaleido"]
+members = ["plotly", "plotly_derive", "plotly_kaleido", "plotly_static"]
diff --git a/README.md b/README.md
@@ -53,7 +53,6 @@ A plotting library for Rust powered by [Plotly.js](https://plot.ly/javascript/).
 
 Documentation and numerous interactive examples are available in the [Plotly.rs Book](https://plotly.github.io/plotly.rs/content/getting_started.html), the [examples/](https://github.com/plotly/plotly.rs/tree/main/examples) directory and [docs.rs](https://docs.rs/crate/plotly).
 
-
 For changes since the last version, please consult the [changelog](https://github.com/plotly/plotly.rs/tree/main/CHANGELOG.md).
 
 # Basic Usage
@@ -62,7 +61,7 @@ Add this to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-plotly = "0.12"
+plotly = "0.13"
 ```
 
 ## Exporting a single Interactive Plot
@@ -108,15 +107,40 @@ When the applications developed with `plotly.rs` are intended for other targets
 
 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
+## Exporting Static Images with plotly_static (Recommended)
+
+The recommended way to export static images is using the `plotly_static` backend, which uses a headless browser via WebDriver (Chrome or Firefox) for rendering. This is available via the `static_export_default` feature:
+
+```toml
+[dependencies]
+plotly = { version = "0.13", features = ["static_export_default"] }
+```
+
+This supports PNG, JPEG, WEBP, SVG, and PDF formats:
+
+```rust
+use plotly::{Plot, Scatter, ImageFormat};
+
+let mut plot = Plot::new();
+plot.add_trace(Scatter::new(vec![0, 1, 2], vec![2, 1, 0]));
+
+plot.write_image("out.png", ImageFormat::PNG, 800, 600, 1.0)?;
+plot.write_image("out.svg", ImageFormat::SVG, 800, 600, 1.0)?;
+let base64_data = plot.to_base64(ImageFormat::PNG, 800, 600, 1.0)?;
+let svg_string = plot.to_svg(800, 600, 1.0)?;
+```
+
+**Note:** This feature requires a WebDriver-compatible browser (Chrome or Firefox) as well as a Webdriver (chromedriver/geckodriver) to be available on the system. For advanced usage, see the [`plotly_static` crate documentation](https://docs.rs/plotly_static/).
+
+## Exporting Static Images with Kaleido (to be deprecated)
 
 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.12", features = ["kaleido", "kaleido_download"] }
+plotly = { version = "0.13", features = ["kaleido", "kaleido_download"] }
 ```
 
 Alternatively, enable only the `kaleido` feature and manually install Kaleido.

diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md
@@ -7,6 +7,7 @@
     - [ndarray Support](./fundamentals/ndarray_support.md)
     - [Shapes](./fundamentals/shapes.md)
     - [Themes](./fundamentals/themes.md)
+    - [Static Image Export](./fundamentals/static_image_export.md)
 - [Recipes](./recipes.md)
     - [Basic Charts](./recipes/basic_charts.md)
         - [Scatter Plots](./recipes/basic_charts/scatter_plots.md)

diff --git a/docs/book/src/fundamentals.md b/docs/book/src/fundamentals.md
@@ -18,4 +18,12 @@
 
 # Fundamentals
 
-Functionality that applies to the library as a whole is described in the next sections.
+Functionality that applies to the library as a whole is described in the next sections.
+
+## Core Features
+
+- **[Jupyter Support](./fundamentals/jupyter_support.md)**: Interactive plotting in Jupyter notebooks
+- **[ndarray Support](./fundamentals/ndarray_support.md)**: Integration with the ndarray crate for numerical computing
+- **[Shapes](./fundamentals/shapes.md)**: Adding shapes and annotations to plots
+- **[Themes](./fundamentals/themes.md)**: Customizing plot appearance with themes
+- **[Static Image Export](./fundamentals/static_image_export.md)**: Exporting plots to static images (PNG, JPEG, SVG, PDF) using WebDriver