Command/setupexternalfigure

\setupexternalfigure

Summary

The command \setupexternalfigure sets up \externalfigure

Settings

\setupexternalfigure[...,...][...=...,...]
[...,...]	name
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	none
resolution	number
color	color
cmyk	yes no auto
arguments	text
repeat	yes no
factor	fit broad max auto default
hfactor	fit broad max auto default
wfactor	fit broad max 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
reset	yes no
background	color foreground name
frame	on off
backgroundcolor	color
xmax	number
ymax	number
frames	on off
interaction	yes all none 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 number
transform	auto number
userpassword	text
ownerpassword	text

Option	Explanation
label	internal name
page	Page number of PDF.
object	Reuse this image file as an object, i.e. embed it only once in PDF if it’s used several times?
method	force a file type (and processing), e.g. if there are different versions mov is removed from LMTX auto strips suffix and uses "order"
controls	Show media controls (for movies)
resolution	Set the image resolution (after scaling) for automatic downsampling number dpi
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 color color name
cmyk	Force CMYK conversion
arguments	used for converters
factor	If both width and height are set, the factor is important. If factor is empty, the image is deformed accordingly. fit aspect ratio is kept, the image is scaled to the smaller (fitted) variant max aspect ratio is kept, the image is scaled to the bigger (oversized) variant
maxwidth	maximum width
maxheight	maximum height
scale	1000 is original size (100%); to get 72%, use scale=720.
lines	Height in lines
location	Where to find figure files. Multiple comma-separated options are allowed, and the default value is local,global local search in the current directory global search path specified with the directory key default search in the texmf tree
directory	comma-separated directories to search for figure files
option	empty don’t include actual image (“draft mode”)
foregroundcolor	probably synonymous to "color"
background	like \setupframed
frame	Show frame around image. Most(?) options of \setupframed are usable!
backgroundcolor	like \setupframed, used if background=color
interaction	How to handle the interaction (links etc.) of included PDFs – default is to disable all of them. yes keep all(?) all keep all none disable all reference keep references layer keep PDF layers (viewer layers, optional content groups) bookmark keep bookmarks
size	Use specified box of PDF (MediaBox, CropBox, TrimBox, ArtBox). (No BleedBox?)
cache	Set location of cache for conversions
display	alternative figure, e.g. lowres; used with movie and 3D contents, probably obsolete
conversion	see grph-con.lua. conversion=mp activates internal processing of SVG via MetaPost
order	Sets the order in which the individual file types are looked up.
crossreference	yes use counter for referencing
transform	Rotation in 90˚ steps (otherwise use \rotate); does not always work (?) orientation=90|180|270 works
userpassword	Access to encrypted PDFs
ownerpassword	Access to encrypted PDFs

Description

There are a few more options that are missing in the interface files:

• orientation: rotation (in LMTX arbitrary angles, in MkIV only 90˚steps)
• minwidth/minheight
• strut: strut=none also avoids the \noindent; otherwise we're in hmode when blank happens and we get a lineskip

Examples

Example 1

\setupexternalfigures
   [order={pdf,png,jpg},
    location=global,
    directory={images}]

See also

• \defineexternalfigure
• \externalfigure
• \definegraphictypesynonym
• grph-inc.mkvi MkIV source
• grph-inc.mkxl LMTX source
• grph-con.lua conversions source
• Using Graphics
• Multimedia Inclusion to add audio and video contents

Help from ConTeXt-Mailinglist/Forum

All issues with:

• \setupexternalfigure on the mailing list (all results)
• \setupexternalfigure on the mailing list (subject only)
• \setupexternalfigure on stack exchange
• \setupexternalfigure in ConTeXt's source