Command/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

width

target width of the image

height

target height of the image

label

internal name

page

Page number of a multi-page source file (PDF)

object

Reuse this image file as an object, i.e. embed it only once in the PDF if it’s used several times
no	don't reuse this image (e.g. you may want differently recolored versions of the same image, see the Pdfmerge manual)

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)

preview

Show preview image (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 to pass arguments to converters; when object=no, it could be used in compactors (PDF merging) to prevent object sharing (see the Pdfmerge manual)

factor

If both `width` and `height` are set, the `factor` is important. If `factor` is empty, the image is deformed accordingly. `fit` and `max` behave the same, while `min` replaces the intention of `fit`.
fit	same as `max` (was “aspect ratio is kept, the image is scaled to the smaller (fitted) variant”)
broad	(currently broken)
max	aspect ratio is kept, the image is scaled to the bigger (oversized) variant
default	same as `auto`

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` There’s also `none` as “Don’t search, use only given paths.”
local	search in the current directory
global	search path specified with the `directory` key
default	search in the texmf tree

directory

comma-separated list of 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 and MetaFun

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 also exists the following option which is missing in the interface files:

orientation : rotation (in LMTX arbitrary angles, in MkIV only 90˚steps)

Examples

Example 1

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

Notes

Help from ConTeXt-Mailinglist/Forum

All issues with: