Difference between revisions of "Using Graphics"

From Wiki
Jump to navigation Jump to search
m
m (→‎Visualize Bounding Box: <pre> no longer processes tags ...)
(15 intermediate revisions by 4 users not shown)
Line 1: Line 1:
< [[Graphics]] | [[Combinations]] | [[File Formats|Supported Media File Formats]] | [[Including pages from PDF documents]] | [[Animation]] >
+
< [[Graphics]] | [[Combinations]] | [[File Formats|Supported Media File Formats]] | [[Including pages from PDF documents]] | [[Animation]] | [[Downsampling]] >
  
 
= Usage =
 
= Usage =
Line 58: Line 58:
 
<tr class="even">
 
<tr class="even">
 
<td align="left"><strong>GIF</strong></td>
 
<td align="left"><strong>GIF</strong></td>
<td align="left"><code>.git</code></td>
+
<td align="left"><code>.gif</code></td>
 
<td align="left"><code>gm</code> from GraphicsMagick</td>
 
<td align="left"><code>gm</code> from GraphicsMagick</td>
 
</tr>
 
</tr>
Line 69: Line 69:
  
 
The conversion generates a PDF file with prefix <tt>m_k_i_v_</tt> and a suffix <tt>.pdf</tt> added to the name of the original file. The result is cached, and the conversion is rerun if the timestamp of the original file is newer than that of the converted file.
 
The conversion generates a PDF file with prefix <tt>m_k_i_v_</tt> and a suffix <tt>.pdf</tt> added to the name of the original file. The result is cached, and the conversion is rerun if the timestamp of the original file is newer than that of the converted file.
 +
 +
It is possible to change the converter used with the following code:
 +
 +
<pre>
 +
\startluacode
 +
local function converter(oldname, newname, resolution)
 +
    if not resolution or resolution == "" then
 +
        resolution = 50
 +
    end
 +
    os.execute(string.format(
 +
        'convert -density %ix%i "%s" "%s"',
 +
        resolution, resolution, oldname, newname)
 +
    )
 +
end
 +
 +
-- Set the PDF and default TIFF converters to the above function.
 +
figures.converters.tif.pdf = converter
 +
figures.converters.tif.default = converter
 +
\stopluacode
 +
 +
\starttext
 +
  % Substitute any TIFF here.
 +
  \externalfigure[cow.tiff]
 +
\stoptext
 +
</pre>
 +
 +
See also: https://source.contextgarden.net/tex/context/base/mkiv/grph-inc.lua
 +
 +
== Interaction ==
 +
 +
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>
  
 
== Image Directory ==
 
== Image Directory ==
Line 76: Line 108:
 
To search for images in other directories, for example a <tt>./images</tt> subdirectory and <tt>/home/user/images</tt>, use:
 
To search for images in other directories, for example a <tt>./images</tt> subdirectory and <tt>/home/user/images</tt>, use:
  
<texcode>\setupexternalfigures
+
<texcode>\setupexternalfigures[directory={images, /home/user/images}]</texcode>
    [directory={images, /home/user/images}]</texcode>
 
  
 
Note: always use forward slashes (`/`) in path names, regardless of operating system.
 
Note: always use forward slashes (`/`) in path names, regardless of operating system.
Line 83: Line 114:
 
The default search order is: the current directory, the parent directory, the grand-parent directory, and then the paths specified by the <tt>directory</tt> key. To restrict image search only to the paths specified by the <tt>directory</tt> key, use:
 
The default search order is: the current directory, the parent directory, the grand-parent directory, and then the paths specified by the <tt>directory</tt> key. To restrict image search only to the paths specified by the <tt>directory</tt> key, use:
  
<texcode>\setupexternalfigures
+
<texcode>\setupexternalfigures[location=global]</texcode>
    [location=global]</texcode>
 
  
 
To restore the default search behavior, use:
 
To restore the default search behavior, use:
  
<texcode>\setupexternalfigures
+
<texcode>\setupexternalfigures[location={local,global}]</texcode>
    [location={local,global}]</texcode>
 
  
 
The ConTeXt distribution includes three sample images: <tt>cow.pdf</tt>, <tt>mill.png</tt>, and <tt>hacker.jpg</tt>, that are useful when creating minimum working examples to illustrate a bug on the mailing list. These images are locating in the <tt>TEXMF</tt> directory. To add the <tt>TEXMF</tt> directory to the image search path, use:
 
The ConTeXt distribution includes three sample images: <tt>cow.pdf</tt>, <tt>mill.png</tt>, and <tt>hacker.jpg</tt>, that are useful when creating minimum working examples to illustrate a bug on the mailing list. These images are locating in the <tt>TEXMF</tt> directory. To add the <tt>TEXMF</tt> directory to the image search path, use:
  
<texcode>\setupexternalfigures
+
<texcode>\setupexternalfigures[location={local,global,default}]</texcode>
    [location={local,global,default}]</texcode>
 
  
 
The above alternative adds the ''entire'' <tt>TEXMF</tt> directory to the search path, ''including the'' <tt>doc/</tt> ''directory!'' Therefore, one needs to be extremely careful when using this option. In fact, I would advise not using <tt>location=default</tt> except for illustrative minimal working examples.
 
The above alternative adds the ''entire'' <tt>TEXMF</tt> directory to the search path, ''including the'' <tt>doc/</tt> ''directory!'' Therefore, one needs to be extremely careful when using this option. In fact, I would advise not using <tt>location=default</tt> except for illustrative minimal working examples.
Line 102: Line 130:
 
The {{cmd|externalfigure}} command supports reading files from web servers, for example:
 
The {{cmd|externalfigure}} command supports reading files from web servers, for example:
  
<texcode>\externalfigure
+
<texcode>\externalfigure[http://tug.org/images/logobw.jpg]</texcode>
  [http://tug.org/images/logobw.jpg]</texcode>
 
 
When a document containing a remote file is compiled for the first time, the remote file is downloaded from the server and stored in the LuaTeX cache directory. This cached file is used during subsequent runs.
 
When a document containing a remote file is compiled for the first time, the remote file is downloaded from the server and stored in the LuaTeX cache directory. This cached file is used during subsequent runs.
  
Line 114: Line 141:
 
<pre>context --directives=schemes.threshold=120 <em>filename</em></pre>
 
<pre>context --directives=schemes.threshold=120 <em>filename</em></pre>
 
The variable <tt>schemes.threshold</tt> is global, so changing its value affects all other macros like <tt>\input</tt>, <tt>\usemodule</tt>, <tt>\component</tt>, etc. that load remote files.
 
The variable <tt>schemes.threshold</tt> is global, so changing its value affects all other macros like <tt>\input</tt>, <tt>\usemodule</tt>, <tt>\component</tt>, etc. that load remote files.
 +
 +
=== HTTP Proxy ===
 +
 +
To use an http proxy for fetching images, the http variable ([http://w3.impa.br/~diego/software/luasocket/http.html LuaSocket]) has to be set up as follows:
 +
 +
<texcode>
 +
\ctxlua{http = require("socket.http"); http.PROXY = "http://proxy.example.com:3128"}
 +
</texcode>
 +
 +
Replace `http://proxy.example.com:3128` with the proxy URL.
 +
 +
To disable the proxy again:
 +
 +
<texcode>
 +
\ctxlua{http = require("socket.http"); http.PROXY = nil}
 +
</texcode>
  
 
=== HTTPS ===
 
=== HTTPS ===
  
For self-signed certificates retrieved over HTTPS, the `curl` command requires a flag to retrieve insecure files, which is not enabled by default. Open `tex/texmf-context/tex/context/base/data-sch.lua` to find:
+
For self-signed certificates retrieved over HTTPS, the `curl` command requires a flag to retrieve insecure files, which is not enabled by default. Open `tex/texmf-context/tex/context/base/mkiv/data-sch.lua` to find:
  
 
<pre>
 
<pre>
Line 132: Line 175:
 
</pre>
 
</pre>
  
=== HTTP Proxy ===
+
== Inline Images ==
 
 
To use an http proxy for fetching images, the http variable ([http://w3.impa.br/~diego/software/luasocket/http.html LuaSocket]) has to be set up as follows:
 
 
 
<texcode>
 
\ctxlua{http = require("socket.http"); http.PROXY = "http://proxy.example.com:3128"}
 
</texcode>
 
 
 
Replace `http://proxy.example.com:3128` with the proxy URL.
 
  
To disable the proxy again:
+
Embedding inline images via base64 encoding using the memstream function (supports pdf and png streams):
  
 
<texcode>
 
<texcode>
\ctxlua{http = require("socket.http"); http.PROXY = nil}
+
\startluacode
 +
local cow = mime.unb64("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Y1NldFsvUERGXQovQ29sb3JTcGFjZSAxMCAwIFIKL0V4dEdTdGF0ZSAxMSAwIFIKPj4KL0NvbnRlbnRzIDUgMCBSCj4+CmVuZG9iagozIDAgb2JqCjw8IC9UeXBlIC9QYWdlcyAvS2lkcyBbCjQgMCBSCl0gL0NvdW50IDEKPj4KZW5kb2JqCjEgMCBvYmoKPDwvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMyAwIFIKPj4KZW5kb2JqCjcgMCBvYmoKPDwvVHlwZS9FeHRHU3RhdGUKL09QTSAxPj5lbmRvYmoKOSAwIG9iagpbL1NlcGFyYXRpb24KL0JsYWNrCi9EZXZpY2VDTVlLCjggMCBSXWVuZG9iagoxMCAwIG9iago8PC9SOQo5IDAgUj4+CmVuZG9iagoxMSAwIG9iago8PC9SNwo3IDAgUj4+CmVuZG9iago4IDAgb2JqCjw8L0ZpbHRlci9GbGF0ZURlY29kZQovRnVuY3Rpb25UeXBlIDQKL0RvbWFpblswCjFdCi9SYW5nZVswCjEKMAoxCjAKMQowCjFdL0xlbmd0aCAyOT4+c3RyZWFtCnicq04pLVAwUMgtzVFIrUjOUMDPNQQzawHfFRGFCmVuZHN0cmVhbQplbmRvYmoKMiAwIG9iago8PC9Qcm9kdWNlcihBRlBMIEdob3N0c2NyaXB0IDguNTIpCi9DcmVhdGlvbkRhdGUoRDoyMDA2MDUxNTEyMjA1OSkKL01vZERhdGUoRDoyMDA2MDUxNTEyMjA1OSkKL0NyZWF0b3IoQ29yZWxEUkFXISkKL1RpdGxlKENPVy5FUFMpPj5lbmRvYmoKeHJlZgowIDEyCjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwNDYzNiAwMDAwMCBuIAowMDAwMDA0OTg2IDAwMDAwIG4gCjAwMDAwMDQ1NzcgMDAwMDAgbiAKMDAwMDAwNDQyNiAwMDAwMCBuIAowMDAwMDAwMDE1IDAwMDAwIG4gCjAwMDAwMDQ0MDYgMDAwMDAgbiAKMDAwMDAwNDY4NCAwMDAwMCBuIAowMDAwMDA0ODM4IDAwMDAwIG4gCjAwMDAwMDQ3MjUgMDAwMDAgbiAKMDAwMDAwNDc3OCAwMDAwMCBuIAowMDAwMDA0ODA4IDAwMDAwIG4gCnRyYWlsZXIKPDwgL1NpemUgMTIgL1Jvb3QgMSAwIFIgL0luZm8gMiAwIFIKL0lEIFs8ODE0NjQ5NTc3Qzg3MTE1QzRDQzBDQjg0QkU3RTQ1MEY+PDgxNDY0OTU3N0M4NzExNUM0Q0MwQ0I4NEJFN0U0NTBGPl0KPj4Kc3RhcnR4cmVmCjUxMzMKJSVFT0YK")
 +
figures.setmemstream("inline",cow)
 +
context.externalfigure({"memstream:///inline"})
 +
\stopluacode
 
</texcode>
 
</texcode>
  
Line 166: Line 205:
 
<texcode>\externalfigure[logo.pdf][xscale=500]
 
<texcode>\externalfigure[logo.pdf][xscale=500]
 
\externalfigure[logo.pdf][yscale=500]</texcode>
 
\externalfigure[logo.pdf][yscale=500]</texcode>
 +
 +
Scaling changes the visible size of a picture, but not the data or file size. If you want to reduce your file size by decreasing image resolution, see [[Downsampling]].
  
 
== Image Dimension Restriction ==
 
== Image Dimension Restriction ==
Line 214: Line 255:
 
<texcode>\clip[nx=3,ny=3,x=2,y=2]
 
<texcode>\clip[nx=3,ny=3,x=2,y=2]
 
     {\externalfigure[logo.pdf]}</texcode>
 
     {\externalfigure[logo.pdf]}</texcode>
 +
 +
 +
In PDF files, it is possible to specify different size information in PDF headers MediaBox, TrimBox, CropBox, and ArtBox. To clip to one of these sizes, use
 +
 +
<texcode>\externalfigure[logo.pdf][size=art]</texcode>
 +
 +
Other options are: `none` (detault), `media` for MediaBox, `crop` for CropBox, `trim` for TrimBox, and `art` for ArtBox.
  
 
= Troubleshooting =
 
= Troubleshooting =
Line 227: Line 275:
 
ConTeXt includes a Perl script <tt>pdftrimwhite</tt> that removes extra white space at the borders of a PDF file. To run this script:
 
ConTeXt includes a Perl script <tt>pdftrimwhite</tt> that removes extra white space at the borders of a PDF file. To run this script:
  
<pre>mtxrun --script pdftrimwhite <em>[flags] input output</em></pre>
+
<pre>mtxrun --script pdftrimwhite [flags] input output</pre>
  
 
The most important flag is <tt>--offset=dimen</tt>, which keeps some extra space around the trimmed image.
 
The most important flag is <tt>--offset=dimen</tt>, which keeps some extra space around the trimmed image.
Line 308: Line 356:
 
<texcode>\externalfigure[mylogo]</texcode>
 
<texcode>\externalfigure[mylogo]</texcode>
  
= Pictures in Text =
 
 
You can directly place a figure in a text using <tt>\externalfigure[cow]</tt>. If you want to align it not to the baseline, but lower you can try whether <tt>\bbox{\externalfigure[cow]}</tt> does the right thing, otherwise you have to tweek <tt>\smash{\lower24pt\hbox{\externalfigure[cow]}}</tt>
 
 
= Pictures and Flowing Text =
 
 
<context source=yes>
 
\setuppapersize[A5]
 
\setupexternalfigures[location={local,default}]
 
\starthanging{\externalfigure[cow][width=4cm]}
 
\input tufte
 
\stophanging
 
</context>
 
 
{{cmd|starthanging}} is influenced by {{cmd|setuphanging}}, but doesn’t take parameters itself.
 
It’s currently broken in MkII (here in the garden), but works with MkIV.
 
 
If you want to have the image to the right, you can do:
 
 
<texcode>
 
\setuppapersize[A5]
 
\setupexternalfigures[location={local,default}]
 
\setuphanging[location=right]
 
\starthanging{\externalfigure[cow][width=4cm]}
 
    \input tufte
 
\stophanging
 
</texcode>
 
 
There are more options (distance can even be negative):
 
 
<texcode>
 
\setuppapersize[A5]
 
\setupexternalfigures[location={local,default}]
 
\setuphanging[location=right,n=2,distance=1cm]
 
\starthanging{\externalfigure[cow][width=4cm]}
 
    \input tufte
 
\stophanging
 
</texcode>
 
 
Parameter <tt>n</tt> defines how many lines should flow around, useful for pictures with whitespace below.
 
 
This replaces undocumented {{cmd|starthangaround}} command that might exist [http://source.contextgarden.net/tex/context/base/cont-new.mkiv?search=hangaround in the source], if the wiki isn’t updated yet.
 
 
You might also want to look into [[Combinations]].
 
 
= Pictures and Hyperlinks =
 
 
This example makes a picture interactive; when clicked, it opens a browser to the given URL:
 
 
<texcode>
 
\setupinteraction[state=start]
 
 
\starttext
 
This is a cow: \goto{\externalfigure[cow][height=2ex]}[url(http://en.wikipedia.org/wiki/Cow)]
 
\stoptext
 
</texcode>
 
  
= Pictures as [[Floating Objects]] =
+
= [[Floating Objects]] =
  
 
Floats are numbered and placed by ConTeXt, with a configurable (and optional) caption.
 
Floats are numbered and placed by ConTeXt, with a configurable (and optional) caption.
Line 381: Line 373:
  
 
You find more about floats ([[Floating Objects]]) in the manual.
 
You find more about floats ([[Floating Objects]]) in the manual.
 
= Floating graphics with an enlarged, shaded background =
 
 
To place a figure in, say, the right margin with a shaded background that is slightly larger than the figure (to give a bit of breathing room):
 
 
<texcode>
 
\setupcolors[state=start]
 
\placefigure[right,high,none]{}{\framed[frame=on, offset=10pt, framecolor=lightgray,
 
    background=color, backgroundcolor=lightgray]%
 
  {\externalfigure[sample/cow.pdf][scale=500]}}
 
\input knuth
 
</texcode>
 
 
 
= Movies =
 
= Movies =
  
Line 419: Line 398:
 
FILE=$(basename "$0"); mplayer -fs -zoom ${FILE/.sh/}
 
FILE=$(basename "$0"); mplayer -fs -zoom ${FILE/.sh/}
 
</nowiki></pre>
 
</nowiki></pre>
 
== Full Page Image ==
 
 
* See [[Simple Cover Page]]
 
  
 
= See Also =
 
= See Also =
Line 431: Line 406:
  
 
[[Category:Graphics]]
 
[[Category:Graphics]]
 +
 +
 +
{{Getting started navbox}}

Revision as of 04:10, 1 June 2020

< Graphics | Combinations | Supported Media File Formats | Including pages from PDF documents | Animation | Downsampling >

Usage

The simplest way to insert an image is to use:

\externalfigure[logo.pdf]

This command places the PDF image logo.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[logo.pdf][width=1cm]

Similarly, to set the height of the image to a specific size, say 2cm, use:

\externalfigure[logo.pdf][height=2cm]

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[logo.pdf][page=5]

These four variations cover the most common use cases.

File Formats

ConTeXt supports the image formats enumerated below. The image format is determined from the file extension (case insensitive).

  • PDF: File extension .pdf
  • MPS (MetaPost output): File extension .mps or .<digits>
  • JPEG: File extension .jpg or .jpeg
  • PNG: File extension .png
  • JPEG 2000: File extension .jp2
  • JBIG or JBIG2: File extension .jbig, .jbig2, or .jb2

Image Conversion

The image file formats listed in the previous section are the ones that may be embedded directly in a PDF. ConTeXt also supports a few other formats that are first converted to PDF using an external program. Of course, for such a conversion to work, the corresponding converter must be in the PATH.

Format Extension Converter
SVG .svg, .svgz inkscape
EPS .eps, .ai gs (or gswin32c on Windows) from Ghostscript
GIF .gif gm from GraphicsMagick
TIFF .tiff gm from GraphicsMagick

The conversion generates a PDF file with prefix m_k_i_v_ and a suffix .pdf added to the name of the original file. The result is cached, and the conversion is rerun if the timestamp of the original file is newer than that of the converted file.

It is possible to change the converter used with the following code:

\startluacode
local function converter(oldname, newname, resolution)
    if not resolution or resolution == "" then
        resolution = 50
    end
    os.execute(string.format(
        'convert -density %ix%i "%s" "%s"',
        resolution, resolution, oldname, newname)
    )
end

-- Set the PDF and default TIFF converters to the above function.
figures.converters.tif.pdf = converter
figures.converters.tif.default = converter
\stopluacode

\starttext
  % Substitute any TIFF here.
  \externalfigure[cow.tiff]
\stoptext

See also: https://source.contextgarden.net/tex/context/base/mkiv/grph-inc.lua

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]

Image Directory

By default, ConTeXt searches an image in the current directory, the parent directory, and the grand-parent directory.

To search for images in other directories, for example a ./images subdirectory and /home/user/images, use:

\setupexternalfigures[directory={images, /home/user/images}]

Note: always use forward slashes (/) in path names, regardless of operating system.

The default search order is: the current directory, the parent directory, the grand-parent directory, and then the paths specified by the directory key. To restrict image search only to the paths specified by the directory key, use:

\setupexternalfigures[location=global]

To restore the default search behavior, use:

\setupexternalfigures[location={local,global}]

The ConTeXt distribution includes three sample images: cow.pdf, mill.png, and hacker.jpg, that are useful when creating minimum working examples to illustrate a bug on the mailing list. These images are locating in the TEXMF directory. To add the TEXMF directory to the image search path, use:

\setupexternalfigures[location={local,global,default}]

The above alternative adds the entire TEXMF directory to the search path, including the doc/ directory! Therefore, one needs to be extremely careful when using this option. In fact, I would advise not using location=default except for illustrative minimal working examples.

Remote Images

The \externalfigure command supports reading files from web servers, for example:

\externalfigure[http://tug.org/images/logobw.jpg]

When a document containing a remote file is compiled for the first time, the remote file is downloaded from the server and stored in the LuaTeX cache directory. This cached file is used during subsequent runs.

Normally, the remote image is downloaded again if the image in the cache is older than 1~day. To change this threshold to, for example, 2minutes (120seconds), either add

\enabledirectives[schemes.threshold=120]

in the ConTeXt file, or compile the ConTeXt file using the command

context --directives=schemes.threshold=120 <em>filename</em>

The variable schemes.threshold is global, so changing its value affects all other macros like \input, \usemodule, \component, etc. that load remote files.

HTTP Proxy

To use an http proxy for fetching images, the http variable (LuaSocket) has to be set up as follows:

\ctxlua{http = require("socket.http"); http.PROXY = "http://proxy.example.com:3128"}

Replace http://proxy.example.com:3128 with the proxy URL.

To disable the proxy again:

\ctxlua{http = require("socket.http"); http.PROXY = nil}

HTTPS

For self-signed certificates retrieved over HTTPS, the curl command requires a flag to retrieve insecure files, which is not enabled by default. Open tex/texmf-context/tex/context/base/mkiv/data-sch.lua to find:

local function runcurl(name,cachename) -- we use sockets instead or the curl library when possible
    local command = "curl --silent --create-dirs --output " .. cachename .. " " .. name
    os.spawn(command)
end

Insert the -k or --insecure option:

    local command = "curl --insecure --silent --create-dirs --output " .. cachename .. " " .. name

Inline Images

Embedding inline images via base64 encoding using the memstream function (supports pdf and png streams):

\startluacode
local cow = mime.unb64("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Y1NldFsvUERGXQovQ29sb3JTcGFjZSAxMCAwIFIKL0V4dEdTdGF0ZSAxMSAwIFIKPj4KL0NvbnRlbnRzIDUgMCBSCj4+CmVuZG9iagozIDAgb2JqCjw8IC9UeXBlIC9QYWdlcyAvS2lkcyBbCjQgMCBSCl0gL0NvdW50IDEKPj4KZW5kb2JqCjEgMCBvYmoKPDwvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMyAwIFIKPj4KZW5kb2JqCjcgMCBvYmoKPDwvVHlwZS9FeHRHU3RhdGUKL09QTSAxPj5lbmRvYmoKOSAwIG9iagpbL1NlcGFyYXRpb24KL0JsYWNrCi9EZXZpY2VDTVlLCjggMCBSXWVuZG9iagoxMCAwIG9iago8PC9SOQo5IDAgUj4+CmVuZG9iagoxMSAwIG9iago8PC9SNwo3IDAgUj4+CmVuZG9iago4IDAgb2JqCjw8L0ZpbHRlci9GbGF0ZURlY29kZQovRnVuY3Rpb25UeXBlIDQKL0RvbWFpblswCjFdCi9SYW5nZVswCjEKMAoxCjAKMQowCjFdL0xlbmd0aCAyOT4+c3RyZWFtCnicq04pLVAwUMgtzVFIrUjOUMDPNQQzawHfFRGFCmVuZHN0cmVhbQplbmRvYmoKMiAwIG9iago8PC9Qcm9kdWNlcihBRlBMIEdob3N0c2NyaXB0IDguNTIpCi9DcmVhdGlvbkRhdGUoRDoyMDA2MDUxNTEyMjA1OSkKL01vZERhdGUoRDoyMDA2MDUxNTEyMjA1OSkKL0NyZWF0b3IoQ29yZWxEUkFXISkKL1RpdGxlKENPVy5FUFMpPj5lbmRvYmoKeHJlZgowIDEyCjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwNDYzNiAwMDAwMCBuIAowMDAwMDA0OTg2IDAwMDAwIG4gCjAwMDAwMDQ1NzcgMDAwMDAgbiAKMDAwMDAwNDQyNiAwMDAwMCBuIAowMDAwMDAwMDE1IDAwMDAwIG4gCjAwMDAwMDQ0MDYgMDAwMDAgbiAKMDAwMDAwNDY4NCAwMDAwMCBuIAowMDAwMDA0ODM4IDAwMDAwIG4gCjAwMDAwMDQ3MjUgMDAwMDAgbiAKMDAwMDAwNDc3OCAwMDAwMCBuIAowMDAwMDA0ODA4IDAwMDAwIG4gCnRyYWlsZXIKPDwgL1NpemUgMTIgL1Jvb3QgMSAwIFIgL0luZm8gMiAwIFIKL0lEIFs8ODE0NjQ5NTc3Qzg3MTE1QzRDQzBDQjg0QkU3RTQ1MEY+PDgxNDY0OTU3N0M4NzExNUM0Q0MwQ0I4NEJFN0U0NTBGPl0KPj4Kc3RhcnR4cmVmCjUxMzMKJSVFT0YK")
figures.setmemstream("inline",cow)
context.externalfigure({"memstream:///inline"})
\stopluacode

Transformations

Image Scaling

To scale an image use the scale key: scale=1000 corresponds to the original dimensions of the image, scale=500 scales the image to 50% of the original size, scale=1500 scales the images to 150% of the original size, and so on. For example:

\externalfigure[logo.pdf][scale=500]

Use \setupexternalfigures to set the scale of all images. For example, to scale all images to be twice their original size, use:

\setupexternalfigures[scale=2000]

If either width or height is specified, then the scale key has no effect.

In addition, the xscale and yscale keys scale the image in only one dimension. For example:

\externalfigure[logo.pdf][xscale=500]
\externalfigure[logo.pdf][yscale=500]

Scaling changes the visible size of a picture, but not the data or file size. If you want to reduce your file size by decreasing image resolution, see Downsampling.

Image Dimension Restriction

ConTeXt can limit included images to particular dimensions. For example, to ensure that an included image is not more than 0.2\textwidth:

\externalfigure[logo.pdf][maxwidth=0.2\textwidth]

If maxwidth is specified and the width of the image is less than maxwidth, then the image is not scaled; if the width of the image is greater than maxwidth, then the width is restricted to maxwidth and the height is scaled appropriately to maintain the original aspect ratio.

The option maxheight is analogous to maxwidth, for checking the height of the image.

For example, to ensure that figures do not overflow the text~area, one may set:

\setupexternalfigures
    [maxwidth=\textwidth,
     maxheight=0.8\textheight]

Image Rotation

Rotate included images by 90°, 180°, or 270° using the orientation key. For example:

\externalfigure[logo.pdf][orientation=90]

To rotate by an arbitrary angle, use the \rotate command. For example:

\rotate[rotation=45]{\externalfigure[logo.pdf]}

Image Mirroring

To mirror (flip) an image, use the generic \mirror command. For example, to mirror horizontally:

\mirror{\externalfigure[logo.pdf]}

To mirror vertically, first rotate the image by 180° and then mirror it:

\mirror{\externalfigure[logo.pdf][orientation=180]}

Image Clipping

Clip an image using the generic \clip command. For example, to clip the original image to a 1cm x 2cm rectangle at an offset of (3mm,5mm) from the top left corner:

\clip[width=1cm, height=2cm, hoffset=3mm, voffset=5mm]
     {\externalfigure[logo.pdf]}

As another example, this cuts the image into a 3x3 pieces and then outputs the (2,2) piece:

\clip[nx=3,ny=3,x=2,y=2]
     {\externalfigure[logo.pdf]}


In PDF files, it is possible to specify different size information in PDF headers MediaBox, TrimBox, CropBox, and ArtBox. To clip to one of these sizes, use

\externalfigure[logo.pdf][size=art]

Other options are: none (detault), media for MediaBox, crop for CropBox, trim for TrimBox, and art for ArtBox.

Troubleshooting

This section describes various tips for discovering problems with embedded images.

Visualize Bounding Box

If, for instance, the image is taking more space than expected, it can be useful to visualize the bounding box of the image. To do this:

\externalfigure[logo.pdf][frame=on]

ConTeXt includes a Perl script pdftrimwhite that removes extra white space at the borders of a PDF file. To run this script:

mtxrun --script pdftrimwhite [flags] input output

The most important flag is --offset=dimen, which keeps some extra space around the trimmed image.

Similar functionality is provided by another Perl script, pdfcrop, that is included in most TeX distributions.

Diagnostic Tracking

To get diagnostic information about image inclusion, enable the tracker graphics.locating by editing the ConTeXt file and adding:

\enabletrackers[graphics.locating]

Alternatively, compile the ConTeXt file using:

context --trackers=graphics.locating filename

The tracker writes diagnostics to the console. Suppose we use \externalfigure[somefile.pdf] and ConTeXt finds the file in the current search path; then the following information is printed on the console:

graphics > inclusion > locations: local,global
graphics > inclusion > path list: . .. ../..
graphics > inclusion > strategy: forced format pdf
graphics > inclusion > found: somefile.pdf -> somefile.pdf
graphics > inclusion > format natively supported by backend: pdf

If the file somefile.pdf is not found in the current search path, then the following information is printed on the console (even if the graphics.locating tracker is not set):

graphics > inclusion > strategy: forced format pdf
graphics > inclusion > not found: somefile.pdf
graphics > inclusion > not found: ./somefile.pdf
graphics > inclusion > not found: ../somefile.pdf
graphics > inclusion > not found: ../../somefile.pdf
graphics > inclusion > not found: images/somefile.pdf
graphics > inclusion > not found: /home/user/images/somefile.pdf
graphics > inclusion > format not supported: 

and a placeholder gray box is put in the output:

Sometimes, one would rather use a placeholder image for an image that is yet to be made. In such cases, load the MP library dum via:

\useMPlibrary[dum]

Then, whenever an image file is not found in the current search path, a random MetaPost image is shown in the output.

Leading Paragraph

Using \externalfigure[...] at the beginning of a paragraph results in a line break after the image. This is because \externalfigure is a \vbox and when a \vbox is encountered at (what appears to be) the beginning of a paragraph, it remains in vertical mode. To prevent this, add \dontleavehmode before \externalfigure, like this:

\dontleavehmode
\externalfigure[...] ... first line ...

Multiple Image Settings

Image Settings

Suppose your document contains many side-by-side images, and you want all of these images to be of the same size. In addition, you want to control the size of all images by changing only one setup. To do this, you can use the \defineexternalfigure macro, which defines a named collection of image settings. For example, to define a collection where the image width is 3cm, use:

\defineexternalfigure[logo-settings]
                     [width=3cm]

And then to use these settings in an image, use:

\externalfigure[group.pdf][logo-settings]

or, if you want to add or override settings, use:

\externalfigure[group.pdf][logo-settings]
               [height=2cm]

Image Labels

Suppose your document contains an image at multiple locations; all of these images are to be of the same size, which is not necessarily the same as the natural size of the image. Furthermore, as before, you want to set the size of all the images by changing only one setup. Here, the macro to use is \useexternalfigure, which defines a symbolic label for inserting an image plus settings. For example:

\useexternalfigure[mylogo]
                  [logo.pdf][width=2cm]

defines an image label mylogo that maps to the image file logo.pdf and sets its width to 2cm. This image label may be used as a normal image filename:

\externalfigure[mylogo]


Floating Objects

Floats are numbered and placed by ConTeXt, with a configurable (and optional) caption.

\placefigure[place]{My Caption}{\externalfigure[myone]}

place is one of: left, right, here, top, bottom, inleft, inright, inmargin, margin, page, opposite, always, force, tall

You get no caption with none. You get a table of figures with \showexternalfigures[alternative=a]. Alternatives (styles) a, b and c are predefined.

The second brackets of \placefigure can contain any command, e.g. \getbuffer.

You find more about floats (Floating Objects) in the manual.

Movies

Movies aren't recognized automatically yet; they must be delcared verbosely:

\externalfigure[demo.mov][label=demo,width=4cm,height=4cm,preview=yes]

preview=yes shows the first image as preview. You find more about interactive Elements in mwidget-s.pdf

Unfortunately, people who are fond of Linux cannot embed movies because the linux release of acroread doesn't support that. An alternative solution consists in launching your prefered player (MPlayer) from acroread:

\defineprogram[dummy.mpeg][dummy.mpeg.sh]

\starttext
\goto{\externalfigure[dummy-preview][width=0.48\textwidth]}[program(dummy.mpeg{})]
\stoptext

The script dummy.mpeg.sh should contain:

FILE=$(basename "$0"); mplayer -fs -zoom ${FILE/.sh/}

See Also


Template:Getting started navbox