Difference between revisions of "Command/externalfigure"

From Wiki
Jump to navigation Jump to search
m (Formatting)
m (Reordering and clarifying material)
Line 22: Line 22:
 
== Description ==  
 
== Description ==  
  
−
Command to include an external figure/movie inside ConTeXt. Includes both local
+
Command to include an external figure/movie inside ConTeXt. Includes both local files or remote files hosted on HTTP servers.  
−
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).
 +
* '''<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. (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:
 
The following image formats are supported natively in MkIV:
Line 33: Line 42:
 
* '''[http://en.wikipedia.org/wiki/JPEG_2000 JPEG 2000]''': File extesion <code>.jp2</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>
 
* '''[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.
 
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.
Line 65: Line 76:
  
 
     gm convert [inputfile] [outputfile]
 
     gm convert [inputfile] [outputfile]
 +
 +
=== Supported movie formats ===
 +
 +
{{note| Inclusion of movie formats is broken in MkIV }}
  
 
The following movie formats are supported.
 
The following movie formats are supported.
Line 70: Line 85:
 
* '''[http://en.wikipedia.org/wiki/QuickTime QuickTime]''': File extension <code>.mov</code>.  
 
* '''[http://en.wikipedia.org/wiki/QuickTime QuickTime]''': File extension <code>.mov</code>.  
  
−
: (Note: Check if this works?)
+
=== Support for special TeX formats ===
  
−
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 for remote images that do not have a file extension.
+
The following special formats are supported:
−
 
 
−
In addition, the following special formats are supported:
 
  
 
* '''buffer''': Typeset the buffer with the given name and include the result as a PDF file.
 
* '''buffer''': Typeset the buffer with the given name and include the result as a PDF file.
Line 81: Line 94:
  
 
* '''cld''': Typeset the [[CLD|ConTeXt Lua document]] 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.
−
 
−
 
−
'''Note''': The file extesions are case insensitive.
 
−
 
  
 
== Example ==
 
== Example ==
Line 90: Line 99:
 
=== Including a local image ===
 
=== 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.
+
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">
 
<context source="yes">
Line 99: Line 108:
 
</context>
 
</context>
  
−
ConTeXt distribution also includes a sample image `hacker.jpg`. To include it use:
+
ConTeXt distribution also includes a sample image <code>hacker.jpg</code>. To include it use:
  
 
<context source="yes">
 
<context source="yes">
Line 114: Line 123:
 
</context>
 
</context>
  
−
The above example does not work on the wiki due to security restrictions. It should run on the default ConTeXt installation.
+
The above example does not work on the wiki due to security restrictions. It runs on the default ConTeXt installation.
  
 
== See also ==
 
== See also ==
Line 126: Line 135:
  
 
[[Category:Command/FiguresImages|externalfigure]]
 
[[Category:Command/FiguresImages|externalfigure]]
 +
/code>. Converted to PDF on the fly using MPtoPDF.
 +
* '''[http://en.wikipedia.org/wiki/JPEG JPEG]''': File extension

Revision as of 23:02, 1 December 2012

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


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

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

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. 

% look for figure files in texmf tree
\setupexternalfigures[location=default]

\externalfigure[cow][width=4cm]

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

% look for figure files in texmf tree
\setupexternalfigures[location=default]

\externalfigure[hacker][height=3cm]

Include a remote image

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

The above example does not work on the wiki due to security restrictions. It runs on the default ConTeXt installation.

See also

Help from ConTeXt-Mailinglist/Forum

All issues with:

/code>. Converted to PDF on the fly using MPtoPDF.

  • JPEG: File extension
Retrieved from "https://wiki.contextgarden.net/index.php?title=Command/externalfigure&oldid=21281"