Images for documentation examples

ConTeXt users tend to use the famous Dutch cow as a place holder image for documentation examples. At times, it gets annoying. One alternative is to use random figures:

\useMPlibrary[dum]

\starttext
  \placefigure[left,none]{}
    {\externalfigure[whatever][width=0.5\textwidth, height=0.3\textheight]}
  \input knuth
\stoptext

which gives an image as shown below:

The image is draws random circles with random colors using metapost.

In a recent discussion on tex.se, Sharpie mentioned a website: http://placekitten.com, that provides pictures of kittens as placeholders for images. Those kittens are definitely cuter than the Dutch cow. Using these kittens as placeholder images is easy: if you want a 300pt x 400pt images, just type:

\externalfigure[http://placekitten.com/g/300/400][method=jpg]

ConTeXt takes care of downloading and caching the image. However, to use this approach, you need to know the required image dimensions in postscript points. Many a times, the image dimensions are known in relative terms like the above example where we asked for an image that is 0.5\textwidth wide and 0.3\textheight high. To convert a arbitrary TeX dimention to points, we can use \dimexpr which reports its result in points. So, to know how much is 0.5\textwidth we can use

\the\dimexpr0.5\textwidth

For the default setup, this reports 213.3937pt. To use this dimension with place kitten website, we need to get rid of the pt suffix—a freqeuntly needed feature for which ConTeXt, like almost all other macro packages, provides a built-in macro: \withoutpt. Thus, we can use

\withoutpt{\the\dimexpr0.5\textwidth}

to get the value of 0.5\textwidth without the pt suffix. However, this is not enough: the place kitten website does not provide images with fractional sizes. So, we need to round (or truncate) the value to a whole number. I don’t know if ConTeXt has a built-in macro for that; neither do I care enough to write such a macro in TeX. Truncating a float to an integer is easy in Lua, and that is what I will use. Combining all this, here is a macro that places an image of a kitten that is of a particular size:

\def\externalkitten[#1]%
    {\getparameters[kitten][width=10pt, height=10pt, #1]
     \externalfigure
        [\ctxlua{context("http://placekitten.com/g/\%0.0f/\%0.0f",
                  \withoutpt{\the\dimexpr\kittenwidth},
                  \withoutpt{\the\dimexpr\kittenheight})}]
        [#1, method=jpg]}

This can be used as:

\starttext
  \placefigure[left,none]{}
    {\externalkitten[width=0.5\textwidth, height=0.3\textheight]}
  \input knuth
\stoptext

which gives the following result:

I think that this looks much nicer than the random image above. Below is an example that uses the place kitten images to show how the location key works.

\startcombination[3*3]
  {\externalkitten[width=0.2\textwidth, height=0.15\textheight, location=top]}{}
  {\externalkitten[width=0.2\textwidth, height=0.20\textheight, location=top]}{}
  {\externalkitten[width=0.2\textwidth, height=0.25\textheight, location=top]}{}
  {\externalkitten[width=0.2\textwidth, height=0.15\textheight, location=middle]}{}
  {\externalkitten[width=0.2\textwidth, height=0.20\textheight, location=middle]}{}
  {\externalkitten[width=0.2\textwidth, height=0.25\textheight, location=middle]}{}
  {\externalkitten[width=0.2\textwidth, height=0.15\textheight, location=bottom]}{}
  {\externalkitten[width=0.2\textwidth, height=0.20\textheight, location=bottom]}{}
  {\externalkitten[width=0.2\textwidth, height=0.25\textheight, location=bottom]}{}
\stopcombination

Note that all three images are of different sizes. The first row is top aligned, the second row is middle aligned, and the third row is bottom aligned. Now imagine how this would have looked if all three images were scaled cows!