BinderScriptNotebook

Static image export

Table of contents

As Plotly.NET generates static html pages that contain charts rendered by plotly.js, static image export needs a lot more overhead under the hood than you might expect. The underlying renderer needs to execute javascript, leading to the usage of headless browsers.

The package Plotly.NET.ImageExport contains extensions for Plotly.NET to render static images. It is designed with extensibility in mind and it is very easy to add a new rendering engine. The current engines are provided:

Rendering engine

Type

Prerequisites

PuppeteerSharp

headless browser

read more here

Saving static images

By referencing the Plotly.NET.ImageExport package, you get access to:

  • jpg via Chart.SaveJPG
  • png via Chart.SavePNG
  • svg via Chart.SaveSVG

(and Extensions for C# style fluent interfaces by opening the GenericChartExtensions namespace)

The parameters for all three functions are exactly the same.

open Plotly.NET
open Plotly.NET.ImageExport

let exampleChart = 
    Chart.Histogram2dContour(
        [1.;2.;2.;4.;5.],
        [1.;2.;2.;4.;5.]
    )
exampleChart
|> Chart.saveJPG(
    "/your/path/without/extension/here",
    Width=300,
    Height=300
)

Generating URIs for static chart images

By referencing the Plotly.NET.ImageExport package, you get access to:

  • jpg via Chart.toBase64JPGString
  • png via Chart.toBase64PNGString
  • svg via Chart.toSVGString

(and Extensions for C# style fluent interfaces by opening the GenericChartExtensions namespace)

let base64JPG =
    exampleChart
    |> Chart.toBase64JPGString(
        Width=300,
        Height=300
    )

It is very easy to construct a html tag that includes this image via a base64 uri. For SVGs, not even that is necessary and just the SVG string can be used.

$"""<img
    src= "{base64JPG}"
/>"""

SVGs can be included without the image tag:

let svgString =
    exampleChart
    |> Chart.toSVGString(
        Width=300,
        Height=300
    )

svgString.Substring(0,300)
|> printfn "%s"
<svg class="main-svg" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="300" height="300" style="" viewBox="0 0 300 300"><rect x="0" y="0" width="300" height="300" style="fill: rgb(255, 255, 255); fill-opacity: 1;"/><defs id="defs-aef4d7"><g class="clips"><clipPath

In fact, the images shown on this site are included just the same way.

Including static images in dotnet interactive notebooks

To include the images in dotnet interactive, convert them to html tags as above and include them via dotnet interactive's DisplayAs function. The content type for PNG/JPG is "text/html", and "image/svg+xml" for SVG.

let base64PNGTag =
    let base64 =
        exampleChart
        |> Chart.toBase64PNGString(
            Width=300,
            Height=300
        )
    $"""<img src= "{base64JPG}"/>"""

let svgString2 =
    exampleChart
    |> Chart.toSVGString(
        Width=300,
        Height=300
    )

// DisplayExtensions.DisplayAs(base64PNG,"text/html")
// DisplayExtensions.DisplayAs(svgString2,"image/svg+xml")
namespace Plotly
namespace Plotly.NET
namespace Plotly.NET.ImageExport
val exampleChart : GenericChart.GenericChart
type Chart = static member Area : x:seq<#IConvertible> * y:seq<#IConvertible> * ?Name:string * ?ShowMarkers:bool * ?ShowLegend:bool * ?MarkerSymbol:MarkerSymbol * ?Color:Color * ?Opacity:float * ?Labels:seq<#IConvertible> * ?TextPosition:TextPosition * ?TextFont:Font * ?Dash:DrawingStyle * ?Width:float -> GenericChart + 1 overload static member Bar : values:seq<#IConvertible> * ?Keys:seq<#IConvertible> * ?Name:string * ?ShowLegend:bool * ?Color:Color * ?PatternShape:PatternShape * ?MultiPatternShape:seq<PatternShape> * ?Pattern:Pattern * ?Base:#IConvertible * ?Width:'a3 * ?MultiWidth:seq<'a3> * ?Opacity:float * ?MultiOpacity:seq<float> * ?Text:'a4 * ?MultiText:seq<'a4> * ?TextPosition:TextPosition * ?MultiTextPosition:seq<TextPosition> * ?TextFont:Font * ?Marker:Marker -> GenericChart (requires 'a3 :> IConvertible and 'a4 :> IConvertible) + 1 overload static member BoxPlot : ?x:'a0 * ?y:'a1 * ?Name:string * ?ShowLegend:bool * ?Color:Color * ?Fillcolor:Color * ?Opacity:float * ?Whiskerwidth:'a2 * ?Boxpoints:Boxpoints * ?Boxmean:BoxMean * ?Jitter:'a3 * ?Pointpos:'a4 * ?Orientation:Orientation * ?Marker:Marker * ?Line:Line * ?Alignmentgroup:'a5 * ?Offsetgroup:'a6 * ?Notched:bool * ?NotchWidth:float * ?QuartileMethod:QuartileMethod -> GenericChart + 1 overload static member Bubble : x:seq<#IConvertible> * y:seq<#IConvertible> * sizes:seq<int> * ?Name:string * ?ShowLegend:bool * ?MarkerSymbol:MarkerSymbol * ?Color:Color * ?Opacity:float * ?Labels:seq<#IConvertible> * ?TextPosition:TextPosition * ?TextFont:Font * ?StackGroup:string * ?Orientation:Orientation * ?GroupNorm:GroupNorm * ?UseWebGL:bool -> GenericChart + 1 overload static member Candlestick : open:seq<#IConvertible> * high:seq<#IConvertible> * low:seq<#IConvertible> * close:seq<#IConvertible> * x:seq<#IConvertible> * ?Increasing:Line * ?Decreasing:Line * ?WhiskerWidth:float * ?Line:Line * ?XCalendar:Calendar -> GenericChart + 1 overload static member Column : values:seq<#IConvertible> * ?Keys:seq<#IConvertible> * ?Name:string * ?ShowLegend:bool * ?Color:Color * ?Pattern:Pattern * ?PatternShape:PatternShape * ?MultiPatternShape:seq<PatternShape> * ?Base:#IConvertible * ?Width:'a3 * ?MultiWidth:seq<'a3> * ?Opacity:float * ?MultiOpacity:seq<float> * ?Text:'a4 * ?MultiText:seq<'a4> * ?TextPosition:TextPosition * ?MultiTextPosition:seq<TextPosition> * ?TextFont:Font * ?Marker:Marker -> GenericChart (requires 'a3 :> IConvertible and 'a4 :> IConvertible) + 1 overload static member Contour : data:seq<#seq<'a1>> * ?X:seq<#IConvertible> * ?Y:seq<#IConvertible> * ?Name:string * ?ShowLegend:bool * ?Opacity:float * ?Colorscale:Colorscale * ?Showscale:'a4 * ?zSmooth:SmoothAlg * ?ColorBar:'a5 -> GenericChart (requires 'a1 :> IConvertible) static member Funnel : x:seq<#IConvertible> * y:seq<#IConvertible> * ?Name:string * ?ShowLegend:bool * ?Opacity:float * ?Labels:seq<#IConvertible> * ?TextPosition:TextPosition * ?TextFont:Font * ?Color:Color * ?Line:Line * ?x0:'a3 * ?dX:float * ?y0:'a4 * ?dY:float * ?Width:float * ?Offset:float * ?Orientation:Orientation * ?Alignmentgroup:string * ?Offsetgroup:string * ?Cliponaxis:bool * ?Connector:FunnelConnector * ?Insidetextfont:Font * ?Outsidetextfont:Font -> GenericChart static member Heatmap : data:seq<#seq<'a1>> * ?ColNames:seq<#IConvertible> * ?RowNames:seq<#IConvertible> * ?Name:string * ?ShowLegend:bool * ?Opacity:float * ?Colorscale:Colorscale * ?Showscale:'a4 * ?Xgap:'a5 * ?Ygap:'a6 * ?zSmooth:SmoothAlg * ?ColorBar:'a7 * ?UseWebGL:bool -> GenericChart (requires 'a1 :> IConvertible) static member Histogram : data:seq<#IConvertible> * ?Orientation:Orientation * ?Name:string * ?ShowLegend:bool * ?Opacity:float * ?Color:Color * ?HistNorm:HistNorm * ?HistFunc:HistFunc * ?nBinsx:int * ?nBinsy:int * ?Xbins:Bins * ?Ybins:Bins * ?xError:'a1 * ?yError:'a2 -> GenericChart ...
static member Chart.Histogram2dContour : x:seq<#System.IConvertible> * y:seq<#System.IConvertible> * ?Z:seq<#seq<'d>> * ?Name:'e * ?Colorscale:StyleParam.Colorscale * ?Showscale:'f * ?Line:Line * ?zSmooth:StyleParam.SmoothAlg * ?ColorBar:'g * ?zAuto:'h * ?zMin:'i * ?zMax:'j * ?nBinsx:int * ?nBinsy:int * ?xBins:TraceObjects.Bins * ?yBins:TraceObjects.Bins * ?HistNorm:StyleParam.HistNorm * ?HistFunc:StyleParam.HistFunc -> GenericChart.GenericChart (requires 'd :> System.IConvertible)
static member Chart.saveJPG : path:string * ?EngineType:ExportEngine * ?Width:int * ?Height:int -> (GenericChart.GenericChart -> unit)
static member Chart.toBase64JPGString : ?EngineType:ExportEngine * ?Width:int * ?Height:int -> (GenericChart.GenericChart -> string)
val base64JPG : string
val svgString : string
static member Chart.toSVGString : ?EngineType:ExportEngine * ?Width:int * ?Height:int -> (GenericChart.GenericChart -> string)
System.String.Substring(startIndex: int) : string
System.String.Substring(startIndex: int, length: int) : string
val printfn : format:Printf.TextWriterFormat<'T> -> 'T
<summary>Print to <c>stdout</c> using the given format, and add a newline.</summary>
<param name="format">The formatter.</param>
<returns>The formatted result.</returns>
val base64PNGTag : string
val base64 : string
static member Chart.toBase64PNGString : ?EngineType:ExportEngine * ?Width:int * ?Height:int -> (GenericChart.GenericChart -> string)
val svgString2 : string