869
edits
Changes
Jump to navigation
Jump to search
m
These four variations cover 90% of the use cases.
The conversion generates a PDF file with prefix <tt>m_k_i_v_<See also: https://tt> and a suffix <tt>source.contextgarden.pdf<net/tex/context/base/mkiv/tt> added to grph-inc.lua == Interaction == By default, the name interactive elements of the original included PDF fileare discarded. The result is cached, and the conversion is rerun if To enable the timestamp interactive elements of the original file is newer than that of the converted included PDF file, use<texcode>\externalfigure[filename.pdf][interaction=yes]</texcode>
<texcode>\setupexternalfigures [directory={images, /home/user/images}]</texcode>Note that one should : always use forward slashes (`/`) in path names, ''even on Windows''regardless of operating system.
Like all other ConTeXt macros that read files, <tt>\The {{cmd|externalfigure</tt> also }} command supports reading remote files from '''HTTP(S)''' web servers. An , for example:
== Specifying maximum size of an image ==
OftentimesScaling changes the visible size of a picture, we don't but not the data or file size. If you want the to reduce your file size by decreasing image resolution, see [[Downsampling]]. == Image Dimension Restriction == ConTeXt can limit included image images to be greater than a particular sizedimensions. For example, to ensure that an included image is not more than <tt>0.2\textwidth</tt>:
== Rotating images ==
To rotate the == Image Rotation == Rotate included image images by 9090°, 180180°, or 270 degrees, use 270° using the <tt>orientation</tt> key. For example:
== Mirroring images ==
== Clipping images ==
To clip == Image Clipping == Clip an image, use using the generic <tt>\{{cmd|clip</tt> }} command. For example, to clip the original image to a <tt>1cm x 2cm</tt> rectangle at an offset of <tt>(3mm,5mm)</tt> from the top left corner:
in the ConTeXt fileAlternatively, or by compiling compile the ConTeXt file using the command:
= Settings for multiple images =
== Labeled images ==
------------------------------------------- == Direct use of an image == This way you can use your image <tt>mypic.pdf</tt> :<texcode>\externalfigure[mypic]</texcode> Additional parameters:<texcode>\externalfigure[file or reference name][key=value, key=value, ...]</texcode> * scale = ''scaling value''* factor = max, fit, broad* wfactor, hfactor = max, fit, broad, ''value''* width, height = ''dimension''* frame = on, off* preset, preview, repeat, object = yes, no* display = ''file name''* type, method = eps, mps, pdf, tif, png, jpg, mov, tex If only one dimension is given, scaling is proportional. == Where ConTeXt finds your picture files == ConTeXt looks in the current and parent directory plus those given in <tt>texmf.cnf</tt>. You can define your own image directory with:<texcode>\setupexternalfigures[directory={../pictures}]</texcode>or even for multiple directories:<texcode>\setupexternalfigures[directory={../drawings,../bitmaps}]</texcode>You can define the path relative or absolute, but use always forward slashes! == Referenced Pictures == Declaration of all used pictures in your environment, project or header file is better than direct use of file names in your code. <texcode>\useexternalfigure[reference name][file name][options]</texcode> Same options as above. You can even inherit them like this: <texcode>\useexternalfigure[dummy][nofile][width=\textwidth]\useexternalfigure[myone][my_pic_one][dummy]\useexternalfigure[mytwo][my_pic_two][dummy] Somewhere in your text there's \externalfigure[myone].</texcode> == Place picture in the 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> == Flow text around a picture == That's an undocumented feature Hans told us about in a [http://archive.contextgarden.net/message/20080624.074046.56e76622.en.html mail from 2008-06-24]. It's [http://source.contextgarden.net/tex/context/base/cont-new.tex?search=hangaround in the source]. <context source=yes>\setuppapersize[A5]\setupexternalfigures[location={local,default}]\starthangaround{\externalfigure[cow][width=4cm]}\input tufte\stophangaround</context> {{cmd|starthangaround}} is influenced by {{cmd|setuphanging}}[distance=...]</cmd> (distance may even be negative!), but takes no parameters itself. Update, December 11, 2012:Now there are options for {{cmd|starthangaround}}. If you want to have the image to the right, you can do:<texcode>\setuppapersize[A5]\starttext\starthanging[right]{\externalfigure[cow][width=4cm]} \input tufte\stophanging\stoptext</texcode> There are even more options:<texcode>\setuppapersize[A5]\starttext\starthanging[location=right,n=2,distance=1cm]{\externalfigure[cow][width=4cm]} \input tufte\stophanging\stoptext</texcode> == Pictures as [[Floating Objects]] == Floats are numbered and placed by ConTeXt, with a configurable (and they can get a optional) caption.
== 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)Movies aren't recognized automatically yet; they must be delcared verbosely:
== Movies ==
Movies aren't recognized automatically yet, you need a more verbose declaration:
<texcode>
\externalfigure[demo.mov][label=demo,width=4cm,height=4cm,preview=yes]
</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>
== See also ==
→Visualize Bounding Box: <pre> no longer processes tags ...
< [[Graphics]] | [[Combinations]] | [[File Formats|Supported Media File Formats]] | [[Including pages from PDF documents]] | [[Animation]] | [[Downsampling]] >
= Basic usage Usage =
The simplest way to insert an image is to use:
<texcode>\externalfigure[logo.pdf]</texcode>
This command places the PDF image <tt>logo.pdf</tt> in a <tt>\{{cmd|vbox</tt>}}; 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 <tt>1cm</tt>, use:
<texcode>\externalfigure[logo.pdf][width=1cm]</texcode>
Similarly, to set the height of the image to a specific size, say <tt>2cm</tt>, use:
<texcode>\externalfigure[logo.pdf][height=2cm]</texcode>
If only the <tt>width</tt> or <tt>height</tt> of the image is specified, the other dimension is scaled appropriately to keep the aspect ratio.
<texcode>\externalfigure[logo.pdf][page=5]</texcode>
These four variations cover the most common use cases. == Natively supported file formats File Formats ==
ConTeXt natively supports the image formats enumerated below. The image format is determined from the file extension (case insensitive).
* '''PDF''': File extension <tt>.pdf</tt>
* '''JBIG''' or '''JBIG2''': File extension <tt>.jbig</tt>, <tt>.jbig2</tt>, or <tt>.jb2</tt>
== Including images after conversion 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 which 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 <tt>PATH</tt>.
<table>
<tr class="even">
<td align="left"><strong>GIF</strong></td>
<td align="left"><code>.gitgif</code></td>
<td align="left"><code>gm</code> from GraphicsMagick</td>
</tr>
</table>
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>
== Specifying image directories 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, say for example a <tt>./images</tt> subdirectory and <tt>/home/user/images</tt>, use: <texcode>\setupexternalfigures[directory={images, /home/user/images}]</texcode>
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 [location=global]</texcode>
To restore the default search behavior, use:
<texcode>\setupexternalfigures [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:
<texcode>\setupexternalfigures [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.
== Including remote images Remote Images ==
<texcode>\externalfigure [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.
<texcode>\enabledirectives[schemes.threshold=120]</texcode>
in the ConTeXt file, or compile the ConTeXt file using the command
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.
= Image transformations == 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 === 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>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</pre> Insert the `-k` or `--insecure` option: <pre> local command = "curl --insecure --silent --create-dirs --output " .. cachename .. " " .. name</pre> == Inline Images == Embedding inline images via base64 encoding using the memstream function (supports pdf and png streams): <texcode>\startluacodelocal cow = mime.unb64("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Y1NldFsvUERGXQovQ29sb3JTcGFjZSAxMCAwIFIKL0V4dEdTdGF0ZSAxMSAwIFIKPj4KL0NvbnRlbnRzIDUgMCBSCj4+CmVuZG9iagozIDAgb2JqCjw8IC9UeXBlIC9QYWdlcyAvS2lkcyBbCjQgMCBSCl0gL0NvdW50IDEKPj4KZW5kb2JqCjEgMCBvYmoKPDwvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMyAwIFIKPj4KZW5kb2JqCjcgMCBvYmoKPDwvVHlwZS9FeHRHU3RhdGUKL09QTSAxPj5lbmRvYmoKOSAwIG9iagpbL1NlcGFyYXRpb24KL0JsYWNrCi9EZXZpY2VDTVlLCjggMCBSXWVuZG9iagoxMCAwIG9iago8PC9SOQo5IDAgUj4+CmVuZG9iagoxMSAwIG9iago8PC9SNwo3IDAgUj4+CmVuZG9iago4IDAgb2JqCjw8L0ZpbHRlci9GbGF0ZURlY29kZQovRnVuY3Rpb25UeXBlIDQKL0RvbWFpblswCjFdCi9SYW5nZVswCjEKMAoxCjAKMQowCjFdL0xlbmd0aCAyOT4+c3RyZWFtCnicq04pLVAwUMgtzVFIrUjOUMDPNQQzawHfFRGFCmVuZHN0cmVhbQplbmRvYmoKMiAwIG9iago8PC9Qcm9kdWNlcihBRlBMIEdob3N0c2NyaXB0IDguNTIpCi9DcmVhdGlvbkRhdGUoRDoyMDA2MDUxNTEyMjA1OSkKL01vZERhdGUoRDoyMDA2MDUxNTEyMjA1OSkKL0NyZWF0b3IoQ29yZWxEUkFXISkKL1RpdGxlKENPVy5FUFMpPj5lbmRvYmoKeHJlZgowIDEyCjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwNDYzNiAwMDAwMCBuIAowMDAwMDA0OTg2IDAwMDAwIG4gCjAwMDAwMDQ1NzcgMDAwMDAgbiAKMDAwMDAwNDQyNiAwMDAwMCBuIAowMDAwMDAwMDE1IDAwMDAwIG4gCjAwMDAwMDQ0MDYgMDAwMDAgbiAKMDAwMDAwNDY4NCAwMDAwMCBuIAowMDAwMDA0ODM4IDAwMDAwIG4gCjAwMDAwMDQ3MjUgMDAwMDAgbiAKMDAwMDAwNDc3OCAwMDAwMCBuIAowMDAwMDA0ODA4IDAwMDAwIG4gCnRyYWlsZXIKPDwgL1NpemUgMTIgL1Jvb3QgMSAwIFIgL0luZm8gMiAwIFIKL0lEIFs8ODE0NjQ5NTc3Qzg3MTE1QzRDQzBDQjg0QkU3RTQ1MEY+PDgxNDY0OTU3N0M4NzExNUM0Q0MwQ0I4NEJFN0U0NTBGPl0KPj4Kc3RhcnR4cmVmCjUxMzMKJSVFT0YK")figures.setmemstream("inline",cow)context.externalfigure({"memstream:///inline"})\stopluacode</texcode> = Transformations = == Image Scaling images ==
To scale an image use the <tt>scale</tt> key: <tt>scale=1000</tt> corresponds to the original dimensions of the image, <tt>scale=500</tt> scales the image to 50% of the original size, <tt>scale=1500</tt> scales the images to 150% of the original size, and so on. For example:
<texcode>\externalfigure[logo.pdf][scale=500]</texcode>
Use <tt>\setupexternalfigures</tt> to set the scale of all images. For example, to scale all images to be twice their original size, use:
<texcode>\setupexternalfigures[scale=2000]</texcode>
If either <tt>width</tt> or <tt>height</tt> is specified, then the <tt>scale</tt> key has no effect.
<texcode>\externalfigure[logo.pdf][xscale=500]
\externalfigure[logo.pdf][yscale=500]</texcode>
<texcode>\externalfigure[logo.pdf][maxwidth=0.2\textwidth]</texcode>
If <tt>maxwidth</tt> is specified and the width of the image is less than <tt>maxwidth</tt>, then the image is not scaled; if the width of the image is greater than <tt>maxwidth</tt>, then the width is restricted to <tt>maxwidth</tt> and the height is scaled appropriately to maintain the original aspect ratio.
[maxwidth=\textwidth,
maxheight=0.8\textheight]</texcode>
<texcode>\externalfigure[logo.pdf][orientation=90]</texcode>
To rotate by an arbitrary angle, use the <tt>\{{cmd|rotate</tt> }} command. For example:
<texcode>\rotate[rotation=45]{\externalfigure[logo.pdf]}</texcode>
== Image Mirroring == To mirror (flip) an image, use the generic <tt>\{{cmd|mirror</tt> }} command. For example, to mirror horizontally:
<texcode>\mirror{\externalfigure[logo.pdf]}</texcode>
To mirror vertically, first rotate the image by 180° and then mirror it:
<texcode>\mirror{\externalfigure[logo.pdf][orientation=180]}</texcode>
<texcode>\clip[width=1cm, height=2cm, hoffset=3mm, voffset=5mm]
{\externalfigure[logo.pdf]}</texcode>
As another example, this cuts the image into a <tt>3x3</tt> pieces and then outputs the <tt>(2,2)</tt> piece:
<texcode>\clip[nx=3,ny=3,x=2,y=2]
{\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 =
This section describes various tips for discovering problems with embedded images. == Visualizing the image bounding box 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:
<texcode>\externalfigure[logo.pdf][frame=on]</texcode>
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>
The most important flag is <tt>--offset=dimen</tt>, which keeps some extra space around the trimmed image.
Similar functionality is provided by another Perl script, <tt>pdfcrop</tt>, that is included in most TeX distributions.
== Diagnostic Tracking what is happening ==
To get diagnostic information about image inclusion, enable the tracker <tt>graphics.locating</tt> either by editing the ConTeXt file and adding:
<texcode>\enabletrackers[graphics.locating]</texcode>
<texcode>context --trackers=graphics.locating filename</texcode>
The tracker writes diagnostics to the console. Suppose we use <tt>\externalfigure[somefile.pdf]</tt> and ConTeXt finds the file in the current search path; then the following information is printed on the console:
<texcode>\useMPlibrary[dum]</texcode>
Then, whenever an image file is not found in the current search path, a random MetaPost image is shown in the output.
<context> </context>
== Images at the beginning of a paragraph Leading Paragraph ==
Using {{cmd|externalfigure}}<tt>\externalfigure[...]</tt> at the beginning of a paragraph results in a line break after the image. This is because <tt>\{{cmd|externalfigure</tt> }} is a <tt>\{{cmd|vbox</tt> }} and when encounters a <tt>\{{cmd|vbox</tt> }} is encountered at (what appears to be) the beginning of a paragraph, it remains in vertical mode. To prevent this, add <tt>\{{cmd|dontleavehmode</tt> }} before <tt>\{{cmd|externalfigure</tt>}}, like this:
<texcode>\dontleavehmode
\externalfigure[...] ... first line ...</texcode>
== Multiple Image settings =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 <tt>\{{cmd|defineexternalfigure</tt> }} macro, which defines a named collection of image settings. For example, to define a collection where the image width is <tt>3cm</tt>, use:
<texcode>\defineexternalfigure[logo-settings]
[width=3cm]</texcode>
And then to use these settings in an image, use:
<texcode>\externalfigure[group.pdf][logo-settings]</texcode>
or, if you want to add or override settings, use:
<texcode>\externalfigure[group.pdf][logo-settings]
[height=2cm]</texcode>
== 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 <tt>\{{cmd|useexternalfigure</tt>}}, which defines a symbolic label for inserting an image plus settings. For example:
<texcode>\useexternalfigure[mylogo]
[logo.pdf][width=2cm]</texcode>
defines an image label <tt>mylogo</tt> that maps to the image file <tt>logo.pdf</tt> and sets its width to <tt>2cm</tt>. This image label may be used as a normal image filename:
= [[Floating Objects]] =
<texcode>
You find more about floats ([[Floating Objects]]) in the manual.
= Movies =
<texcode>
\setupcolorsexternalfigure[state=start]\placefigure[right,high,nonedemo.mov]{}{\framed[frame=on, offsetlabel=10ptdemo, framecolorwidth=lightgray4cm, backgroundheight=color4cm, backgroundcolor=lightgray]% {\externalfigure[sample/cow.pdf][scalepreview=500yes]}}\input knuth
</texcode>
<tt>preview=yes</tt> shows the first image as preview.
You find more about interactive Elements in [http://www.pragma-ade.com/general/manuals/mwidget-s.pdf 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:
<texcode>
\defineprogram[dummy.mpeg][dummy.mpeg.sh]
</nowiki></pre>
== Full page images ==* See [[Simple Cover Page]] == Picture with hyperlink == This is an example of how to make a picture interactive. When the user clicks it, it invokes the user's browser to a given URL. <texcode>\setupinteraction[state=start] \starttextThis is a cow: \goto{\externalfigure[cow][height=2ex]}[url(http://en.wikipedia.org/wiki/Cow)]\stoptext </texcode> === 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 Also = "http://proxy.example.com:3128"}</texcode>
* [[Animation]]
* [[Example photo page layout]]
[[Category:Graphics]]
{{Getting started navbox}}
