Difference between revisions of "Command/externalfigure"
m (Text replace - "Reference/en|" to "Commands|") |
m (Add \definegraphictypesynonym to 'See also') |
||
(47 intermediate revisions by 9 users not shown) | |||
Line 1: | Line 1: | ||
+ | <noinclude> | ||
+ | |||
{{Reference | {{Reference | ||
|name=externalfigure | |name=externalfigure | ||
Line 4: | Line 6: | ||
}} | }} | ||
− | == [[Help:Reference|Syntax]] == | + | == [[Help:Reference|Syntax]] (autogenerated) == |
− | < | + | <syntax>externalfigure</syntax> |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | </ | ||
+ | </noinclude> | ||
== Description == | == Description == | ||
− | < | + | 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> | <texcode> | ||
− | \externalfigure[ | + | \externalfigure[filename.pdf][page=5] |
</texcode> | </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 === | ||
+ | |||
+ | The following image formats are supported natively in MkIV: | ||
+ | |||
+ | * '''[http://en.wikipedia.org/wiki/Portable_Document_Format PDF]''': File extension <code>.pdf</code>. By default, ''mediabox'' is used to determine size. Use <code>size=artbox</code> to use ''artbox''. | ||
+ | * '''MPS (MetaPost Output)''': File extension <code>.mp</code>, <code>.mps</code> or <code>.[digits]</code>. | ||
+ | <!-- Converted to PDF on the fly using MPtoPDF. --> | ||
+ | * '''[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> | ||
+ | |||
+ | Additionally supported natively in LMTX: | ||
+ | |||
+ | * '''[http://en.wikipedia.org/wiki/Scalable_Vector_Graphics SVG]''': File extension <code>.svg</code> and <code>.svgz</code> via an internal Metapost conversion; use <code>conversion=mp</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 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. | ||
+ | |||
+ | |||
+ | * '''[http://en.wikipedia.org/wiki/Scalable_Vector_Graphics SVG]''': File extension <code>.svg</code> and <code>.svgz</code>. Converted to PDF using [http://en.wikipedia.org/wiki/Inkscape Inkscape]. | ||
+ | |||
+ | : For the conversion to work, <code>inkscape</code> should be in the <code>PATH</code>. 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)). | ||
+ | |||
+ | * '''[http://en.wikipedia.org/wiki/PostScript PS]''' and '''[http://en.wikipedia.org/wiki/Encapsulated_PostScript EPS]''': File extension <code>.eps</code> and <code>.ai</code>. Converted to PDF using [http://en.wikipedia.org/wiki/Ghostscript Ghostscript]. | ||
+ | |||
+ | |||
+ | : For the conversion to work, on Windows <code>gswin32c</code> must be in the <code>PATH</code>; on other platforms <code>gs</code> must be in the <code>PATH</code>. 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 <code>[resolution]</code> is ''prepress''. Use <code>resolution=low</code> to change the <code>[resolution]</code> to ''screen'' and <code>resolution=meidum</code> to change the <code>[resolution]</code> to ''ebook''. | ||
+ | |||
+ | * '''[http://en.wikipedia.org/wiki/GIF GIF]''': File extension <code>.gif</code>. Converted to PDF using [http://en.wikipedia.org/wiki/GraphicsMagick GraphicsMagick]. | ||
+ | |||
+ | : For the conversion to work, <code>gm</code> should be in the <code>PATH</code>. The following command is used for the conversion: | ||
+ | |||
+ | gm convert [inputfile] [outputfile] | ||
+ | |||
+ | * '''[http://en.wikipedia.org/wiki/Tagged_Image_File_Format TIFF]''': File extensions <code>.tiff</code> and <code>.tif</code>. Converted to PDF using [http://en.wikipedia.org/wiki/GraphicsMagick GraphicsMagick]. | ||
+ | |||
+ | : For the conversion to work, <code>gm</code> should be in the <code>PATH</code>. The following command is used for the conversion: | ||
+ | |||
+ | 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> | ||
+ | |||
+ | {{ note| Movie inclusion only works in a few PDF viewers }} | ||
+ | |||
+ | === 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 <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 == | ||
+ | |||
+ | === <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 == | == 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" 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 == | ||
+ | |||
+ | 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 <code>cat.pdf</code> should '''not''' exist in the current directory) | ||
+ | |||
+ | <context source=yes> | ||
+ | \externalfigure[cat.pdf] | ||
+ | </context> | ||
+ | |||
+ | == Tracking == | ||
+ | |||
+ | The following trackers are available for {{cmd|externalfigure}} (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 the '''graphics.locating''' tracker is enabled, including a known file displays 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 requested 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 the '''graphics.conversion''' tracker is enabled and a file type that requires conversion (e.g., PS) is included, the following message is displayed 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 the '''graphics.inclusion''' tracker is enabled and a movie is included, the following message is displayed on the terminal: | ||
+ | |||
+ | graphics > inclusion > including movie 'clip.mov': width 5594039.4330709, height 5594039.4330709 | ||
+ | |||
+ | |||
+ | <noinclude> | ||
== See also == | == See also == | ||
− | + | * {{cmd|defineexternalfigure}} to define a collection of settings | |
+ | * {{cmd|setupexternalfigure}} to define a different collection of settings | ||
+ | * {{cmd|useexternalfigure}} to define an image+settings combination | ||
+ | * {{cmd|definegraphictypesynonym}} to map a file extension to a particular image type handler | ||
+ | * [[Using Graphics]] | ||
+ | * [[Multimedia Inclusion]] to add audio and video contents. | ||
+ | |||
+ | == Help from ConTeXt-Mailinglist/Forum == | ||
+ | All issues with: | ||
+ | {{Forum|{{SUBPAGENAME}}}} | ||
+ | </noinclude> | ||
− | [[Category: | + | [[Category:Command/FiguresImages|externalfigure]] |
Latest revision as of 20:50, 5 March 2024
\externalfigure
Syntax (autogenerated)
\externalfigure[...][...][...=...,...] | |
[...] | file |
[...] | name |
...=...,... | inherits from \setupexternalfigure |
Description
The \externalfigure
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:
\externalfigure[cow.pdf]
This command places the PDF image cow.pdf
in a
\vbox
; 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 1cm
, use:
\externalfigure[cow.pdf][width=1cm]
which gives
Similarly, to set the height of the image to a specific size, say 2cm
, use:
\externalfigure[cow.pdf][height=2cm]
which gives
If only the width
or height
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:
\externalfigure[filename.pdf][page=5]
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).
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.
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
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
.mp
,.mps
or.[digits]
. - JPEG: File extension
.jpg
and.jpeg
- PNG: File extesion
.png
- JPEG 2000: File extesion
.jp2
- JBIG and JBIG2: File extension
.jbig
,.jbib2
, and.jb2
Additionally supported natively in LMTX:
- SVG: File extension
.svg
and.svgz
via an internal Metapost conversion; useconversion=mp
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 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.
- 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
The following movie formats are supported.
- QuickTime: File extension
.mov
. - Flash Video: File extension
.flv
- MPEG 4: File extension
.mp4
NOTE: Movie inclusion only works in a few PDF viewers |
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.
Command options
interaction
By default, the interactive elements of the included PDF file are discarded. To enable the interactive elements of the included PDF file, use
\externalfigure[filename.pdf][interaction=yes]
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]}
Flip an image
Use \mirror to horizontally flip an image
\mirror{\externalfigure[cow][width=3cm]}
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 \externalfigure (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 the graphics.locating tracker is enabled, including a known file displays 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 requested 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 the graphics.conversion tracker is enabled and a file type that requires conversion (e.g., PS) is included, the following message is displayed 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 the graphics.inclusion tracker is enabled and a movie is included, the following message is displayed on the terminal:
graphics > inclusion > including movie 'clip.mov': width 5594039.4330709, height 5594039.4330709
See also
- \defineexternalfigure to define a collection of settings
- \setupexternalfigure to define a different collection of settings
- \useexternalfigure to define an image+settings combination
- \definegraphictypesynonym to map a file extension to a particular image type handler
- Using Graphics
- Multimedia Inclusion to add audio and video contents.
Help from ConTeXt-Mailinglist/Forum
All issues with: