\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.

How the filetype is determined

• File extension: Normally, the type of file is determined by the extension of the file (in a case-insensitive manner).
• `method=type` If the file uses a non-standard extension, specify the file type using `method=type` where type is any of the file extensions that is recognized by \externalfigure.
• auto: When the file extension is `.auto` or `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.

If the extension of the file is not specified, ConTeXt searches for all possible extensions in the order given below. (When postscript output was used, the order in which the file extensions were searched depended on the output format (PDF or PS). These days, PDF is the default output format, so for all practical purposes, the order in which the file extensions are searched is fixed).

Natively supported image formats

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`

Image formats supported through external converters

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]
```

Supported movie formats

 NOTE: Inclusion of movie formats is broken in MkIV

The following movie formats are supported.

• QuickTime: File extension `.mov`.

Support for special TeX formats

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.

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.

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

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

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

Include a remote image

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

Rotate an image

• Rotate by 90, 180, or 270 degrees: Use `orientation=90|180|270` to rotate an image in multiples of 90. For example:
```\externalfigure[mill][orientation=180]
```

• Rotate by an arbitrary angle: Use \rotate command.
```\rotate[rotation=45]{\externalfigure[mill]}
```

Error Messages

When a file is specified by its full name, and is not found, no error message is displayed in the log; rather a gray box is shown in the generated PDF which indicates that the figure was not found. For example (note that `cat.pdf` should not exist in the current directory)

```\externalfigure[cat.pdf]
```

Tracking

The following trackers are available for \externalfigures (MkIV only)

• graphics.locating: Gives details about where the image files are searched, what strategy was used to infer the file format, and what was the inferred file format.
• graphics.conversion: Gives details about the conversion from one file format to another
• graphics.inclusions: Gives details of including a movie

The trackers are enabled using

``` \enabletrackers[...tracker...]
```

or

``` context --trackers=list [filename]
```

When graphics.locating tracker is enabled, including a known file gives the following information on the terminal

``` graphics        > inclusion > locations: local,global
graphics        > inclusion > path list: . .. ../..
graphics        > inclusion > strategy: unknown format, prefer quality
graphics        > inclusion > found: ./cow.pdf -> /opt/context-minimals/texmf-context/tex/context/sample/cow.pdf
graphics        > inclusion > format natively supported by backend: pdf
```

If the asked file does not exist, the following information is displayed.

``` graphics        > inclusion > locations: local,global
graphics        > inclusion > path list: . .. ../..
graphics        > inclusion > strategy: forced format pdf
graphics        > inclusion > format not supported: %s
```

When graphics.conversion tracker is enabled, and, including a file type that requires conversion, say PS, displays the following message on the terminal

``` graphics        > inclusion > checking conversion of './tiger.ps' (./tiger.ps): old format 'ps', new format 'pdf', conversion 'default', resolution 'default'
graphics        > inclusion > no need to convert './tiger.ps' (tiger.ps) from 'ps' to 'pdf'
graphics        > inclusion > new graphic, hash: m_k_i_v_tiger.ps.pdf->1->crop->unknown->unknown->unknown->
```

When graphics.inclusion tracker is enabled, including a movie displays the following message on the terminal

``` graphics        > inclusion > including movie 'clip.mov': width 5594039.4330709, height 5594039.4330709
```