gxhconvert manual

↑ Home (Graphics conversion hints)

gxhconvert - Graphics conversions in LaTeX environments

This page shows how to use the gxhconvert script for graphics conversions.

Synopsis

gxhconvert -o=suffix file(s) 

---

Description

The gxhconvert script converts between graphics file formats in environments using LaTeX/pdfLaTeX.
The script provides a simple interface, especially for multi-step conversions. It runs external programs and provides arguments to them to do the real conversions.

---

Options

Group	Option	Purpose
Setup check, debugging	--check	Check for required external programs, issue installation hints for missing programs.
	--debug	Produce verbose output.
Output type	-o=suffix	String Output file name suffix, indicates the output file type. Required. One from: "tex", "pdf" "eps", "ps", "svg", "png", "jpg", "jpeg", "ico", "xpm"
Output file options	-d --document	Conversion from Fig or Gnuplot to *.tex: The *.tex output file is a LaTeX document, not a LaTeX image (default). Conversion from PNG/JPEG/TIFF to PDF/PS: Fit output to a paper size (default: A4). Only available when converting Fig/Gnuplot to *.tex and when converting PNG/JPEG/TIFF to PDF/PS.
	-i --image	Conversion from PNG/TIFF to PDF: Create a PDF image instead of an object (default). The alpha channel for PNG/TIFF input is transferred to PDF output unchanged for objects. The alpha channel is used to mix against a background color for images. Only available when converting PNG/JPEG/TIFF to PDF/PS.
	--paper=format	String Paper format to fit image to. Only available when converting PNG/JPEG/NetPBM/TIFF to PDF/EPS/PS.
	--duplex	Use front and back page, binding on the left/right side like a book.
	--tumble	Use front and back page, binding on the top/bottom side like a wall calendar.
	-a --alpha	Create alpha channel. Untouched input regions result in transparent output regions. Only available when converting vector graphics to PNG/ICO/XPM.
	-r=resolution	Resolution in dpi (dots per inch) for conversion from vector graphics (Fig, SVG, Gnuplot, LaTeX docs, PDF, or EPS) to bitmap images (PNG, JPEG).
	-q=quality	Quality factor in the range 0...100 for JPEG creation. Only available when converting to JPEG.
	--interlaced	Create interlaced PNG. The start of the file (data stream) allows to render the image in low quality, details for better quality follow.
	--optimized	Optimize (decrease) file size. Computation takes a little longer and uses more memory.
	--ultra-optimized	PNG file size optimization, do exhaustive search with large number of trials using optipng options "-zc8-9 -zm1-9 -zs0-3 -f0-5"
	--web	Shortcut for "--interlaced --optimized --ultra-optimized".
Input file options	--pgf	For conversions with LaTeX involved, write a LaTeX image using PGF instructions instead of using a *.pdf/*.tex file combination. Only available for Fig and Gnuplot input files.
	--eps	Write LaTeX image using a *.eps/*.tex file combination for use with latex/dvixxx instead of the usual *.pdf/*.tex combination for use with pdflatex. Only available when converting Fig or Gnuplot input files to LaTeX images.
	--font-size=size	Font size for the LaTeX document class. This number is typically in the range 8...12. Only available for Fig input files.
	--fig2lat=options	Additional options for fig2lat. Only available for Fig input files.
	--svg-area=area	String Area to export, one from: drawing to export just the area containing drawing elements, snap to enlarge the drawing area to the next snap grid points, page to export the entire page. Only available for SVG input files.
	--svg-latex	Required, if the file name does not end in "-il" to indicate the texts must be processed by LaTeX. Only available for SVG input files.
System setup	--netpbm-debian --netpbm-non-debian	Set ppmtoxpm options for a ppmtoxpm from a Debian (or derivative) netpbm package or for a non-Debian netpbm package. Only recommended for Debian users having a real NetPBM (not from Debian package management) installed.
Help	--help	Show help text.

---

Return value

The program returns 0 on success, any other value indicates an error.

---

Files

Configuration files

At startup the script searches for the configuration files:

• /etc/gxhints/gxhconvert.conf
• ${HOME}/.gxhconvert
• gxhconvert.conf (in the current directory)

and uses all files found.

Each line of the file is either just a key or a key/value pair:

Key	Purpose
document = number	Flag to produce a document (non-0) or an image/object (0).
svg resolution = number	Default resolution (pixels per inch) when converting from SVG to bitmap files.
pdf resolution = number	Default resolution (pixels per inch) when converting from PDF to bitmap files.
other resolution = number	Default resolution (pixels per inch) when converting from other vector graphics files to bitmap files.
alpha = number	Flag to convert untouched input regions from vector graphics input into transparent regions in PNG/ICO/XPM output. On for non-0 values, off for 0.
jpeg quality = number	JPEG quality value in the range 0...100.
jpeg optimize = number	Flag to turn JPEG optimization on (non-0) or off (0).
jpeg progressive = number	Flag to turn progressive JPEGs on (non-0) or off (0).
pgf = number	Flag to turn PGF instead of PDF/TeX for Fig/Gnuplot input on (non-0) or off (0).
eps = number	Flag to turn EPS/TeX combination instead of PDF/TeX for Fig/Gnuplot to LaTeX image conversion on (non-0) or off (0).
latex font size = number	Font size for LaTeX document class when converting Fig input to LaTeX documents.
fig2lat options = string	Additional options for fig2lat.
svg area = string	Area to export for SVG input, one from "page", "snap", or "drawing".
svg latex = number	Flag to indicate whether an SVG input file contains LaTeX texts (non-0) or not (0).
cairolatex preamble line = string	A preamble line to insert into the output after the "% Load packages" line when using the cairolatex terminal for a Gnuplot file to produce a LaTeX document. This option may be used multiple times. In addition to the documentclass line the *.tex file generated by the cairolatex terminal already contains a number of setup lines, see below.
tikz preamble line = string	A preamble line to insert immediately before the "\usepackage{gnuplot-lua-tikz}" line when using the tikz terminal for a Gnuplot file to produce a LaTeX document. This option may be used multiple times. In addition to the documentclass line the *.tex file generated by the tikz terminal already contains some setup lines, see below.
preamble line = string	A preamble line to use with both tikz and cairolatex terminal when converting a Gnuplot file to a LaTeX document. This option may be used multiple times.
netpbm-debian netpbm-non-debian	Skip automatic detection of Debian netpbm package.

Default setup lines for cairolatex terminal

\usepackage{graphicx}
\usepackage{color}

Default setup lines for tikz terminal

\usepackage[T1]{fontenc}
\usepackage{textcomp}   
\usepackage[utf8x]{inputenc}

Gnuplot input files

When processing a Gnuplot file using the gxhconvert script there is
one little restriction about the contents of the Gnuplot file.
Optionally you can add information like diagram width and height in
special comments.

• No terminal, no output file name
  Do not use

  set terminal ...
  set output ...
  

  in Gnuplot files you want to use with gxhconvert.
  Terminal type and output file name are provided by the gxhconvert script and passed as command line arguments to Gnuplot.
   
  
• Optionally: Diagram width and height in special comments
  Special comments have two raute characters (`#') at the start of line, example:
  

  ##  width   =   10cm
  ##  height  =   10cm
  set xrange [0:10]
  plot x*x title "\\(y=x^2\\)"
  

  The gxhconvert script uses the tikz terminal instead of the usual cairolatex pdf terminal if width and height are specified. Make sure you have installed the "gnuplot-lua-tikz" package for LaTeX.
   
  
• Optionally: Terminal type and setup in special comments
  Example:

  ##  terminal    =   tikz
  ##  terminal setup  =   solid
  

  For the terminal you can choose either "tikz" or "cairolatex".
   
  
• Two backslashes in Gnuplot file for each LaTeX backslash
  Gnuplot uses the backslash to escape some characters. So for each backslash you want to pass to LaTeX, write a sequence of two backslashes in the Gnuplot file. Example:

  set xlabel "\\(\\frac{x}{x_0}\\rightarrow\\)"
  set ylabel "\\(\\overset{\\uparrow\\vspace{0.3em}}{y}\\)" rotate by 0
  

  Note: The \\overset instruction requires a line

  preamble line = \usepackage{amsmath}
  

  in the gxhconvert.conf file in the current working directory.

Fig input files to produce an ICO file

Make sure the drawing is a 1 inch × 1 inch square.
You can place a bounding box rectangle in a *.fig file, specifying the drawing size.

A bounding box rectangle is a box (object type 2, subtype 2) which is only used to calculate the bounding box of the image. It is not drawn to output files.

If no source type was specified when starting fig2lat the bounding box rectangle is also used to recognize the source file type.

Depending on your drawing program you should set the following attributes on a bounding box rectangle:

Attribute	XFig	jFig	WinFIG
Layer	999	999	999
Line width	0	0	0
Pen colour	Default (-1)	White (7)	White (7)
Fill style	None (-1)	None (-1)	None (-1)

If a background rectangle was found and the source type is not yet known the pen color is used to separate files created by XFig from files created by jFig.
Files created by WinFIG are recognized by the METADATA lines in the file.

Fig input files to produce an XPM file for wxWidgets toolbar

Make sure the drawing is rectangle: 1 inch wide, 15/16 inches high. You should place an appropriate bounding box rectangle (see section above).

Inkscape SVG files to produce an ICO file

Make sure the drawing is a 1 inch × 1 inch square.
In the document settings switch the unit to in and change page width and height to 1.

To create a new icon, copy the SVG template for icons to a file name of your choice and modify that file in inkscape.

Inkscape SVG files to produce an XPM file for wxWidgets toolbar

Make sure the drawing is rectangle: 1 inch wide, 15/16 inches high.
In the document settings switch the unit to in and change the page width to 1, page height to 0.9375.

To create a new wxWidgets toolbar image, copy the SVG template for toolbar button images to a file name of your choice and modify that file in inkscape.

Temporary files

Some of the conversions - especially the multi-step conversions -
use temporary files.
Example: When converting x.fig to x.png a temporary file x.pdf is used. An existing x.pdf file is updated during the conversion, no backup is made.
If the x.pdf file did not exist before the conversion, it is removed at the end of the conversion.

---

Notes

Output file name for PS or EPS output

The output file name suffix may differ from the suffix specified using -o.
Generally the suffix ".eps" is used, the ".ps" suffix is used only when converting PNG/JPEG/TIFF to PS documents.

The option -o=ps can be used for PNG/JPEG/TIFF only.

---

Author

Dirk Krause

---

Copyright and license

Copyright © 2013-2018 - Dirk Krause

The gxhints project is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

↑ Home (Graphics conversion hints)