869
edits
Changes
Jump to navigation
Jump to search
Content of the tugboat article
< [[Graphics]] | [[Combinations]] | [[File Formats|Supported Media File Formats]] | [[Including pages from PDF documents]] | [[Animation]] >
= Basic usage =
The simplest way to insert an image is to use:
<texcode>\externalfigure[logo.pdf]</texcode>
This command places the PDF image <tt>logo.pdf</tt> in a <tt>\vbox</tt>; the width and height of the image are equal to the natural dimensions of the image.
To set the width of the image to a specific size, say <tt>1cm</tt>, use:
<texcode>\externalfigure[logo.pdf][width=1cm]</texcode>
Similarly, to set the height of the image to a specific size, say <tt>2cm</tt>, use:
<texcode>\externalfigure[logo.pdf][height=2cm]</texcode>
If only the <tt>width</tt> or <tt>height</tt> of the image is specified, the other dimension is scaled appropriately to keep the aspect ratio.
To include a specific page, say page 5, of a multi-page PDF file, use:
<texcode>\externalfigure[logo.pdf][page=5]</texcode>
These four variations cover 90% of the use cases.
== Natively supported file formats ==
ConTeXt natively supports the image formats enumerated below. The image format is determined from the file extension (case insensitive).
* '''PDF''': File extension <tt>.pdf</tt>
* '''MPS''' (MetaPost output): File extension <tt>.mps</tt> or <tt>.<digits></tt>
* '''JPEG''': File extension <tt>.jpg</tt> or <tt>.jpeg</tt>
* '''PNG''': File extension <tt>.png</tt>
* '''JPEG 2000''': File extension <tt>.jp2</tt>
* '''JBIG''' or '''JBIG2''': File extension <tt>.jbig</tt>, <tt>.jbig2</tt>, or <tt>.jb2</tt>
== Including images after conversion ==
The image formats listed in the previous section are the ones that may be embedded directly in a PDF. ConTeXt also supports a few other formats which are first converted to PDF using an external program. Of course, for such a conversion to work, the corresponding converter must be in the <tt>PATH</tt>.
<table>
<tr class="odd">
<td align="left">Format</td>
<td align="left">Extension</td>
<td align="left">Converter</td>
</tr>
<tr class="even">
<td align="left"><strong>SVG</strong></td>
<td align="left"><code>.svg</code>, <code>.svgz</code></td>
<td align="left"><code>inkscape</code></td>
</tr>
<tr class="odd">
<td align="left"><strong>EPS</strong></td>
<td align="left"><code>.eps</code>, <code>.ai</code></td>
<td align="left"><code>gs</code> (or <code>gswin32c</code> on Windows) from Ghostscript</td>
</tr>
<tr class="even">
<td align="left"><strong>GIF</strong></td>
<td align="left"><code>.git</code></td>
<td align="left"><code>gm</code> from GraphicsMagick</td>
</tr>
<tr class="odd">
<td align="left"><strong>TIFF</strong></td>
<td align="left"><code>.tiff</code></td>
<td align="left"><code>gm</code> from GraphicsMagick</td>
</tr>
</table>
The conversion generates a PDF file with prefix <tt>m_k_i_v_</tt> and a suffix <tt>.pdf</tt> added to the name of the original file. The result is cached, and the conversion is rerun if the timestamp of the original file is newer than that of the converted file.
== Specifying image directories ==
By default, ConTeXt searches an image in the current directory, the parent directory, and the grand-parent directory.
To search for images in other directories, say a <tt>./images</tt> subdirectory and <tt>/home/user/images</tt>, use:
<texcode>\setupexternalfigures
[directory={images, /home/user/images}]</texcode>
Note that one should always use forward slashes in path names, ''even on Windows''.
The default search order is: the current directory, the parent directory, the grand-parent directory, and then the paths specified by the <tt>directory</tt> key. To restrict image search only to the paths specified by the <tt>directory</tt> key, use:
<texcode>\setupexternalfigures
[location=global]</texcode>
To restore the default search behavior, use:
<texcode>\setupexternalfigures
[location={local,global}]</texcode>
The ConTeXt distribution includes three sample images: <tt>cow.pdf</tt>, <tt>mill.png</tt>, and <tt>hacker.jpg</tt>, that are useful when creating minimum working examples to illustrate a bug on the mailing list. These images are locating in the <tt>TEXMF</tt> directory. To add the <tt>TEXMF</tt> directory to the image search path, use:
<texcode>\setupexternalfigures
[location={local,global,default}]</texcode>
The above alternative adds the ''entire'' <tt>TEXMF</tt> directory to the search path, ''including the'' <tt>doc/</tt> ''directory!'' Therefore, one needs to be extremely careful when using this option. In fact, I would advise not using <tt>location=default</tt> except for illustrative minimal working examples.
== Including remote images ==
Like all other ConTeXt macros that read files, <tt>\externalfigure</tt> also supports reading remote files from '''HTTP(S)''' servers. An example:
<texcode>\externalfigure
[http://tug.org/images/logobw.jpg]</texcode>
When a document containing a remote file is compiled for the first time, the remote file is downloaded from the server and stored in the LuaTeX cache directory. This cached file is used during subsequent runs.
Normally, the remote image is downloaded again if the image in the cache is older than 1~day. To change this threshold to, for example, 2<sub>minutes (120</sub>seconds), either add
<texcode>\enabledirectives[schemes.threshold=120]</texcode>
in the ConTeXt file, or compile the ConTeXt file using the command
<pre>context --directives=schemes.threshold=120 <em>filename</em></pre>
The variable <tt>schemes.threshold</tt> is global, so changing its value affects all other macros like <tt>\input</tt>, <tt>\usemodule</tt>, <tt>\component</tt>, etc. that load remote files.
= Image transformations =
== Scaling images ==
To scale an image use the <tt>scale</tt> key: <tt>scale=1000</tt> corresponds to the original dimensions of the image, <tt>scale=500</tt> scales the image to 50% of the original size, <tt>scale=1500</tt> scales the images to 150% of the original size, and so on. For example:
<texcode>\externalfigure[logo.pdf][scale=500]</texcode>
Use <tt>\setupexternalfigures</tt> to set the scale of all images. For example, to scale all images to be twice their original size, use:
<texcode>\setupexternalfigures[scale=2000]</texcode>
If either <tt>width</tt> or <tt>height</tt> is specified, then the <tt>scale</tt> key has no effect.
In addition, the <tt>xscale</tt> and <tt>yscale</tt> keys scale the image in only one dimension. For example:
<texcode>\externalfigure[logo.pdf][xscale=500]
\externalfigure[logo.pdf][yscale=500]</texcode>
== Specifying maximum size of an image ==
Oftentimes, we don't want the included image to be greater than a particular size. For example, to ensure that an included image is not more than <tt>0.2\textwidth</tt>:
<texcode>\externalfigure[logo.pdf][maxwidth=0.2\textwidth]</texcode>
If <tt>maxwidth</tt> is specified and the width of the image is less than <tt>maxwidth</tt>, then the image is not scaled; if the width of the image is greater than <tt>maxwidth</tt>, then the width is restricted to <tt>maxwidth</tt> and the height is scaled appropriately to maintain the original aspect ratio.
The option <tt>maxheight</tt> is analogous to <tt>maxwidth</tt>, for checking the height of the image.
For example, to ensure that figures do not overflow the text~area, one may set:
<texcode>\setupexternalfigures
[maxwidth=\textwidth,
maxheight=0.8\textheight]</texcode>
== Rotating images ==
To rotate the included image by 90, 180, or 270 degrees, use the <tt>orientation</tt> key. For example:
<texcode>\externalfigure[logo.pdf][orientation=90]</texcode>
To rotate by an arbitrary angle, use the <tt>\rotate</tt> command. For example:
<texcode>\rotate[rotation=45]{\externalfigure[logo.pdf]}</texcode>
== Mirroring images ==
To mirror (flip) an image, use the generic <tt>\mirror</tt> command. For example, to mirror horizontally:
<texcode>\mirror{\externalfigure[logo.pdf]}</texcode>
To mirror vertically, first rotate the image by 180° and then mirror it:
<texcode>\mirror{\externalfigure[logo.pdf][orientation=180]}</texcode>
== Clipping images ==
To clip an image, use the generic <tt>\clip</tt> command. For example, to clip the original image to a <tt>1cm x 2cm</tt> rectangle at an offset of <tt>(3mm,5mm)</tt> from the top left corner:
<texcode>\clip[width=1cm, height=2cm, hoffset=3mm, voffset=5mm]
{\externalfigure[logo.pdf]}</texcode>
As another example, this cuts the image into a <tt>3x3</tt> pieces and then outputs the <tt>(2,2)</tt> piece:
<texcode>\clip[nx=3,ny=3,x=2,y=2]
{\externalfigure[logo.pdf]}</texcode>
= Troubleshooting =
== Visualizing the image bounding box ==
If, for instance, the image is taking more space than expected, it can be useful to visualize the bounding box of the image. To do this:
<texcode>\externalfigure[logo.pdf][frame=on]</texcode>
ConTeXt includes a Perl script <tt>pdftrimwhite</tt> that removes extra white space at the borders of a PDF file. To run this script:
<pre>mtxrun --script pdftrimwhite <em>[flags] input output</em></pre>
The most important flag is <tt>--offset=dimen</tt>, which keeps some extra space around the trimmed image.
Similar functionality is provided by another Perl script, <tt>pdfcrop</tt>, that is included in most TeX distributions.
== Tracking what is happening ==
To get diagnostic information about image inclusion, enable the tracker <tt>graphics.locating</tt> either by adding
<texcode>\enabletrackers[graphics.locating]</texcode>
in the ConTeXt file, or by compiling the ConTeXt file using the command
<texcode>context --trackers=graphics.locating filename</texcode>
The tracker writes diagnostics to the console. Suppose we use <tt>\externalfigure[somefile.pdf]</tt> and ConTeXt finds the file in the current search path; then the following information is printed on the console:
<pre>graphics > inclusion > locations: local,global
graphics > inclusion > path list: . .. ../..
graphics > inclusion > strategy: forced format pdf
graphics > inclusion > found: somefile.pdf -> somefile.pdf
graphics > inclusion > format natively supported by backend: pdf</pre>
If the file <tt>somefile.pdf</tt> is not found in the current search path, then the following information is printed on the console (even if the <tt>graphics.locating</tt> tracker is not set):
<pre>graphics > inclusion > strategy: forced format pdf
graphics > inclusion > not found: somefile.pdf
graphics > inclusion > not found: ./somefile.pdf
graphics > inclusion > not found: ../somefile.pdf
graphics > inclusion > not found: ../../somefile.pdf
graphics > inclusion > not found: images/somefile.pdf
graphics > inclusion > not found: /home/user/images/somefile.pdf
graphics > inclusion > format not supported: </pre>
and a placeholder gray box is put in the output:
<context> </context>
Sometimes, one would rather use a placeholder image for an image that is yet to be made. In such cases, load the MP library <tt>dum</tt> via:
<texcode>\useMPlibrary[dum]</texcode>
Then, whenever an image file is not found in the current search path, a random MetaPost image is shown in the output.
<context> </context>
== Images at the beginning of a paragraph ==
Using <tt>\externalfigure[...]</tt> at the beginning of a paragraph results in a line break after the image. This is because <tt>\externalfigure</tt> is a <tt>\vbox</tt> and when encounters a <tt>\vbox</tt> at (what appears to be) the beginning of a paragraph, it remains in vertical mode. To prevent this, add <tt>\dontleavehmode</tt> before <tt>\externalfigure</tt>, like this:
<texcode>\dontleavehmode
\externalfigure[...] ... first line ...</texcode>
= Settings for multiple images =
== Image settings ==
Suppose your document contains many side-by-side images, and you want all of these images to be of the same size. In addition, you want to control the size of all images by changing only one setup. To do this, you can use the <tt>\defineexternalfigure</tt> macro, which defines a named collection of image settings. For example, to define a collection where the image width is <tt>3cm</tt>, use:
<texcode>\defineexternalfigure[logo-settings]
[width=3cm]</texcode>
And then to use these settings in an image, use:
<texcode>\externalfigure[group.pdf][logo-settings]</texcode>
or, if you want to add or override settings, use:
<texcode>\externalfigure[group.pdf][logo-settings]
[height=2cm]</texcode>
== Labeled images ==
Suppose your document contains an image at multiple locations; all of these images are to be of the same size, which is not necessarily the same as the natural size of the image. Furthermore, as before, you want to set the size of all the images by changing only one setup. Here, the macro to use is <tt>\useexternalfigure</tt>, which defines a symbolic label for inserting an image plus settings. For example:
<texcode>\useexternalfigure[mylogo]
[logo.pdf][width=2cm]</texcode>
defines an image label <tt>mylogo</tt> that maps to the image file <tt>logo.pdf</tt> and sets its width to <tt>2cm</tt>. This image label may be used as a normal image filename:
<texcode>\externalfigure[mylogo]</texcode>
-------------------------------------------
== Direct use of an image ==
