ParaMonte MATLAB 3.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation.
Figure.m
Go to the documentation of this file.
1%> \brief
2%> This is the abstract class for generating instances of objects
3%> that contain the specifications of various types of Figures.<br>
4%>
5%> \details
6%> This is a generic class for generating figures containing
7%> arbitrary number of subplots (to be added by the subclasses).<br>
8%>
9%> \note
10%> See the list of class attributes below,
11%> also those of the superclass [pm.matlab.Handle](@ref Handle).<br>
12%>
13%> \see
14%> [pm.vis.Cascade](@ref Cascade)<br>
15%> [pm.vis.Subplot](@ref Subplot)<br>
16%> [pm.vis.Triplex](@ref Triplex)<br>
17%> [pm.vis.Figure](@ref Figure)<br>
18%> [pm.vis.Plot](@ref Plot)<br>
19%> [pm.vis.Tile](@ref Tile)<br>
20%>
21%> \final
22%>
23%> \author
24%> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
25%> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
26classdef Figure < pm.matlab.Handle
27
28 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
29
30 properties(Access = public)
31 %>
32 %> ``figure``
33 %>
34 %> A MATLAB ``struct`` whose fields and their values will
35 %> be passed as keyword arguments to the MATLAB intrinsic ``figure``.<br>
36 %> The following are the default components of ``figure``:<br>
37 %>
38 %> <ol>
39 %> <li> ``name`` : Name of the figure, specified as a character vector or a string scalar.<br>
40 %> <li> ``color`` : Background color, specified as an RGB triplet, a hexadecimal
41 %> color code, a color name, or a short name.<br>
42 %> If you specify ``'none'``, the background color appears black on screen,
43 %> but if you print the figure, the background prints as though the figure
44 %> window is transparent.<br>
45 %> <li> ``fileName`` : Character vector or string scalar containing the file name for
46 %> saving the figure specified as a character vector or a string scalar.<br>
47 %> <li> ``position`` : Location and size of the drawable area, specified as
48 %> a vector of the form ``[left bottom width height]``.<br>
49 %> This area excludes the figure borders, title bar, menu bar, and tool bars.<br>
50 %> <li> ``units`` : Units of measurement, specified as one of the following values:<br>
51 %> ``'pixels'`` | ``'normalized'`` | ``'inches'`` | ``'centimeters'`` | ``'points'`` | ``'characters'``.<br>
52 %> The MATLAB documentation of the intrinsic ``figure`` for the meaning of the options.<br>
53 %> <li> ``others`` : See the acceptable keyword arguments of the MATLAB intrinsic ``figure()``.<br>
54 %> </ol>
55 %>
56 %> \warning
57 %> Keep in mind that MATLAB keyword arguments are case-INsensitive.<br>
58 %> Hence, ensure you do not add the same keyword as multiple different fields.<br>
59 %> For example, ``figure.color`` and ``figure.Color`` are the same,
60 %> and only one of the two will be processed.<br>
61 %>
62 %> \example{colormap}
63 %> \code{.m}
64 %>
65 %> self.figure.units = pixels;
66 %> self.figure.color = "none";
67 %>
68 %> \endcode
69 %> <br>
70 %>
71 figure = struct();
72 %>
73 %> ``fout``
74 %>
75 %> A MATLAB ``struct`` whose fields are the outputs of
76 %> various plotting tools used to make the current axis.<br>
77 %>
78 fout = struct();
79 %>
80 %> ``silent``
81 %>
82 %> The scalar MATLAB logical (Boolean) indicator which is ``false`` by default.<br>
83 %> If it is set to ``true``, it will silence all output postprocessing messages (except warnings and errors).<br>
84 %>
85 silent = false;
86 end
87
88 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
89
90 %properties(Access = protected, Hidden)
91 % isdryrun = true; % always false after the first make() method call or reset().
92 %end
93
94 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
95
96 methods(Access = public)
97
98 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
99
100 %> \brief
101 %> Construct and return an object of class [pm.vis.figure.Figure](@ref Figure).<br>
102 %>
103 %> \details
104 %> This is the custom constructor of the class [pm.vis.figure.Figure](@ref Figure).<br>
105 %>
106 %> \param[in] varargin : Any ``property, value`` pair of the parent object.<br>
107 %> If the property is a ``struct()``, then its value must be given as a cell array,
108 %> with consecutive elements representing the struct ``property-name, property-value`` pairs.<br>
109 %> Note that all of these property-value pairs can be also directly set via the
110 %> parent object attributes, before calling the ``make()`` method.<br>
111 %>
112 %> \return
113 %> ``self`` : The output scalar object of class [pm.vis.figure.Figure](@ref Figure).<br>
114 %>
115 %> \interface{Figure}
116 %> \code{.m}
117 %>
118 %> f = pm.vis.figure.Figure();
119 %> f = pm.vis.figure.Figure(varargin);
120 %>
121 %> \endcode
122 %>
123 %> \example{Figure}
124 %> \include{lineno} example/vis/figure/Figure/main.m
125 %> \vis{Figure}
126 %> \image html example/vis/figure/Figure/Figure.himmelblau.3d.png width=700
127 %>
128 %> \final{Figure}
129 %>
130 %> \author
131 %> \JoshuaOsborne, May 21 2024, 12:06 AM, University of Texas at Arlington<br>
132 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
133 function self = Figure(varargin)
134 self.figure = struct();
135 self.reset(varargin{:});
136 end
137
138 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
139
140 %> \brief
141 %> Configure the figure settings and specifications,
142 %> make the figure, and return nothing.<br>
143 %>
144 %> \warning
145 %> This method has side-effects by manipulating
146 %> the existing attributes of the parent object.<br>
147 %>
148 %> \param[inout] self : The input/output parent object of class [pm.vis.figure.Figure](@ref Figure)
149 %> which is **implicitly** passed to this dynamic method (not by the user).<br>
150 %> \param[in] varargin : Any ``property, value`` pair of the parent object.<br>
151 %> If the property is a ``struct()``, then its value must be given as a cell array,
152 %> with consecutive elements representing the struct ``property-name, property-value`` pairs.<br>
153 %> Note that all of these property-value pairs can be also directly set via the
154 %> parent object attributes, before calling the ``make()`` method.<br>
155 %>
156 %> \interface{make}
157 %> \code{.m}
158 %>
159 %> f = pm.vis.figure.Figure.make(varargin);
160 %> f.make()
161 %>
162 %> \endcode
163 %>
164 %> \example{make}
165 %> \include{lineno} example/vis/figure/Figure/main.m
166 %> \vis{make}
167 %> \image html example/vis/figure/Figure/Figure.himmelblau.3d.png width=700
168 %>
169 %> \final{make}
170 %>
171 %> \author
172 %> \JoshuaOsborne, May 21 2024, 8:09 AM, University of Texas at Arlington<br>
173 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
174 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
175 function make(self, varargin)
176
177 self.premake(varargin{:});
178
179 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
180 %%%% RULE 0: No component of ``self`` is allowed to appear to the left of assignment operator, except ``fout``.
181 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
182
183 %%%%
184 %%%% Get keyword arguments.
185 %%%%
186
187 kws = struct();
188 for prop = [ "figure" ...
189 ]
190 if isprop(self, prop)
191 kws.(prop) = self.comp2hash(prop);
192 end
193 end
194
195 self.fout.figure = figure(kws.figure{:});
196 %hold on; This interferes with Heatmap plots.
197
198 %%%%
199 %%%% Resize the figure to allow good default visualization.
200 %%%%
201
202 if isempty(self.figure.outerPosition)
203 maxSize = get(0, 'ScreenSize');
204 figSize = self.fout.figure.OuterPosition;
205 figStart = [(maxSize(3) - figSize(3)) / 2, (maxSize(4) - figSize(4)) / 2];
206 set(self.fout.figure, "OuterPosition", [figStart(1:2), figSize(3:4)]);
207 end
208
209 end % function
210
211 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
212
213 %> \brief
214 %> Reset the properties of the figure to the original default settings.<br>
215 %>
216 %> \details
217 %> Use this method when you change many attributes of the plot and
218 %> you want to clean up and go back to the default settings.<br>
219 %>
220 %> \param[inout] self : The input/output parent object of class [pm.vis.figure.Figure](@ref Figure)
221 %> which is **implicitly** passed to this dynamic method (not by the user).<br>
222 %> \param[in] varargin : Any ``property, value`` pair of the parent object.<br>
223 %> If the property is a ``struct()``, then its value must be given as a cell array,
224 %> with consecutive elements representing the struct ``property-name, property-value`` pairs.<br>
225 %> Note that all of these property-value pairs can be also directly set via the
226 %> parent object attributes, before calling the ``make()`` method.<br>
227 %>
228 %> \interface{reset}
229 %> \code{.m}
230 %>
231 %> pm.vis.figure.Figure.reset() % reset the plot to the default settings.
232 %>
233 %> \endcode
234 %>
235 %> \final{reset}
236 %>
237 %> \author
238 %> \JoshuaOsborne, May 21 2024, 8:11 AM, University of Texas at Arlington<br>
239 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
240 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
241 function reset(self, varargin)
242
243 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
244 %%%% RULE 0: Any non-MATLAB-default setting must be preferably set in premake() method to override user null values.
245 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
246
247 self.figure.alphamap = [];
248 self.figure.color = "white";
249 self.figure.colormap = [];
250 self.figure.fileName = [];
251 self.figure.innerPosition = [];
252 self.figure.name = [];
253 self.figure.numberTitle = [];
254 self.figure.outerPosition = [];
255 self.figure.position = [];
256 self.figure.resize = [];
257 self.figure.units = [];
258 self.figure.visible = [];
259 self.figure.windowState = [];
260 if ~isempty(varargin)
261 self.hash2comp(varargin); % parse arguments
262 end
263
264 end
265
266 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
267
268 end
269
270 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
271
272 methods(Access = public, Hidden)
273
274 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
275
276 %> \brief
277 %> Configure the figure settings and specifications and return nothing.<br>
278 %>
279 %> \warning
280 %> This method has side-effects by manipulating
281 %> the existing attributes of the parent object.<br>
282 %>
283 %> \param[inout] self : The input/output parent object of class [pm.vis.figure.Figure](@ref Figure)
284 %> which is **implicitly** passed to this dynamic method (not by the user).<br>
285 %> \param[in] varargin : Any ``property, value`` pair of the parent object.<br>
286 %> If the property is a ``struct()``, then its value must be given as a cell array,
287 %> with consecutive elements representing the struct ``property-name, property-value`` pairs.<br>
288 %> Note that all of these property-value pairs can be also directly set via the
289 %> parent object attributes, before calling the ``premake()`` method.<br>
290 %>
291 %> \interface{premake}
292 %> \code{.m}
293 %>
294 %> f = pm.vis.figure.Figure(varargin);
295 %> f.premake(varargin);
296 %>
297 %> \endcode
298 %>
299 %> \example{premake}
300 %> \code{.m}
301 %>
302 %> f = pm.vis.figure.Figure();
303 %> f.premake("figure", {"color", "none"})
304 %>
305 %> \endcode
306 %>
307 %> \final{premake}
308 %>
309 %> \author
310 %> \JoshuaOsborne, May 21 2024, 8:13 AM, University of Texas at Arlington<br>
311 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
312 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
313 function premake(self, varargin)
314
315 if ~isempty(varargin)
316 self.hash2comp(varargin); % parse arguments
317 end
318
319 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
320 %%%% These settings must happen here so that they can be reset every time user nullifies the values.
321 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
322
323 %%%% figure
324
325 %if isfield(self.figure, "color") && pm.array.len(self.figure.color) == 0
326 % self.figure.color = "none";
327 %end
328
329 end
330
331 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
332
333 %> \brief
334 %> Convert the components of the input component ``comp``
335 %> of the parent object into a cell array of key-val pairs.<br>
336 %>
337 %> \details
338 %> This is a dynamic method of the class [pm.vis.figure.Figure](@ref Figure).<br>
339 %> This method is used internally by the subclasses to convert the parent object
340 %> attributes to input arguments of MATLAB intrinsic visualization functions.<br>
341 %>
342 %> \param[inout] self : The input/output parent object of class [pm.vis.figure.Figure](@ref Figure)
343 %> which is **implicitly** passed to this dynamic method (not by the user).<br>
344 %> \param[in] comp : The input scalar MATLAB string representing the name of a ``struct``
345 %> component of the parent object, whose fields names and values are to
346 %> be returned as subsequent pairs in the output ``hash`` cell array.<br>
347 %>
348 %> \return
349 %> ``hash`` : The output cell array containing the pairs of ``field-name, field-value``
350 %> of the input MATLAB struct ``comp``.<br>
351 %>
352 %> \interface{comp2hash}
353 %> \code{.m}
354 %>
355 %> a = pm.vis.figure.Figure(varargin);
356 %> hash = a.comp2hash(comp);
357 %>
358 %> \endcode
359 %>
360 %> \warning
361 %> This method has side-effects by manipulating
362 %> the existing attributes of the parent object.<br>
363 %>
364 %> \example{comp2hash}
365 %> \code{.m}
366 %>
367 %> a = pm.vis.figure.Figure("figure", {"color", "white"});
368 %> hash = a.comp2hash("figure");
369 %>
370 %> \endcode
371 %>
372 %> \final{comp2hash}
373 %>
374 %> \author
375 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
376 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
377 function hash = comp2hash(self, comp)
378 unique = true;
379 onlyfull = true;
380 excludes = {"enabled"};
381 hash = pm.matlab.hashmap.struct2hash(self.(comp), excludes, unique, onlyfull);
382 end
383
384 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
385
386 end
387
388 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
389
390 methods(Access = public)
391
392 %> \brief
393 %> Export the current figure to the specified external file.<br>
394 %>
395 %> \details
396 %> This method internally uses the venerable ``export_fig`` MATLAB package.<br>
397 %> As such, it accepts all arguments that the ``export_fig()`` function accepts.<br>
398 %> If no optional argument is present, then a default set of options determined
399 %> by the ``export_fig`` library will be used.<br>
400 %>
401 %> \param[inout] self : The input/output parent object of class [pm.vis.figure.Figure](@ref Figure)
402 %> which is **implicitly** passed to this dynamic method (not by the user).<br>
403 %> \param[in] file : The input scalar MATLAB string or char vector containing
404 %> the path to the external file that will contain the visualization.<br>
405 %> The specified file extension determines its type (e.g., ``.pdf``, ``.png``).<br>
406 %> If no file extension is specified, then the default ``.png`` file extension is used.<br>
407 %> (**optional**. If ``file`` is missing or empty, first, the ``fileName`` component of
408 %> the ``figure`` property of the parent object will be used as the filename if not empty.<br>
409 %> Otherwise, the figure will be exported to a file in the current working directory of
410 %> MATLAB with name ``figure`` suffixed by a unique number and ``.png`` extension.)
411 %> \param[in] varargin : The following optional flags are also acceptable as input string arguments.<br>
412 %> This method internally uses the venerable ``export_fig`` MATLAB package.<br>
413 %> As such, it accepts all arguments that the ``export_fig()`` function accepts.<br>
414 %> If no optional argument is present, then a default set of options determined
415 %> by the ``export_fig`` library will be used.<br>
416 %> The recommended set of optional flags for PNG file formats is ``"-m4 -transparent"``.<br>
417 %> <ol>
418 %> <li> ``"-<format>"``
419 %>
420 %> The input scalar (or variadic array of) MATLAB string(s)
421 %> containing the output file extension(s). Options include:
422 %>
423 %> <ol>
424 %> <li> ``'-pdf'``
425 %> <li> ``'-eps'``
426 %> <li> ``'-emf'``
427 %> <li> ``'-svg'``
428 %> <li> ``'-png'``
429 %> <li> ``'-tif'``
430 %> <li> ``'-jpg'``
431 %> <li> ``'-gif'``
432 %> <li> ``'-bmp'``
433 %> </ol>
434 %>
435 %> Multiple formats can be specified, without restriction.<br>
436 %> For example:
437 %>
438 %> \code{.m}
439 %>
440 %> savefig('-jpg', '-pdf', '-png')
441 %>
442 %> \endcode
443 %>
444 %> Note that ``'-tif'`` and ``'-tiff'`` are equivalent.<br>
445 %>
446 %> <li> ``"-transparent"``
447 %>
448 %> The input option indicating that the figure background is to
449 %> be made transparent (PNG, PDF, TIF, EPS, EMF formats only).<br>
450 %> Specifying this option also activates ``"-noinvert"``.<br>
451 %>
452 %> <li> ``"-nocrop"``
453 %>
454 %> The input option indicating that empty margins should not be cropped.<br>
455 %>
456 %> <li> ``"-c[<val>,<val>,<val>,<val>]"``
457 %>
458 %> The input option indicating the crop amounts. It must be
459 %> a 4-element vector of numeric values: ``[top, right, bottom, left]``
460 %> where NaN/Inf indicates auto-cropping, 0 means no cropping, any
461 %> other value means cropping in pixel amounts. e.g. ``'-c7,15,0,NaN'``
462 %> Note that this option is not supported by SVG and EMF formats.<br>
463 %>
464 %> <li> ``"-p<val>"``
465 %>
466 %> The input option to pad a border of width ``val`` to exported files,
467 %> where ``val`` is either a relative size with respect to cropped image
468 %> size (i.e. ``p = 0.01`` adds a ``1%`` border). For EPS & PDF formats,
469 %> ``val`` can also be integer in units of ``1/72`` points (``abs(val) > 1``).<br>
470 %> ``val`` can be positive (padding) or negative (extra cropping).<br>
471 %> If used, the ``-nocrop`` flag will be ignored, i.e. the image will
472 %> always be cropped and then padded. Default: ``0`` (i.e. no padding).<br>
473 %> Note: this option is not supported by SVG and EMF formats.<br>
474 %>
475 %> <li> ``"-m<val>"``
476 %>
477 %> The input option ``val`` indicates the factor to magnify the figure
478 %> dimensions when generating bitmap outputs (does not affect vector formats).<br>
479 %> Default: '-m1' (i.e. val=1). Note: val~=1 slows down savefig.<br>
480 %>
481 %> <li> ``"-r<val>"``
482 %>
483 %> The input option ``val`` indicates the resolution (in pixels per inch)
484 %> to export bitmap and vector outputs, without changing dimensions of
485 %> the on-screen figure. Default: '-r864' (for vector output only).<br>
486 %> Note: -m option overides -r option for bitmap exports only.<br>
487 %>
488 %> <li> ``"-native"``
489 %>
490 %> The input option indicating that the output resolution (when
491 %> outputting a bitmap format) should be such that the vertical
492 %> resolution of the first suitable image found in the figure is
493 %> at the native resolution of that image. To specify a particular
494 %> image to use, give it the tag 'export_fig_native'.<br>
495 %> Notes: This overrides any value set with the -m and -r options.<br>
496 %> It also assumes that the image is displayed front-to-parallel
497 %> with the screen. The output resolution is approximate and
498 %> should not be relied upon. Anti-aliasing can have adverse
499 %> effects on image quality (disable with the -a1 option).<br>
500 %>
501 %> <li> ``"-a1, -a2, -a3, -a4"``
502 %>
503 %> The input option indicating the amount of anti-aliasing (AA) to
504 %> use for bitmap outputs, when GraphicsSmoothing is not available.<br>
505 %> '-a1'=no AA; '-a4'=max. Default: 3 for HG1, 1 for HG2.<br>
506 %>
507 %> <li> ``"-<renderer>"``
508 %>
509 %> The input option to force a particular renderer (painters, opengl or
510 %> [in R2014a or older] zbuffer). Default value: opengl for bitmap
511 %> formats or figures with patches and/or transparent annotations;
512 %> painters for vector formats without patches/transparencies.<br>
513 %>
514 %> <li> ``"-<colorspace>"``
515 %>
516 %> The input option indicating which colorspace color figures should
517 %> be saved in: RGB (default), CMYK or gray. Usage example: '-gray'.<br>
518 %> Note: CMYK is only supported in PDF, EPS and TIF formats.<br>
519 %>
520 %> <li> ``"-q<val>"``
521 %>
522 %> The input option to vary bitmap image quality (PDF, EPS, JPG formats only).<br>
523 %> A larger val, in the range 0-100, produces higher quality and
524 %> lower compression. val > 100 results in lossless compression.<br>
525 %> Default: '-q95' for JPG, ghostscript prepress default for PDF,EPS.<br>
526 %> Note: lossless compression can sometimes give a smaller file size
527 %> than the default lossy compression, depending on the image type.<br>
528 %>
529 %> <li> ``"-n<val>"``
530 %>
531 %> The input option to set minimum output image size (bitmap formats only).<br>
532 %> The output size can be specified as a single value (for both rows
533 %> & cols, e.g. ``-n200``) or comma-separated values (e.g. ``-n300,400``).<br>
534 %> Use an Inf value to keep a dimension unchanged (e.g. ``-n50,inf``).<br>
535 %> Use a NaN value to keep aspect ratio unchanged (e.g. ``-n50,nan``).<br>
536 %>
537 %> <li> ``"-x<val>"``
538 %>
539 %> The input option to set maximum output image size (bitmap formats only).<br>
540 %> The output size can be specified as a single value (for both rows
541 %> & cols, e.g. ``-x200``) or comma-separated values (e.g. ``-x300,400``).<br>
542 %> Use an Inf value to keep a dimension unchanged (e.g. ``-x50,inf``).<br>
543 %> Use a NaN value to keep aspect ratio unchanged (e.g. ``-x50,nan``).<br>
544 %>
545 %> <li> ``"-s<val>"``
546 %>
547 %> The input option to scale output image to specific size (bitmap formats only).<br>
548 %> The fixed size can be specified as a single value (for rows=cols) or
549 %> comma-separated values (e.g. ``-s300,400``). Each value can be a scalar
550 %> integer (signifying pixels) or percentage (e.g. ``-s125%``). The scaling
551 %> is done last, after any other cropping/rescaling due to other params.<br>
552 %>
553 %> <li> ``"-append"``
554 %>
555 %> The input option indicating that if the file already exists the figure is to
556 %> be appended as a new page, instead of being overwritten (default).<br>
557 %> PDF, TIF & GIF output formats only (multi-image GIF = animated).<br>
558 %>
559 %> <li> ``"-bookmark"``
560 %>
561 %> The input option to indicate that a bookmark with the name of the
562 %> figure is to be created in the output file (PDF format only).<br>
563 %>
564 %> <li> ``"-clipboard"``
565 %>
566 %> The input option to save output as an image on the system clipboard.<br>
567 %>
568 %> <li> ``"-clipboard<:format>"``
569 %>
570 %> The input copies to clipboard in the specified format:
571 %> image (default), bitmap, emf, or pdf.<br>
572 %> Notes that only ``-clipboard`` (or ``-clipboard:image``, which is the same)
573 %> applies export_fig parameters such as cropping, padding etc.
574 %> <ol>
575 %> <li> ``-clipboard:image`` create a bitmap image using export_fig processing
576 %> <li> ``-clipboard:bitmap`` create a bitmap image as-is (no auto-cropping etc.)
577 %> <li> ``-clipboard:emf`` is vector format without auto-cropping; Windows-only.
578 %> <li> ``-clipboard:pdf`` is vector format without cropping; not universally supported
579 %> </ol>
580 %>
581 %> <li> ``"-d<gs_option>"``
582 %>
583 %> The input option to indicate a ghostscript setting. For example,
584 %> ``-dMaxBitmap=0`` or ``-dNoOutputFonts`` (Ghostscript 9.15+).<br>
585 %>
586 %> <li> ``"-depsc"``
587 %>
588 %> The input option to use EPS level-3 rather than the default level-2 print
589 %> device. This solves some bugs with MATLAB's default -depsc2 device
590 %> such as discolored subplot lines on images (vector formats only).<br>
591 %>
592 %> <li> ``"-metadata <metaDataInfo>"``
593 %>
594 %> The input adds the specified meta-data information to the
595 %> exported file (PDF format only). metaDataInfo must be either a struct
596 %> or a cell array with pairs of values: ``{'fieldName', fieldValue, ...}``.<br>
597 %> Common metadata fields are Title, Author, Creator, Producer, Subject, Keywords.<br>
598 %>
599 %> <li> ``"-nofontswap"``
600 %>
601 %> The input option to avoid font swapping. Font swapping is automatically
602 %> done in vector formats (only): 11 standard MATLAB fonts are
603 %> replaced by the original figure fonts. This option prevents this.<br>
604 %>
605 %> <li> ``"-font_space <char>"``
606 %>
607 %> The input option to set a spacer character for font-names that
608 %> contain spaces, used by EPS/PDF. Default: ''<br>
609 %>
610 %> <li> ``"-linecaps"``
611 %>
612 %> The input option to create rounded line-caps (vector formats only).<br>
613 %>
614 %> <li> ``"-noinvert"``
615 %>
616 %> The input option to avoid setting figure's InvertHardcopy property to
617 %> 'off' during output (this solves some problems of empty outputs).<br>
618 %>
619 %> <li> ``"-preserve_size"``
620 %>
621 %> The input option to preserve the figure's PaperSize property in output
622 %> file (PDF/EPS formats only; default is to not preserve it).<br>
623 %>
624 %> <li> ``"-options <optionsStruct>"``
625 %>
626 %> The input format-specific parameters as defined in MATLAB's
627 %> documentation of the ``imwrite`` function, contained in a struct under
628 %> the format name. For example to specify the JPG Comment parameter,
629 %> pass a struct such as this: ``options.JPG.Comment='abc'``.<br>
630 %> Similarly, ``options.PNG.BitDepth = 4``.<br>
631 %> Only used by PNG, TIF, JPG, GIF output formats.<br>
632 %> Options can also be specified as a cell array of name-value pairs,
633 %> e.g. ``{'BitDepth', 4, 'Author', 'Yair'}``. These options will be used
634 %> by all supported output formats of the [pm.vis.figure.savefig](@ref savefig) function.<br>
635 %>
636 %> <li> ``"-silent"``
637 %>
638 %> The input option to avoid various warning and informational messages,
639 %> such as version update checks, transparency or renderer issues, etc.<br>
640 %>
641 %> <li> ``"-notify"``
642 %>
643 %> The input option to notify the user when export is done, in both a console
644 %> message and a popup dialog (allow opening the exported file/folder).<br>
645 %>
646 %> <li> ``"-regexprep <old> <new>"``
647 %>
648 %> The input replaces all occurrences of ``<old>`` (a regular expression
649 %> string or array of strings; case-sensitive), with the corresponding
650 %> new string(s), in EPS/PDF files (only). See regexp function's doc.<br>
651 %> Warning: invalid replacement can make your EPS/PDF file unreadable!<br>
652 %>
653 %> <li> ``"-toolbar"``
654 %>
655 %> The input adds an interactive export button to the figure's toolbar<br>
656 %>
657 %> <li> ``"-menubar"``
658 %>
659 %> The input adds an interactive export menu to the figure's menubar<br>
660 %>
661 %> <li> ``"-contextmenu"``
662 %>
663 %> The input adds interactive export menu to figure context-menu (right-click)<br>
664 %>
665 %> <li> ``"handle"``<br>
666 %>
667 %> The input handle of the figure, axes or uipanels (can be an array of handles
668 %> but all the objects must be in the same figure) to be exported.<br>
669 %> The default is ``gcf`` (handle of current figure).<br>
670 %>
671 %> <li> ``"figName"``
672 %>
673 %> The input name (title) of the figure to export (e.g. ``'Figure 1'`` or ``'My fig'``).<br>
674 %> Overridden by handle (if specified)<br>
675 %> The default is the current figure.<br>
676 %> </ol>
677 %>
678 %> \return
679 %> ``imageData`` : The output image cube of type ``uint8`` of
680 %> shape ``[M, N, C]`` containing the exported figure data.<br>
681 %> ``alpha`` : The output image matrix of shape ``[M, N]`` of alpha-matte
682 %> values in the range ``[0, 1]`` for the case of transparent background.<br>
683 %>
684 %> \interface{savefig}
685 %> \code{.m}
686 %>
687 %> f = pm.vis.figure.Figure();
688 %> [imageData, alpha] = f.savefig();
689 %> [imageData, alpha] = f.savefig(file);
690 %> [imageData, alpha] = f.savefig(file, varargin{:});
691 %>
692 %> \endcode
693 %>
694 %> \example{savefig}
695 %> \code{.m}
696 %>
697 %> f = pm.vis.figure.Figure();
698 %> f.savefig(); % export the current figure with the default name.
699 %> f.savefig("gridplot.pdf") % export figure to the specified PDF file.
700 %> f.savefig("gridplot.png", "-m4 -transparent") % export a large png plot of magnitude 4 with transparency.
701 %>
702 %> \endcode
703 %>
704 %> \final{savefig}
705 %>
706 %> \author
707 %> \JoshuaOsborne, May 21 2024, 8:19 AM, University of Texas at Arlington<br>
708 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
709 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
710 function savefig(self, file, varargin)
711
712 if nargin < 2
713 file = [];
714 end
715 if pm.array.len(file) == 0
716 if ~isempty(self.figure.fileName)
717 file = string(self.figure.fileName);
718 else
719 if ~isempty(self.figure.name)
720 prefix = string(self.figure.name);
721 else
722 prefix = "figure";
723 end
724 fid = 0;
725 while true
726 fid = fid + 1;
727 file = prefix + "." + string(fid) + ".png";
728 if ~isfile(file)
729 break;
730 end
731 end
732 end
733 end
734
735 %%%%
736 %%%% Check the consistency of the file name.
737 %%%%
738
739 if ~pm.introspection.istype(file, "string", 1)
740 help("pm.vis.figure.Figure");
741 disp("file = ");
742 disp(file);
743 error ( newline ...
744 + "The optional input argument ``file`` to method ``savefig()``" + newline ...
745 + "must be a scalar MATLAB string or char vector containing the output file name." + newline ...
746 + "For more information, see the class documentation displayed above." + newline ...
747 + newline ...
748 );
749 end
750
751 %%%%
752 %%%% Focus on the target figure to export.
753 %%%%
754
755 if isfield(self.fout, "figure")
756 set(0, "CurrentFigure", self.fout.figure);
757 else
758 set(0, "CurrentFigure", gcf);
759 end
760
761 %%%%
762 %%%% Ensure transparency if figure must be transparent.
763 %%%%
764
765 if any(contains(string(varargin), "-transparent"))
766 istransparent = true;
767 failed = false;
768 errmsg = "";
769 try
770 set(self.fout.figure, "color", "none");
771 catch me
772 failed = true;
773 errmsg = string(me.identifier) + " : " + string(me.message) + newline;
774 end
775 try
776 set(gca, "color", "none");
777 catch me
778 failed = true;
779 errmsg = string(me.identifier) + " : " + string(me.message) + newline;
780 end
781 if failed
782 warning ( newline + errmsg ...
783 + "Failed to set the color property of gcf to ""none"" for transparent image export." + newline ...
784 );
785 end
786 else
787 istransparent = false;
788 end
789
790 pm.vis.figure.savefig(file, varargin{:});
791
792 %%%%
793 %%%% Revert transparency if figure ws not transparent.
794 %%%%
795
796 if istransparent
797 failed = false;
798 errmsg = "";
799 try
800 set(self.currentFig.figure, "color", "default");
801 catch me
802 failed = true;
803 errmsg = string(me.identifier) + " : " + string(me.message) + newline;
804 end
805 try
806 set(gca,"color","default");
807 catch me
808 failed = true;
809 errmsg = string(me.identifier) + " : " + string(me.message) + newline;
810 end
811 if failed
812 warning ( newline + errmsg ...
813 + "Failed to set the color property of gca back to ""default""." + newline ...
814 );
815 end
816 end
817
818 end
819
820 end
821
822 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
823
824end
name
function name(in vendor)
Return the MPI library name as used in naming the ParaMonte MATLAB shared library directories.
list
function list()
Return a list of MATLAB strings containing the names of OS platforms supported by the ParaMonte MATLA...
version
function version(in silent)
Return a scalar MATLAB string containing the latest available ParaMonte MATLAB version newer than the...
abs
function abs(in path, in style)
Return the Get absolute canonical path of a file or folder.
Cascade
This is the abstract class for generating instances of objects that contain the specifications of a c...
Definition: Cascade.m:32
Figure
This is the abstract class for generating instances of objects that contain the specifications of var...
Definition: Figure.m:27
Figure::premake
function premake(in self, in varargin)
Configure the figure settings and specifications and return nothing.
Figure::Figure
function Figure(in varargin)
Construct and return an object of class pm.vis.figure.Figure.
Figure::fout
Property fout
Definition: Figure.m:82
Figure::figure
Property figure
Definition: Figure.m:74
Figure::make
function make(in self, in varargin)
Configure the figure settings and specifications, make the figure, and return nothing.
Figure::comp2hash
function comp2hash(in self, in comp)
Convert the components of the input component comp of the parent object into a cell array of key-val ...
Figure::silent
Property silent
Definition: Figure.m:90
Figure::reset
function reset(in self, in varargin)
Reset the properties of the figure to the original default settings.
Figure::savefig
function savefig(in self, in file, in varargin)
Export the current figure to the specified external file.
Handle
This is the base class for generating subclass of MATLAB handle superclass whose annoying methods are...
Definition: Handle.m:24
Plot
This is the base class for generating instances of objects that contain the specifications of various...
Definition: Plot.m:29
Subplot
This is the abstract class for generating instances of axes with various types of plots from one or m...
Definition: Subplot.m:188
Tile
This is the abstract class for generating instances of objects that contain the specifications of var...
Definition: Tile.m:23
Triplex
This is the base class for generating instances of figures containing a square symmetric tiling of su...
Definition: Triplex.m:31
clean
function clean()
Remove all paths that contain the ParaMonte lib directory from the MATLAB path variable.
ghostscript
function ghostscript(in cmd)
hash2comp
function hash2comp(in hashmap, in object, in insensitive, in extensible, in recursive)
Return a copy of the input object whose property (or field) values are overwritten with the correspon...
istype
function istype(in varval, in vartype, in varsize)
Return true if and only if the input varval conforms with the specified input type vartype and the sp...
parallel
function parallel()
Return a scalar MATLAB logical that is true if and only if the current installation of MATLAB contain...
savefig
function savefig(in varargin)
Export figures in a publication-quality format.
which
function which(in vendor)
Return the a MATLAB string containing the path to the first mpiexec executable binary found in system...