Command/useexternalfigure

From ConTeXt wiki

\useexternalfigure

Syntax (autogenerated)

\useexternalfigure[...][...][...][...=...,...]
[...]name
[...]file
[...]name
...=...,...inherits from \setupexternalfigure


Syntax

\useexternalfigure[...][...][...,...=...,...]
[...] name
[...] file
width dimension
height dimension
label name
page number
object yes no
prefix text
method pdf mps jpg png jp2 jbig svg eps gif tif mov buffer tex cld auto
controls yes no
preview yes no
mask name
resolution number
color color
arguments text
repeat yes no
factor fit max broad auto default
wfactor fit max broad auto default
hfactor fit max broad auto default
maxwidth dimension
maxheight dimension
equalwidth dimension
equalheight dimension
scale number
xscale number
yscale number
s number
sx number
sy number
lines number
location local global default
directory path
option test frame empty
foregroundcolor color
backgroundcolor color
reset yes no
background color foreground name
frame off on
xmax number
ymax number
frames off on
interaction none yes all reference layer bookmark
bodyfont dimension
comment command text
size none media crop trim art
cache path
resources path
display file
conversion text
order list
crossreference yes no
transform auto number
userpassword text
ownerpassword text
orientation -90 90 180 270
preset yes no
type eps mps pdf tif png jpg mov tex (MkII)


Description

  • color: Colorize the image. Works only with some greyscale pictures (no channels, no additional tables, ...?) and only with toned (p=) or spot colors. Use with object=no
  • compact: Try to share fonts of embedded PDFs? (experimental)
  • controls: Show media controls (for movies)?
  • display: alternative figure, e.g. lowres
  • factor: see below.
  • object: Reuse this image file as an object, i.e. embed it only once in PDF if it’s used several times? (default: yes)
  • order: Order of file extensions to try with method=auto, e.g. {pdf,svg,png}. Could make sense to change this for print/web modes.
  • orientation: Rotation in 90˚ steps (otherwise use \rotate).
  • page: Page number of PDF.
  • scale: 1000 is original size (100%); to get 72%, use scale=720.
  • size: Use specified box of PDF (MediaBox, CropBox, TrimBox, ArtBox). (No BleedBox?)
  • type: File type tif is not supported by pdfTeX (MkII).

There are even more undocumented parameters in the source.

If both width and height are set, the factor is important:

none: image is deformed accordingly
max: aspect ratio is kept, the image is scaled to the bigger (oversized) variant
fit: aspect ratio is kept, the image is scaled to the smaller (fitted) variant
broad: ?? shows the same behaviour as fit

Comment

By design, \useexternalfigure works only in local scope. In order to globally declare a figure, one has to wrap it into a \startglobal environment, thereby rendering it accessible outside the current group. [1]

NB: The drawback is that other local stuff might be leaked into the global environment.

\starttext
\bgroup
  \startglobal
    \useexternalfigure[kuh][cow.pdf]
  \stopglobal
  \placefigure[here]{first}{\externalfigure[kuh]}
\egroup
\placefigure[here]{second}{\externalfigure[kuh]}
\stoptext

Example

See also

Help from ConTeXt-Mailinglist/Forum

All issues with: