1PSCONVERT(1) GMT PSCONVERT(1)
2
3
4
6 psconvert - Convert [E]PS file(s) to other formats using GhostScript
7
9 psconvert psfile(s) [ -Aparams ] [ -Cgs_option ] [ -Doutdir ] [
10 -Eresolution ] [ -Fout_name ] [ -Gghost_path ] [ -I ] [ -Llistfile
11 ] [ -P ] [ -Q[g|t][1|2|4] ] [ -S ] [ -Tb|e|E|f|F|j|g|G|m|s|t ] [
12 -V[level] ] [ -Wparams ] [ -Z ]
13
14 Note: No space is allowed between the option flag and the associated
15 arguments.
16
18 psconvert converts one or more PostScript files to other formats (BMP,
19 EPS, JPEG, PDF, PNG, PPM, SVG, TIFF) using GhostScript. Input file
20 names are read from the command line or from a file that lists them.
21 The size of the resulting images is determined by the BoundingBox (or
22 HiResBoundingBox, if present). As an option, a tight (HiRes)BoundingBox
23 may be computed first. As another option, it can compute ESRI type
24 world files used to reference, for instance, tif files and make them be
25 recognized as geotiff. Note: If the PostScript file calls on any of
26 the Adobe PDF transparency extensions and PDF is not the selected out‐
27 put format, then the file will first be converted to a temporary PDF
28 file (for the transparency to take effect) before converting the PDF to
29 the desired output format.
30
32 psfiles
33 Names of PostScript files to be converted. The output files will
34 have the same name (unless -F is used) but with the conventional
35 extension name associated to the raster format (e.g., .jpg for
36 the jpeg format). Use -D to redirect the output to a different
37 directory.
38
40 -A[u][margins][-][+gpaint][+p[pen]][+r][+s[m]|Swidth[u]/height[u]]
41 Adjust the BoundingBox and HiResBoundingBox to the minimum
42 required by the image content. Append u to first remove any
43 GMT-produced time-stamps. Optionally, append extra margins to
44 the bounding box. Give either one (uniform), two (x and y) or
45 four (individual sides) margins; append unit [Default is set by
46 PROJ_LENGTH_UNIT]. Alternatively, use -A- to override any auto‐
47 matic setting of -A by -W.
48
49 Use the -A+snew_width to resize the output image to exactly
50 new_width units. The default is to use what is set by
51 PROJ_LENGTH_UNIT but you can append a new unit and/or impose
52 different width and height. What happens here is that Ghost‐
53 Script will do the re-interpolation work and the final image
54 will retain the DPI resolution set by -E. Use -A+sm to set a
55 maximum size and the new width are only imposed if the original
56 figure width exceeds it. Append /new_height to also also impose
57 a maximum height in addition to the width. Alternatively use
58 -A+Sscale to scale the image by a constant factor.
59
60 Use the -A+r to round the HighRes BoundingBox instead of using
61 the ceil function. This is going against Adobe Law but can be
62 useful when creating very small images where the difference of
63 one pixel might matter. If -V is used we also report the dimen‐
64 sions of the illustration. Use -A+gpaint to paint the Bounding‐
65 Box behind the illustration and use -A+p[pen] to draw the Bound‐
66 ingBox outline (append a pen or accept the default pen of
67 0.25p,black).
68
69 -Cgs_option
70 Specify a single, custom option that will be passed on to Ghost‐
71 Script as is. Repeat to add several options [none].
72
73 -Doutdir
74 Sets an alternative output directory (which must exist) [Default
75 is the same directory as the PS files]. Use -D. to place the
76 output in the current directory instead.
77
78 -Eresolution
79 Set raster resolution in dpi [default = 720 for PDF, 300 for
80 others].
81
82 -Fout_name
83 Force the output file name. By default output names are con‐
84 structed using the input names as base, which are appended with
85 an appropriate extension. Use this option to provide a different
86 name, but without extension. Extension is still determined auto‐
87 matically.
88
89 -Gghost_path
90 Full path to your GhostScript executable. NOTE: For Unix systems
91 this is generally not necessary. Under Windows, the GhostScript
92 path is now fetched from the registry. If this fails you can
93 still add the GS path to system's path or give the full path
94 here. (e.g., -Gc:\programs\gs\gs9.02\bin\gswin64c). WARNING:
95 because of the poor decision of embedding the bits on the gs exe
96 name we cannot satisfy both the 32 and 64 bits GhostScript exe‐
97 cutable names. So in case of 'get from registry' failure the
98 default name (when no -G is used) is the one of the 64 bits ver‐
99 sion, or gswin64c
100
101 -I Enforce gray-shades by using ICC profiles. GhostScript versions
102 >= 9.00 change gray-shades by using ICC profiles. GhostScript
103 9.05 and above provide the '-dUseFastColor=true' option to pre‐
104 vent that and that is what psconvert does by default, unless
105 option -I is set. Note that for GhostScript >= 9.00 and < 9.05
106 the gray-shade shifting is applied to all but PDF format. We
107 have no solution to offer other than upgrade GhostScript.
108
109 -Llistfile
110 The listfile is an ASCII file with the names of the PostScript
111 files to be converted.
112
113 -N This option is obsolete. Use -S to print the GhostScript com‐
114 mand, if applicable. Use -Te to save the intermediate EPS file.
115
116 -P Force Portrait mode. All Landscape mode plots will be rotated
117 back so that they show unrotated in Portrait mode. This is prac‐
118 tical when converting to image formats or preparing EPS or PDF
119 plots for inclusion in documents.
120
121 -Q[g|t][1|2|4]
122 Set the anti-aliasing options for graphics or text. Append the
123 size of the subsample box (1, 2, or 4) [4]. Default is no
124 anti-aliasing (same as bits = 1).
125
126 -S Print to standard error the GhostScript command after it has
127 been executed. This option also prevent all intermediate files
128 from being removed.
129
130 -Tb|e|E|f|F|j|g|G|m|s|t
131 Sets the output format, where b means BMP, e means EPS, E means
132 EPS with PageSize command, f means PDF, F means multi-page PDF,
133 j means JPEG, g means PNG, G means transparent PNG (untouched
134 regions are transparent), m means PPM, s means SVG, and t means
135 TIFF [default is JPEG]. To bjgt you can append - in order to get
136 a grayscale image. The EPS format can be combined with any of
137 the other formats. For example, -Tef creates both an EPS and a
138 PDF file. The -TF creates a multi-page PDF file from the list of
139 input PS or PDF files. It requires the -F option. See also
140 NOTES below.
141
142 -V[level] (more ...)
143 Select verbosity level [c].
144
145 -W[+g][+k][+tdocname][+nlayername][+ofoldername][+aaltmode[alt]][+lmin‐
146 LOD/maxLOD][+fminfade/maxfade][+uURL]
147 Write a ESRI type world file suitable to make (e.g) .tif
148 files be recognized as geotiff by software that know how to
149 do it. Be aware, however, that different results are obtained
150 depending on the image contents and if the -B option has been
151 used or not. The trouble with the -B option is that it cre‐
152 ates a frame and very likely its annotations. That introduces
153 pixels outside the map data extent, and therefore the map
154 extents estimation will be wrong. To avoid this problem use
155 --MAP_FRAME_TYPE=inside option which plots all annotations
156 and ticks inside the image and therefore does not compromise
157 the coordinate computations. Pay attention also to the cases
158 when the plot has any of the sides with whites only because
159 than the algorithm will fail miserably as those whites will
160 be eaten by the GhostScript. In that case you really must use
161 -B or use a slightly off-white color.
162
163 Together with -V it prints on screen the gdal_translate
164 (gdal_translate is a command line tool from the GDAL package)
165 command that reads the raster + world file and creates a true
166 geotiff file. Use -W+g to do a system call to gdal_translate
167 and create a geoTIFF image right away. The output file will
168 have a
169
170 The world file naming follows the convention of jamming a 'w'
171 in the file extension. So, if output is tif -Tt the world
172 file is a sets -A -P.
173
174 Use -W+k to create a minimalist KML file that allows loading
175 the image in GoogleEarth. Note that for this option the image
176 must be in geographical coordinates. If not, a warning is
177 issued but the KML file is created anyway. Several modifier
178 options are available to customize the KML file in the form
179 of +opt strings. Append +ttitle to set the document title
180 [GMT KML Document], +nlayername to set the layer name, and
181 +a/altmode[altitude] to select one of 5 altitude modes recog‐
182 nized by Google Earth that determines the altitude (in m) of
183 the image: G clamped to the ground, g append altitude rela‐
184 tive to ground, a append absolute altitude, s append altitude
185 relative to seafloor, and S clamp it to the seafloor. Con‐
186 trol visibility of the layer with the +lminLOD/maxLOD and
187 +fminfade/maxfade options. Finally, if you plan to leave the
188 image itself on a server and only distribute the KML, use
189 +uURL to prepend the URL to the image reference. If you are
190 building a multi-component KML file then you can issue a KML
191 snipped without the KML header and trailer by using the
192 +ofoldername modification; it will enclose the image and
193 associated KML code within a KML folder of the specified
194 name. See the KML documentation for further explanation (‐
195 http://code.google.com/apis/kml/documentation/). Note: If
196 any of your titles or names contain a plus symbol next to a
197 letter it can be confused with an option modifier. Escape
198 such plus signs by placing a backslash in front of it.
199 Alternatively, enclose the string in double quotes and then
200 the entire -W argument in single-quotes (or vice versa).
201
202 Further notes on the creation of georeferenced rasters.
203 psconvert can create a georeferenced raster image with a
204 world file OR uses GDAL to convert the GMT PostScript file to
205 geotiff. GDAL uses Proj.4 for its projection library. To
206 provide with the information it needs to do the georeferenc‐
207 ing, GMT 4.5 embeds a comment near the start of the Post‐
208 Script file defining the projection using Proj.4 syntax.
209 Users with pre-GMT v4.5 PostScript files, or even non-GMT ps
210 files, can provide the information psconvert requires by man‐
211 ually editing a line into the PostScript file, prefixed with
212 %%PROJ.
213
214 For example the command
215
216 gmt pscoast -JM0/12c -R-10/-4/37/43 -W1 -Di -Bg30m --MAP_FRAME_TYPE=inside > cara.ps
217
218 adds this comment line
219
220 %%PROJ: merc -10.0 -4.0 37.0 43.0 -1113194.908 -445277.963
221 4413389.889 5282821.824 +proj=merc +lon_0=0 +k=-1 +x_0=0 +y_0=0
222 +a=6378137.0 +b=6356752.314245 +ellps=WGS84 +datum=WGS84 +units=m +no_defs
223
224 where 'merc' is the keyword for the coordinate conversion; the 2 to
225 5th elements contain the map limits, 6 to 9th the map limits in
226 projected coordinates and the rest of the line has the regular proj4
227 string for this projection.
228
229 -Z Remove the input PostScript file(s) after the conversion. The
230 input file(s) will not be removed in case of failures.
231
232 -^ or just -
233 Print a short message about the syntax of the command, then
234 exits (NOTE: on Windows just use -).
235
236 -+ or just +
237 Print an extensive usage (help) message, including the explana‐
238 tion of any module-specific option (but not the GMT common
239 options), then exits.
240
241 -? or no arguments
242 Print a complete usage (help) message, including the explanation
243 of all options, then exits.
244
246 The conversion to raster images (BMP, JPEG, PNG, PPM or TIFF) inher‐
247 ently results in loss of details that are available in the original
248 PostScript file. Choose a resolution that is large enough for the
249 application that the image will be used for. For web pages, smaller dpi
250 values suffice, for Word documents and PowerPoint presentations a
251 higher dpi value is recommended. psconvert uses the loss-less DEFLATE
252 compression technique when creating PDF and PNG files and LZW compres‐
253 sion for TIFF images. For smaller dpi images, such as required for
254 building animations, the use of -Qt4 and -Qg4 may help sharpen text and
255 lines.
256
257 EPS is a vector (not a raster) format. Therefore, the -E option has no
258 effect on the creation of EPS files. Using the option -Te will remove
259 setpagedevice commands from the PostScript file and will adjust the
260 BoundingBox when the -A option is used. Note the original and required
261 BoundingBox is limited to integer points, hence Adobe added the
262 optional HiResBoundingBox to add more precision in sizing. The -A
263 option calculates both and writes both to the EPS file and is subse‐
264 quently used in any rasterization, if requested. When the -TE option is
265 used, a new setpagedevice command is added that will indicate the
266 actual pagesize for the plot, similar to the BoundingBox. Note that
267 when the command setpagedevice exists in a PostScript file that is
268 included in another document, this can wreak havoc on the printing or
269 viewing of the overall document. Hence, -TE should only be used for
270 "standalone" PostScript files.
271
272 Although PDF and SVG are also vector formats, the -E option has an
273 effect on the resolution of pattern fills and fonts that are stored as
274 bitmaps in the document. psconvert therefore uses a larger default res‐
275 olution when creating PDF and SVG files. -E also determines the resolu‐
276 tion of the boundingbox values used to indicate the size of the output
277 PDF. In order to obtain high-quality PDF or SVG files, the /prepress
278 options are in effect, allowing only loss-less DEFLATE compression of
279 raster images embedded in the PostScript file.
280
281 Although psconvert was developed as part of the GMT, it can be used to
282 convert PostScript files created by nearly any graphics program. How‐
283 ever, -Au is GMT-specific.
284
285 The ghostscript program continues to be developed and occasionally its
286 developers make decisions that affect psconvert. As of version 9.16
287 the SVG device has been removed. Fortunately, quality SVG graphics can
288 be obtained by first converting to PDF and then install and use the
289 package pdf2svg.
290
291 See include-gmt-graphics of the GMT Technical Reference and Cookbook
292 for more information on how psconvert is used to produce graphics that
293 can be inserted into other documents (articles, presentations, posters,
294 etc.).
295
297 To convert the file psfile.ps to PNG using a tight BoundingBox and
298 rotating it back to normal orientation in case it was in Landscape
299 mode:
300
301 gmt psconvert psfile.ps -A -P -Tg
302
303 To convert the file map.ps to PDF, extend the BoundingBox by 0.2 cm,
304 fill it with lightblue paint and draw outline with a thick pen:
305
306 gmt psconvert map.ps -A0.2c+glightblue+pthick -Tf
307
308 To create a 5 cm PNG version at 300 dpi of our example_01.ps file
309
310 gmt psconvert example_01.ps -A+s5c -Tg
311
312 To create a 3 pages PDF file from 3 individual PS files
313
314 gmt psconvert -TF -Fabc a.ps b.ps c.ps
315
316 To create a simple linear map with pscoast and convert it to tif with a
317
318 gmt pscoast -JX12cd -R-10/-4/37/43 -W1 -Di -Bg30m -P -G200 --MAP_FRAME_TYPE=inside > cara.ps
319 gmt psconvert cara.ps -Tt -W
320
321 To create a Mercator version of the above example and use GDAL to pro‐
322 duce a true geotiff file.
323
324 gmt pscoast -JM0/12c -R-10/-4/37/43 -W1 -Di -Bg30m -P -G200 --MAP_FRAME_TYPE=inside > cara.ps
325 gdalwarp -s_srs +proj=merc cara.tif carageo.tiff
326
327 To create a Polar Stereographic geotiff file of Patagonia
328
329 gmt pscoast -JS-55/-60/15c -R-77/-55/-57.5/-48r -Di -Gred -P -Bg2 --MAP_FRAME_TYPE=inside > patagonia.ps
330 gmt psconvert patagonia.ps -Tt -W+g -V
331
332 To create a simple KML file for use in Google Earth, try
333
334 gmt grdimage lonlatgrid.nc -Jx1 -Ccolors.cpt -P -B0g2 --MAP_FRAME_TYPE=inside > tile.ps
335 gmt psconvert tile.ps -Tg -W+k+t"my title"+l256/-1 -V
336
337 (These commands assume that GhostScript can be found in your system's
338 path.)
339
341 Most of the conversions done in psconvert are handled by GhostScript.
342 On most Unixes this program is available as gs; for Windows there is a
343 version called gswin32c. GhostScript accepts a rich selection of com‐
344 mand-line options that modify its behavior. Many of these are set indi‐
345 rectly by the options available above. However, hard-core usage may
346 require some users to add additional options to fine-tune the result.
347 Use -S to examine the actual command used, and add custom options via
348 one or more instances of the -C option. For instance, to turn on image
349 interpolation for all images, improving image quality for scaled images
350 at the expense of speed, use -C-dDOINTERPOLATE. See www.ghostscript.com
351 for complete documentation.
352
354 If you have made a series of KML files (which may depend on other items
355 like local PNG images), you can consolidate these into a single KMZ
356 file for saving space and for grouping related files together. The
357 bash function gmt_build_kmz in the gmt_shell_functions.sh can be used
358 to do this. You need to source gmt_shell_functions.sh first before you
359 can use it.
360
362 gmt, pscoast
363
365 2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
366
367
368
369
3705.4.5 Feb 24, 2019 PSCONVERT(1)