Command/externalfigure
\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 usingmethod=type
where type is any of the file extensions that is recognized by \externalfigure.- auto: When the file extension is
.auto
ormethod=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 for natively supported image formats. (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. Usesize=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.
- For the conversion to work,
inkscape
should be in thePATH
. 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 thePATH
; on other platformsgs
must be in thePATH
. 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. Useresolution=low
to change the[resolution]
to screen andresolution=meidum
to change the[resolution]
to ebook.
- GIF: File extension
.gif
. Converted to PDF using GraphicsMagick.
- For the conversion to work,
gm
should be in thePATH
. 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 thePATH
. 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.
Tracing and 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]
In MkIV, to see which files were searched, either add
\enabletrackers[graphics.inclusion]
or use the command line switch
context --trackers=graphics.inclusion [filename]
which gives
graphics > inclusion > locations: local,global graphics > inclusion > path list: . .. ../.. graphics > inclusion > strategy: forced format pdf graphics > inclusion > not found: cat.pdf graphics > inclusion > not found: ./cat.pdf graphics > inclusion > not found: ../cat.pdf graphics > inclusion > not found: ../../cat.pdf graphics > inclusion > format not supported: %s
indicating where the file was searched.
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]
See also
- \defineexternalfigure to define a collection of settings
- \setupexternalfigures to define a different collection of settings
- \useexternalfigure to define an image+settings combination
Help from ConTeXt-Mailinglist/Forum
All issues with:
- externalfigure on the mailing list (all results)
- externalfigure on the mailing list (subject only)
- externalfigure on stack exchange
- externalfigure in ConTeXt's source
/code>. Converted to PDF on the fly using MPtoPDF.
- JPEG: File extension