Changes

== [[Help:Reference|Syntax]] (autogenerated) ==<table cellspacing="4" cellpadding="2" class="cmd"> <tr> <td colspan="2" class="cmd"syntax>\externalfigure<span class="first" >[...]</span><span class="second" >[...,...=...,...]</span></td> </tr> <tr valign="top" class="first"> <td class="cmd">[...]</td> <td>file </td> </tr> <tr valign="top" class="second"> <td class="cmd">[...,...=...,...]</td> <td>see [[Command/useexternalfigure|\useexternalfigure]] </td> </tr></tablesyntax>

Command The <code>\externalfigure</code> command is used to include an external figure/movie inside ConTeXt. Includes both local files or remote files hosted on HTTP servers.  The simplest way to insert an image is to use: <context source="yes" mode="mkiv">\externalfigure[cow.pdf]</context> This command places the PDF image <code>cow.pdf</code> in a<code>\vbox</code>; 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 <code>1cm</code>, use:<context source="yes" mode="mkiv" text="which gives">\externalfigure[cow.pdf][width=1cm]</context> Similarly, to set the height of the image to a specific size, say <code>2cm</code>, use:<context source="yes" mode="mkiv" text="which gives">\externalfigure[cow.pdf][height=2cm]</context> If only the <code>width</code> or <code>height</code> 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[filename.pdf][page=5]</texcode> These four variations cover 90% of the use cases. 

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  Historically, when postscript output was used, the order in which the file extensions were searched depended on the output format (PDF or PS). These daysWith recent releases of ConTeXt, PDF is the default output format, so for all practical purposes, the order in which the file extensions are searched is fixed).

* '''MPS (MetaPost Output)''': File extension <code>.mp</code>, <code>.mps</code> or <code>.[digits]</code>. <!-- Converted to PDF on the fly using MPtoPDF. -->

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

: (Note: Conversion to PNG is also possible, but I don't don’t know the details on how to active that -- 03:32, 29 November 2012 (CET)).

== Tracing Command options == === <code>interaction</code> === By default, the interactive elements of the included PDF file are discarded. To enable the interactive elements of the included PDF file, use <texcode>\externalfigure[filename.pdf][interaction=yes]</texcode> == 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: <code>cow.pdf</code>, <code>cow.mps</code>, <code>cow.1</code>, <code>cow.2</code>, etc., <code>cow.jpg</code>, <code>cow.png</code>, <code>cow.jp2</code>, <code>cow.jbig</code>, <code>cow.jbig2</code>, <code>cow.jb2</code>. The file <code>cow.pdf</code>, which is distributed as part of the ConTeXt distribution, is found and error displayed. <context source="yes" mode=mkiv>\externalfigure[cow][width=4cm]</context> ConTeXt distribution also includes a sample image <code>hacker.jpg</code>. To include it use: <context source="yes" mode=mkiv>\externalfigure[hacker][height=3cm]</context> === Include a remote image === <context source="yes" mode="mkiv"> \externalfigure[http://placekitten.com/g/200/300][method=jpg]</context> === Rotate an image === * '''Rotate by 90, 180, or 270 degrees''': Use <code>orientation=90|180|270</code> to rotate an image in multiples of 90. For example: <context source="yes" mode=mkiv>\externalfigure[mill][orientation=180]</context>  * '''Rotate by an arbitrary angle''': Use {{cmd|rotate}} command. <context source="yes" mode=mkiv>\rotate[rotation=45]{\externalfigure[mill]}</context> === Flip an image === Use {{cmd|mirror}} to horizontally flip an image <context source=yes mode=mkiv>\mirror{\externalfigure[cow][width=3cm]}</context> == Error Messages ==

In == Tracking == The following trackers are available for {{cmd|externalfigures}} (MkIVonly)  * '''graphics.locating''': Gives details about where the image files are searched, what strategy was used to see which files were searchedinfer the file format, either addand 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

\enabletrackers context --trackers=list [graphics.inclusionfilename]

or use When '''graphics.locating''' tracker is enabled, including a known file gives the command line switchfollowing 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

context --trackers=graphicsIf the asked file does not exist, the following information is displayed.inclusion [filename]

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

=== Including When '''graphics.inclusion''' tracker is enabled, including a local image ===movie displays the following message on the terminal

In the example below, no file name extension is used. ConTeXt searches for an image file in the following order: <code>cow.pdf</code>, <code>cow.mps</code graphics >, <codeinclusion >cowincluding movie 'clip.1</code>, <code>cow.2</code>, etc., <code>cow.jpg</code>, <code>cow.png</code>, <code>cow.jp2</code>, <code>cowmov': width 5594039.jbig</code>, <code>cow.jbig2</code>, <code>cow.jb2</code>. The file <code>cow.pdf</code>, which is distributed as part of the ConTeXt distribution4330709, is found and displayedheight 5594039.4330709