1+ (**
2+ ---
3+ title: Static image export
4+ category: General
5+ categoryindex: 1
6+ index: 2
7+ ---
8+ *)
9+
10+
11+ (*** hide ***)
12+
13+ (*** condition: prepare ***)
14+ #r " nuget: Newtonsoft.JSON, 12.0.3"
15+ #r " nuget: PuppeteerSharp"
16+ #r " ../bin/Plotly.NET/netstandard2.0/Plotly.NET.dll"
17+ #r " ../bin/Plotly.NET.ImageExport/netstandard2.0/Plotly.NET.ImageExport.dll"
18+
19+ (*** condition: ipynb ***)
20+ #if IPYNB
21+ #r " nuget: Plotly.NET, {{fsdocs-package-version}}"
22+ #r " nuget: Plotly.NET.Interactive, {{fsdocs-package-version}}"
23+ #r " nuget: Plotly.NET.ImageExport, {{fsdocs-package-version}}"
24+ #endif // IPYNB
25+
26+
27+ (**
28+ [](https://mybinder.org/v2/gh/plotly/Plotly.NET/gh-pages?filepath={{fsdocs-source-basename}}.ipynb) 
29+ []({{root}}{{fsdocs-source-basename}}.fsx) 
30+ []({{root}}{{fsdocs-source-basename}}.ipynb)
31+
32+ # Static image export
33+
34+ ### Table of contents
35+
36+ - [Saving static images](#Saving-static-images)
37+ - [Generating URIs for static chart images](#Generating-URIs-for-static-chart-images)
38+ - [Including static images in dotnet interactive notebooks](#Including-static-images-in-dotnet-interactive-notebooks)
39+
40+ 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
41+ than you might expect. The underlying renderer needs to execute javascript, leading to the usage of headless browsers.
42+
43+ The package `Plotly.NET.ImageExport` contains extensions for Plotly.NET to render static images. It is designed with extensibility in mind and
44+ it is very easy to add a new rendering engine. The current engines are provided:
45+
46+ | Rendering engine | Type | Prerequisites |
47+ |-|-|-|
48+ | [PuppeteerSharp](https://github.com/hardkoded/puppeteer-sharp) | headless browser | [read more here](https://github.com/hardkoded/puppeteer-sharp#prerequisites) |
49+
50+ ## Saving static images
51+
52+ By referencing the `Plotly.NET.ImageExport` package, you get access to:
53+
54+ - jpg via `Chart.SaveJPG`
55+ - png via `Chart.SavePNG`
56+ - svg via `Chart.SaveSVG`
57+
58+ (and Extensions for C# style fluent interfaces by opening the `GenericChartExtensions` namespace)
59+
60+ The parameters for all three functions are exactly the same.
61+ *)
62+
63+ open Plotly.NET
64+ open Plotly.NET .ImageExport
65+
66+ let exampleChart =
67+ Chart.Histogram2dContour(
68+ [ 1. ; 2. ; 2. ; 4. ; 5. ],
69+ [ 1. ; 2. ; 2. ; 4. ; 5. ]
70+ )
71+
72+ (***do-not-eval***)
73+ exampleChart
74+ |> Chart.saveJPG(
75+ " /your/path/without/extension/here" ,
76+ Width= 300 ,
77+ Height= 300
78+ )
79+
80+ (*** condition: ipynb ***)
81+ #if IPYNB
82+ let imgString = $""" <img
83+ src= "{exampleChart|> Chart.toBase64JPGString(Width=300,Height=300)}"
84+ />"""
85+ DisplayExtensions.DisplayAs( imgString, " text/html" )
86+ #endif // IPYNB
87+
88+ (***hide***)
89+ $""" <img
90+ src= "{exampleChart|> Chart.toBase64JPGString(Width=300,Height=300)}"
91+ />"""
92+ (***include-it-raw***)
93+
94+ (**
95+ ## Generating URIs for static chart images
96+
97+ By referencing the `Plotly.NET.ImageExport` package, you get access to:
98+
99+ - jpg via `Chart.toBase64JPGString`
100+ - png via `Chart.toBase64PNGString`
101+ - svg via `Chart.toSVGString`
102+
103+ (and Extensions for C# style fluent interfaces by opening the `GenericChartExtensions` namespace)
104+
105+ *)
106+
107+ let base64JPG =
108+ exampleChart
109+ |> Chart.toBase64JPGString(
110+ Width= 300 ,
111+ Height= 300
112+ )
113+
114+ (**
115+ It is very easy to construct a html tag that includes this image via a base64 uri. For SVGs,
116+ not even that is necessary and just the SVG string can be used.
117+ *)
118+
119+ (***do-not-eval***)
120+ $""" <img
121+ src= "{base64JPG}"
122+ />"""
123+
124+ (*** condition: ipynb ***)
125+ #if IPYNB
126+ let imgString = $""" <img
127+ src= "{base64JPG}"
128+ />"""
129+ DisplayExtensions.DisplayAs( imgString, " text/html" )
130+ #endif // IPYNB
131+
132+ (***hide***)
133+ $""" <img
134+ src= "{base64JPG}"
135+ />"""
136+
137+ (***include-it-raw***)
138+
139+ (**
140+ SVGs can be included without the image tag:
141+ *)
142+
143+ let svgString =
144+ exampleChart
145+ |> Chart.toSVGString(
146+ Width= 300 ,
147+ Height= 300
148+ )
149+
150+ svgString.Substring( 0 , 300 )
151+ |> printfn " %s "
152+
153+ (***include-output***)
154+
155+ (**
156+ In fact, the images shown on this site are included just the same way.
157+
158+ ## Including static images in dotnet interactive notebooks
159+
160+ To include the images in dotnet interactive, convert them to html tags as above and include them via
161+ dotnet interactive's `DisplayAs` function. The content type for PNG/JPB is "text/html", and "image/svg+xml" for SVG.
162+ *)
163+
164+ let base64PNG =
165+ exampleChart
166+ |> Chart.toBase64PNGString(
167+ Width= 300 ,
168+ Height= 300
169+ )
170+
171+ let svgString2 =
172+ exampleChart
173+ |> Chart.toSVGString(
174+ Width= 300 ,
175+ Height= 300
176+ )
177+
178+ // DisplayExtensions.DisplayAs(base64PNG,"text/html")
179+ // DisplayExtensions.DisplayAs(svgString,"image/svg+xml")
180+
181+ (*** condition: ipynb ***)
182+ #if IPYNB
183+ DisplayExtensions.DisplayAs( base64PNG, " text/html" )
184+ DisplayExtensions.DisplayAs( svgString, " image/svg+xml" )
185+ #endif // IPYNB
0 commit comments