973
edits
Changes
Jump to navigation
Jump to search
Command The <code>\externalfigure</code> command is used to include an external figure/movie inside ConTeXt. Includes both localfiles 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. === 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).* '''<code>method=type</code>''' If the file uses a non-standard extension, specify the file type using <code>method=type</code> where type is any of the file extensions that is recognized by {{cmd|externalfigure}}.* '''auto''': When the file extension is <code>.auto</code> or <code>method=auto</code> 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. Historically, when postscript output was used, the order in which the file extensions were searched depended on the output format (PDF or PS). With 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. === Natively supported image formats ===
: (Note: Check if this {{ note| Movie inclusion only works?)in Adobe Acrobat but does not work on Linux }}
Normally, the type of file is determined by the extension of the file. If the file uses a non-standard extension, then use <code>method=....</code> to specify the file type. If <code>method=<b>auto</b></code> is used, ConTeXt reads the first few bytes of the file to determine the filetype. Such an auto-discovery is useful = Support for remote images that do not have a file extension.special TeX formats ===
In addition, the The following special formats are supported:
'''Note''': The file extesions are case insensitive.=== <code>interaction</code> ===
The above example does == Error Messages == When a file is specified by its full name, and is not work on found, no error message is displayed in the log; rather a gray box is shown in the generated PDF which indicates that the wiki due to security restrictionsfigure was not found. For example (note that <code>cat. It pdf</code> should run on '''not''' exist in the default ConTeXt installation.current directory)
no edit summary
<noinclude>
{{Reference
|name=externalfigure
}}
== [[Help:Reference|Syntax]] (autogenerated) ==
<syntax>externalfigure</syntax>
== [[Help:Reference|Syntax]] ==
<table cellspacing="4" cellpadding="2" class="cmd">
</table>
</noinclude>
== Description ==
The following image formats are supported natively in MkIV:
* '''[http://en.wikipedia.org/wiki/JPEG JPEG]''': File extension <code>.jpg</code> and <code>.jpeg</code>
* '''[http://en.wikipedia.org/wiki/Portable_Network_Graphics PNG]''': File extesion <code>.png</code>
* '''[http://en.wikipedia.org/wiki/JPEG_2000 JPEG 2000]''': File extesion <code>.jp2</code>
* '''[http://en.wikipedia.org/wiki/JBIG JBIG]''' and '''[http://en.wikipedia.org/wiki/JBIG2 JBIG2]''': File extension <code>.jbig</code>, <code>.jbib2</code>, and <code>.jb2</code>
=== 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 <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 removed). The result is cached, and the conversion is rerun only if the timestamp of the original file is newer than the converted file.
gm convert [inputfile] [outputfile]
=== Supported movie formats ===
The following movie formats are supported.
* '''[http://en.wikipedia.org/wiki/QuickTime QuickTime]''': File extension <code>.mov</code>.
* '''[https://en.wikipedia.org/wiki/Flash_Video Flash Video]''': File extension <code>.flv</code>
* '''[https://en.wikipedia.org/wiki/MPEG-4 MPEG 4]''': File extension <code>.mp4</code>
* '''buffer''': Typeset the buffer with the given name and include the result as a PDF file.
* '''tex''': Typeset the TeX file using <code>context</code> and include the result as a PDF file
* '''cld''':Typeset the [[CLD|ConTeXt Lua document]] using <code>context</code> and include the result as a PDF file.
== Command options ==
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 displayed. <context source="yes">% look for figure files in texmf tree\setupexternalfigures[location=default]
<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">% look for figure files in texmf tree\setupexternalfigures[location=default]
<context source="yes" mode=mkiv>
\externalfigure[hacker][height=3cm]
</context>
=== Include a remote image ===
<context source="yes" mode="mkiv">\externalfigure[http://placekitten.com.s3.amazonaws.com/homepage-samplesg/200/286300][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.jpgFor 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>
<context source=yes>
\externalfigure[cat.pdf]
</context>
== Tracking ==
The following trackers are available for {{cmd|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 > 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
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
<noinclude>
== See also ==
* {{cmd|defineexternalfigure}} to define a collection of settings
* {{cmd|setupexternalfigures}} to define a different collection of settings
* {{cmd|useexternalfigure}} to define an image+settings combination
* {{cmd|setupexternalfigures}} to define a different collection of settings[[Using Graphics]]
== Help from ConTeXt-Mailinglist/Forum ==
All issues with:
{{Forum|{{SUBPAGENAME}}}}
</noinclude>
[[Category:Command/FiguresImages|externalfigure]]
