# \externalfigure

## Syntax

 \externalfigure[...][...,...=...,...] [...] file [...,...=...,...] see \useexternalfigure

## Description

Command to include an external figure/movie inside ConTeXt. Includes both local files or remote files hosted on HTTP servers.

The following image formats are supported natively in MkIV:

• PDF: File extension `.pdf`. By default, mediabox is used to determine size. Use `size=artbox` to use artbox.
• MPS (MetaPost Output): File extension `.mps` or `.[digits]`. Converted to PDF on the fly using MPtoPDF.
• JPEG: File extension `.jpg` and `.jpeg`
• PNG: File extesion `.png`
• JPEG 2000: File extesion `.jp2`
• JBIG and JBIG2: File extension `.jbig`, `.jbib2`, and `.jb2`

The following formats are converted to PDF by external programs before being included. The conversion generates a new file with a prefix `m_k_i_v_` and a suffix `.pdf` added to the name of the original file (the original extension is nor removed). The result is cached, and the conversion is rerun only if the timestamp of the original file is newer than the converted file.

• SVG: File extension `.svg` and `.svgz`. Converted to PDF using Inkscape.
For the conversion to work, `inkscape` should be in the `PATH`. The following command is used for conversion:
```   inkscape [inputfile] --export-dpi=600 -A [outputfile]
```
(Note: Conversion to PNG is also possible, but I don't know the details on how to active that -- 03:32, 29 November 2012 (CET)).
• PS and EPS: File extension `.eps` and `.ai`. Converted to PDF using Ghostscript.

For the conversion to work, on Windows `gswin32c` must be in the `PATH`; on other platforms `gs` must be in the `PATH`. The following command line options are passed to Ghostscript
```   gs -q -sDEVICE=pdfwrite -dNOPAUSE -dNOCACHE -dBATCH [resolution] -sOutputFile=[outputfile] [inputfile] -c quit
```
By default, the `[resolution]` is prepress. Use `resolution=low` to change the `[resolution]` to screen and `resolution=meidum` to change the `[resolution]` to ebook.
For the conversion to work, `gm` should be in the `PATH`. The following command is used for the conversion:
```   gm convert [inputfile] [outputfile]
```
• TIFF: File extensions `.tiff` and `.tif`. Converted to PDF using GraphicsMagick.
For the conversion to work, `gm` should be in the `PATH`. The following command is used for the conversion:
```   gm convert [inputfile] [outputfile]
```

The following movie formats are supported.

• QuickTime: File extension `.mov`.
(Note: Check if this works?)

Normally, the type of file is determined by the extension of the file. If the file uses a non-standard extension, then use `method=....` to specify the file type. If `method=auto` is used, ConTeXt reads the first few bytes of the file to determine the filetype. Such an auto-discovery is useful for remote images that do not have a file extension.

In addition, the following special formats are supported:

• buffer: Typeset the buffer with the given name and include the result as a PDF file.
• tex: Typeset the TeX file using `context` and include the result as a PDF file
• cld: Typeset the ConTeXt Lua document using `context` and include the result as a PDF file.

Note: The file extesions are case insensitive.

## Example

### Including a local image

In the example below, no file name extension is used. ConTeXt searches for an image file in the following order: `cow.pdf`, `cow.mps`, `cow.1`, `cow.2`, etc., `cow.jpg`, `cow.png`, `cow.jp2`, `cow.jbig`, `cow.jbig2`, `cow.jb2`. The file `cow.pdf`, which is distributed as part of the ConTeXt distribution, is found and displayed.

```% look for figure files in texmf tree
\setupexternalfigures[location=default]

\externalfigure[cow][width=4cm]
```

ConTeXt distribution also includes a sample image `hacker.jpg`. To include it use:

```% look for figure files in texmf tree
\setupexternalfigures[location=default]

\externalfigure[hacker][height=3cm]
```

### Include a remote image

```\externalfigure[http://placekitten.com/g/200/300][method=jpg]
```

The above example does not work on the wiki due to security restrictions. It should run on the default ConTeXt installation.