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