1
- # ' Static image exporting
2
- # '
1
+ # ' Static image exporting
2
+ # '
3
3
# ' Export plotly objects to static images (e.g., pdf, png, jpeg, svg, etc) via the
4
4
# ' [orca command-line utility](https://github.com/plotly/orca#installation).
5
- # '
5
+ # '
6
6
# ' The `orca()` function is designed for exporting one plotly graph whereas `orca_serve()`
7
7
# ' is meant for exporting many graphs at once. The former starts and stops an external (nodejs)
8
8
# ' process everytime it is called whereas the latter starts up a process when called, then
9
- # ' returns an `export()` method for exporting graphs as well as a `close()` method for stopping
9
+ # ' returns an `export()` method for exporting graphs as well as a `close()` method for stopping
10
10
# ' the external (background) process.
11
- # '
11
+ # '
12
12
# ' @param p a plotly object.
13
13
# ' @param file output filename.
14
14
# ' @param format the output format (png, jpeg, webp, svg, pdf, eps).
15
15
# ' @param scale Sets the image scale. Applies to all output images.
16
- # ' @param width Sets the image width. If not set, defaults to `layout.width` value.
16
+ # ' @param width Sets the image width. If not set, defaults to `layout.width` value.
17
17
# ' Applies to all output images.
18
- # ' @param height Sets the image height. If not set, defaults to `layout.height` value.
18
+ # ' @param height Sets the image height. If not set, defaults to `layout.height` value.
19
19
# ' Applies to all output images.
20
20
# ' @param mathjax whether or not to include MathJax (required to render [TeX]).
21
- # ' If `TRUE`, the PLOTLY_MATHJAX_PATH environment variable must be set and point
22
- # ' to the location of MathJax (this variable is also used to render [TeX] in
21
+ # ' If `TRUE`, the PLOTLY_MATHJAX_PATH environment variable must be set and point
22
+ # ' to the location of MathJax (this variable is also used to render [TeX] in
23
23
# ' interactive graphs, see [config]).
24
24
# ' @param parallel_limit Sets the limit of parallel tasks run.
25
25
# ' @param verbose Turn on verbose logging on stdout.
26
26
# ' @param debug Starts app in debug mode and turn on verbose logs on stdout.
27
- # ' @param safe Turns on safe mode: where figures likely to make browser window
27
+ # ' @param safe Turns on safe mode: where figures likely to make browser window
28
28
# ' hang during image generating are skipped.
29
29
# ' @param more_args additional arguments to pass along to system command. This is useful
30
30
# ' for specifying display and/or electron options, such as `--enable-webgl` or `--disable-gpu`.
31
- # ' @param ... for `orca()`, additional arguments passed along to `processx::run`. For
31
+ # ' @param ... for `orca()`, additional arguments passed along to `processx::run`. For
32
32
# ' `orca_serve()`, additional arguments passed along to `processx::process`.
33
33
# ' @export
34
34
# ' @author Carson Sievert
35
35
# ' @md
36
36
# ' @rdname orca
37
37
# ' @examples
38
- # '
38
+ # '
39
39
# ' \dontrun{
40
40
# ' # NOTE: in a headless environment, you may need to set `more_args="--enable-webgl"`
41
41
# ' # to export webgl correctly
42
42
# ' p <- plot_ly(z = ~volcano) %>% add_surface()
43
43
# ' orca(p, "surface-plot.svg")
44
- # '
44
+ # '
45
45
# ' #' # launch the server
46
46
# ' server <- orca_serve()
47
- # '
47
+ # '
48
48
# ' # export as many graphs as you'd like
49
49
# ' server$export(qplot(1:10), "test1.pdf")
50
50
# ' server$export(plot_ly(x = 1:10, y = 1:10), "test2.pdf")
51
- # '
51
+ # '
52
52
# ' # the underlying process is exposed as a field, so you
53
53
# ' # have full control over the external process
54
54
# ' server$process$is_alive()
55
- # '
55
+ # '
56
56
# ' # convenience method for closing down the server
57
57
# ' server$close()
58
- # '
58
+ # '
59
59
# ' # remove the exported files from disk
60
60
# ' unlink("test1.pdf")
61
61
# ' unlink("test2.pdf")
62
62
# ' }
63
- # '
63
+ # '
64
64
65
- orca <- function (p , file = " plot.png" , format = tools :: file_ext(file ),
65
+ orca <- function (p , file = " plot.png" , format = tools :: file_ext(file ),
66
66
scale = NULL , width = NULL , height = NULL , mathjax = FALSE ,
67
- parallel_limit = NULL , verbose = FALSE , debug = FALSE ,
67
+ parallel_limit = NULL , verbose = FALSE , debug = FALSE ,
68
68
safe = FALSE , more_args = NULL , ... ) {
69
-
69
+
70
70
orca_available()
71
-
71
+
72
72
b <- plotly_build(p )
73
-
73
+
74
74
# find the relevant plotly.js bundle
75
75
plotlyjs <- plotlyjsBundle(b )
76
76
plotlyjs_path <- file.path(plotlyjs $ src $ file , plotlyjs $ script )
77
77
# package field means src file path should be relative to pkg dir
78
78
if (! is.null(plotlyjs $ package )) {
79
79
plotlyjs_path <- system.file(plotlyjs_path , package = plotlyjs $ package )
80
80
}
81
-
81
+
82
82
tmp <- tempfile(fileext = " .json" )
83
83
cat(to_JSON(b $ x [c(" data" , " layout" )]), file = tmp )
84
-
84
+
85
85
args <- c(
86
- " graph" , tmp ,
86
+ " graph" , tmp ,
87
87
" -o" , file ,
88
88
" --format" , format ,
89
89
" --plotlyjs" , plotlyjs_path ,
@@ -92,67 +92,67 @@ orca <- function(p, file = "plot.png", format = tools::file_ext(file),
92
92
if (safe ) " --safe-mode" ,
93
93
more_args
94
94
)
95
-
95
+
96
96
if (! is.null(scale )) args <- c(args , " --scale" , scale )
97
97
if (! is.null(width )) args <- c(args , " --width" , width )
98
98
if (! is.null(height )) args <- c(args , " --height" , height )
99
99
if (! is.null(parallel_limit )) args <- c(args , " --parallel-limit" , parallel_limit )
100
100
if (! is.null(tryNULL(mapbox_token()))) args <- c(args , " --mapbox-access-token" , mapbox_token())
101
101
if (isTRUE(mathjax )) args <- c(args , " --mathjax" , file.path(mathjax_path(), " MathJax.js" ))
102
-
102
+
103
103
# TODO: point to local topojson? Should this only work if plot_geo(standalone = TRUE)?
104
104
try_library(" processx" , " orca" )
105
105
invisible (processx :: run(" orca" , args , echo = TRUE , spinner = TRUE , ... ))
106
106
}
107
107
108
108
# ' Orca image export server
109
- # '
109
+ # '
110
110
# ' @inheritParams orca
111
111
# ' @param port Sets the server's port number.
112
112
# ' @param keep_alive Turn on keep alive mode where orca will (try to) relaunch server if process unexpectedly exits.
113
113
# ' @param window_max_number Sets maximum number of browser windows the server can keep open at a given time.
114
114
# ' @param request_limit Sets a request limit that makes orca exit when reached.
115
115
# ' @param quiet Suppress all logging info.
116
- # '
116
+ # '
117
117
# ' @section Methods:
118
- # '
118
+ # '
119
119
# ' The `orca_serve()` function returns an object with two methods:
120
- # '
120
+ # '
121
121
# ' \describe{
122
122
# ' \item{\code{export(p, file = "plot.png", format = tools::file_ext(file), scale = NULL, width = NULL, height = NULL)}}{
123
123
# ' Export a static image of a plotly graph. Arguments found here are the same as those found in `orca()`
124
124
# ' }
125
125
# ' \item{\code{close()}}{Close down the orca server and kill the underlying node process.}
126
126
# ' }
127
- # '
127
+ # '
128
128
# ' @section Fields:
129
- # '
129
+ # '
130
130
# ' The `orca_serve()` function returns an object with two fields:
131
- # '
131
+ # '
132
132
# ' \describe{
133
133
# ' \item{\code{port}}{The port number that the server is listening to.}
134
134
# ' \item{\code{process}}{An R6 class for controlling and querying the underlying node process.}
135
135
# ' }
136
- # '
136
+ # '
137
137
# ' @export
138
138
# ' @rdname orca
139
139
140
140
orca_serve <- function (port = 5151 , mathjax = FALSE , safe = FALSE , request_limit = NULL ,
141
- keep_alive = TRUE , window_max_number = NULL , quiet = FALSE ,
141
+ keep_alive = TRUE , window_max_number = NULL , quiet = FALSE ,
142
142
debug = FALSE , more_args = NULL , ... ) {
143
-
143
+
144
144
# make sure we have the required infrastructure
145
145
orca_available()
146
146
try_library(" processx" , " orca_serve" )
147
-
147
+
148
148
# use main bundle since any plot can be thrown at the server
149
149
plotlyjs <- plotlyMainBundle()
150
150
plotlyjs_path <- file.path(plotlyjs $ src $ file , plotlyjs $ script )
151
151
# package field means src file path should be relative to pkg dir
152
152
if (! is.null(plotlyjs $ package )) {
153
153
plotlyjs_path <- system.file(plotlyjs_path , package = plotlyjs $ package )
154
154
}
155
-
155
+
156
156
args <- c(
157
157
" serve" ,
158
158
" -p" , port ,
@@ -164,21 +164,21 @@ orca_serve <- function(port = 5151, mathjax = FALSE, safe = FALSE, request_limit
164
164
if (quiet ) " --quiet" ,
165
165
more_args
166
166
)
167
-
167
+
168
168
if (! is.null(request_limit ))
169
169
args <- c(args , " --request-limit" , request_limit )
170
-
170
+
171
171
if (! is.null(window_max_number ))
172
172
args <- c(args , " --window-max-number" , window_max_number )
173
-
174
- if (! is.null(tryNULL(mapbox_token())))
173
+
174
+ if (! is.null(tryNULL(mapbox_token())))
175
175
args <- c(args , " --mapbox-access-token" , mapbox_token())
176
-
177
- if (isTRUE(mathjax ))
176
+
177
+ if (isTRUE(mathjax ))
178
178
args <- c(args , " --mathjax" , file.path(mathjax_path(), " MathJax.js" ))
179
-
179
+
180
180
process <- processx :: process $ new(" orca" , args , ... )
181
-
181
+
182
182
list (
183
183
port = port ,
184
184
process = process ,
@@ -193,7 +193,7 @@ orca_serve <- function(port = 5151, mathjax = FALSE, safe = FALSE, request_limit
193
193
scale = scale
194
194
)
195
195
res <- httr :: POST(
196
- paste0(" http://127.0.0.1:" , port ),
196
+ paste0(" http://127.0.0.1:" , port ),
197
197
body = to_JSON(bod )
198
198
)
199
199
httr :: stop_for_status(res )
@@ -204,28 +204,24 @@ orca_serve <- function(port = 5151, mathjax = FALSE, safe = FALSE, request_limit
204
204
)
205
205
}
206
206
207
- correct_orca <- function () {
208
- orca_help <- processx :: run(" orca" , " -h" )
209
- grepl(" plotly" , orca_help [[" stdout" ]], ignore.case = TRUE )
210
- }
211
207
212
208
orca_available <- function () {
213
- if (Sys.which(" orca" ) == " " || ! correct_orca() ) {
209
+ if (Sys.which(" orca" ) == " " ) {
214
210
stop(
215
211
" The orca command-line utility is required for this functionality.\n\n " ,
216
212
" Please follow the installation instructions here -- https://github.com/plotly/orca#installation" ,
217
213
call. = FALSE
218
214
)
219
215
}
220
-
216
+
221
217
TRUE
222
218
}
223
219
224
220
orca_version <- function () {
225
221
orca_available()
226
222
# default to initial release if we can't correctly parse version
227
223
tryCatch(
228
- as.package_version(system(" orca --version" , intern = TRUE )),
224
+ as.package_version(system(" orca --version" , intern = TRUE )),
229
225
error = function (e ) " 1.0.0"
230
226
)
231
227
}
0 commit comments