Provided by: gmt-common_5.2.1+dfsg-3build1_all 
NAME
psconvert - Convert [E]PS file(s) to other formats using GhostScript
SYNOPSIS
psconvert psfile(s) [ [u][margins][-][+gpaint][+p[pen]][+r][+s[m]|Swidth[u]/height[u]] ] [
gs_option ] [ -Doutdir ] [ -Eresolution ] [ -F<out_name> ] [ ghost_path ] [ ] [ listfile
] [ ] [ [g|t][1|2|4] ] [ -S ] [ b|e|E|f|F|j|g|G|m|s |t ] [ [level] ] [
[+g][+k][+tdocname][+nlayername][+ofoldername][+aaltmode[alt]][+lminLOD/maxLOD][+fminfade/maxfade][+uURL]
]
Note: No space is allowed between the option flag and the associated arguments.
DESCRIPTION
psconvert converts one or more PostScript files to other formats (BMP, EPS, JPEG, PDF,
PNG, PPM, SVG, TIFF) using GhostScript. Input file names are read from the command line or
from a file that lists them. The size of the resulting images is determined by the
BoundingBox (or HiResBoundingBox, if present). As an option, a tight (HiRes)BoundingBox
may be computed first. As another option, it can compute ESRI type world files used to
reference, for instance, tif files and make them be recognized as geotiff. Note: If the
PostScript file calls on any of the Adobe PDF transparency extensions and PDF is not the
selected output format, then the file will first be converted to a temporary PDF file (for
the transparency to take effect) before converting the PDF to the desired output format.
REQUIRED ARGUMENTS
psfiles
Names of PostScript files to be converted. The output files will have the same name
(unless -F is used) but with the conventional extension name associated to the
raster format (e.g., .jpg for the jpeg format). Use -D to redirect the output to a
different directory.
OPTIONAL ARGUMENTS
-A[u][margins][-][+gpaint][+p[pen]][+r][+s[m]|Swidth[u]/height[u]]
Adjust the BoundingBox and HiResBoundingBox to the minimum required by the image
content. Append u to first remove any GMT-produced time-stamps. Optionally, append
extra margins to the bounding box. Give either one (uniform), two (x and y) or
four (individual sides) margins; append unit [Default is set by PROJ_LENGTH_UNIT].
Alternatively, use -A- to override any automatic setting of -A by -W.
Use the -A+snew_width to resize the output image to exactly new_width units. The
default is to use what is set by PROJ_LENGTH_UNIT but you can append a new unit
and/or impose different width and height. What happens here is that GhostScript
will do the re-interpolation work and the final image will retain the DPI
resolution set by -E. Use -A+sm to set a maximum size and the new width are only
imposed if the original figure width exceeds it. Append /new_height to also also
impose a maximum height in addition to the width. Alternatively use -A+Sscale to
scale the image by a constant factor.
Use the -A+r to round the HighRes BoundingBox instead of using the ceil function.
This is going against Adobe Law but can be useful when creating very small images
where the difference of one pixel might matter. If -V is used we also report the
dimensions of the illustration. Use -A+gpaintto paint the BoundingBox behind the
illustration and use -A+p[pen] to draw the BoundingBox outline (append a pen or
accept the default pen of 0.25p,black).
-Cgs_option
Specify a single, custom option that will be passed on to GhostScript as is. Repeat
to add several options [none].
-Doutdir
Sets an alternative output directory (which must exist) [Default is the same
directory as the PS files]. Use -D. to place the output in the current directory
instead.
-Eresolution
Set raster resolution in dpi [default = 720 for PDF, 300 for others].
-Fout_name
Force the output file name. By default output names are constructed using the input
names as base, which are appended with an appropriate extension. Use this option to
provide a different name, but without extension. Extension is still determined
automatically.
-Gghost_path
Full path to your GhostScript executable. NOTE: For Unix systems this is generally
not necessary. Under Windows, the GhostScript path is now fetched from the
registry. If this fails you can still add the GS path to system's path or give the
full path here. (e.g., -Gc:\programs\gs\gs9.02\bin\gswin64c). WARNING: because of
the poor decision of embedding the bits on the gs exe name we cannot satisfy both
the 32 and 64 bits GhostScript executable names. So in case of 'get from registry'
failure the default name (when no -G is used) is the one of the 64 bits version, or
gswin64c
-I Enforce gray-shades by using ICC profiles. GhostScript versions >= 9.00 change
gray-shades by using ICC profiles. GhostScript 9.05 and above provide the
'-dUseFastColor=true' option to prevent that and that is what psconvert does by
default, unless option -I is set. Note that for GhostScript >= 9.00 and < 9.05 the
gray-shade shifting is applied to all but PDF format. We have no solution to offer
other than upgrade GhostScript.
-Llistfile
The listfile is an ASCII file with the names of the PostScript files to be
converted.
-N This option is obsolete. Use -S to print the GhostScript command, if applicable.
Use -Te to save the intermediate EPS file.
-P Force Portrait mode. All Landscape mode plots will be rotated back so that they
show unrotated in Portrait mode. This is practical when converting to image formats
or preparing EPS or PDF plots for inclusion in documents.
-Q[g|t][1|2|4]
Set the anti-aliasing options for graphics or text. Append the size of the
subsample box (1, 2, or 4) [4]. Default is no anti-aliasing (same as bits = 1).
-S Print to standard error the GhostScript command after it has been executed. This
option also prevent all intermediate files from being removed.
-Tb|e|E|f|F|j|g|G|m|s|t
Sets the output format, where b means BMP, e means EPS, E means EPS with PageSize
command, f means PDF, F means multi-page PDF, j means JPEG, g means PNG, G means
transparent PNG (untouched regions are transparent), m means PPM, s means SVG, and
t means TIFF [default is JPEG]. To bjgt you can append - in order to get a
grayscale image. The EPS format can be combined with any of the other formats. For
example, -Tef creates both an EPS and a PDF file. The -TF creates a multi-page PDF
file from the list of input PS or PDF files. It requires the -F option.
-V[level] (more ...)
Select verbosity level [c].
-W[+g][+k][+tdocname][+nlayername][+ofoldername][+aaltmode[alt]][+lminLOD/maxLOD][+fminfade/maxfade][+uURL]
Write a ESRI type world file suitable to make (e.g) .tif files be recognized as
geotiff by software that know how to do it. Be aware, however, that different
results are obtained depending on the image contents and if the -B option has
been used or not. The trouble with the -B option is that it creates a frame and
very likely its annotations. That introduces pixels outside the map data extent,
and therefore the map extents estimation will be wrong. To avoid this problem
use --MAP_FRAME_TYPE=inside option which plots all annotations and ticks inside
the image and therefore does not compromise the coordinate computations. Pay
attention also to the cases when the plot has any of the sides with whites only
because than the algorithm will fail miserably as those whites will be eaten by
the GhostScript. In that case you really must use -B or use a slightly off-white
color.
Together with -V it prints on screen the gdal_translate (gdal_translate is a
command line tool from the GDAL package) command that reads the raster + world
file and creates a true geotiff file. Use -W+g to do a system call to
gdal_translate and create a geoTIFF image right away. The output file will have
a
The world file naming follows the convention of jamming a 'w' in the file
extension. So, if output is tif -Tt the world file is a sets -A -P.
Use -W+k to create a minimalist KML file that allows loading the image in
GoogleEarth. Note that for this option the image must be in geographical
coordinates. If not, a warning is issued but the KML file is created anyway.
Several modifier options are available to customize the KML file in the form of
+opt strings. Append +ttitle to set the document title [GMT KML Document],
+nlayername to set the layer name, and +a/altmode[altitude] to select one of 5
altitude modes recognized by Google Earth that determines the altitude (in m) of
the image: G clamped to the ground, g append altitude relative to ground, a
append absolute altitude, s append altitude relative to seafloor, and S clamp it
to the seafloor. Control visibility of the layer with the +lminLOD/maxLOD and
+fminfade/maxfade options. Finally, if you plan to leave the image itself on a
server and only distribute the KML, use +uURL to prepend the URL to the image
reference. If you are building a multi-component KML file then you can issue a
KML snipped without the KML header and trailer by using the +ofoldername
modification; it will enclose the image and associated KML code within a KML
folder of the specified name. See the KML documentation for further explanation
(http://code.google.com/apis/kml/documentation/).
Further notes on the creation of georeferenced rasters. psconvert can create a
georeferenced raster image with a world file OR uses GDAL to convert the GMT
PostScript file to geotiff. GDAL uses Proj.4 for its projection library. To
provide with the information it needs to do the georeferencing, GMT 4.5 embeds a
comment near the start of the PostScript file defining the projection using
Proj.4 syntax. Users with pre-GMT v4.5 PostScript files, or even non-GMT ps
files, can provide the information psconvert requires by manually editing a line
into the PostScript file, prefixed with %%PROJ.
For example the command
gmt pscoast -JM0/12c -R-10/-4/37/43 -W1 -Di -Bg30m --MAP_FRAME_TYPE=inside > cara.ps
adds this comment line
%%PROJ: merc -10.0 -4.0 37.0 43.0 -1113194.908 -445277.963
4413389.889 5282821.824 +proj=merc +lon_0=0 +k=-1 +x_0=0 +y_0=0
+a=6378137.0 +b=6356752.314245 +ellps=WGS84 +datum=WGS84 +units=m +no_defs
where 'merc' is the keyword for the coordinate conversion; the 2 to
5th elements contain the map limits, 6 to 9th the map limits in
projected coordinates and the rest of the line has the regular proj4
string for this projection.
-Z Remove the input PostScript file(s) after the conversion. The input file(s) will
not be removed in case of failures.
-^ or just -
Print a short message about the syntax of the command, then exits (NOTE: on Windows
use just -).
-+ or just +
Print an extensive usage (help) message, including the explanation of any
module-specific option (but not the GMT common options), then exits.
-? or no arguments
Print a complete usage (help) message, including the explanation of options, then
exits.
--version
Print GMT version and exit.
--show-datadir
Print full path to GMT share directory and exit.
NOTES
The conversion to raster images (BMP, JPEG, PNG, PPM or TIFF) inherently results in loss
of details that are available in the original PostScript file. Choose a resolution that is
large enough for the application that the image will be used for. For web pages, smaller
dpi values suffice, for Word documents and PowerPoint presentations a higher dpi value is
recommended. psconvert uses the loss-less DEFLATE compression technique when creating PDF
and PNG files and LZW compression for TIFF images.
EPS is a vector, not a raster format. Therefore, the -E option has no effect on the
creation of EPS files. Using the option -Te will remove PageSize commands from the
PostScript file and will adjust the BoundingBox when the -A option is used. Note the
original and required BoundingBox is limited to integer points, hence Adobe added the
optional HiResBoundingBox to add more precision in sizing. The -A option calculates both
and writes both to the EPS file used in the rasterization (and output if -Te is set).
Although PDF and SVG are also vector formats, the -E option has an effect on the
resolution of pattern fills and fonts that are stored as bitmaps in the document.
psconvert therefore uses a larger default resolution when creating PDF and SVG files. -E
also determines the resolution of the boundingbox values used to indicate the size of the
output PDF. In order to obtain high-quality PDF or SVG files, the /prepress options are
in effect, allowing only loss-less DEFLATE compression of raster images embedded in the
PostScript file.
Although psconvert was developed as part of the GMT, it can be used to convert PostScript
files created by nearly any graphics program. However, -Au is GMT-specific.
The ghostscript program continues to be developed and occasionally its developers make
decisions that affect psconvert. As of version 9.16 the SVG device has been removed.
Fortunately, quality SVG graphics can be obtained by first converting to PDF and then
install and use the package pdf2svg.
See include-gmt-graphics of the GMT Technical Reference and Cookbook for more information
on how psconvert is used to produce graphics that can be inserted into other documents
(articles, presentations, posters, etc.).
EXAMPLES
To convert the file psfile.ps to PNG using a tight BoundingBox and rotating it back to
normal orientation in case it was in Landscape mode:
gmt psconvert psfile.ps -A -P -Tg
To convert the file map.ps to PDF, extend the BoundingBox by 0.2 cm, fill it with
lightblue paint and draw outline with a thick pen:
gmt psconvert map.ps -A0.2c+glightblue+pthick -Tf
To create a 5 cm PNG version at 300 dpi of our example_01.ps file
gmt psconvert example_01.ps -A+s5c -Tg
To create a 3 pages PDF file from 3 individual PS files
gmt psconvert -TF -Fabc a.ps b.ps c.ps
To create a simple linear map with pscoast and convert it to tif with a
gmt pscoast -JX12cd -R-10/-4/37/43 -W1 -Di -Bg30m -P -G200 --MAP_FRAME_TYPE=inside > cara.ps
gmt psconvert cara.ps -Tt -W
To create a Mercator version of the above example and use GDAL to produce a true geotiff
file.
gmt pscoast -JM0/12c -R-10/-4/37/43 -W1 -Di -Bg30m -P -G200 --MAP_FRAME_TYPE=inside > cara.ps
gdalwarp -s_srs +proj=merc cara.tif carageo.tiff
To create a Polar Stereographic geotiff file of Patagonia
gmt pscoast -JS-55/-60/15c -R-77/-55/-57.5/-48r -Di -Gred -P -Bg2 --MAP_FRAME_TYPE=inside > patagonia.ps
gmt psconvert patagonia.ps -Tt -W+g -V
To create a simple KMZ file for use in Google Earth, try
gmt grdimage lonlatgrid.nc -Jx1 -Ccolors.cpt -P -B0g2 --MAP_FRAME_TYPE=inside > tile.ps
gmt psconvert tile.ps -Tg -W+k+t"my title"+l256/-1 -V
(These commands assume that GhostScript can be found in your system's path.)
GHOSTSCRIPT OPTIONS
Most of the conversions done in psconvert are handled by GhostScript. On most Unixes this
program is available as gs; for Windows there is a version called gswin32c. GhostScript
accepts a rich selection of command-line options that modify its behavior. Many of these
are set indirectly by the options available above. However, hard-core usage may require
some users to add additional options to fine-tune the result. Use -S to examine the actual
command used, and add custom options via one or more instances of the -C option. For
instance, to turn on image interpolation for all images, improving image quality for
scaled images at the expense of speed, use -C-dDOINTERPOLATE. See www.ghostscript.com for
complete documentation.
SEE ALSO
gmt
COPYRIGHT
2015, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe