PRINTFIGURE Print figure to image file with metadata.
Syntax:
IMGINFO = PRINTFIGURE(OPTIONS)
IMGINFO = PRINTFIGURE(OPT1, VAL1, ...)
IMGINFO = PRINTFIGURE(H, OPTIONS)
IMGINFO = PRINTFIGURE(H, OPT1, VAL1, ...)
Description:
IMGINFO = PRINTFIGURE(OPTIONS) and IMGINFO = PRINTFIGURE(OPT1, VAL1, ...)
print current figure to image file according to given options and return a
struct IMGINFO with information about the generated image file.
Options may be given in key-value pairs OPT1, VAL1... or in a struct
OPTIONS with field names as option keys and field values as option values.
Recognized options are:
DIRNAME: image file directory.
String with the path of the directory of the output image file.
It may be absolute or relative to the current directory as reported
by PWD.
Default value: '' (empty, use current directory)
FILENAME: image file name without extension.
String with name of the output image file without path prefix nor
extension.
Default value: sprintf('figure%03d', h) where h is the figure handle
FORMAT: image file format (extension)
String with the extension of the output image file (no leading dot).
It also specifies the image format. Any format recognized by the
program 'convert' in the ImageMagick suite may be used. See note on
format below.
Default value: 'eps'
RESOLUTION: image resolution in dots per inch.
Positive integer with the resolution of the output image file in dpi.
See note on image size below.
Default value: 72
DATE: image time stamp.
String with the value of the 'date' property of the output image file,
usually the creation date. Some image formats might not support it.
Default value: datestr(now(), 31)
TITLE: image title label.
String with the value of the 'title' property of the output image file.
Some image formats might not support it.
Default value: ''
COMMENT: image description comment.
String with the value of the 'comment' property of the output image
file. Some image formats might not support it. It should describe the
figure contents.
Default value: ''
DRIVER: driver to print intermediate vector image file.
String setting whether the intermediate vector image file should be
printed using a mono or color driver. It should be one of:
'eps' : mono
'eps2' : mono
'epsc' : color
'epsc2': color
See note on format below.
Default value: 'epsc2'
RENDER: renderer to use when printing intermediate vector file.
String setting which renderer should be used when printing the
intermediate vector image file. Any renderer supported by function
PRINT is allowed. If empty, the renderer options is not set when
calling PRINT, and the renderer is automatically selected either from
figure properties or depending on the contents of the figure.
Default value: '' (renderer automatically selected)
LOOSE: uncrop image when printing intermediate vector file.
String setting the value of the loose option (MATLAB only) to produce
an uncropped image when printing to the intermediate vector file.
The only recognized value is 'loose', which prevents the figure being
cropped. If empty, no option is set when calling PRINT.
Default value: 'loose' (produce uncropped images).
CONVERT: program to convert intermediate vector file to final format.
String setting which program should be called to convert the
intermediate vector image file to the final format using SYSTEM
(see note on format conversion below). If empty, the conversion is
omitted and the image file in the final format is produced by the
built-in driver in option DRIVER.
Default value: 'convert'
KEEPEPS: preserve intermediate vector file after conversion.
Boolean setting whether to preseve the intermediate vector file after
the conversion to the final format. If false, the intermediate file
is deleted after a successful conversion.
Default value: false
Returned struct IMGINFO contains information about the figure and the
generated image. It has the following fields:
TITLE: string with the image label (taken from options).
COMMENT: string with the image comment (taken from options).
DATE: string with the image timestamp (taken from options).
FULLFILE: string with the absolute path of the generated image file.
FILENAME: string with the image base file name (taken from options).
DIRNAME: string with the image directory name (taken from options).
FORMAT: string with the format extension (taken from options).
RESOLUTION: scalar with the image resolution (taken from options).
WIDTH: scalar with the image width (taken from the figure handle).
HEIGHT: scalar with the image height (taken from the figure handle).
UNITS: string with the image size units (taken from the figure handle).
IMGINFO = PRINTFIGURE(H, ...) prints figure given by figure handle H
instead of THE current figure.
Notes:
This function is inspired by function PRINTIMAGE by Tomeu Garau. He is the
true glider man. Main changes are:
- Changed input syntax to support output parameter setting.
- Changed output to return image information.
- Added metadata to generated image file.
- Removed thumbnail generation.
Due to quality limitations when printing to some output formats in MATLAB
(like png), the image file is generated first printing the corresponding
figure to eps format with PRINT, and then calling the program 'convert'
from ImageMagick/GraphicsMagick suite through SYSTEM to convert it to the
final format and add metadata tags. If the final format is eps, no
conversion is performed. Since eps does not seem to support metadata tags,
the program is not invoked at all.
The 'convert' program is part of the GraphicsMagick and ImageMagick suites:
<http://www.imagemagick.org/script/convert.php>
<http://www.graphicsmagick.org/convert.html>
The resulting image size, either in pixel or metric units, is governed by
the resolution option and the figure position properties 'PaperPosition'
and 'PaperUnits'.
The resulting image file path is build calling the function FULLFILE with
the value of the options DIRNAME, FILENAME and FORMAT.
Examples:
hfig = figure('PaperUnits', 'inches', 'PaperPosition', [0 0 6.83 5.12])
x = -pi:.1:pi;
y = sin(x);
plot(x,y)
options = struct()
options.dirname = 'images'
options.filename = 'example_figure'
options.format = 'png'
options.resolution = 150
options.date = datestr(now(), 31)
options.title = 'Example plot'
options.comment = 'Example 6.83x5.12 inch figure printed to png at 150 dpi (approx. 1024x768 pixels)'
imginfo = printfigure(hfig, options)
See also:
SYSTEM
PRINT
GCF
FULLFILE
DATESTR
NOW
Authors:
Joan Pau Beltran <joanpau.beltran@socib.cat>0001 function imginfo = printfigure(varargin) 0002 %PRINTFIGURE Print figure to image file with metadata. 0003 % 0004 % Syntax: 0005 % IMGINFO = PRINTFIGURE(OPTIONS) 0006 % IMGINFO = PRINTFIGURE(OPT1, VAL1, ...) 0007 % IMGINFO = PRINTFIGURE(H, OPTIONS) 0008 % IMGINFO = PRINTFIGURE(H, OPT1, VAL1, ...) 0009 % 0010 % Description: 0011 % IMGINFO = PRINTFIGURE(OPTIONS) and IMGINFO = PRINTFIGURE(OPT1, VAL1, ...) 0012 % print current figure to image file according to given options and return a 0013 % struct IMGINFO with information about the generated image file. 0014 % Options may be given in key-value pairs OPT1, VAL1... or in a struct 0015 % OPTIONS with field names as option keys and field values as option values. 0016 % Recognized options are: 0017 % DIRNAME: image file directory. 0018 % String with the path of the directory of the output image file. 0019 % It may be absolute or relative to the current directory as reported 0020 % by PWD. 0021 % Default value: '' (empty, use current directory) 0022 % FILENAME: image file name without extension. 0023 % String with name of the output image file without path prefix nor 0024 % extension. 0025 % Default value: sprintf('figure%03d', h) where h is the figure handle 0026 % FORMAT: image file format (extension) 0027 % String with the extension of the output image file (no leading dot). 0028 % It also specifies the image format. Any format recognized by the 0029 % program 'convert' in the ImageMagick suite may be used. See note on 0030 % format below. 0031 % Default value: 'eps' 0032 % RESOLUTION: image resolution in dots per inch. 0033 % Positive integer with the resolution of the output image file in dpi. 0034 % See note on image size below. 0035 % Default value: 72 0036 % DATE: image time stamp. 0037 % String with the value of the 'date' property of the output image file, 0038 % usually the creation date. Some image formats might not support it. 0039 % Default value: datestr(now(), 31) 0040 % TITLE: image title label. 0041 % String with the value of the 'title' property of the output image file. 0042 % Some image formats might not support it. 0043 % Default value: '' 0044 % COMMENT: image description comment. 0045 % String with the value of the 'comment' property of the output image 0046 % file. Some image formats might not support it. It should describe the 0047 % figure contents. 0048 % Default value: '' 0049 % DRIVER: driver to print intermediate vector image file. 0050 % String setting whether the intermediate vector image file should be 0051 % printed using a mono or color driver. It should be one of: 0052 % 'eps' : mono 0053 % 'eps2' : mono 0054 % 'epsc' : color 0055 % 'epsc2': color 0056 % See note on format below. 0057 % Default value: 'epsc2' 0058 % RENDER: renderer to use when printing intermediate vector file. 0059 % String setting which renderer should be used when printing the 0060 % intermediate vector image file. Any renderer supported by function 0061 % PRINT is allowed. If empty, the renderer options is not set when 0062 % calling PRINT, and the renderer is automatically selected either from 0063 % figure properties or depending on the contents of the figure. 0064 % Default value: '' (renderer automatically selected) 0065 % LOOSE: uncrop image when printing intermediate vector file. 0066 % String setting the value of the loose option (MATLAB only) to produce 0067 % an uncropped image when printing to the intermediate vector file. 0068 % The only recognized value is 'loose', which prevents the figure being 0069 % cropped. If empty, no option is set when calling PRINT. 0070 % Default value: 'loose' (produce uncropped images). 0071 % CONVERT: program to convert intermediate vector file to final format. 0072 % String setting which program should be called to convert the 0073 % intermediate vector image file to the final format using SYSTEM 0074 % (see note on format conversion below). If empty, the conversion is 0075 % omitted and the image file in the final format is produced by the 0076 % built-in driver in option DRIVER. 0077 % Default value: 'convert' 0078 % KEEPEPS: preserve intermediate vector file after conversion. 0079 % Boolean setting whether to preseve the intermediate vector file after 0080 % the conversion to the final format. If false, the intermediate file 0081 % is deleted after a successful conversion. 0082 % Default value: false 0083 % Returned struct IMGINFO contains information about the figure and the 0084 % generated image. It has the following fields: 0085 % TITLE: string with the image label (taken from options). 0086 % COMMENT: string with the image comment (taken from options). 0087 % DATE: string with the image timestamp (taken from options). 0088 % FULLFILE: string with the absolute path of the generated image file. 0089 % FILENAME: string with the image base file name (taken from options). 0090 % DIRNAME: string with the image directory name (taken from options). 0091 % FORMAT: string with the format extension (taken from options). 0092 % RESOLUTION: scalar with the image resolution (taken from options). 0093 % WIDTH: scalar with the image width (taken from the figure handle). 0094 % HEIGHT: scalar with the image height (taken from the figure handle). 0095 % UNITS: string with the image size units (taken from the figure handle). 0096 % 0097 % IMGINFO = PRINTFIGURE(H, ...) prints figure given by figure handle H 0098 % instead of THE current figure. 0099 % 0100 % Notes: 0101 % This function is inspired by function PRINTIMAGE by Tomeu Garau. He is the 0102 % true glider man. Main changes are: 0103 % - Changed input syntax to support output parameter setting. 0104 % - Changed output to return image information. 0105 % - Added metadata to generated image file. 0106 % - Removed thumbnail generation. 0107 % 0108 % Due to quality limitations when printing to some output formats in MATLAB 0109 % (like png), the image file is generated first printing the corresponding 0110 % figure to eps format with PRINT, and then calling the program 'convert' 0111 % from ImageMagick/GraphicsMagick suite through SYSTEM to convert it to the 0112 % final format and add metadata tags. If the final format is eps, no 0113 % conversion is performed. Since eps does not seem to support metadata tags, 0114 % the program is not invoked at all. 0115 % 0116 % The 'convert' program is part of the GraphicsMagick and ImageMagick suites: 0117 % <http://www.imagemagick.org/script/convert.php> 0118 % <http://www.graphicsmagick.org/convert.html> 0119 % 0120 % The resulting image size, either in pixel or metric units, is governed by 0121 % the resolution option and the figure position properties 'PaperPosition' 0122 % and 'PaperUnits'. 0123 % 0124 % The resulting image file path is build calling the function FULLFILE with 0125 % the value of the options DIRNAME, FILENAME and FORMAT. 0126 % 0127 % Examples: 0128 % hfig = figure('PaperUnits', 'inches', 'PaperPosition', [0 0 6.83 5.12]) 0129 % x = -pi:.1:pi; 0130 % y = sin(x); 0131 % plot(x,y) 0132 % options = struct() 0133 % options.dirname = 'images' 0134 % options.filename = 'example_figure' 0135 % options.format = 'png' 0136 % options.resolution = 150 0137 % options.date = datestr(now(), 31) 0138 % options.title = 'Example plot' 0139 % options.comment = 'Example 6.83x5.12 inch figure printed to png at 150 dpi (approx. 1024x768 pixels)' 0140 % imginfo = printfigure(hfig, options) 0141 % 0142 % See also: 0143 % SYSTEM 0144 % PRINT 0145 % GCF 0146 % FULLFILE 0147 % DATESTR 0148 % NOW 0149 % 0150 % Authors: 0151 % Joan Pau Beltran <joanpau.beltran@socib.cat> 0152 0153 % Copyright (C) 2013-2016 0154 % ICTS SOCIB - Servei d'observacio i prediccio costaner de les Illes Balears 0155 % <http://www.socib.es> 0156 % 0157 % This program is free software: you can redistribute it and/or modify 0158 % it under the terms of the GNU General Public License as published by 0159 % the Free Software Foundation, either version 3 of the License, or 0160 % (at your option) any later version. 0161 % 0162 % This program is distributed in the hope that it will be useful, 0163 % but WITHOUT ANY WARRANTY; without even the implied warranty of 0164 % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 0165 % GNU General Public License for more details. 0166 % 0167 % You should have received a copy of the GNU General Public License 0168 % along with this program. If not, see <http://www.gnu.org/licenses/>. 0169 0170 % No argument number checking since any number of arguments is allowed. 0171 0172 %% Get optional figure handle and option arguments. 0173 if (nargin > 0) && isscalar(varargin{1}) && ishghandle(varargin{1}) 0174 args = varargin(2:end); 0175 hfig = figure(varargin{1}); 0176 else 0177 args = varargin; 0178 hfig = gcf(); 0179 end 0180 0181 0182 %% Set plot options and default values. 0183 options = struct(); 0184 options.dirname = pwd(); 0185 options.filename = sprintf('figure%03d', hfig); 0186 options.format = 'eps'; 0187 options.resolution = 72; 0188 options.date = datestr(now(), 31); 0189 options.title = ''; 0190 options.comment = ''; 0191 options.driver = 'epsc2'; 0192 options.render = []; 0193 options.loose = 'loose'; 0194 options.convert = 'convert'; 0195 options.keepeps = false; 0196 0197 0198 %% Get options from extra arguments. 0199 % Parse option key-value pairs in any accepted call signature. 0200 if isscalar(args) && isstruct(args{1}) 0201 % Options passed as a single option struct argument: 0202 % field names are option keys and field values are option values. 0203 option_key_list = fieldnames(args{1}); 0204 option_val_list = struct2cell(args{1}); 0205 elseif mod(numel(args), 2) == 0 0206 % Options passed as key-value argument pairs. 0207 option_key_list = args(1:2:end); 0208 option_val_list = args(2:2:end); 0209 else 0210 error('glider_toolbox:printfigure:InvalidOptions', ... 0211 'Invalid optional arguments (neither key-value pairs nor struct).'); 0212 end 0213 % Overwrite default options with values given in extra arguments. 0214 for opt_idx = 1:numel(option_key_list) 0215 opt = lower(option_key_list{opt_idx}); 0216 val = option_val_list{opt_idx}; 0217 if isfield(options, opt) 0218 options.(opt) = val; 0219 else 0220 error('glider_toolbox:printfigure:InvalidOption', ... 0221 'Invalid option: %s.', opt); 0222 end 0223 end 0224 0225 0226 %% Create image directory if needed. 0227 % MATLAB does not provide a proper way to check if a relative path points to 0228 % an existing directory (EXIST checks for existance in the whole load path). 0229 [status, attrout] = fileattrib(options.dirname); 0230 if ~status 0231 [success, message] = mkdir(options.dirname); 0232 if ~success 0233 error('glider_toolbox:printfigure:ImageDirectoryError', ... 0234 'Could not create directory %s: %s.', options.dirname, message); 0235 end 0236 elseif ~attrout.directory 0237 error('glider_toolbox:printfigure:ImageDirectoryError', ... 0238 'Not a directory: %s.', options.dirname); 0239 end 0240 0241 0242 %% Print figure to intermediate vector image file and convert it to final format. 0243 fullfile_eps = fullfile(options.dirname, [options.filename '.eps']); 0244 fullfile_ext = fullfile(options.dirname, [options.filename '.' options.format]); 0245 resdpiopt = ['-r' num2str(options.resolution)]; 0246 driveropt = ['-d' options.driver]; 0247 renderopt = ''; 0248 if ~isempty(options.render) 0249 renderopt = ['-' options.render]; 0250 end 0251 looseopt = ''; 0252 if ~isempty(options.loose) % needed to create an uncropped image (eps bounding box better matches figure position) 0253 looseopt = ['-' options.loose]; 0254 end 0255 if isempty(options.convert) || strcmpi(options.format, 'eps') 0256 print(hfig, resdpiopt, renderopt, driveropt, looseopt, fullfile_ext); 0257 else 0258 print(hfig, resdpiopt, renderopt, driveropt, looseopt, fullfile_eps); 0259 [failure, output] = system( ... 0260 [options.convert ... 0261 ' -depth 8' ... % needed because ImageMagick identifies the eps as 16 bit color depth. 0262 ' -colorspace RGB' ... % needed because ImageMagick identifies the eps as CMYK due to the %%DocumentProcessColor comment. 0263 ' -density ' num2str(options.resolution) ... 0264 ' ' fullfile_eps ... 0265 ' -set date ''' options.date '''' ... 0266 ' -set label ''' options.title '''' ... 0267 ' -set comment ''' options.comment '''' ... 0268 ' ' fullfile_ext ';'] ); 0269 if failure 0270 error('glider_toolbox:printfigure:ConvertError', ... 0271 'Command convert failed (eps file preserved): %s.', output); 0272 elseif ~options.keepeps 0273 delete(fullfile_eps); 0274 end 0275 end 0276 0277 0278 %% Report image information with absolute name of the generated file. 0279 [status, attrout] = fileattrib(fullfile_ext); 0280 if status == 0 0281 % We should never get here (if image creation succeed, file must exist). 0282 error('glider_toolbox:printfigure:ImageFileError', ... 0283 'Image generation succeed but problems with image file %s: %s.', ... 0284 fullfile_ext, attrout); 0285 end 0286 hfigpaperpos = get(hfig, 'PaperPosition'); 0287 hfigpaperuts = get(hfig, 'PaperUnits'); 0288 imginfo.width = hfigpaperpos(3); 0289 imginfo.height = hfigpaperpos(4); 0290 imginfo.units = hfigpaperuts; 0291 imginfo.resolution = options.resolution; 0292 imginfo.title = options.title; 0293 imginfo.comment = options.comment; 0294 imginfo.date = options.date; 0295 imginfo.format = options.format; 0296 imginfo.filename = options.filename; 0297 imginfo.dirname = options.dirname; 0298 imginfo.fullfile = attrout.Name; 0299 0300 end