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+ [ ![ Binder] ( {{root}}img/badge-binder.svg )] ( https://mybinder.org/v2/gh/plotly/Plotly.NET/gh-pages?filepath={{fsdocs-source-basename}}.ipynb ) &emsp ;
29+ [ ![ Script] ( {{root}}img/badge-script.svg )] ( {{root}}{{fsdocs-source-basename}}.fsx ) &emsp ;
30+ [ ![ Notebook] ( {{root}}img/badge-notebook.svg )] ( {{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