\startcomponent co-en-14

\environment contextref-env
\product contextref

\chapter[figures,external figures]{Figures}

\section{Introduction}

In this chapter we discuss how to place figures in your
document. In \in {section} [floats] we introduced the float
mechanism. In this chapter the placement of figures is
discussed. Most of the time these figures are created with
external applications.

After processing a document the result is a \DVI\ file or,
when we use \PDFTEX, a \PDF\ file. The \DVI\ document
reserves space for the figure, but the figure itself will be
put in the document during postprocessing of the \DVI\ file.
\PDFTEX\ needs no postprocessing and the external figures
are automatically included in the \PDF\ file.

External figures may have different formats like the vector
formats \EPS\ and \PDF, or the bitmap formats \TIF, \PNG\
and \JPG. Note that we refer to figures but we could also
refer to movies. \CONTEXT\ has special mechsnisms to handle
figures generated by \METAPOST. We have to take care that
fonts used in \METAPOST\ figures are recognized by \PDFTEX.
Finally, we'll see that \METAPOST\ code can be embedded in
\CONTEXT\ documents.

Normally, users need not concern themselves with the
internal mechanisms used by \CONTEXT\ for figure processing.
However some insight may be useful.

\section{Defining figures}
\index{external figures}
\index{figures+defining}
\macro{\tex{setupexternalfigures}}
\macro{\tex{useexternalfigure}}
\macro{\tex{externalfigure}}

A figure is designed within specific dimensions. These
dimensions may of may not be known by the document designer.

\startlinecorrection
\startcombination[4*1]
  {\externalfigure[cow][scale=300,frame=on]}
     {natural dimension}
  {\externalfigure[cow][scale=225,frame=on]}
     {scaled to 25\%}
  {\externalfigure[cow][height=2cm,frame=on]}
     {a height of 2~cm}
  {\externalfigure[cow][height=2cm,width=3cm,frame=on]}
     {a height of 2~cm and a width 3~cm}
\stopcombination
\stoplinecorrection

If the original dimensions are unknown, then scaling the
figure to 40\% can have some astonishing results. A figure
with width and height of 1~cm becomes almost invisible, but
a figure width width and height of 50~cm will still be very
large when scaled to 40\% of its original size. A better
strategy is to perform the scaling based on the current
bodyfont size, the width of text on the page, or to set
absolute dimensions, such as 3~cm by 2~cm.

To give \TEX\ the opportunity to scale the figure adequately
the file format must be known. \in {Table} [tab:drivers]
shows the file formats supported by \DVIPS, \DVIPSONE, and
\PDFTEX\ respectively. \PDFTEX\ has the unique capability to
determine the file format during processing.

When we use \DVI, \TEX\ can determine the dimensions of an
\EPS\ illustration by searching for the so called {\em
bounding box}. However, with other formats such as \TIF, the
user is responsible for the determination of the figure
dimensions.

\startbuffer
\starttable[|l||||||||]
\HL
\VL           \VL\EPS\VL\PDF\VL\METAPOST\VL\TIF\VL\PNG\VL\JPG\VL\MOV\VL\SR
\HL
\VL \DVIPS    \VL +  \VL -- \VL +       \VL -  \VL -  \VL -  \VL +  \VL\FR
\VL \DVIPSONE \VL +  \VL -- \VL +       \VL +  \VL -  \VL -  \VL +  \VL\MR
\VL \PDFTEX   \VL -  \VL +  \VL +       \VL +  \VL +  \VL +  \VL +  \VL\LR
\HL
\stoptable
\stopbuffer

\placetable
  [here][tab:drivers]
  {Some examples of supported file formats.}
  {\getbuffer}

Now, let us assume that the dimensions of a figure are
found. When we want to place the same figure many times, it
would be obvious to search for these dimensions only once.
That is exactly what happens. When a figure is found it is
stored as an object. Such an object is re||used in \TEX\ and
in \PDF\ but not in \DVI, since reuse of information is not
supported by the \DVI\ format. To compensate for this
shortcoming, when producing \DVI\ output, \CONTEXT\ will
internally reuse figures, and put duplicates in the \DVI\
file.

\starttyping
\useexternalfigure[some logo][logo][width=3cm]

\placeexternalfigure{first logo}{\externalfigure[some logo]}

\placeexternalfigure{second logo}{\externalfigure[some logo]}
\stoptyping

So, when the second logo is placed, the information
collected while placing the first one is used. In \PDFTEX\
even the content is reused, if requested, at a different
scale.

A number of characteristics of external figures are specified
by:

\showsetup{setupexternalfigures}

This command affect all figures that follow. Three options are
available: \type {frame}, \type{empty} and \type{test}. With
\type {empty} no figures are placed, but the necessary space
is reserved. This can save you some time when \quote
{testing} a document. \footnote {A similar effect can be
obtained with the \type {--fast} switch in \TEXEXEC.}
Furthermore the figure characteristics are printed in that
space. When \type {frame} is set at \type {on} a frame is
generated around the figure. The option \type {test} relates
to testing hyperactive areas in figures.

When \CONTEXT\ is not able to determine the dimensions of an
external figure directly, it will fall back on a simple
database that can be generated by the \PERL\ script
\TEXUTIL. You can generate such a database by calling this
script as follows:

\starttyping
texutil  --figures  *.tif
\stoptyping

This will generate the \type {texutil.tuf} file, which
contains the dimensions of the \TIF\ figures found. You need
to repeat this procedure every time you change a graphic.
Therefore, it can be more convenient to let \CONTEXT\
communicate with \TEXUTIL\ directly. You can enable that by
adding \type {\runutilityfiletrue} to your local \type
{cont-sys.tex} file.

When a figure itself is not available but it is listed in
the \type {texutil.tuf} file then \CONTEXT\ presumes that
the figure does exist. This means that the graphics do not
need to be physically present on the system.

Although \CONTEXT\ very hard tries to locate a figure, it
may fail due to missing or invalid figure, or invalid path
specifications (more on that later). The actual search
depends on the setup of directories and the formats
supported. In most cases, it it best not to specify a suffix
or type.

\starttyping
\externalfigure[hownice]
\externalfigure[hownice.pdf]
\externalfigure[hownice][type=pdf]
\stoptyping

In the first case, \CONTEXT\ will use the graphic that has
the highest quality, while in both other cases, a \PDF\
graphic will be used. In most cases, the next four calls are
equivalent, given that \type {hownice} is available in
\METAPOST\ output format with a suffix \type {eps} or \type
{mps}:

\starttyping
\externalfigure[hownice]
\externalfigure[hownice][type=eps]
\externalfigure[hownice][type=eps,method=mps]
\externalfigure[hownice][type=mps]
\stoptyping

In most cases, a \METAPOST\ graphic will have a number as
suffix, so the next call makes the most sense:

\starttyping
\externalfigure[hownice.1]
\stoptyping

Let us summarize the process. Depending on the formats
supported by the currently selected driver (\DVI, \PDFTEX,
etc.), \CONTEXT\ tries to locate the graphics file, starting
with the best quality. When found, \CONTEXT\ first tries to
determine the dimensions itself. If this is impossible,
\CONTEXT\ will look into \type {texutil.tuf}. The graphic as
well as the file \type {texutil.tuf} are searched on the
current directory (\type {local}) and|/|or dedicated
graphics directories (\type {global}), as defined by \type
{\setupexternalfugures}. By default the \type {location} is
set at \type {{local,global}}, so both the local and global
directories are searched. You can set up several directories
for your search by providing a comma||delimited list:

\starttyping
\setupexternalfigures[directory={c:/fig/eps,c:/fig/pdf}]
\stoptyping

Even if your operating uses a \texescape\ as separator, you
should use a \type {/}. The figure directory may be system
dependent and is either set in the file \type {cont-sys}, in
the document preamble, or in a style.

An external figure is summoned by the command \type
{\externalfigure}. The cow is recalled with:

\starttyping
\externalfigure[cow][width=2cm]
\stoptyping

For reasons of maintenance it is better to specify all
figures at the top of your source file or in a separate
file. The figure definition is done with:

\showsetup{useexternalfigure}

Valid definitions are:

\starttyping
\useexternalfigure [cow]
\useexternalfigure [some cow] [cow230]
\useexternalfigure [big cow]  [cow230] [width=4cm]
\stoptyping

In the first definition, the figure can be recalled as \type
{cow} and the graphics file is also \type {cow}. In the
second and third definition, the symbolic name is \type
{some cow}, while the filename is \type {cow230}. The last
example also specifies the dimensions.

The \type {scale} is given in percentages. A scale of \type
{800} (80\%) reduces the figure, while a value of \type
{1200} (120\%) enlarges the figure. Instead of using
percentages you can also scale with a factor that is related
to the actual bodyfont. A setup of \type {hfactor=20}
supplies a figure with 2~times the height of the bodyfont
size, and \type {hfactor=120} will result in a width of
12~times the bodyfont size (so 144pt when using a 12pt
bodyfont size). When we want to place two figures next to
one another we can set the height of both figures with \type
{hfactor} at the same value:

\startexample
\starttyping
\useexternalfigure[alfa][file0001][hfactor=50]
\useexternalfigure[beta][file0002][hfactor=50]

\placefigure
  {Two figures close to one another.}
  \startcombination[2]
    {\externalfigure[alfa]} {this is alfa}
    {\externalfigure[beta]} {this is beta}
  \stopcombination
\stoptyping
\stopexample

We can see that \type {\externalfigure} is capable of using
a predefined figure. The typographical consistency of a
figure may be enhanced by consistently scaling the figures.
Also, figures can inherit characteristics of previously
defined figures:

\startexample
\starttyping
\useexternalfigure [alfa]  [file0001] [hfactor=50]
\useexternalfigure [beta]  [file0002] [alfa]
\useexternalfigure [gamma] [file0003] [alfa]
\useexternalfigure [delta] [file0004] [alfa]
\stoptyping
\stopexample

Normalizing a figure's width must also be advised when
figures are placed with \type {\startfiguretext} below one
another.

In most cases you will encounter isolated figures of which
you want to specify width or height. In that case there is
no relation with the bodyfont except when the units \type
{em} or \type {ex} are used.

In \in {figure} [fig:factors] we drew a pattern with squares
of a factor~10.

\placefigure
  [here]
  [fig:factors]
  {Factors at the actual bodyfont.}
  {\vskip\lineheight
   \grid
     [nx=30,ny=10,
      dx=\bodyfontpoints,dy=\bodyfontpoints,
      xstep=1,ystep=1,
      unit=pt]}

\section{Recalling figures}
\index{figures+recalling}
\macro{\tex{showexternalfigures}}
\macro{\tex{externalfigure}}

A figure is recalled with the command:

\showsetup{externalfigure}

For reasons of downward compatibility a figure can also be
recalled with a command that equals the figure name. In the
example below we also could have used \type {\acow} and
\type {\bcow}, unless they are already defined. Using \type
{\externalfigure} instead is more safe, since it has its own
namespace.

\startbuffer
\useexternalfigure[acow][cow][factor=10]
\useexternalfigure[bcow][cow][factor=20]

\placefigure[left]{none}{\externalfigure[bcow]}

The \hbox {\externalfigure[acow]} is a very well known animal in the Dutch
landscape. But for environmental reasons the \hbox {\externalfigure[acow]}
is slowly disappearing. In the near future the cow will fulfil a marginal
\inleft {\externalfigure[bcow]} role in the Netherlands. That is the
reason why we would like to write the word \hbox {\externalfigure[bcow]}
in big print.
\stopbuffer

\startexample
\typebuffer
\stopexample

Here we see how \type {acow} and \type {bcow} are reused.
This code will result in:

\getbuffer

Normalized figures adapt to the actual bodyfont at least
when the font is set with \type {\setupbodyfont} or \type
{\switchtobodyfont}. When a text is used for different media
and is generated with different fontsizes the use of
normalized figures is a good practice. The example above
looks different in a smaller fontsize.

\start
\switchtobodyfont[small]
\getbuffer\par
\stop

\section{Automatic scaling}
\index{figures+maximum}

In cases where you want the figure displayed as big as
possible you can set the parameter \type{factor} at
\type{max}, \type{fit} or \type{broad}. In most
situations the value \type{broad} will suffice, because then
the caption still fits on a page.

\placetable{Normalized figures.}
\starttable[|l|l|]
\HL
\VL \bf setup    \VL \bf result                     \VL\SR
\HL
\VL \tttf max    \VL maximum width or height        \VL\FR
\VL \tttf fit    \VL remaining width or height      \VL\MR
\VL \tttf broad  \VL more remaining width or height \VL\MR
\VL \ttsl number \VL scaling factor (times 10)      \VL\LR
\HL
\stoptable

So, one can use \type {max} to scale a figure to the full
page, or \type {fit} to let it take up all the remaining
space. With \type {broad} some space is reserved for a
caption.

Sometimes it is not clear whether the height or the width of
a figure determines the optimal display. In that case you
can set \type {factor} at \type {max}, so that the maximal
dimensions are determined automatically.

\starttyping
\externalfigure[cow][factor=max]
\stoptyping

This figure of a cow will scale to the width or height of
the text, whichever fits best. Even combinations of settings
are possible:

\starttyping
\externalfigure[cow][factor=max,height=.4\textheight]
\stoptyping

In this case, the cow will scale to either the width o fthe
text or 40\% of the height of the text, depending on what
fits best.

As already said, the figures and their characteristics are
stored in the file \type {texutil.tuf} and can be displayed
with:

\showsetup{showexternalfigures}

There are two alternatives: \type {a}, \type {b} and~\type
{c}. The first alternative leaves room for figure
corrections and annotations, the second alternative is
somewhat more efficient and places more figures on one page.
The third alternative puts each figure on its own page. Of
course one needs to provide the file \type {texutil.tuf} by
saying:

\starttyping
texutil --figures *.mps *.jpg *.png
\stoptyping

Even more straightforward is running \TEXEXEC, for instance:

\starttyping
texexec --figures=c --pdf *.mps *.jpg *.png
\stoptyping

This will give you a \PDF\ file of the figures requested,
with one figure per page.

\section{\TEX||figures}
\index{figures+tables}
\index{tables+scaling}

Figures can be scaled. This mechanism can also be used for
other text elements. These elements are then stored in
separate files or in a buffer. The next example shows how a
table is scaled to the pagewidth. The result is typeset in
\in {figure} [fig:table].

\startbuffer
\startbuffer[table]
  \starttable[||||||]
    \HL
    \VL \bf factor           \VL \bf width            \VL
        \bf height           \VL \bf width and height \VL
        \bf nothing          \VL \SR
    \HL
    \VL \type{max}           \VL automatically        \VL
        automatically        \VL automatically        \VL
        width or height      \VL \FR
    \VL \type{fit}           \VL automatically        \VL
        automatically        \VL automatically        \VL
        width or height      \VL \MR
    \VL \type{broad}         \VL automatically        \VL
        automatically        \VL automatically        \VL
        width or height      \VL \MR
    \VL \type{...}           \VL width                \VL
        height               \VL isometric            \VL
        original dimensions  \VL \LR
    \HL
  \stoptable
\stopbuffer

\placefigure
  [here][fig:table]
  {An example of a \TEX\ figure.}
  {\externalfigure[table.tmp][width=\textwidth]}

\placefigure
  {An example of a \TEX\ figure.}
  {\externalfigure[table.tmp][width=.5\textwidth]}
\stopbuffer

\typebuffer

\getbuffer

Buffers are written to a file with the extension \type
{tmp}, so we recall the table with \type{table.tmp}. Other
types of figures are searched on the directories
automatically. With \TEX\ figures this is not the case. This
might lead to conflicting situations when an \EPS\ figure is
meant and not found, but a \TEX\ file of that name is.

\section{Extensions of figures}
\index{figures+extensions}

In the introduction we mentioned different figure formats
like \EPS\ and \PNG. In most situations the format does not
have to be specified. On the contrary, format specification
would mean that we would have to re||specify when we
switch from \DVI\ to \PDF\ output. The figure format that
\CONTEXT\ will use depends on the special driver. First
preference is an outline, second a bitmap.

\METAPOST\ figures, that can have a number as suffix, are
recognized automatically. \CONTEXT\ will take care of the
font management when it encounters \METAPOST\ figures. When
color is disabled, or \RGB\ is to be converted to \CMYK,
\CONTEXT\ will determine what color specifications have to
be converted in the \METAPOST\ file. If needed, colors are
converted to weighted grey scales, that print acceptable on
black and white printers. In the next step the fonts are
smuggled into the file.\footnote {Fonts are a problem in
\METAPOST\ files, since it it up to the postprocessor to
take care of them. In this respect, \METAPOST\ output is not
self contained.} In case of \PDF\ output the \METAPOST\ code
is converted into \PDF\ by \TEX.

If necessary the code needed to insert the graphic is stored
as a so called object for future re||use. This saves
processing time, as well as bytes when producing \PDF. You
can prevent this by setting \type {object=no}.

When \EPS\ and \MPS\ (\METAPOST) figures are processed
\CONTEXT\ searches for the high resolution bounding box. By
default the \POSTSCRIPT\ bounding box may have a deviation
of half a point, which is within the accuracy of our eyes.
Especially when aligning graphics, such deviations will not
go unnoticed.

\CONTEXT\ determines the file format automatically, as is the
case when you use:

\starttyping
\externalfigure[cow]
\stoptyping

Sometimes however, as we already explained, the user may
want to force the format for some reason. This can be done
by:

\starttyping
\externalfigure[cow.eps]
\externalfigure[cow][type=eps]
\stoptyping

In special cases you can specify in which way figure
processing takes place. In the next example \CONTEXT\
determines dimensions asif the file were in \EPS\ format,
that is, it has a bounding box, but processes the files as
if it were a \METAPOST\ file. This kind of detailed
specification is seldom needed.

\starttyping
\externalfigure[graphic.xyz][type=eps,method=mps]
\stoptyping

The automatic searching for dimensions can be blocked by
\type {preset=no}.

\section{Movies}
\index{movies}

In \CONTEXT\ moving images or \quote {movies} are handled
just like figures. The file format type is not determined
automatically yet. This means the user has to specify the
file format.

\starttyping
\externalfigure[demo.mov][label=demo,width=4cm,height=4cm,preview=yes]
\stoptyping

With this setup a preview is shown (the first image of the
movie). If necessary an ordinary (static) figure can be
layed over the first movie image with the overlay mechanism.

Movies can be controlled either by clicking on them, or by
providing navigational tools, like:

\starttyping
... \goto {start me} [StartMovie{demo}] ...
\stoptyping

A more detailed discussion on controlling widgets is beyond
this chapter. Keep in mind that you need to distribute the
movies along with your document, since they are not included.
This makes sense, since movies can be pretty large.

\section{Some remarks on figures}

Figures, and photos in particular, have to be produced with
consistent proportions. The proportions specified in \in
{figure} [fig:proportions] can be used as a guideline.
Scaling of photos may cause quality loss.

\def\imageproportion#1:#2%
  {\bgroup
   \dimen0=4em
   \dimen2=#1\dimen0
   \divide\dimen2 by #2
   \framed[width=\dimen0,height=\dimen2]{#1 : #2}%
   \egroup}

\placefigure
  [here][fig:proportions]
  {Some preferred image proportions.}
\startcombination[3*2]
  {\imageproportion4:5} {}
  {\imageproportion3:4} {}
  {\imageproportion2:3} {}
  {\imageproportion5:4} {}
  {\imageproportion4:3} {}
  {\imageproportion3:2} {}
\stopcombination

In the background of a figure you typeset a background (see
\in{figure}[fig:background in figures]). In this example the
external figures get a background (for a black and white
reader: a green screen).

\startbuffer
\def\showacow#1%
  {\externalfigure
     [cow]
     [hfactor=80,background=screen,backgroundscreen=#1]}

\def\showascreen#1%
  {\type{raster=#1}}

\startcombination[3*2]
  {\showacow{0.70}} {\showascreen{0.70}}
  {\showacow{0.75}} {\showascreen{0.75}}
  {\showacow{0.80}} {\showascreen{0.80}}
  {\showacow{0.85}} {\showascreen{0.85}}
  {\showacow{0.90}} {\showascreen{0.90}}
  {\showacow{0.95}} {\showascreen{0.95}}
\stopcombination
\stopbuffer

\start

\setupfloats
  [background=color,
   backgroundcolor=green,
   backgroundoffset=3pt]

\placefigure
  [][fig:backgrounds in figures]
  {Some examples of backgrounds in figures.}
  {\getbuffer}

\stop

\startexample
\starttyping
\setupfloats
  [background=color,
   backgroundcolor=green,
   backgroundoffset=3pt]

\useexternalfigure [cow]
  [hfactor=80,
   background=screen,
   backgroundscreen=0.75]
\stoptyping
\stopexample

Note that we use only one float and that there are six
external figures. The background of the float is used for
the complete combination and the background of the external
figure only for the figure itself.

\stopcomponent

