2%> This is the abstract
class for generating instances of objects
3%> that contain the specifications of various types of Figures.<br>
6%> This is a
generic class for generating figures containing
7%> arbitrary number of subplots (to be added by the subclasses).<br>
10%> See the
list of
class attributes below,
11%> also those of the superclass [pm.matlab.Handle](@ref
Handle).<br>
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>
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>
28 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
30 properties(Access =
public)
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>
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>
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>
65 %> self.figure.units = pixels;
66 %> self.figure.color =
"none";
75 %> A MATLAB ``
struct`` whose fields are the outputs of
76 %> various plotting tools used to make the current axis.<br>
81 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
83 %properties(Access =
protected, Hidden)
84 % isdryrun =
true; % always
false after the first make() method call or reset().
87 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
89 methods(Access = public)
91 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
94 %> Construct and return an
object of class [pm.vis.figure.
Figure](@ref
Figure).<br>
97 %> This is the custom constructor of the class [pm.vis.figure.
Figure](@ref
Figure).<br>
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>
106 %> ``self`` : The output scalar
object of class [pm.vis.figure.
Figure](@ref
Figure).<br>
111 %> f = pm.vis.
figure.Figure();
112 %> f = pm.vis.figure.Figure(varargin);
117 %> \include{lineno} example/vis/figure/
Figure/main.m
119 %> \image html example/vis/figure/
Figure/
Figure.himmelblau.3d.png width=700
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)
128 self.reset(varargin{:});
131 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
134 %> Configure the figure settings and specifications,
135 %> make the figure, and
return nothing.<br>
138 %> This method has side-effects by manipulating
139 %> the existing attributes of the parent
object.<br>
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>
152 %> f = pm.vis.figure.Figure.make(varargin);
158 %> \include{lineno} example/vis/figure/
Figure/main.m
160 %> \image html example/vis/figure/
Figure/
Figure.himmelblau.3d.png width=700
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)
172 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
173 %%%% RULE 0: No component of ``self`` is allowed to appear to the left of assignment
operator, except ``fout``.
174 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
177 %%%% Get keyword arguments.
181 for prop = [
"figure" ...
183 if isprop(self, prop)
184 kws.(prop) = self.comp2hash(prop);
188 self.fout.figure = figure(kws.figure{:});
189 %hold on; This interferes with Heatmap plots.
192 %%%% Resize the figure to allow good
default visualization.
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)]);
204 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
207 %> Reset the properties of the figure to the original default settings.<br>
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>
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>
224 %> pm.vis.figure.Figure.reset() % reset the plot to the
default settings.
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)
236 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
237 %%%% RULE 0: Any non-MATLAB-
default setting must be preferably set in premake() method to override user null values.
238 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
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
259 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
263 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
265 methods(Access = public, Hidden)
267 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
270 %> Configure the figure settings and specifications and return nothing.<br>
273 %> This method has side-effects by manipulating
274 %> the existing attributes of the parent
object.<br>
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>
284 %> \interface{premake}
287 %> f = pm.vis.figure.Figure(varargin);
288 %> f.premake(varargin);
295 %> f = pm.vis.figure.Figure();
296 %> f.premake(
"figure", {
"color",
"none"})
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)
308 if ~isempty(varargin)
309 self.hash2comp(varargin); % parse arguments
312 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
313 %%%% These settings must happen here so that they can be reset every time user nullifies the values.
314 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
318 %
if isfield(self.figure,
"color") && pm.array.len(self.figure.color) == 0
319 % self.figure.color =
"none";
324 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
327 %> Convert the components of the input component ``comp``
328 %> of the parent
object into a cell array of key-val pairs.<br>
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>
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>
342 %> ``hash`` : The output cell array containing the pairs of ``field-
name, field-value``
343 %> of the input MATLAB
struct ``comp``.<br>
345 %> \interface{comp2hash}
348 %> a = pm.vis.figure.Figure(varargin);
349 %> hash = a.comp2hash(comp);
354 %> This method has side-effects by manipulating
355 %> the existing attributes of the parent
object.<br>
357 %> \example{comp2hash}
360 %> a = pm.vis.figure.Figure(
"figure", {
"color",
"white"});
361 %> hash = a.comp2hash(
"figure");
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)
373 excludes = {
"enabled"};
374 hash = pm.matlab.hashmap.struct2hash(self.(comp), excludes, unique, onlyfull);
377 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
381 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
383 methods(Access =
public)
386 %> Export the current figure to the specified external file.<br>
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>
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>
411 %> <li> ``
"-<format>"``
413 %> The input scalar (or variadic array of) MATLAB string(s)
414 %> containing the output file extension(s). Options include:
428 %> Multiple formats can be specified, without restriction.<br>
433 %>
savefig(
'-jpg',
'-pdf',
'-png')
437 %> Note that ``
'-tif'`` and ``
'-tiff'`` are equivalent.<br>
439 %> <li> ``
"-transparent"``
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>
445 %> <li> ``
"-nocrop"``
447 %> The input option indicating that empty margins should not be cropped.<br>
449 %> <li> ``
"-c[<val>,<val>,<val>,<val>]"``
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>
457 %> <li> ``
"-p<val>"``
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>
468 %> <li> ``
"-m<val>"``
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>
474 %> <li> ``
"-r<val>"``
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>
481 %> <li> ``
"-native"``
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>
494 %> <li> ``
"-a1, -a2, -a3, -a4"``
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>
500 %> <li> ``
"-<renderer>"``
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>
507 %> <li> ``
"-<colorspace>"``
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>
513 %> <li> ``
"-q<val>"``
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>
522 %> <li> ``
"-n<val>"``
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>
530 %> <li> ``
"-x<val>"``
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>
538 %> <li> ``
"-s<val>"``
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>
546 %> <li> ``
"-append"``
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>
552 %> <li> ``
"-bookmark"``
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>
557 %> <li> ``
"-clipboard"``
559 %> The input option to save output as an image on the system clipboard.<br>
561 %> <li> ``
"-clipboard<:format>"``
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.
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
574 %> <li> ``
"-d<gs_option>"``
576 %> The input option to indicate a
ghostscript setting. For example,
577 %> ``-dMaxBitmap=0`` or ``-dNoOutputFonts`` (Ghostscript 9.15+).<br>
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>
585 %> <li> ``"-metadata <metaDataInfo>"``
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>
592 %> <li> ``"-nofontswap"``
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>
598 %> <li> ``"-font_space <char>"``
600 %> The input option to set a spacer character for font-names that
601 %> contain spaces, used by EPS/PDF. Default: ''<br>
603 %> <li> ``"-linecaps"``
605 %> The input option to create rounded line-caps (vector formats only).<br>
607 %> <li> ``"-noinvert"``
609 %> The input option to avoid setting figure's InvertHardcopy property to
610 %>
'off' during output (
this solves some problems of empty outputs).<br>
612 %> <li> ``
"-preserve_size"``
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>
617 %> <li> ``"-options <optionsStruct>"``
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>
629 %> <li> ``
"-silent"``
631 %> The input option to avoid various warning and informational messages,
632 %> such as
version update checks, transparency or renderer issues, etc.<br>
634 %> <li> ``
"-notify"``
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>
639 %> <li> ``
"-regexprep <old> <new>"``
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>
646 %> <li> ``"-toolbar"``
648 %> The input adds an interactive export button to the figure's toolbar<br>
650 %> <li> ``
"-menubar"``
652 %> The input adds an interactive export menu to the figure
's menubar<br>
654 %> <li> ``"-contextmenu"``
656 %> The input adds interactive export menu to figure context-menu (right-click)<br>
658 %> <li> ``"handle"``<br>
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>
664 %> <li> ``"figName"``
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>
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>
680 %> f = pm.vis.figure.Figure();
681 %> [imageData, alpha] = f.savefig();
682 %> [imageData, alpha] = f.savefig(file);
683 %> [imageData, alpha] = f.savefig(file, varargin{:});
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.
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)
708 if pm.array.len(file) == 0
709 if ~isempty(self.figure.fileName)
710 file =
string(self.figure.fileName);
712 if ~isempty(self.figure.
name)
713 prefix =
string(self.figure.
name);
720 file = prefix + "." +
string(fid) + ".png";
729 %%%% Check the consistency of the file
name.
732 if ~pm.introspection.
istype(file, "
string", 1)
733 help("pm.vis.figure.
Figure");
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 ...
745 %%%% Focus on the target figure to export.
748 if isfield(self.fout, "figure")
749 set(0, "CurrentFigure", self.fout.figure);
751 set(0, "CurrentFigure", gcf);
755 %%%% Ensure transparency if figure must be transparent.
758 if any(contains(
string(varargin), "-transparent"))
759 istransparent = true;
763 set(self.fout.figure, "color", "none");
766 errmsg =
string(me.identifier) + " : " +
string(me.message) + newline;
769 set(gca, "color", "none");
772 errmsg =
string(me.identifier) + " : " +
string(me.message) + newline;
775 warning ( newline + errmsg ...
776 + "Failed to set the color property of gcf to ""none"" for transparent image export." + newline ...
780 istransparent = false;
783 pm.vis.figure.
savefig(file, varargin{:});
786 %%%% Revert transparency
if figure ws not transparent.
793 set(self.currentFig.figure,
"color",
"default");
796 errmsg = string(me.identifier) +
" : " + string(me.message) + newline;
799 set(gca,
"color",
"default");
802 errmsg = string(me.identifier) +
" : " + string(me.message) + newline;
805 warning ( newline + errmsg ...
806 +
"Failed to set the color property of gca back to ""default""." + newline ...
815 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
function name(in vendor)
Return the MPI library name as used in naming the ParaMonte MATLAB shared libraries.
function list()
Return a list of MATLAB strings containing the names of OS platforms supported by the ParaMonte MATLA...
function version(in silent)
Return a scalar MATLAB string containing the latest available ParaMonte MATLAB version newer than the...
function abs(in path, in style)
Return the Get absolute canonical path of a file or folder.
This is the abstract class for generating instances of objects that contain the specifications of a c...
This is the base class for generating instances of figures containing a symmetric square grid or corn...
This is the base class for generating subclass of MATLAB handle superclass whose annoying methods are...
This is the base class for generating instances of objects that contain the specifications of various...
This is the abstract class for generating instances of axes with various types of plots from one or m...
This is the abstract class for generating instances of objects that contain the specifications of var...
function clean()
Remove all paths that contain the ParaMonte lib directory from the MATLAB path variable.
function ghostscript(in cmd)
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...
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...
function parallel()
Return a scalar MATLAB logical that is true if and only if the current installation of MATLAB contain...
function savefig(in varargin)
Export figures in a publication-quality format.
function which(in vendor)
Return the a MATLAB string containing the path to the first mpiexec executable binary found in system...