Background

Looking to make a background image scale to fill an entire page.

Code

I tried changing the dimensions of the page to fill the entire area and then drop in an external image:

\setuplayout[
backspace=0mm,
leftmargin=0mm,
rightmargin=0mm,
topdistance=0mm,
footer=0mm,
]

\starttext

\startfrontmatter

% Title page (front cover).
\startstandardmakeup
% Front Cover Photo
\externalfigure[cover.png][width=\paperwidth,height=\paperheight]
\stopstandardmakeup

\startstandardmakeup
% date
% author

\stopstandardmakeup

\completecontent
\stopfrontmatter

\stoptext


Update

Other attempts that don't quite work.

Layer

Using a defined layer:

\definelayer[cover][
x=0mm,
y=0mm,
width=\paperwidth,
height=\paperheight,
]

\setlayer[cover][
hoffset=0mm,
voffset=0mm,
]{%
\framed[
frame=off
width=\paperwidth,
height=\paperheight,
]{%
\externalfigure[cover.png][width=\paperwidth,height=\paperheight]
}
}

\starttext

\startfrontmatter
\setupbackgrounds[page][background=cover]
\startstandardmakeup
\stopstandardmakeup
\setupbackground[page][background=]
\stopfrontmatter
\stoptext


This produces a white border along the left and bottom edges:

Problem

There is a small amount of whitespace that is not taken up by the image:

Related

The wiki shows how to fill a page using an MP graphic, but that seems to be overly complicated for just adding an image to the page:

The question on filling the background graphic across two pages is similar, but has text on top of the image:

External figures are set up as follows:

\setupexternalfigures[
order={svg,pdf,png,jpg},
location=global,
width=\hsize,
]


Question

What is the proper way to scale an image, without respecting its aspect ratio, such that it fills the entire page?

-
You don't need a \framed inside the layer. Simply use \setlayer[cover]{\externalfigure[cover.png][width=..., height=...]} (with no whitespace after ] of \externalfigure) – Aditya Sep 22 '13 at 6:43
By any chance, do you have \setupexternalfigures[factor=fit] somewhere in your code? If so, you could try using \externalfigure[...][... factor=]. – Aditya Sep 22 '13 at 6:45

Normally, you use \setupbackgrounds[page][background=...] to set a page background. So, one option is to use

\setupbackgrounds[page][background=...]
\startstandardmakeup
...
\stopstandardmakeup
\setupbackground[page][background=] %Reset


A more elegant option is to extend the makeup mechanism to accept the background key:

\unprotect
\appendtoks
\setupbackgrounds[\v!page][\c!background=\makeupparameter\c!background]
\to \t_page_makeup_every_setup
\protect


Then you can use

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

\defineoverlay
[backgroundimage]
[{\externalfigure[cow.pdf][width=\overlaywidth, height=\overlayheight]}]

\starttext

\startstandardmakeup[background=backgroundimage]
Whatever
\stopstandardmakeup

Next

\stoptext


If you just want to include an image, you can also use:

\startTEXpage
\externalfigure[cow.pdf][width=\paperwidth, height=\paperheight]
\stopTEXpage

-
The only solution that worked for me was the elegant solution. I updated my question to reflect the problems I encountered with the two other solutions you've given. – Dave Jarvis Sep 22 '13 at 6:14
TEXpage does not add any whitespace, so I am surprised on why you are seeing whitespace. Try adding \externalfigure[...][..., frame=on] to see the bounding box of the image. What happens if you replace cover.png with some other image? – Aditya Sep 22 '13 at 6:41
Ah. It was due to textwidth=\dimexpr\textwidth+2.75em, on the page layout. – Dave Jarvis Sep 22 '13 at 6:43
In general, it is bad idea to specify textwidth inside \setuplayout. Use width=<dim>, if you must specify the width. – Aditya Sep 22 '13 at 6:46